Merge "Fix up types within API documentation"

keystoneclient/auth/base.py

@@ -34,6 +34,7 @@ def get_plugin_class(name):
     :param str name: The name of the object to get.
 
     :returns: An auth plugin class.
+    :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
 
     :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
                                                         created.
@@ -67,6 +68,8 @@ class BaseAuthPlugin(object):
         Returning None will indicate that no token was able to be retrieved.
 
         :param session: A session object so the plugin can make HTTP calls.
+        :type session: keystoneclient.session.Session
+
         :return: A token to use.
         :rtype: string
         """
@@ -84,8 +87,8 @@ class BaseAuthPlugin(object):
         - ``interface``: what visibility the endpoint should have.
         - ``region_name``: the region the endpoint exists in.
 
-        :param Session session: The session object that the auth_plugin
+        :param session: The session object that the auth_plugin belongs to.
-                                belongs to.
+        :type session: keystoneclient.session.Session
 
         :returns: The base URL that will be used to talk to the required
                   service or None if not available.
@@ -167,8 +170,8 @@ class BaseAuthPlugin(object):
         Given a plugin class convert it's options into argparse arguments and
         add them to a parser.
 
-        :param AuthPlugin plugin: an auth plugin class.
+        :param parser: the parser to attach argparse options.
-        :param argparse.ArgumentParser: the parser to attach argparse options.
+        :type parser: argparse.ArgumentParser
         """
 
         # NOTE(jamielennox): ideally oslo.config would be smart enough to
@@ -201,10 +204,11 @@ class BaseAuthPlugin(object):
 
         Convert the results of a parse into the specified plugin.
 
-        :param AuthPlugin plugin: an auth plugin class.
+        :param namespace: The result from CLI parsing.
-        :param Namespace namespace: The result from CLI parsing.
+        :type namespace: argparse.Namespace
 
         :returns: An auth plugin, or None if a name is not provided.
+        :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
         """
         for opt in cls.get_options():
             val = getattr(namespace, 'os_%s' % opt.dest)
@@ -218,7 +222,8 @@ class BaseAuthPlugin(object):
     def register_conf_options(cls, conf, group):
         """Register the oslo.config options that are needed for a plugin.
 
-        :param conf: An oslo.config conf object.
+        :param conf: A config object.
+        :type conf: oslo.config.cfg.ConfigOpts
         :param string group: The group name that options should be read from.
         """
         plugin_opts = cls.get_options()
@@ -230,11 +235,12 @@ class BaseAuthPlugin(object):
 
         Convert the options already registered into a real plugin.
 
-        :param conf: An oslo.config conf object.
+        :param conf: A config object.
+        :type conf: oslo.config.cfg.ConfigOpts
         :param string group: The group name that options should be read from.
 
         :returns: An authentication Plugin.
-        :rtype: plugin:
+        :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
         """
         plugin_opts = cls.get_options()
 

keystoneclient/auth/cli.py

@@ -30,6 +30,7 @@ def register_argparse_arguments(parser, argv, default=None):
                               if one isn't specified by the CLI. default: None.
 
     :returns: The plugin class that will be loaded or None if not provided.
+    :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
 
     :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
                                                         created.
@@ -68,6 +69,7 @@ def load_from_argparse_arguments(namespace, **kwargs):
     :param Namespace namespace: The result from CLI parsing.
 
     :returns: An auth plugin, or None if a name is not provided.
+    :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
 
     :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
                                                         created.

keystoneclient/auth/conf.py

@@ -60,7 +60,8 @@ def register_conf_options(conf, group):
          taken. If section is not provided then the auth plugin options will be
          taken from the same group as provided in the parameters.
 
-    :param oslo.config.Cfg conf: config object to register with.
+    :param conf: config object to register with.
+    :type conf: oslo.config.cfg.ConfigOpts
     :param string group: The ini group to register options in.
     """
     conf.register_opt(_AUTH_SECTION_OPT, group=group)
@@ -85,11 +86,12 @@ def load_from_conf_options(conf, group, **kwargs):
     The base options should have been registered with register_conf_options
     before this function is called.
 
-    :param conf: An oslo.config conf object.
+    :param conf: A conf object.
+    :type conf: oslo.config.cfg.ConfigOpts
     :param string group: The group name that options should be read from.
 
     :returns: An authentication Plugin or None if a name is not provided
-    :rtype: plugin
+    :rtype: :py:class:`keystoneclient.auth.BaseAuthPlugin`
 
     :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
                                                         created.

keystoneclient/auth/identity/base.py

@@ -74,6 +74,9 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         when invoked. If you are looking to just retrieve the current auth
         data then you should use get_access.
 
+        :param session: A session object that can be used for communication.
+        :type session: keystoneclient.session.Session
+
         :raises keystoneclient.exceptions.InvalidResponse: The response
                                                            returned wasn't
                                                            appropriate.
@@ -89,6 +92,9 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
 
         If a valid token is not present then a new one will be fetched.
 
+        :param session: A session object that can be used for communication.
+        :type session: keystoneclient.session.Session
+
         :raises keystoneclient.exceptions.HttpError: An error from an invalid
                                                      HTTP response.
 
@@ -125,6 +131,9 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         If a valid AccessInfo is present then it is returned otherwise a new
         one will be fetched.
 
+        :param session: A session object that can be used for communication.
+        :type session: keystoneclient.session.Session
+
         :raises keystoneclient.exceptions.HttpError: An error from an invalid
                                                      HTTP response.
 
@@ -164,6 +173,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         If a valid token is not present then a new one will be fetched using
         the session and kwargs.
 
+        :param session: A session object that can be used for communication.
+        :type session: keystoneclient.session.Session
         :param string service_type: The type of service to lookup the endpoint
                                     for. This plugin will return None (failure)
                                     if service_type is not provided.
@@ -253,7 +264,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
         This function is expected to be used by subclasses and should not
         be needed by users.
 
-        :param Session session: A session object to discover with.
+        :param session: A session object to discover with.
+        :type session: keystoneclient.session.Session
         :param str url: The url to lookup.
         :param bool authenticated: Include a token in the discovery call.
                                    (optional) Defaults to None (use a token

keystoneclient/auth/identity/generic/base.py

@@ -81,7 +81,8 @@ class BaseGenericPlugin(base.BaseIdentityPlugin):
         params then it should return it. If not return None and then another
         call will be made with other available URLs.
 
-        :param Session session: A session object.
+        :param session: A session object.
+        :type session: keystoneclient.session.Session
         :param tuple version: A tuple of the API version at the URL.
         :param string url: The base URL for this version.
         :param string raw_status: The status that was in the discovery field.

keystoneclient/auth/identity/v3.py

@@ -176,7 +176,8 @@ class AuthMethod(object):
     def get_auth_data(self, session, auth, headers, **kwargs):
         """Return the authentication section of an auth plugin.
 
-        :param Session session: The communication session.
+        :param session: The communication session.
+        :type session: keystoneclient.session.Session
         :param Auth auth: The auth plugin calling the method.
         :param dict headers: The headers that will be sent with the auth
                              request if a plugin needs to add to them.