openstack/keystoneauth
Code Issues Proposed changes

Docstring corrections

Browse Source 
Fixes some of the more obvious issues with docstrings.

Change-Id: I85faf10ecc99f3ab9f0d5670e32df74bedd02793
This commit is contained in:
Brant Knudson 2015-12-17 17:09:58 -06:00
parent 84f61b58f9
commit d493e71070
5 changed files with 43 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/conf.py
View File

@ -103,7 +103,7 @@ add_module_names = True
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
modindex_common_prefix = ['keystoneauth1.']
# Grouping the document tree for man pages.
# List of tuples 'sourcefile', 'target', 'title', 'Authors name', 'manual'

10
doc/source/using-sessions.rst
View File

@ -165,11 +165,11 @@ While authentication plugins will endeavour to maintain a consistent set of
arguments for an ``endpoint_filter`` the concept of an authentication plugin is
purposefully generic and a specific mechanism may not know how to interpret
certain arguments and ignore them. For example the
:py:class:`keystoneauth1.auth.token_endpoint.Token` plugin (which is used when
you want to always use a specific endpoint and token combination) will always
return the same endpoint regardless of the parameters to ``endpoint_filter`` or
a custom OpenStack authentication mechanism may not have the concept of
multiple ``interface`` options and choose to ignore that parameter.
:class:`keystoneauth1.token_endpoint.Token` plugin (which is used when you want
to always use a specific endpoint and token combination) will always return the
same endpoint regardless of the parameters to ``endpoint_filter`` or a custom
OpenStack authentication mechanism may not have the concept of multiple
``interface`` options and choose to ignore that parameter.
There is some expectation on the user that they understand the limitations of
the authentication system they are using.

36
keystoneauth1/adapter.py
View File

@ -25,7 +25,7 @@ class Adapter(object):
of client local data around the global session object.
:param session: The session object to wrap.
:type session: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:param str service_type: The default service_type for URL discovery.
:param str service_name: The default service_name for URL discovery.
:param str interface: The default interface for URL discovery.
@ -34,7 +34,7 @@ class Adapter(object):
for this client.
:param tuple version: The version that this API targets.
:param auth: An auth plugin to use instead of the session one.
:type auth: keystonauth.auth.base.BaseAuthPlugin
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:param str user_agent: The User-Agent string to set.
:param int connect_retries: the maximum number of retries that should
be attempted for connection errors.
@ -102,13 +102,13 @@ class Adapter(object):
:param auth: The auth plugin to use for token. Overrides the plugin
on the session. (optional)
:type auth: :class:`keystonauth.auth.base.BaseAuthPlugin`
:type auth: keystoneauth1.plugin.BaseAuthPlugin
:raises keystonauth.exceptions.AuthorizationFailure: if a new token
fetch fails.
:raises keystoneauth1.exceptions.auth.AuthorizationFailure: if a new
token fetch fails.
:returns: A valid token.
:rtype: string
:rtype: :class:`str`
"""
return self.session.get_token(auth or self.auth)
@ -117,13 +117,13 @@ class Adapter(object):
:param auth: The auth plugin to use for token. Overrides the plugin on
the session. (optional)
:type auth: :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
:rtype: :class:`str`
"""
if self.endpoint_override:
return self.endpoint_override
@ -140,15 +140,15 @@ class Adapter(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: Current `user_id` or None if not supported by plugin.
:rtype: string
:rtype: :class:`str`
"""
return self.session.get_user_id(auth or self.auth)
@ -157,15 +157,15 @@ class Adapter(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: Current `project_id` or None if not supported by plugin.
:rtype: string
:rtype: :class:`str`
"""
return self.session.get_project_id(auth or self.auth)

16
keystoneauth1/identity/v3/k2k.py
View File

@ -30,17 +30,17 @@ class Keystone2Keystone(federation._Rescoped):
:param base_plugin: Auth plugin already authenticated against the keystone
IdP.
:type base_plugin: ``keystoneauth1.v3.base.BaseAuth``
:type base_plugin: keystoneauth1.identity.v3.base.BaseAuth
:param service_provider: The Service Provider ID as returned by
ServiceProviderManager.list()
:type service_provider: string
:type service_provider: str
"""
# Path where the ECP wrapped SAML assertion should be presented to
# the Keystone Service Provider.
REQUEST_ECP_URL = '/auth/OS-FEDERATION/saml2/ecp'
"""Path where the ECP wrapped SAML assertion should be presented to the
Keystone Service Provider."""
def __init__(self, base_plugin, service_provider, **kwargs):
super(Keystone2Keystone, self).__init__(auth_url=None, **kwargs)
@ -63,11 +63,11 @@ class Keystone2Keystone(federation._Rescoped):
function will simply return whole string.
:param auth_url: auth_url of the remote cloud
:type auth_url: string
:type auth_url: str
:returns: auth_url of remote cloud where a token can be validated or
scoped.
:rtype: string
:rtype: str
"""
PATTERN = '/OS-FEDERATION/'
@ -131,13 +131,13 @@ class Keystone2Keystone(federation._Rescoped):
:param sp_url: URL where the ECP wrapped SAML assertion will be
presented to the keystone SP. Usually, something like:
https://sp.com/Shibboleth.sso/SAML2/ECP
:type sp_url: string
:type sp_url: str
:param sp_auth_url: Federated authentication URL of the keystone SP.
It is specified by IdP, for example:
https://sp.com/v3/OS-FEDERATION/identity_providers/
idp_id/protocols/protocol_id/auth
:type sp_auth_url: string
:type sp_auth_url: str
"""

22
keystoneauth1/plugin.py
View File

@ -43,7 +43,7 @@ class BaseAuthPlugin(object):
the `get_headers` method instead.
:param session: A session object so the plugin can make HTTP calls.
:type session: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:return: A token to use.
:rtype: string
@ -74,7 +74,7 @@ class BaseAuthPlugin(object):
achieved by returning an empty dictionary.
:param session: The session object that the auth_plugin belongs to.
:type session: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:returns: Headers that are set to authenticate a message or None for
failure. Note that when checking this value that the empty
@ -102,7 +102,7 @@ class BaseAuthPlugin(object):
- ``region_name``: the region the endpoint exists in.
:param session: The session object that the auth_plugin belongs to.
:type session: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:returns: The base URL that will be used to talk to the required
service or None if not available.
@ -147,7 +147,7 @@ class BaseAuthPlugin(object):
currently authenticated user id.
:param session: A session object so the plugin can make HTTP calls.
:type session: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:returns: A user identifier or None if one is not available.
:rtype: str
@ -162,7 +162,7 @@ class BaseAuthPlugin(object):
the currently authenticated project id.
:param session: A session object so the plugin can make HTTP calls.
:type session: keystonauth.session.Session
:type session: keystoneauth1.session.Session
:returns: A project identifier or None if one is not available.
:rtype: str
@ -224,15 +224,15 @@ class BaseAuthPlugin(object):
This should not fetch any new data if it is not present.
:raises: keystoneclient.exceptions.NotImplementedError:
if the plugin does not support this feature.
:raises NotImplementedError: if the plugin does not support this
feature.
:returns: raw python data (which can be JSON serialized) that can be
moved into another plugin (of the same type) to have the
same authenticated state.
:rtype: object or None if unauthenticated.
"""
return NotImplementedError()
raise NotImplementedError()
def set_auth_state(self, data):
"""Install existing authentication state for a plugin.
@ -240,7 +240,7 @@ class BaseAuthPlugin(object):
Take the output of get_auth_state and install that authentication state
into the current authentication plugin.
:raises: keystoneclient.exceptions.NotImplementedError:
if the plugin does not support this feature.
:raises NotImplementedError: if the plugin does not support this
feature.
"""
return NotImplementedError()
raise NotImplementedError()