openstack/python-keystoneclient
Code Issues Proposed changes

Docstring usability improvements

Browse Source 
The generated docs didn't provide enough information for a developer
to get started using the API. This change enhances the documentation
for the module so that a developer knows where to go to start (create
a Client).

Partial-Bug: #1330769
Change-Id: I907187d34ebf2c2e662ff7b9547b0ecaef008414
This commit is contained in:
Brant Knudson
2014-10-12 18:43:01 -05:00
parent b71a0a22c5
commit 3568acb617
2 changed files with 21 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
keystoneclient/__init__.py
View File

@@ -15,9 +15,15 @@
"""The python bindings for the OpenStack Identity (Keystone) project. """The python bindings for the OpenStack Identity (Keystone) project.
See :py:class:`keystoneclient.v3.client.Client` for the Identity V3 client. A Client object will allow you to communicate with the Identity server. The
recommended way to get a Client object is to use
:py:func:`keystoneclient.client.Client()`. :py:func:`~.Client()` uses version
discovery to create a V3 or V2 client depending on what versions the Identity
server supports and what version is requested.
See :py:class:`keystoneclient.v2_0.client.Client` for the Identity V2.0 client. Identity V2 and V3 clients can also be created directly. See
:py:class:`keystoneclient.v3.client.Client` for the V3 client and
:py:class:`keystoneclient.v2_0.client.Client` for the V2 client.
""" """

21
keystoneclient/client.py
View File

@@ -22,22 +22,27 @@ HTTPClient = httpclient.HTTPClient
def Client(version=None, unstable=False, session=None, **kwargs): def Client(version=None, unstable=False, session=None, **kwargs):
"""Factory function to create a new identity service client. """Factory function to create a new identity service client.
The returned client will be either a V3 or V2 client. Check the version
using the :py:attr:`~keystoneclient.v3.client.Client.version` property or
the instance's class (with instanceof).
:param tuple version: The required version of the identity API. If :param tuple version: The required version of the identity API. If
specified the client will be selected such that the specified the client will be selected such that the
major version is equivalent and an endpoint provides major version is equivalent and an endpoint provides
at least the specified minor version. For example to at least the specified minor version. For example to
specify the 3.1 API use (3, 1). specify the 3.1 API use ``(3, 1)``.
:param bool unstable: Accept endpoints not marked as 'stable'. (optional) :param bool unstable: Accept endpoints not marked as 'stable'. (optional)
:param Session session: A session object to be used for communication. If :param session: A session object to be used for communication. If one is
one is not provided it will be constructed from the not provided it will be constructed from the provided
provided kwargs. (optional) kwargs. (optional)
:type session: keystoneclient.session.Session
:param kwargs: Additional arguments are passed through to the client :param kwargs: Additional arguments are passed through to the client
that is being created. that is being created.
:returns: New keystone client object :returns: New keystone client object.
(keystoneclient.v2_0.Client or keystoneclient.v3.Client). :rtype: :py:class:`keystoneclient.v3.client.Client` or
:py:class:`keystoneclient.v2_0.client.Client`
:raises keystoneclient.exceptions.DiscoveryFailure: if the server's :raises keystoneclient.exceptions.DiscoveryFailure: if the server's
response is invalid response is invalid.
:raises keystoneclient.exceptions.VersionNotAvailable: if a suitable client :raises keystoneclient.exceptions.VersionNotAvailable: if a suitable client
cannot be found. cannot be found.
""" """