openstack/python-keystoneclient
Code Issues Proposed changes

Merge "Docstring cleanup for return type"

Browse Source
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
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 required: the version that must be met.
:param tuple candidate: the version to test against required. :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 # 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) # 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_deprecated: Allow deprecated version endpoints.
:param bool allow_unknown: Allow endpoints with an unrecognised status. :param bool allow_unknown: Allow endpoints with an unrecognised status.
:returns list: The endpoints returned from the server that match the :returns: The endpoints returned from the server that match the
criteria. criteria.
:rtype: list
""" """
versions = [] versions = []
for v in self._data: for v in self._data:
@@ -184,13 +186,14 @@ class Discover(object):
Return version data in a structured way. Return version data in a structured way.
:returns list(dict): A list of version data dictionaries sorted by :returns: A list of version data dictionaries sorted by version number.
version number. Each data element in the returned Each data element in the returned list is a dictionary
list is a dictionary consisting of at least: consisting of at least:
:version tuple: The normalized version of the endpoint. :version tuple: The normalized version of the endpoint.
:url str: The url for the endpoint. :url str: The url for the endpoint.
:raw_status str: The status as provided by the server :raw_status str: The status as provided by the server
:rtype: list(dict)
""" """
data = self.raw_version_data(**kwargs) data = self.raw_version_data(**kwargs)
versions = [] versions = []
@@ -241,9 +244,10 @@ class Discover(object):
same major release as there should be no compatibility issues with same major release as there should be no compatibility issues with
using a version newer than the one asked for. using a version newer than the one asked for.
:returns dict: the endpoint data for a URL that matches the required :returns: the endpoint data for a URL that matches the required version
version (the format is described in version_data) (the format is described in version_data) or None if no
or None if no match. match.
:rtype: dict
""" """
version = normalize_version_number(version) version = normalize_version_number(version)
version_data = self.version_data(**kwargs) version_data = self.version_data(**kwargs)
@@ -261,7 +265,8 @@ class Discover(object):
same major release as there should be no compatibility issues with same major release as there should be no compatibility issues with
using a version newer than the one asked for. 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) data = self.data_for(version, **kwargs)
return data['url'] if data else None 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): def will_expire_soon(self, stale_duration=None):
"""Determines if expiration is about to occur. """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 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 """Determines if processing v2 or v3 token given a successful
auth body or a user-provided dict. 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() raise NotImplementedError()

6
keystoneclient/adapter.py
View File

@@ -97,7 +97,8 @@ class Adapter(object):
:raises keystoneclient.exceptions.AuthorizationFailure: if a new token :raises keystoneclient.exceptions.AuthorizationFailure: if a new token
fetch fails. fetch fails.
:returns string: A valid token. :returns: A valid token.
:rtype: string
""" """
return self.session.get_token(auth or self.auth) 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 :raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
available. available.
:returns string: An endpoint if available or None. :returns: An endpoint if available or None.
:rtype: string
""" """
self._set_endpoint_filter_kwargs(kwargs) self._set_endpoint_filter_kwargs(kwargs)
return self.session.get_endpoint(auth or self.auth, **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. Returning None will indicate that no token was able to be retrieved.
:param session: A session object so the plugin can make HTTP calls. :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): def get_endpoint(self, session, **kwargs):
@@ -86,8 +87,9 @@ class BaseAuthPlugin(object):
:param Session session: The session object that the auth_plugin :param Session session: The session object that the auth_plugin
belongs to. belongs to.
:returns string: The base URL that will be used to talk to the :returns: The base URL that will be used to talk to the required
required service or None if not available. service or None if not available.
:rtype: string
""" """
def invalidate(self): def invalidate(self):
@@ -99,9 +101,10 @@ class BaseAuthPlugin(object):
returned to indicate that the token may have been revoked or is returned to indicate that the token may have been revoked or is
otherwise now invalid. otherwise now invalid.
:returns bool: True if there was something that the plugin did to :returns: True if there was something that the plugin did to
invalidate. This means that it makes sense to try again. invalidate. This means that it makes sense to try again. If
If nothing happens returns False to indicate give up. nothing happens returns False to indicate give up.
:rtype: bool
""" """
return False return False
@@ -111,8 +114,9 @@ class BaseAuthPlugin(object):
This list may be used to generate CLI or config arguments. This list may be used to generate CLI or config arguments.
:returns list: A list of Param objects describing available plugin :returns: A list of Param objects describing available plugin
parameters. parameters.
:rtype: list
""" """
return [] return []
@@ -201,7 +205,8 @@ class BaseAuthPlugin(object):
:param conf: An oslo.config conf object. :param conf: An oslo.config conf object.
:param string group: The group name that options should be read from. :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() 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 conf: An oslo.config conf object.
:param string group: The group name that options should be read from. :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 :raises keystoneclient.exceptions.NoMatchingPlugin: if a plugin cannot be
created. 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 :raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response. HTTP response.
:returns AccessInfo: Token access information. :returns: Token access information.
:rtype: :py:class:`keystoneclient.access.AccessInfo`
""" """
def get_token(self, session, **kwargs): def get_token(self, session, **kwargs):
@@ -91,7 +92,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
:raises keystoneclient.exceptions.HttpError: An error from an invalid :raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response. HTTP response.
:return string: A valid token. :return: A valid token.
:rtype: string
""" """
return self.get_access(session).auth_token return self.get_access(session).auth_token
@@ -126,7 +128,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
:raises keystoneclient.exceptions.HttpError: An error from an invalid :raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response. HTTP response.
:returns AccessInfo: Valid AccessInfo :returns: Valid AccessInfo
:rtype: :py:class:`keystoneclient.access.AccessInfo`
""" """
if self._needs_reauthenticate(): if self._needs_reauthenticate():
self.auth_ref = self.get_auth_ref(session) 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 returned to indicate that the token may have been revoked or is
otherwise now invalid. otherwise now invalid.
:returns bool: True if there was something that the plugin did to :returns: True if there was something that the plugin did to
invalidate. This means that it makes sense to try again. invalidate. This means that it makes sense to try again. If
If nothing happens returns False to indicate give up. nothing happens returns False to indicate give up.
:rtype: bool
""" """
if self.auth_ref: if self.auth_ref:
self.auth_ref = None self.auth_ref = None
@@ -178,7 +182,8 @@ class BaseIdentityPlugin(base.BaseAuthPlugin):
:raises keystoneclient.exceptions.HttpError: An error from an invalid :raises keystoneclient.exceptions.HttpError: An error from an invalid
HTTP response. 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 # 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 # 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 :param dict headers: The headers that will be sent with the auth
request if a plugin needs to add to them. 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 Auth auth: The auth plugin calling the method.
:param dict headers: The headers that will be sent with the auth :param dict headers: The headers that will be sent with the auth
request if a plugin needs to add to them. request if a plugin needs to add to them.
:return tuple(string, dict): The identifier of this plugin and a dict :return: The identifier of this plugin and a dict of authentication
of authentication data for the auth type. 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. :param session : a session object to send out HTTP requests.
:type session: keystoneclient.session.Session :type session: keystoneclient.session.Session
:return access.AccessInfoV3: an object with scoped token's id and :return: an object with scoped token's id and unscoped token json
unscoped token json included. included.
:rtype: :py:class:`keystoneclient.access.AccessInfoV3`
""" """
token, token_json = self._get_unscoped_token(session) 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. :param session : a session object to send out HTTP requests.
:type session: keystoneclient.session.Session :type session: keystoneclient.session.Session
:returns (Unscoped federated token, token JSON body) :returns: (Unscoped federated token, token JSON body)
""" """
self._prepare_adfs_request() 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 fields of the revocation event. The leaf node will always be set to
the latest 'issued_before' for events that are otherwise identical. 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 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_deprecated: Allow deprecated version endpoints.
:param bool allow_unknown: Allow endpoints with an unrecognised status. :param bool allow_unknown: Allow endpoints with an unrecognised status.
:returns list: The endpoints returned from the server that match the :returns: The endpoints returned from the server that match the
criteria. criteria.
:rtype: list
Example:: Example::

6
keystoneclient/session.py
View File

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