From 9b15c4133c8a04dd1cdcb3c8ae612fdebe5e3fa3 Mon Sep 17 00:00:00 2001 From: Lorin Hochstein Date: Fri, 4 May 2012 09:33:29 -0400 Subject: [PATCH] Updated Sphinx documentation - Added examples using the API - Added API reference pages - Added docstrings to classes so they would be picked up by sphinx - Removed warning about CLI coming soon Change-Id: I6e187efe508c5ae310ec97efe4650495f958306d --- docs/api.rst | 25 ------- docs/index.rst | 15 +++-- docs/ref/client.rst | 8 +++ docs/ref/endpoints.rst | 11 ++++ docs/ref/generic-client.rst | 12 ++++ docs/ref/index.rst | 7 ++ docs/ref/roles.rst | 9 +++ docs/ref/services.rst | 11 ++++ docs/ref/tenants.rst | 11 ++++ docs/ref/users.rst | 9 +++ docs/shell.rst | 4 -- docs/using-api.rst | 109 +++++++++++++++++++++++++++++++ keystoneclient/v2_0/endpoints.py | 6 ++ keystoneclient/v2_0/roles.py | 2 + keystoneclient/v2_0/services.py | 6 ++ keystoneclient/v2_0/tenants.py | 17 +++++ keystoneclient/v2_0/users.py | 2 + 17 files changed, 228 insertions(+), 36 deletions(-) delete mode 100644 docs/api.rst create mode 100644 docs/ref/client.rst create mode 100644 docs/ref/endpoints.rst create mode 100644 docs/ref/generic-client.rst create mode 100644 docs/ref/roles.rst create mode 100644 docs/ref/services.rst create mode 100644 docs/ref/tenants.rst create mode 100644 docs/ref/users.rst create mode 100644 docs/using-api.rst diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index c223d28d6..000000000 --- a/docs/api.rst +++ /dev/null @@ -1,25 +0,0 @@ -The :mod:`keystoneclient` Python API -==================================== - -.. module:: keystoneclient - :synopsis: A client for the OpenStack Keystone API. - -.. currentmodule:: keystoneclient.generic.client - -.. autoclass:: Client - - .. automethod:: discover - -.. currentmodule:: keystoneclient.v2_0.client - -.. autoclass:: Client - - .. automethod:: authenticate - - -For more information, see the reference documentation: - -.. toctree:: - :maxdepth: 2 - - ref/index diff --git a/docs/index.rst b/docs/index.rst index 8dea24b33..bece0aa9b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,18 +2,15 @@ Python bindings to the OpenStack Keystone API ================================================== This is a client for OpenStack Keystone API. There's :doc:`a Python API -` (the :mod:`keystoneclient` module), and a :doc:`command-line script +` (the :mod:`keystoneclient` module), and a :doc:`command-line script ` (installed as :program:`keystone`). -You'll need an `OpenStack Keystone` account, which you can get by -using `keystone-manage`. - Contents: .. toctree:: :maxdepth: 1 - api + using-api shell ref/index releases @@ -21,9 +18,13 @@ Contents: Contributing ============ -Development takes place `on GitHub`__; please file bugs/pull requests there. +Code is hosted `on GitHub`_. Submit bugs to the Keystone project on +`Launchpad`_. Submit code to the openstack/python-keystoneclient project using +`Gerrit`_. -__ https://github.com/4P/python-keystoneclient +.. _on GitHub: https://github.com/openstack/python-keystoneclient +.. _Launchpad: https://launchpad.net/keystone +.. _Gerrit: http://wiki.openstack.org/GerritWorkflow Run tests with ``python setup.py test``. diff --git a/docs/ref/client.rst b/docs/ref/client.rst new file mode 100644 index 000000000..cb21e3ec9 --- /dev/null +++ b/docs/ref/client.rst @@ -0,0 +1,8 @@ +Client +====== + +.. currentmodule:: keystoneclient.v2_0.client + +.. autoclass:: Client + + .. automethod:: authenticate diff --git a/docs/ref/endpoints.rst b/docs/ref/endpoints.rst new file mode 100644 index 000000000..ed2b4e2c6 --- /dev/null +++ b/docs/ref/endpoints.rst @@ -0,0 +1,11 @@ +============================== +Endpoint Manager and Endpoints +============================== + + + +.. currentmodule:: keystoneclient.v2_0.endpoints + +.. automodule:: keystoneclient.v2_0.endpoints + :members: + diff --git a/docs/ref/generic-client.rst b/docs/ref/generic-client.rst new file mode 100644 index 000000000..990555871 --- /dev/null +++ b/docs/ref/generic-client.rst @@ -0,0 +1,12 @@ +Generic client +============== + +Use the generic client to obtain access to a specific endpoint version. + + +.. currentmodule:: keystoneclient.generic.client + +.. autoclass:: Client + + .. automethod:: discover + diff --git a/docs/ref/index.rst b/docs/ref/index.rst index 677a9c210..d99127e3c 100644 --- a/docs/ref/index.rst +++ b/docs/ref/index.rst @@ -6,4 +6,11 @@ The following API reference documents are available: .. toctree:: :maxdepth: 1 + client + generic-client + tenants + users + roles + services + endpoints exceptions diff --git a/docs/ref/roles.rst b/docs/ref/roles.rst new file mode 100644 index 000000000..9cb92839e --- /dev/null +++ b/docs/ref/roles.rst @@ -0,0 +1,9 @@ +====================== +Role Manager and Roles +====================== + +.. currentmodule:: keystoneclient.v2_0.roles + +.. automodule:: keystoneclient.v2_0.roles + :members: + diff --git a/docs/ref/services.rst b/docs/ref/services.rst new file mode 100644 index 000000000..a4b677cf1 --- /dev/null +++ b/docs/ref/services.rst @@ -0,0 +1,11 @@ +============================ +Service Manager and Services +============================ + + + +.. currentmodule:: keystoneclient.v2_0.services + +.. automodule:: keystoneclient.v2_0.services + :members: + diff --git a/docs/ref/tenants.rst b/docs/ref/tenants.rst new file mode 100644 index 000000000..d6e38618d --- /dev/null +++ b/docs/ref/tenants.rst @@ -0,0 +1,11 @@ +========================== +Tenant Manager and Tenants +========================== + + + +.. currentmodule:: keystoneclient.v2_0.tenants + +.. automodule:: keystoneclient.v2_0.tenants + :members: + diff --git a/docs/ref/users.rst b/docs/ref/users.rst new file mode 100644 index 000000000..953daeca1 --- /dev/null +++ b/docs/ref/users.rst @@ -0,0 +1,9 @@ +====================== +User Manager and Users +====================== + +.. currentmodule:: keystoneclient.v2_0.users + +.. automodule:: keystoneclient.v2_0.users + :members: + diff --git a/docs/shell.rst b/docs/shell.rst index 921611366..c44d6b3d3 100644 --- a/docs/shell.rst +++ b/docs/shell.rst @@ -4,10 +4,6 @@ The :program:`keystone` shell utility .. program:: keystone .. highlight:: bash -.. warning:: COMING SOON - - The command line interface is not yet completed. This document serves - as a reference for the implementation. The :program:`keystone` shell utility interacts with OpenStack Keystone API from the command line. It supports the entirety of the OpenStack Keystone API. diff --git a/docs/using-api.rst b/docs/using-api.rst new file mode 100644 index 000000000..d8fa0bcf8 --- /dev/null +++ b/docs/using-api.rst @@ -0,0 +1,109 @@ +============== +The client API +============== + +Introduction +============ +The main concepts in the Keystone API are: + + * tenants + * users + * roles + * services + * endpoints + +The Keystone API lets you query and make changes through managers. For example, +to maipulate tenants, you interact with a +``keystoneclient.v2_0.tenants.TenantManger`` object. + +You obtain access to managers through via atributes of the ``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants`` attribute of the ``Client`` +class is a tenant manager:: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> keystone.tenants.list() # List tenants + +You create a valid ``keystoneclient.v2_0.client.Client`` object by passing +authentication data to the constructor. Authentication and examples of common +tasks are provided below. + +Authenticating +============== + +There are two ways to authenticate against Keystone: + * against the admin endpoint with the admin token + * against the public endpoint with a username and password + +If you are an administrator, you can authenticate by connecting to the admin +endpoint and using the admin token (sometimes referred to as the service +token). The token is specified as the ``admin_token`` configuration option in your +keystone.conf config file, which is typically in /etc/keystone:: + + >>> from keystoneclient.v2_0 import client + >>> token = '012345SECRET99TOKEN012345' + >>> endpoint = 'http://192.168.206.130:35357/v2.0' + >>> keystone = client.Client(token=token, endpoint=endpoint) + +If you have a username and password, authentication is done against the +public endpoint. You must also specify a tenant that is associated with the +user:: + + >>> from keystoneclient.v2_0 import client + >>> username='adminUser' + >>> password='secreetword' + >>> tenant_name='openstackDemo' + >>> auth_url='http://192.168.206.130:5000/v2.0' + >>> keystone = client.Client(username=username, password=password, + ... tenant_name, auth_url=auth_url) + +Creating tenants +================ + +This example will create a tenant named *openStackDemo*:: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> keystone.tenants.create(tenant_name="openstackDemo", + ... description="Default Tenant", enabled=True) + + +Creating users +============== + +This example will create a user named *adminUser* with a password *secretword* +in the opoenstackDemo tenant. We first need to retrieve the tenant:: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> tenants = keystone.tenants.list() + >>> my_tenant = [x for x in tenants if x.name=='openstackDemo'][0] + >>> my_user = keystone.users.create(name="adminUser", password="secretword", + ... tenant_id=my_tenant.id) + +Creating roles and adding users +=============================== + +This example will create an admin role and add the *my_user* user to that +role, but only for the *my_tenant* tenant: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> role = keystone.roles.create('admin') + >>> my_tenant = ... + >>> my_user = ... + >>> keystone.roles.add_user_role(my_user, role, my_tenant) + +Creating services and endpoints +=============================== + +This example will create the service and corresponding endpoint for the +Compute service:: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> service = keystone.services.create(name="nova", service_type="compute", + ... description="Nova Compute Service") + >>> keystone.endpoints.create(region="RegionOne", service_id=service.id, + ... publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s", + ... adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s", + ... internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s") diff --git a/keystoneclient/v2_0/endpoints.py b/keystoneclient/v2_0/endpoints.py index 73e58b4e0..866c033f7 100644 --- a/keystoneclient/v2_0/endpoints.py +++ b/keystoneclient/v2_0/endpoints.py @@ -17,17 +17,22 @@ from keystoneclient import base class Endpoint(base.Resource): + """Represents a Keystone endpoint""" def __repr__(self): return "" % self._info class EndpointManager(base.ManagerWithFind): + """Manager class for manipulating Keystone endpoints""" + resource_class = Endpoint def list(self): + """List all available endpoints""" return self._list('/endpoints', 'endpoints') def create(self, region, service_id, publicurl, adminurl, internalurl): + """Create a new endpoint""" body = {'endpoint': {'region': region, 'service_id': service_id, 'publicurl': publicurl, @@ -36,4 +41,5 @@ class EndpointManager(base.ManagerWithFind): return self._create('/endpoints', body, 'endpoint') def delete(self, id): + """Delete an endpoint""" return self._delete('/endpoints/%s' % id) diff --git a/keystoneclient/v2_0/roles.py b/keystoneclient/v2_0/roles.py index aed2b2775..71f75ad94 100644 --- a/keystoneclient/v2_0/roles.py +++ b/keystoneclient/v2_0/roles.py @@ -18,6 +18,7 @@ from keystoneclient import base class Role(base.Resource): + """Represents a Keystone role""" def __repr__(self): return "" % self._info @@ -26,6 +27,7 @@ class Role(base.Resource): class RoleManager(base.ManagerWithFind): + """Manager class for manipulating Keystone roles""" resource_class = Role def get(self, role): diff --git a/keystoneclient/v2_0/services.py b/keystoneclient/v2_0/services.py index ac53d00b9..04dd90f0e 100644 --- a/keystoneclient/v2_0/services.py +++ b/keystoneclient/v2_0/services.py @@ -18,24 +18,30 @@ from keystoneclient import base class Service(base.Resource): + """Represents a Keystone service""" def __repr__(self): return "" % self._info class ServiceManager(base.ManagerWithFind): + """Manager class for manipulating Keystone services""" resource_class = Service def list(self): + """List available services""" return self._list("/OS-KSADM/services", "OS-KSADM:services") def get(self, id): + """Retrieve a service by id""" return self._get("/OS-KSADM/services/%s" % id, "OS-KSADM:service") def create(self, name, service_type, description): + """Create a new service""" body = {"OS-KSADM:service": {'name': name, 'type': service_type, 'description': description}} return self._create("/OS-KSADM/services", body, "OS-KSADM:service") def delete(self, id): + """Delete a service""" return self._delete("/OS-KSADM/services/%s" % id) diff --git a/keystoneclient/v2_0/tenants.py b/keystoneclient/v2_0/tenants.py index 6804f9d73..7a3057e6f 100644 --- a/keystoneclient/v2_0/tenants.py +++ b/keystoneclient/v2_0/tenants.py @@ -20,6 +20,15 @@ from keystoneclient import base class Tenant(base.Resource): + """Represents a Keystone tenant + + Attributes: + * id: a uuid that identifies the tenant + * name: tenant name + * description: tenant description + * enabled: boolean to indicate if tenant is enabled + + """ def __repr__(self): return "" % self._info @@ -56,6 +65,7 @@ class Tenant(base.Resource): class TenantManager(base.ManagerWithFind): + """Manager class for manipulating Keystone tenants""" resource_class = Tenant def get(self, tenant_id): @@ -64,6 +74,7 @@ class TenantManager(base.ManagerWithFind): def create(self, tenant_name, description=None, enabled=True): """ Create a new tenant. + """ params = {"tenant": {"name": tenant_name, "description": description, @@ -74,7 +85,13 @@ class TenantManager(base.ManagerWithFind): def list(self, limit=None, marker=None): """ Get a list of tenants. + + :param integer limit: maximum number to return. (optional) + :param string marker: use when specifying a limit and making + multiple calls for querying. (optional) + :rtype: list of :class:`Tenant` + """ params = {} diff --git a/keystoneclient/v2_0/users.py b/keystoneclient/v2_0/users.py index 9f60c52de..53e51acea 100644 --- a/keystoneclient/v2_0/users.py +++ b/keystoneclient/v2_0/users.py @@ -20,6 +20,7 @@ from keystoneclient import base class User(base.Resource): + """Represents a Keystone user""" def __repr__(self): return "" % self._info @@ -31,6 +32,7 @@ class User(base.Resource): class UserManager(base.ManagerWithFind): + """Manager class for manipulating Keystone users""" resource_class = User def get(self, user):