openstack
/
python-keystoneclient
Code Issues Proposed changes

Cleanup docs - raises class 

The argument to the :raises: directive is the class name. If the
class name is a valid reference it's rendered as a link to the
class. This change cleans up the :raises: directives to use the
reference correctly and use a valid class reference.

Change-Id: I84188b60de0ab4c6b5b2fb5a203c43bfde094707
This commit is contained in:
Brant Knudson 2014-10-12 19:41:38 -05:00
parent 8b267842a7
commit 14a6d80116
14 changed files with 73 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
keystoneclient/adapter.py
View File

@ -93,7 +93,8 @@ class Adapter(object):
on the session. (optional)
:type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
:raises AuthorizationFailure: if a new token fetch fails.
:raises keystoneclient.exceptions.AuthorizationFailure: if a new token
fetch fails.
:returns string: A valid token.
"""
@ -106,7 +107,8 @@ class Adapter(object):
the session. (optional)
:type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
:raises MissingAuthPlugin: if a plugin is not available.
:raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
available.
:returns string: An endpoint if available or None.
"""

3
keystoneclient/auth/base.py
View File

@ -33,7 +33,8 @@ def get_plugin_class(name):
:returns: An auth plugin class.
:raises exceptions.NoMatchingPlugin: if a plugin cannot be created.
:raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
created.
"""
try:
mgr = stevedore.DriverManager(namespace=PLUGIN_NAMESPACE,

6
keystoneclient/auth/cli.py
View File

@ -31,7 +31,8 @@ def register_argparse_arguments(parser, argv, default=None):
:returns: The plugin class that will be loaded or None if not provided.
:raises exceptions.NoMatchingPlugin: if a plugin cannot be created.
:raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
created.
"""
in_parser = argparse.ArgumentParser(add_help=False)
env_plugin = os.environ.get('OS_AUTH_PLUGIN', default)
@ -68,7 +69,8 @@ def load_from_argparse_arguments(namespace, **kwargs):
:returns: An auth plugin, or None if a name is not provided.
:raises exceptions.NoMatchingPlugin: if a plugin cannot be created.
:raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
created.
"""
if not namespace.os_auth_plugin:
return None

3
keystoneclient/auth/conf.py
View File

@ -90,7 +90,8 @@ def load_from_conf_options(conf, group, **kwargs):
:returns plugin: An authentication Plugin or None if a name is not provided
:raises exceptions.NoMatchingPlugin: if a plugin cannot be created.
:raises keystoneclient.exceptions.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

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

@ -73,8 +73,11 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
when invoked. If you are looking to just retrieve the current auth
data then you should use get_access.
:raises InvalidResponse: The response returned wasn't appropriate.
:raises HttpError: An error from an invalid HTTP response.
:raises keystoneclient.exceptions.InvalidResponse: The response
returned wasn't
appropriate.
:raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response.
:returns AccessInfo: Token access information.
"""
@ -84,7 +87,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
If a valid token is not present then a new one will be fetched.
:raises HttpError: An error from an invalid HTTP response.
:raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response.
:return string: A valid token.
"""
@ -118,7 +122,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
If a valid AccessInfo is present then it is returned otherwise a new
one will be fetched.
:raises HttpError: An error from an invalid HTTP response.
:raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response.
:returns AccessInfo: Valid AccessInfo
"""
@ -169,7 +174,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
:param tuple version: The minimum version number required for this
endpoint. (optional)
:raises HttpError: An error from an invalid HTTP response.
:raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response.
:return string or None: A valid endpoint URL or None if not available.
"""
@ -240,8 +246,10 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
(optional) Defaults to None (use a token
if a plugin is installed).
:raises: DiscoveryFailure if for some reason the lookup fails.
:raises: HttpError An error from an invalid HTTP response.
:raises keystoneclient.exceptions.DiscoveryFailure: if for some reason
the lookup fails.
:raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response.
:returns: A discovery object with the results of looking up that URL.
"""

6
keystoneclient/client.py
View File

@ -36,8 +36,10 @@ def Client(version=None, unstable=False, session=None, **kwargs):
:returns: New keystone client object
(keystoneclient.v2_0.Client or keystoneclient.v3.Client).
:raises: DiscoveryFailure if the server's response is invalid
:raises: VersionNotAvailable if a suitable client cannot be found.
:raises keystoneclient.exceptions.DiscoveryFailure: if the server's
response is invalid
:raises keystoneclient.exceptions.VersionNotAvailable: if a suitable client
cannot be found.
"""
if not session:
session = client_session.Session.construct(kwargs)

6
keystoneclient/common/cms.py
View File

@ -132,8 +132,10 @@ def cms_verify(formatted, signing_cert_file_name, ca_file_name,
inform=PKI_ASN1_FORM):
"""Verifies the signature of the contents IAW CMS syntax.
:raises: subprocess.CalledProcessError
:raises: CertificateConfigError if certificate is not configured properly.
:raises subprocess.CalledProcessError:
:raises keystoneclient.exceptions.CertificateConfigError: if certificate
is not configured
properly.
"""
_ensure_subprocess()
if isinstance(formatted, six.string_types):

17
keystoneclient/contrib/auth/v3/saml2.py
View File

@ -519,7 +519,7 @@ class ADFSUnscopedToken(_BaseSAMLPlugin):
:param session
:returns: True if cookie jar is nonempty, False otherwise
:raises: AttributeError in case cookies are not find anywhere
:raises AttributeError: in case cookies are not find anywhere
"""
try:
@ -704,11 +704,12 @@ class ADFSUnscopedToken(_BaseSAMLPlugin):
:param session : a session object to send out HTTP requests.
:type session: keystoneclient.session.Session
:raises: exceptions.AuthorizationFailure when HTTP response from the
ADFS server is not a valid XML ADFS security token.
:raises: exceptions.InternalServerError: If response status code is
HTTP 500 and the response XML cannot be recognized.
:raises keystoneclient.exceptions.AuthorizationFailure: when HTTP
response from the ADFS server is not a valid XML ADFS security
token.
:raises keystoneclient.exceptions.InternalServerError: If response
status code is HTTP 500 and the response XML cannot be
recognized.
"""
def _get_failure(e):
@ -797,8 +798,8 @@ class ADFSUnscopedToken(_BaseSAMLPlugin):
:param session : a session object to send out HTTP requests.
:type session: keystoneclient.session.Session
:raises: exceptions.AuthorizationFailure: in case session object
has empty cookie jar.
:raises keystoneclient.exceptions.AuthorizationFailure: in case session
object has empty cookie jar.
"""
if self._cookies(session) is False:

6
keystoneclient/discover.py
View File

@ -261,8 +261,10 @@ class Discover(_discover.Discover):
:returns: An instantiated identity client object.
:raises: DiscoveryFailure if the server response is invalid
:raises: VersionNotAvailable if a suitable client cannot be found.
:raises keystoneclient.exceptions.DiscoveryFailure: if the server
response is invalid
:raises keystoneclient.exceptions.VersionNotAvailable: if a suitable
client cannot be found.
"""
version_data = self._calculate_version(version, unstable)
return self._create_client(version_data, **kwargs)

9
keystoneclient/exceptions.py
View File

@ -14,6 +14,15 @@
# under the License.
"""
Exception definitions.
.. py:exception:: AuthorizationFailure
.. py:exception:: ClientException
.. py:exception:: HttpError
.. py:exception:: Unauthorized
"""
#flake8: noqa

7
keystoneclient/httpclient.py
View File

@ -364,9 +364,10 @@ class HTTPClient(baseclient.Client, base.BaseAuthPlugin):
self.management_url from the details provided in the token.
:returns: ``True`` if authentication was successful.
:raises: AuthorizationFailure if unable to authenticate or validate
the existing authorization token
:raises: ValueError if insufficient parameters are used.
:raises keystoneclient.exceptions.AuthorizationFailure: if unable to
authenticate or validate the existing authorization token
:raises keystoneclient.exceptions.ValueError: if insufficient
parameters are used.
If keyring is used, token is retrieved from keyring instead.
Authentication will only be necessary if any of the following

10
keystoneclient/session.py
View File

@ -259,8 +259,8 @@ class Session(object):
'allow_redirects' is ignored as redirects are handled
by the session.
:raises exceptions.ClientException: For connection failure, or to
indicate an error response code.
:raises keystoneclient.exceptions.ClientException: For connection
failure, or to indicate an error response code.
:returns: The response to the request.
"""
@ -500,7 +500,8 @@ class Session(object):
on the session. (optional)
:type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
:raises AuthorizationFailure: if a new token fetch fails.
:raises keystoneclient.exceptions.AuthorizationFailure: if a new token
fetch fails.
:returns string: A valid token.
"""
@ -523,7 +524,8 @@ class Session(object):
the session. (optional)
:type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
:raises MissingAuthPlugin: if a plugin is not available.
:raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
available.
:returns string: An endpoint if available or None.
"""

4
keystoneclient/v2_0/client.py
View File

@ -158,8 +158,8 @@ class Client(httpclient.HTTPClient):
password.
:returns: access.AccessInfo if authentication was successful.
:raises: AuthorizationFailure if unable to authenticate or validate
the existing authorization token
:raises keystoneclient.exceptions.AuthorizationFailure: if unable to
authenticate or validate the existing authorization token
"""
try:
if auth_url is None:

7
keystoneclient/v3/client.py
View File

@ -227,9 +227,10 @@ EndpointPolicyManager`
be used in the request.
:returns: access.AccessInfo if authentication was successful.
:raises: AuthorizationFailure if unable to authenticate or validate
the existing authorization token
:raises: Unauthorized if authentication fails due to invalid token
:raises keystoneclient.exceptions.AuthorizationFailure: if unable to
authenticate or validate the existing authorization token.
:raises keystoneclient.exceptions.Unauthorized: if authentication fails
due to invalid token.
"""
try: