openstack/keystoneauth
Code Issues Proposed changes

Cleanup docstrings

Browse Source 
Several of these docstrings were referring to classes that didn't
exist. For example, they referenced keystonauth which doesn't
exist and is supposed to be keystoneauth1.

Change-Id: I070d32937c11b111f1821c466e8dfe55caadd748
This commit is contained in:
Brant Knudson 2016-02-19 13:52:16 -06:00
parent e250f99b5b
commit 417f2238ae
11 changed files with 125 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
keystoneauth1/fixture/__init__.py
View File

@ -14,11 +14,10 @@
The generators in this directory produce keystone compliant structures for use
in testing.
They should be considered part of the public API because they may be relied
upon to generate test tokens for other clients. However they should never be
imported into the main client (keystonauth or other). Because of this there
may be dependencies from this module on libraries that are only available in
testing.
They are part of the public API because they may be relied upon to generate
test tokens for other clients. However they should never be imported into the
main client (keystoneauth or other). Because of this there may be dependencies
from this module on libraries that are only available in testing.
"""
from keystoneauth1.fixture.discovery import * # noqa

2
keystoneauth1/identity/access.py
View File

@ -27,7 +27,7 @@ class AccessInfoPlugin(base.BaseIdentityPlugin):
authorizing information.
:param auth_ref: the existing AccessInfo object.
:type auth_ref: keystonauth.access.AccessInfo
:type auth_ref: keystoneauth1.access.AccessInfo
:param auth_url: the url where this AccessInfo was retrieved from. Required
if using the AUTH_INTERFACE with get_endpoint. (optional)
"""

43
keystoneauth1/identity/base.py
View File

@ -61,16 +61,15 @@ class BaseIdentityPlugin(plugin.BaseAuthPlugin):
data then you should use get_access.
:param session: A session object that can be used for communication.
:type session: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:raises keystonauth.exceptions.InvalidResponse: The response
returned wasn't
appropriate.
:raises keystonauth.exceptions.HttpError: An error from an invalid
HTTP response.
:raises keystoneauth1.exceptions.response.InvalidResponse:
The response returned wasn't appropriate.
:raises keystoneauth1.exceptions.http.HttpError:
An error from an invalid HTTP response.
:returns: Token access information.
:rtype: :py:class:`keystonauth.access.AccessInfo`
:rtype: :class:`keystoneauth1.access.AccessInfo`
"""
def get_token(self, session, **kwargs):
@ -79,10 +78,10 @@ class BaseIdentityPlugin(plugin.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: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:raises keystonauth.exceptions.HttpError: An error from an invalid
HTTP response.
:raises keystoneauth1.exceptions.http.HttpError: An error from an
invalid HTTP response.
:return: A valid token.
:rtype: string
@ -118,13 +117,13 @@ class BaseIdentityPlugin(plugin.BaseAuthPlugin):
one will be fetched.
:param session: A session object that can be used for communication.
:type session: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:raises keystonauth.exceptions.HttpError: An error from an invalid
HTTP response.
:raises keystoneauth1.exceptions.http.HttpError: An error from an
invalid HTTP response.
:returns: Valid AccessInfo
:rtype: :py:class:`keystonauth.access.AccessInfo`
:rtype: :class:`keystoneauth1.access.AccessInfo`
"""
# Hey Kids! Thread safety is important particularly in the case where
# a service is creating an admin style plugin that will then proceed
@ -166,7 +165,7 @@ class BaseIdentityPlugin(plugin.BaseAuthPlugin):
the session and kwargs.
:param session: A session object that can be used for communication.
:type session: keystonauth.session.Session
:type session: keystoneauth1.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.
@ -182,8 +181,8 @@ class BaseIdentityPlugin(plugin.BaseAuthPlugin):
:param tuple version: The minimum version number required for this
endpoint. (optional)
:raises keystonauth.exceptions.HttpError: An error from an invalid
HTTP response.
:raises keystoneauth1.exceptions.http.HttpError: An error from an
invalid HTTP response.
:return: A valid endpoint URL or None if not available.
:rtype: string or None
@ -274,16 +273,16 @@ class BaseIdentityPlugin(plugin.BaseAuthPlugin):
be needed by users.
:param session: A session object to discover with.
:type session: keystonauth.session.Session
:type session: keystoneauth1.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
if a plugin is installed).
:raises keystonauth.exceptions.DiscoveryFailure: if for some reason
the lookup fails.
:raises keystonauth.exceptions.HttpError: An error from an invalid
HTTP response.
:raises keystoneauth1.exceptions.discovery.DiscoveryFailure:
if for some reason the lookup fails.
:raises keystoneauth1.exceptions.http.HttpError: An error from an
invalid HTTP response.
:returns: A discovery object with the results of looking up that URL.
"""

8
keystoneauth1/identity/generic/base.py
View File

@ -60,7 +60,7 @@ class BaseGenericPlugin(base.BaseIdentityPlugin):
@abc.abstractmethod
def create_plugin(self, session, version, url, raw_status=None):
"""Create a plugin from the given paramters.
"""Create a plugin from the given parameters.
This function will be called multiple times with the version and url
of a potential endpoint. If a plugin can be constructed that fits the
@ -68,10 +68,10 @@ class BaseGenericPlugin(base.BaseIdentityPlugin):
call will be made with other available URLs.
:param session: A session object.
:type session: keystonauth.session.Session
:type session: keystoneauth1.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.
:param str url: The base URL for this version.
:param str raw_status: The status that was in the discovery field.
:returns: A plugin that can match the parameters or None if nothing.
"""

2
keystoneauth1/identity/v3/base.py
View File

@ -235,7 +235,7 @@ class AuthMethod(object):
"""Return the authentication section of an auth plugin.
:param session: The communication session.
:type session: keystonauth.session.Session
:type session: keystoneauth1.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.

4
keystoneauth1/identity/v3/federation.py
View File

@ -56,10 +56,10 @@ class _Rescoped(base.BaseAuth):
is present then the token is rescoped to that target.
:param session: a session object to send out HTTP requests.
:type session: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:returns: a token data representation
:rtype: :py:class:`keystonauth.access.AccessInfo`
:rtype: :py:class:`keystoneauth1.access.AccessInfo`
"""
auth_ref = self.get_unscoped_auth_ref(session)

4
keystoneauth1/identity/v3/oidc.py
View File

@ -79,7 +79,7 @@ class _OidcBase(federation.FederationBaseAuth):
"""Exchange a variety of user supplied values for an access token.
:param session: a session object to send out HTTP requests.
:type session: keystoneauth.session.Session
:type session: keystoneauth1.session.Session
:param client_auth: a tuple representing client id and secret
:type client_auth: tuple
@ -112,7 +112,7 @@ class _OidcBase(federation.FederationBaseAuth):
succeed, a Keystone token will be presented to the user.
:param session: a session object to send out HTTP requests.
:type session: keystoneauth.session.Session
:type session: keystoneauth1.session.Session
:param headers: an Authorization header containing the access token.
:type headers_: dict

8
keystoneauth1/loading/base.py
View File

@ -63,8 +63,8 @@ def get_plugin_loader(name):
:returns: An auth plugin class.
:rtype: :py:class:`keystoneauth1.loading.BaseLoader`
:raises keystonauth.exceptions.NoMatchingPlugin: if a plugin cannot be
created.
:raises keystoneauth1.exceptions.auth_plugins.NoMatchingPlugin:
if a plugin cannot be created.
"""
try:
mgr = stevedore.DriverManager(namespace=PLUGIN_NAMESPACE,
@ -84,8 +84,8 @@ def get_plugin_options(name):
:returns: A list of :py:class:`keystoneauth1.loading.Opt` options.
:raises keystonauth.exceptions.NoMatchingPlugin: if a plugin cannot be
created.
:raises keystoneauth1.exceptions.auth_plugins.NoMatchingPlugin:
if a plugin cannot be created.
"""
return get_plugin_loader(name).get_options()

15
keystoneauth1/loading/cli.py
View File

@ -38,16 +38,17 @@ def register_argparse_arguments(parser, argv, default=None):
The function inspects the provided arguments so that it can also register
the options required for that specific plugin if available.
:param argparse.ArgumentParser: the parser to attach argparse options to.
:param parser: the parser to attach argparse options to.
:type parser: argparse.ArgumentParser
:param list argv: the arguments provided to the appliation.
:param str/class default: a default plugin name or a plugin object to use
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:`keystonauth.auth.BaseAuthPlugin`
:rtype: :class:`keystoneauth1.plugin.BaseAuthPlugin`
:raises keystonauth.exceptions.NoMatchingPlugin: if a plugin cannot be
created.
:raises keystoneauth1.exceptions.auth_plugins.NoMatchingPlugin:
if a plugin cannot be created.
"""
in_parser = argparse.ArgumentParser(add_help=False)
env_plugin = os.environ.get('OS_AUTH_TYPE',
@ -85,10 +86,10 @@ 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:`keystonauth.auth.BaseAuthPlugin`
:rtype: :class:`keystoneauth1.plugin.BaseAuthPlugin`
:raises keystonauth.exceptions.NoMatchingPlugin: if a plugin cannot be
created.
:raises keystoneauth1.exceptions.auth_plugins.NoMatchingPlugin:
if a plugin cannot be created.
"""
if not namespace.os_auth_type:
return None

8
keystoneauth1/loading/conf.py
View File

@ -105,13 +105,13 @@ def load_from_conf_options(conf, group, **kwargs):
:param conf: A conf object.
:type conf: oslo_config.cfg.ConfigOpts
:param string group: The group name that options should be read from.
:param str group: The group name that options should be read from.
:returns: An authentication Plugin or None if a name is not provided
:rtype: :py:class:`keystonauth.auth.BaseAuthPlugin`
:rtype: :class:`keystoneauth1.plugin.BaseAuthPlugin`
:raises keystonauth.exceptions.NoMatchingPlugin: if a plugin cannot be
created.
:raises keystoneauth1.exceptions.auth_plugins.NoMatchingPlugin:
if a plugin cannot be created.
"""
# NOTE(jamielennox): plugins are allowed to specify a 'section' which is
# the group that auth options should be taken from. If not present they

142
keystoneauth1/session.py
View File

@ -97,16 +97,16 @@ class Session(object):
"""Maintains client communication state and common functionality.
As much as possible the parameters to this class reflect and are passed
directly to the requests library.
directly to the :mod:`requests` library.
:param auth: An authentication plugin to authenticate the session with.
(optional, defaults to None)
:type auth: :py:class:`keystonauth.auth.base.BaseAuthPlugin`
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:param requests.Session session: A requests session object that can be used
for issuing requests. (optional)
:param string original_ip: The original IP of the requesting user which
will be sent to identity service in a
'Forwarded' header. (optional)
:param str original_ip: The original IP of the requesting user which will
be sent to identity service in a 'Forwarded'
header. (optional)
:param verify: The verification arguments to pass to requests. These are of
the same form as requests expects, so True or False to
verify (or not) against system certificates or a path to a
@ -121,13 +121,13 @@ class Session(object):
numerical value indicating some amount (or fraction)
of seconds or 0 for no timeout. (optional, defaults
to 0)
:param string user_agent: A User-Agent header string to use for the
request. If not provided, a default of
:attr:`~keystoneauth1.session.DEFAULT_USER_AGENT`
is used, which contains the keystoneauth1 version
as well as those of the requests library and
which Python is being used. When a non-None value
is passed, it will be prepended to the default.
:param str user_agent: A User-Agent header string to use for the request.
If not provided, a default of
:attr:`~keystoneauth1.session.DEFAULT_USER_AGENT` is
used, which contains the keystoneauth1 version as
well as those of the requests library and which
Python is being used. When a non-None value is
passed, it will be prepended to the default.
:param int/bool redirect: Controls the maximum number of redirections that
can be followed by a request. Either an integer
for a specific count or True/False for
@ -291,19 +291,18 @@ class Session(object):
Arguments that are not handled are passed through to the requests
library.
:param string url: Path or fully qualified URL of HTTP request. If only
a path is provided then endpoint_filter must also be
provided such that the base URL can be determined.
If a fully qualified URL is provided then
endpoint_filter will be ignored.
:param string method: The http method to use. (e.g. 'GET', 'POST')
:param string original_ip: Mark this request as forwarded for this ip.
(optional)
:param str url: Path or fully qualified URL of HTTP request. If only a
path is provided then endpoint_filter must also be
provided such that the base URL can be determined. If a
fully qualified URL is provided then endpoint_filter
will be ignored.
:param str method: The http method to use. (e.g. 'GET', 'POST')
:param str original_ip: Mark this request as forwarded for this ip.
(optional)
:param dict headers: Headers to be included in the request. (optional)
:param json: Some data to be represented as JSON. (optional)
:param string user_agent: A user_agent to use for the request. If
present will override one present in headers.
(optional)
:param str user_agent: A user_agent to use for the request. If present
will override one present in headers. (optional)
:param int/bool redirect: the maximum number of redirections that
can be followed by a request. Either an
integer for a specific count or True/False
@ -325,14 +324,14 @@ class Session(object):
ignored if a fully qualified URL is
provided but take priority over an
endpoint_filter. This string may contain
the values %(project_id)s and %(user_id)s
to have those values replaced by the
project_id/user_id of the current
authentication. (optional)
the values ``%(project_id)s`` and
``%(user_id)s`` to have those values
replaced by the project_id/user_id of the
current authentication. (optional)
:param auth: The auth plugin to use when authenticating this request.
This will override the plugin that is attached to the
session (if any). (optional)
:type auth: :py:class:`keystonauth.auth.base.BaseAuthPlugin`
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:param requests_auth: A requests library auth plugin that cannot be
passed via kwarg because the `auth` kwarg
collides with our own auth plugins. (optional)
@ -346,16 +345,19 @@ class Session(object):
:param bool log: If True then log the request and response data to the
debug log. (optional, default True)
:param logger: The logger object to use to log request and responses.
If not provided the keystonauth.session default
If not provided the keystoneauth1.session default
logger will be used.
:type logger: logging.Logger
:param kwargs: any other parameter that can be passed to
requests.Session.request (such as `headers`). Except:
'data' will be overwritten by the data in 'json' param.
'allow_redirects' is ignored as redirects are handled
by the session.
:meth:`requests.Session.request` (such as `headers`).
Except:
:raises keystonauth.exceptions.ClientException: For connection
- `data` will be overwritten by the data in the `json`
param.
- `allow_redirects` is ignored as redirects are handled
by the session.
:raises keystoneauth1.exceptions.base.ClientException: For connection
failure, or to indicate an error response code.
:returns: The response to the request.
@ -610,15 +612,15 @@ class Session(object):
:param auth: The auth plugin to use for token. Overrides the plugin
on the session. (optional)
:type auth: :py:class:`keystonauth.auth.base.BaseAuthPlugin`
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:raises keystonauth.exceptions.AuthorizationFailure: if a new token
fetch fails.
:raises keystonauth.exceptions.MissingAuthPlugin: if a plugin is not
available.
:raises keystoneauth1.exceptions.auth.AuthorizationFailure:
if a new token fetch fails.
:raises keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin:
if a plugin is not available.
:returns: Authentication headers or None for failure.
:rtype: dict
:rtype: :class:`dict`
"""
auth = self._auth_required(auth, 'fetch a token')
return auth.get_headers(self, **kwargs)
@ -628,16 +630,17 @@ class Session(object):
:param auth: The auth plugin to use for token. Overrides the plugin
on the session. (optional)
:type auth: :py:class:`keystonauth.auth.base.BaseAuthPlugin`
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:raises keystonauth.exceptions.AuthorizationFailure: if a new token
fetch fails.
:raises keystonauth.exceptions.MissingAuthPlugin: if a plugin is not
available.
:raises keystoneauth1.exceptions.auth.AuthorizationFailure:
if a new token fetch fails.
:raises keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin:
if a plugin is not available.
*DEPRECATED*: This assumes that the only header that is used to
authenticate a message is 'X-Auth-Token'. This may not be
correct. Use get_auth_headers instead.
.. warning::
**DEPRECATED**: This assumes that the only header that is used to
authenticate a message is ``X-Auth-Token``. This may not be
correct. Use :meth:`get_auth_headers` instead.
:returns: A valid token.
:rtype: string
@ -649,10 +652,10 @@ class Session(object):
:param auth: The auth plugin to use for token. Overrides the plugin on
the session. (optional)
:type auth: :py:class:`keystonauth.auth.base.BaseAuthPlugin`
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:raises keystonauth.exceptions.MissingAuthPlugin: if a plugin is not
available.
:raises keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin:
if a plugin is not available.
:returns: An endpoint if available or None.
:rtype: string
@ -680,17 +683,18 @@ class Session(object):
:param auth: The auth plugin to use for tokens. Overrides the plugin
on the session. (optional)
:type auth: keystoneclient.auth.base.BaseAuthPlugin
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:raises keystoneclient.exceptions.AuthorizationFailure: if a new token
fetch fails.
:raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
available.
:raises keystoneclient.exceptions.UnsupportedParameters: if the plugin
returns a parameter that is not supported by this session.
:raises keystoneauth1.exceptions.auth.AuthorizationFailure:
if a new token fetch fails.
:raises keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin:
if a plugin is not available.
:raises keystoneauth1.exceptions.auth_plugins.UnsupportedParameters:
if the plugin returns a parameter that is not supported by this
session.
:returns: Authentication headers or None for failure.
:rtype: dict
:rtype: :class:`dict`
"""
msg = 'An auth plugin is required to fetch connection params'
auth = self._auth_required(auth, msg)
@ -718,7 +722,7 @@ class Session(object):
:param auth: The auth plugin to invalidate. Overrides the plugin on the
session. (optional)
:type auth: :py:class:`keystonauth.auth.base.BaseAuthPlugin`
:type auth: keystoneauth1.plugin.BaseAuthPlugin
"""
auth = self._auth_required(auth, 'validate')
@ -729,14 +733,15 @@ class Session(object):
:param auth: The auth plugin to use for token. Overrides the plugin
on the session. (optional)
:type auth: keystonauth.auth.base.BaseAuthPlugin
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:raises keystonauth.exceptions.AuthorizationFailure:
:raises keystoneauth1.exceptions.auth.AuthorizationFailure:
if a new token fetch fails.
:raises keystonauth.exceptions.MissingAuthPlugin:
:raises keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin:
if a plugin is not available.
:returns string: Current user_id or None if not supported by plugin.
:returns: Current user_id or None if not supported by plugin.
:rtype: :class:`str`
"""
auth = self._auth_required(auth, 'get user_id')
return auth.get_user_id(self)
@ -746,14 +751,15 @@ class Session(object):
:param auth: The auth plugin to use for token. Overrides the plugin
on the session. (optional)
:type auth: keystonauth.auth.base.BaseAuthPlugin
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:raises keystonauth.exceptions.AuthorizationFailure:
:raises keystoneauth1.exceptions.auth.AuthorizationFailure:
if a new token fetch fails.
:raises keystonauth.exceptions.MissingAuthPlugin:
:raises keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin:
if a plugin is not available.
:returns string: Current project_id or None if not supported by plugin.
:returns: Current project_id or None if not supported by plugin.
:rtype: :class:`str`
"""
auth = self._auth_required(auth, 'get project_id')
return auth.get_project_id(self)