openstack/python-keystoneclient
Code Issues Proposed changes

Correct Session docstring

Browse Source 
The online docs for the Session class are unusable because the
arguments to __init__ were not displayed.

This and other issues in the docstrings for the class are corrected.

Change-Id: Ia03b785f132f7d21ba576c0c8d634051d7127319
This commit is contained in:
Brant Knudson
2014-10-11 11:20:46 -05:00
parent 6f2be1341d
commit cc0c93fc0c
1 changed files with 110 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
keystoneclient/session.py
View File

@@ -54,16 +54,6 @@ def request(url, method='GET', **kwargs):
class Session(object):
user_agent = None
REDIRECT_STATUSES = (301, 302, 303, 305, 307)
DEFAULT_REDIRECT_LIMIT = 30
@utils.positional(2, enforcement=utils.positional.WARN)
def __init__(self, auth=None, session=None, original_ip=None, verify=True,
cert=None, timeout=None, user_agent=None,
redirect=DEFAULT_REDIRECT_LIMIT):
"""Maintains client communication state and common functionality.
As much as possible the parameters to this class reflect and are passed
@@ -71,35 +61,51 @@ class Session(object):
:param auth: An authentication plugin to authenticate the session with.
(optional, defaults to None)
: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
:type auth: :py:class:`keystoneclient.auth.base.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 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 bundle or CA certs to check against or None
for requests to attempt to locate and use certificates.
(optional, defaults to True)
: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
bundle or CA certs to check against or None for requests to
attempt to locate and use certificates. (optional, defaults
to True)
:param cert: A client certificate to pass to requests. These are of the
same form as requests expects. Either a single filename
containing both the certificate and key or a tuple
containing the path to the certificate then a path to the
key. (optional)
containing both the certificate and key or a tuple containing
the path to the certificate then a path to the key. (optional)
:param float timeout: A timeout to pass to requests. This should be a
numerical value indicating some amount
(or fraction) of seconds or 0 for no timeout.
(optional, defaults to 0)
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 is used.
(optional, defaults to
'python-keystoneclient')
: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 forever/never. (optional, default to 30)
(optional, defaults to 'python-keystoneclient')
: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
forever/never. (optional, default to 30)
"""
user_agent = None
_REDIRECT_STATUSES = (301, 302, 303, 305, 307)
REDIRECT_STATUSES = _REDIRECT_STATUSES
"""This property is deprecated."""
_DEFAULT_REDIRECT_LIMIT = 30
DEFAULT_REDIRECT_LIMIT = _DEFAULT_REDIRECT_LIMIT
"""This property is deprecated."""
@utils.positional(2, enforcement=utils.positional.WARN)
def __init__(self, auth=None, session=None, original_ip=None, verify=True,
cert=None, timeout=None, user_agent=None,
redirect=_DEFAULT_REDIRECT_LIMIT):
if not session:
session = requests.Session()
@@ -241,11 +247,11 @@ class Session(object):
: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: :class:`keystoneclient.auth.base.BaseAuthPlugin`
:type auth: :py:class:`keystoneclient.auth.base.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)
:type requests_auth: :class:`requests.auth.AuthBase`
:type requests_auth: :py:class:`requests.auth.AuthBase`
:param bool raise_exc: If True then raise an appropriate exception for
failed HTTP requests. If False then return the
request object. (optional, default True)
@@ -398,7 +404,7 @@ class Session(object):
if log:
self._http_log_response(response=resp)
if resp.status_code in self.REDIRECT_STATUSES:
if resp.status_code in self._REDIRECT_STATUSES:
# be careful here in python True == 1 and False == 0
if isinstance(redirect, bool):
redirect_allowed = redirect
@@ -430,31 +436,63 @@ class Session(object):
return resp
def head(self, url, **kwargs):
"""Perform a HEAD request.
This calls :py:meth:`.request()` with ``method`` set to ``HEAD``.
"""
return self.request(url, 'HEAD', **kwargs)
def get(self, url, **kwargs):
"""Perform a GET request.
This calls :py:meth:`.request()` with ``method`` set to ``GET``.
"""
return self.request(url, 'GET', **kwargs)
def post(self, url, **kwargs):
"""Perform a POST request.
This calls :py:meth:`.request()` with ``method`` set to ``POST``.
"""
return self.request(url, 'POST', **kwargs)
def put(self, url, **kwargs):
"""Perform a PUT request.
This calls :py:meth:`.request()` with ``method`` set to ``PUT``.
"""
return self.request(url, 'PUT', **kwargs)
def delete(self, url, **kwargs):
"""Perform a DELETE request.
This calls :py:meth:`.request()` with ``method`` set to ``DELETE``.
"""
return self.request(url, 'DELETE', **kwargs)
def patch(self, url, **kwargs):
"""Perform a PATCH request.
This calls :py:meth:`.request()` with ``method`` set to ``PATCH``.
"""
return self.request(url, 'PATCH', **kwargs)
@classmethod
def construct(cls, kwargs):
"""Handles constructing a session from the older HTTPClient args as
well as the new request style arguments.
"""Handles constructing a session from the older
:py:class:`~keystoneclient.httpclient.HTTPClient` args as well as the
new request-style arguments.
.. warning::
*DEPRECATED*: This function is purely for bridging the gap between
older client arguments and the session arguments that they relate to.
It is not intended to be used as a generic Session Factory.
older client arguments and the session arguments that they relate
to. It is not intended to be used as a generic Session Factory.
This function purposefully modifies the input kwargs dictionary so that
the remaining kwargs dict can be reused and passed on to other
@@ -499,10 +537,12 @@ class Session(object):
:param auth: The auth plugin to use for token. Overrides the plugin
on the session. (optional)
:type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
:type auth: :py:class:`keystoneclient.auth.base.BaseAuthPlugin`
:raises keystoneclient.exceptions.AuthorizationFailure: if a new token
fetch fails.
:raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
available.
:returns: A valid token.
:rtype: string
@@ -524,7 +564,7 @@ class Session(object):
:param auth: The auth plugin to use for token. Overrides the plugin on
the session. (optional)
:type auth: :class:`keystoneclient.auth.base.BaseAuthPlugin`
:type auth: :py:class:`keystoneclient.auth.base.BaseAuthPlugin`
:raises keystoneclient.exceptions.MissingAuthPlugin: if a plugin is not
available.
@@ -544,6 +584,11 @@ class Session(object):
def invalidate(self, auth=None):
"""Invalidate an authentication plugin.
:param auth: The auth plugin to invalidate. Overrides the plugin on the
session. (optional)
:type auth: :py:class:`keystoneclient.auth.base.BaseAuthPlugin`
"""
if not auth:
auth = self.auth
@@ -556,7 +601,8 @@ class Session(object):
@utils.positional.classmethod()
def get_conf_options(cls, deprecated_opts=None):
"""Get the oslo.config options that are needed for a session.
"""Get the oslo.config options that are needed for a
:py:class:`.Session`.
These may be useful without being registered for config file generation
or to manipulate the options before registering them yourself.
@@ -569,12 +615,12 @@ class Session(object):
:timeout: The max time to wait for HTTP connections.
:param dict deprecated_opts: Deprecated options that should be included
in the definition of new options. This should be a dictionary from
the name of the new option to a list of oslo.DeprecatedOpts that
in the definition of new options. This should be a dict from the
name of the new option to a list of oslo.DeprecatedOpts that
correspond to the new option. (optional)
Example to support the 'ca_file' option pointing to the new
'cafile' option name::
For example, to support the ``ca_file`` option pointing to the new
``cafile`` option name::
old_opt = oslo.cfg.DeprecatedOpt('ca_file', 'old_group')
deprecated_opts={'cafile': [old_opt]}
@@ -617,12 +663,12 @@ class Session(object):
:param oslo.config.Cfg conf: config object to register with.
:param string group: The ini group to register options in.
:param dict deprecated_opts: Deprecated options that should be included
in the definition of new options. This should be a dictionary from
the name of the new option to a list of oslo.DeprecatedOpts that
in the definition of new options. This should be a dict from the
name of the new option to a list of oslo.DeprecatedOpts that
correspond to the new option. (optional)
Example to support the 'ca_file' option pointing to the new
'cafile' option name::
For example, to support the ``ca_file`` option pointing to the new
``cafile`` option name::
old_opt = oslo.cfg.DeprecatedOpt('ca_file', 'old_group')
deprecated_opts={'cafile': [old_opt]}
@@ -646,6 +692,7 @@ class Session(object):
:param dict kwargs: Additional parameters to pass to session
construction.
:returns: A new session object.
:rtype: :py:class:`.Session`
"""
c = conf[group]
@@ -697,13 +744,15 @@ class Session(object):
@classmethod
def load_from_cli_options(cls, args, **kwargs):
"""Create a session object from CLI arguments.
"""Create a :py:class:`.Session` object from CLI arguments.
The CLI arguments must have been registered with register_cli_options.
The CLI arguments must have been registered with
:py:meth:`.register_cli_options`.
:param Namespace args: result of parsed arguments.
:returns: A new session object.
:rtype: :py:class:`.Session`
"""
kwargs['insecure'] = args.insecure
kwargs['cacert'] = args.os_cacert