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',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.intersphinx',
'oslosphinx',
# NOTE(blk-u): Uncomment the [pbr] section in setup.cfg and
# remove this Sphinx extension when
@@ -232,3 +233,8 @@ latex_documents = [
# If false, no module index is generated.
#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.
: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
belongs to.
:param session: The session object that the auth_plugin 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.
@@ -137,8 +140,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 argparse.ArgumentParser: the parser to attach argparse options.
:param parser: the parser to attach argparse options.
:type parser: argparse.ArgumentParser
"""
# 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.
:param AuthPlugin plugin: an auth plugin class.
:param Namespace namespace: The result from CLI parsing.
:param 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)
@@ -190,7 +194,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()
@@ -202,11 +207,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()

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.
: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.

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 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.

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
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.
@@ -247,7 +258,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

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
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.

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

@@ -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.

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
specify the 3.1 API use (3, 1).
:param bool unstable: Accept endpoints not marked as 'stable'. (optional)
:param Session session: A session object to be used for communication. If
one is not provided it will be constructed from the
provided kwargs. (optional)
:param session: A session object to be used for communication. If one is
not provided it will be constructed from the provided
kwargs. (optional)
:type session: keystoneclient.session.Session
:param kwargs: Additional arguments are passed through to the client
that is being created.
:returns: New keystone client object