From 3568acb61732d1ce090b41e2c991307a257070db Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 12 Oct 2014 18:43:01 -0500 Subject: [PATCH] Docstring usability improvements 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 --- keystoneclient/__init__.py | 10 ++++++++-- keystoneclient/client.py | 21 +++++++++++++-------- 2 files changed, 21 insertions(+), 10 deletions(-) diff --git a/keystoneclient/__init__.py b/keystoneclient/__init__.py index a3c0408b8..08545c573 100644 --- a/keystoneclient/__init__.py +++ b/keystoneclient/__init__.py @@ -15,9 +15,15 @@ """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. """ diff --git a/keystoneclient/client.py b/keystoneclient/client.py index 8b6a6b012..f4b9f87fe 100644 --- a/keystoneclient/client.py +++ b/keystoneclient/client.py @@ -22,22 +22,27 @@ HTTPClient = httpclient.HTTPClient def Client(version=None, unstable=False, session=None, **kwargs): """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 specified the client will be selected such that the major version is equivalent and an endpoint provides 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 Session session: A session object to be used for communication. If - one is not provided it will be constructed from the - provided kwargs. (optional) + :param session: A session object to be used for communication. If one is + not provided it will be constructed from the provided + kwargs. (optional) + :type session: keystoneclient.session.Session :param kwargs: Additional arguments are passed through to the client that is being created. - :returns: New keystone client object - (keystoneclient.v2_0.Client or keystoneclient.v3.Client). - + :returns: New keystone client object. + :rtype: :py:class:`keystoneclient.v3.client.Client` or + :py:class:`keystoneclient.v2_0.client.Client` :raises keystoneclient.exceptions.DiscoveryFailure: if the server's - response is invalid + response is invalid. :raises keystoneclient.exceptions.VersionNotAvailable: if a suitable client cannot be found. """