openstack
/
python-keystoneclient
Code Issues Proposed changes

Merge "Docstring cleanup for return type"

This commit is contained in:
Jenkins 2014-12-02 01:46:24 +00:00 committed by Gerrit Code Review
parent 4a49d970b0 3f1ba9f007
commit 41afe3c963
12 changed files with 69 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
keystoneclient/_discover.py
View File

@ -115,7 +115,8 @@ def version_match(required, candidate):
:param tuple required: the version that must be met.
:param tuple candidate: the version to test against required.
:returns bool: True if candidate is suitable False otherwise.
:returns: True if candidate is suitable False otherwise.
:rtype: bool
"""
# major versions must be the same (e.g. even though v2 is a lower
# version than v3 we can't use it if v2 was requested)
@ -152,8 +153,9 @@ class Discover(object):
:param bool allow_deprecated: Allow deprecated version endpoints.
:param bool allow_unknown: Allow endpoints with an unrecognised status.
:returns list: The endpoints returned from the server that match the
criteria.
:returns: The endpoints returned from the server that match the
criteria.
:rtype: list
"""
versions = []
for v in self._data:
@ -184,13 +186,14 @@ class Discover(object):
Return version data in a structured way.
:returns list(dict): A list of version data dictionaries sorted by
version number. Each data element in the returned
list is a dictionary consisting of at least:
:returns: A list of version data dictionaries sorted by version number.
Each data element in the returned list is a dictionary
consisting of at least:
:version tuple: The normalized version of the endpoint.
:url str: The url for the endpoint.
:raw_status str: The status as provided by the server
:rtype: list(dict)
"""
data = self.raw_version_data(**kwargs)
versions = []
@ -241,9 +244,10 @@ class Discover(object):
same major release as there should be no compatibility issues with
using a version newer than the one asked for.
:returns dict: the endpoint data for a URL that matches the required
version (the format is described in version_data)
or None if no match.
:returns: the endpoint data for a URL that matches the required version
(the format is described in version_data) or None if no
match.
:rtype: dict
"""
version = normalize_version_number(version)
version_data = self.version_data(**kwargs)
@ -261,7 +265,8 @@ class Discover(object):
same major release as there should be no compatibility issues with
using a version newer than the one asked for.
:returns str: The url for the specified version or None if no match.
:returns: The url for the specified version or None if no match.
:rtype: str
"""
data = self.data_for(version, **kwargs)
return data['url'] if data else None

6
keystoneclient/access.py
View File

@ -85,7 +85,8 @@ class AccessInfo(dict):
def will_expire_soon(self, stale_duration=None):
"""Determines if expiration is about to occur.
:returns: boolean : true if expiration is within the given duration
:returns: true if expiration is within the given duration
:rtype: boolean
"""
stale_duration = (STALE_TOKEN_DURATION if stale_duration is None
@ -102,7 +103,8 @@ class AccessInfo(dict):
"""Determines if processing v2 or v3 token given a successful
auth body or a user-provided dict.
:returns: boolean : true if auth body matches implementing class
:returns: true if auth body matches implementing class
:rtype: boolean
"""
raise NotImplementedError()

6
keystoneclient/adapter.py
View File

@ -97,7 +97,8 @@ class Adapter(object):
:raises keystoneclient.exceptions.AuthorizationFailure: if a new token
fetch fails.
:returns string: A valid token.
:returns: A valid token.
:rtype: string
"""
return self.session.get_token(auth or self.auth)
@ -111,7 +112,8 @@ class Adapter(object):
:raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
available.
:returns string: An endpoint if available or None.
:returns: An endpoint if available or None.
:rtype: string
"""
self._set_endpoint_filter_kwargs(kwargs)
return self.session.get_endpoint(auth or self.auth, **kwargs)

23
keystoneclient/auth/base.py
View File

@ -67,7 +67,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.
:return string: A token to use.
:return: A token to use.
:rtype: string
"""
def get_endpoint(self, session, **kwargs):
@ -86,8 +87,9 @@ class BaseAuthPlugin(object):
:param Session session: The session object that the auth_plugin
belongs to.
:returns string: The base URL that will be used to talk to the
required service or None if not available.
:returns: The base URL that will be used to talk to the required
service or None if not available.
:rtype: string
"""
def invalidate(self):
@ -99,9 +101,10 @@ class BaseAuthPlugin(object):
returned to indicate that the token may have been revoked or is
otherwise now invalid.
:returns bool: True if there was something that the plugin did to
invalidate. This means that it makes sense to try again.
If nothing happens returns False to indicate give up.
:returns: True if there was something that the plugin did to
invalidate. This means that it makes sense to try again. If
nothing happens returns False to indicate give up.
:rtype: bool
"""
return False
@ -111,8 +114,9 @@ class BaseAuthPlugin(object):
This list may be used to generate CLI or config arguments.
:returns list: A list of Param objects describing available plugin
parameters.
:returns: A list of Param objects describing available plugin
parameters.
:rtype: list
"""
return []
@ -201,7 +205,8 @@ class BaseAuthPlugin(object):
:param conf: An oslo.config conf object.
:param string group: The group name that options should be read from.
:returns plugin: An authentication Plugin.
:returns: An authentication Plugin.
:rtype: plugin:
"""
plugin_opts = cls.get_options()

3
keystoneclient/auth/conf.py
View File

@ -88,7 +88,8 @@ def load_from_conf_options(conf, group, **kwargs):
:param conf: An oslo.config conf object.
:param string group: The group name that options should be read from.
:returns plugin: 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
:raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
created.

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

@ -80,7 +80,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
:raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response.
:returns AccessInfo: Token access information.
:returns: Token access information.
:rtype: :py:class:`keystoneclient.access.AccessInfo`
"""
def get_token(self, session, **kwargs):
@ -91,7 +92,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
:raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response.
:return string: A valid token.
:return: A valid token.
:rtype: string
"""
return self.get_access(session).auth_token
@ -126,7 +128,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
:raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response.
:returns AccessInfo: Valid AccessInfo
:returns: Valid AccessInfo
:rtype: :py:class:`keystoneclient.access.AccessInfo`
"""
if self._needs_reauthenticate():
self.auth_ref = self.get_auth_ref(session)
@ -142,9 +145,10 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
returned to indicate that the token may have been revoked or is
otherwise now invalid.
:returns bool: True if there was something that the plugin did to
invalidate. This means that it makes sense to try again.
If nothing happens returns False to indicate give up.
:returns: True if there was something that the plugin did to
invalidate. This means that it makes sense to try again. If
nothing happens returns False to indicate give up.
:rtype: bool
"""
if self.auth_ref:
self.auth_ref = None
@ -178,7 +182,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
:raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response.
:return string or None: A valid endpoint URL or None if not available.
:return: A valid endpoint URL or None if not available.
:rtype: string or None
"""
# NOTE(jamielennox): if you specifically ask for requests to be sent to
# the auth url then we can ignore the rest of the checks. Typically if

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

@ -91,7 +91,8 @@ class Auth(base.BaseIdentityPlugin):
:param dict headers: The headers that will be sent with the auth
request if a plugin needs to add to them.
:return dict: A dict of authentication data for the auth type.
:return: A dict of authentication data for the auth type.
:rtype: dict
"""

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

@ -182,8 +182,9 @@ class AuthMethod(object):
: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.
:return tuple(string, dict): The identifier of this plugin and a dict
of authentication data for the auth type.
:return: The identifier of this plugin and a dict of authentication
data for the auth type.
:rtype: tuple(string, dict)
"""

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

@ -427,8 +427,9 @@ class Saml2UnscopedToken(_BaseSAMLPlugin):
:param session : a session object to send out HTTP requests.
:type session: keystoneclient.session.Session
:return access.AccessInfoV3: an object with scoped token's id and
unscoped token json included.
:return: an object with scoped token's id and unscoped token json
included.
:rtype: :py:class:`keystoneclient.access.AccessInfoV3`
"""
token, token_json = self._get_unscoped_token(session)
@ -840,7 +841,7 @@ class ADFSUnscopedToken(_BaseSAMLPlugin):
:param session : a session object to send out HTTP requests.
:type session: keystoneclient.session.Session
:returns (Unscoped federated token, token JSON body)
:returns: (Unscoped federated token, token JSON body)
"""
self._prepare_adfs_request()

4
keystoneclient/contrib/revoke/model.py
View File

@ -110,9 +110,9 @@ class RevokeTree(object):
fields of the revocation event. The leaf node will always be set to
the latest 'issued_before' for events that are otherwise identical.
:param: Event to add to the tree
:param: Event to add to the tree
:returns: the event that was passed in.
:returns: the event that was passed in.
"""
revoke_map = self.revoke_map

5
keystoneclient/discover.py
View File

@ -164,8 +164,9 @@ class Discover(_discover.Discover):
:param bool allow_deprecated: Allow deprecated version endpoints.
:param bool allow_unknown: Allow endpoints with an unrecognised status.
:returns list: The endpoints returned from the server that match the
criteria.
:returns: The endpoints returned from the server that match the
criteria.
:rtype: list
Example::

6
keystoneclient/session.py
View File

@ -504,7 +504,8 @@ class Session(object):
:raises keystoneclient.exceptions.AuthorizationFailure: if a new token
fetch fails.
:returns string: A valid token.
:returns: A valid token.
:rtype: string
"""
if not auth:
auth = self.auth
@ -528,7 +529,8 @@ class Session(object):
:raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
available.
:returns string: An endpoint if available or None.
:returns: An endpoint if available or None.
:rtype: string
"""
if not auth:
auth = self.auth