openstack/python-keystoneclient
Code Issues Proposed changes

Fix up types within API documentation

Browse Source 
Correct the type signature of some API documentation. Add inter-sphinx
mapping to documentation to provide links to external docs. Correct some
phrases and errors.

Change-Id: Id4a71a9901e5adc695afed656e3bc84e4e54e67a
This commit is contained in:
Jamie Lennox
2014-12-15 12:16:39 +10:00
parent b9f17e3bbb
commit a15dd80dd2
8 changed files with 49 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/source/conf.py
View File

@@ -42,6 +42,7 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
extensions = ['sphinx.ext.autodoc', extensions = ['sphinx.ext.autodoc',
'sphinx.ext.todo', 'sphinx.ext.todo',
'sphinx.ext.coverage', 'sphinx.ext.coverage',
'sphinx.ext.intersphinx',
'oslosphinx', 'oslosphinx',
# NOTE(blk-u): Uncomment the [pbr] section in setup.cfg and # NOTE(blk-u): Uncomment the [pbr] section in setup.cfg and
# remove this Sphinx extension when # remove this Sphinx extension when
@@ -232,3 +233,8 @@ latex_documents = [
# If false, no module index is generated. # If false, no module index is generated.
#latex_use_modindex = True #latex_use_modindex = True
intersphinx_mapping = {
'python': ('http://docs.python.org/', None),
'osloconfig': ('http://docs.openstack.org/developer/oslo.config/', None),
}

24
keystoneclient/auth/base.py
View File

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

2
keystoneclient/auth/cli.py
View File

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

8
keystoneclient/auth/conf.py
View File

@@ -60,7 +60,8 @@ def register_conf_options(conf, group):
taken. If section is not provided then the auth plugin options will be taken. If section is not provided then the auth plugin options will be
taken from the same group as provided in the parameters. 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. :param string group: The ini group to register options in.
""" """
conf.register_opt(_AUTH_SECTION_OPT, group=group) 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 The base options should have been registered with register_conf_options
before this function is called. 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. :param string group: The group name that options should be read from.
:returns: An authentication Plugin or None if a name is not provided :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 :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
created. created.

14
keystoneclient/auth/identity/base.py
View File

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

3
keystoneclient/auth/identity/generic/base.py
View File

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

3
keystoneclient/auth/identity/v3.py
View File

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

7
keystoneclient/client.py
View File

@@ -28,9 +28,10 @@ def Client(version=None, unstable=False, session=None, **kwargs):
at least the specified minor version. For example to at least the specified minor version. For example to
specify the 3.1 API use (3, 1). specify the 3.1 API use (3, 1).
:param bool unstable: Accept endpoints not marked as 'stable'. (optional) :param bool unstable: Accept endpoints not marked as 'stable'. (optional)
:param Session session: A session object to be used for communication. If :param session: A session object to be used for communication. If one is
one is not provided it will be constructed from the not provided it will be constructed from the provided
provided kwargs. (optional) kwargs. (optional)
:type session: keystoneclient.session.Session
:param kwargs: Additional arguments are passed through to the client :param kwargs: Additional arguments are passed through to the client
that is being created. that is being created.
:returns: New keystone client object :returns: New keystone client object