diff --git a/keystoneauth1/fixture/__init__.py b/keystoneauth1/fixture/__init__.py index 9035c5ef..15d695b7 100644 --- a/keystoneauth1/fixture/__init__.py +++ b/keystoneauth1/fixture/__init__.py @@ -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 diff --git a/keystoneauth1/identity/access.py b/keystoneauth1/identity/access.py index 323df233..a4704c0a 100644 --- a/keystoneauth1/identity/access.py +++ b/keystoneauth1/identity/access.py @@ -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) """ diff --git a/keystoneauth1/identity/base.py b/keystoneauth1/identity/base.py index 6b255a02..622bd9fd 100644 --- a/keystoneauth1/identity/base.py +++ b/keystoneauth1/identity/base.py @@ -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. """ diff --git a/keystoneauth1/identity/generic/base.py b/keystoneauth1/identity/generic/base.py index 712f904c..260c7721 100644 --- a/keystoneauth1/identity/generic/base.py +++ b/keystoneauth1/identity/generic/base.py @@ -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. """ diff --git a/keystoneauth1/identity/v3/base.py b/keystoneauth1/identity/v3/base.py index 4a549dbe..73fef49d 100644 --- a/keystoneauth1/identity/v3/base.py +++ b/keystoneauth1/identity/v3/base.py @@ -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. diff --git a/keystoneauth1/identity/v3/federation.py b/keystoneauth1/identity/v3/federation.py index fc7c4f58..2412ba1c 100644 --- a/keystoneauth1/identity/v3/federation.py +++ b/keystoneauth1/identity/v3/federation.py @@ -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) diff --git a/keystoneauth1/identity/v3/oidc.py b/keystoneauth1/identity/v3/oidc.py index 8b640f59..349d6658 100644 --- a/keystoneauth1/identity/v3/oidc.py +++ b/keystoneauth1/identity/v3/oidc.py @@ -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 diff --git a/keystoneauth1/loading/base.py b/keystoneauth1/loading/base.py index 84ca232a..3ed1183c 100644 --- a/keystoneauth1/loading/base.py +++ b/keystoneauth1/loading/base.py @@ -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() diff --git a/keystoneauth1/loading/cli.py b/keystoneauth1/loading/cli.py index 60afb438..d64d346e 100644 --- a/keystoneauth1/loading/cli.py +++ b/keystoneauth1/loading/cli.py @@ -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 diff --git a/keystoneauth1/loading/conf.py b/keystoneauth1/loading/conf.py index b3a34d01..9141bd3d 100644 --- a/keystoneauth1/loading/conf.py +++ b/keystoneauth1/loading/conf.py @@ -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 diff --git a/keystoneauth1/session.py b/keystoneauth1/session.py index dc626884..fc1f71e2 100644 --- a/keystoneauth1/session.py +++ b/keystoneauth1/session.py @@ -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)