Expose version matching functions to the public

The functions to match a version or convert a string version number into
a tuple have shown to be useful in at least auth_token middleware. I
think this is also better as _discover should really only be a shadow
for the discover file because of the circular dependency problems.
_discover shouldn't really need to be used even within client.

Closes-Bug: #1400998
Change-Id: Icf700c30d01e0700e437437a23e63a7f100ce4d3

keystoneclient/auth/identity/generic/base.py

@@ -17,8 +17,8 @@ from oslo.config import cfg
 import six
 import six.moves.urllib.parse as urlparse
 
-from keystoneclient import _discover
 from keystoneclient.auth.identity import base
+from keystoneclient import discover
 from keystoneclient import exceptions
 from keystoneclient.i18n import _, _LW
 
@@ -147,7 +147,7 @@ class BaseGenericPlugin(base.BaseIdentityPlugin):
             for data in disc_data:
                 version = data['version']
 
-                if (_discover.version_match((2,), version) and
+                if (discover.version_match((2,), version) and
                         self._has_domain_scope):
                     # NOTE(jamielennox): if there are domain parameters there
                     # is no point even trying against v2 APIs.

keystoneclient/auth/identity/generic/password.py

@@ -14,10 +14,10 @@ import logging
 
 from oslo.config import cfg
 
-from keystoneclient import _discover
 from keystoneclient.auth.identity.generic import base
 from keystoneclient.auth.identity import v2
 from keystoneclient.auth.identity import v3
+from keystoneclient import discover
 from keystoneclient import utils
 
 LOG = logging.getLogger(__name__)
@@ -56,7 +56,7 @@ class Password(base.BaseGenericPlugin):
         self._user_domain_name = user_domain_name
 
     def create_plugin(self, session, version, url, raw_status=None):
-        if _discover.version_match((2,), version):
+        if discover.version_match((2,), version):
             if self._user_domain_id or self._user_domain_name:
                 # If you specify any domain parameters it won't work so quit.
                 return None
@@ -67,7 +67,7 @@ class Password(base.BaseGenericPlugin):
                                password=self._password,
                                **self._v2_params)
 
-        elif _discover.version_match((3,), version):
+        elif discover.version_match((3,), version):
             return v3.Password(auth_url=url,
                                user_id=self._user_id,
                                username=self._username,

keystoneclient/auth/identity/generic/token.py

@@ -14,10 +14,10 @@ import logging
 
 from oslo.config import cfg
 
-from keystoneclient import _discover
 from keystoneclient.auth.identity.generic import base
 from keystoneclient.auth.identity import v2
 from keystoneclient.auth.identity import v3
+from keystoneclient import discover
 
 LOG = logging.getLogger(__name__)
 
@@ -39,10 +39,10 @@ class Token(base.BaseGenericPlugin):
         self._token = token
 
     def create_plugin(self, session, version, url, raw_status=None):
-        if _discover.version_match((2,), version):
+        if discover.version_match((2,), version):
             return v2.Token(url, self._token, **self._v2_params)
 
-        elif _discover.version_match((3,), version):
+        elif discover.version_match((3,), version):
             return v3.Token(url, self._token, **self._v3_params)
 
     @classmethod

keystoneclient/discover.py

@@ -30,6 +30,46 @@ _CLIENT_VERSIONS = {2: v2_client.Client,
                     3: v3_client.Client}
 
 
+# functions needed from the private file that can be made public
+
+def normalize_version_number(version):
+    """Turn a version representation into a tuple.
+
+    Takes a string, tuple or float which represent version formats we can
+    handle and converts them into a (major, minor) version tuple that we can
+    actually use for discovery.
+
+    e.g. 'v3.3' gives (3, 3)
+         3.1 gives (3, 1)
+
+    :param version: Inputted version number to try and convert.
+
+    :returns: A usable version tuple
+    :rtype: tuple
+
+    :raises TypeError: if the inputted version cannot be converted to tuple.
+    """
+    return _discover.normalize_version_number(version)
+
+
+def version_match(required, candidate):
+    """Test that an available version is a suitable match for a required
+    version.
+
+    To be suitable a version must be of the same major version as required
+    and be at least a match in minor/patch level.
+
+    eg. 3.3 is a match for a required 3.1 but 4.1 is not.
+
+    :param tuple required: the version that must be met.
+    :param tuple candidate: the version to test against required.
+
+    :returns: True if candidate is suitable False otherwise.
+    :rtype: bool
+    """
+    return _discover.version_match(required, candidate)
+
+
 def available_versions(url, session=None, **kwargs):
     """Retrieve raw version data from a url."""
     if not session: