From 42f9e54b9fd11fd124566d22372b19a8f20f2073 Mon Sep 17 00:00:00 2001 From: Paul Millette Date: Tue, 23 May 2017 10:52:08 -0400 Subject: [PATCH] Add pydocs in client and examples in documentation Change-Id: Ib6e886cdc9b972dbac59c75253a9aea60d9e2e2e --- .gitignore | 1 + almanachclient/v1/client.py | 88 +++++++++++++++++++++++++++++++++++++ doc/python_api.rst | 50 +++++++++++++++++++++ 3 files changed, 139 insertions(+) create mode 100644 doc/python_api.rst diff --git a/.gitignore b/.gitignore index 963e589..00631e8 100644 --- a/.gitignore +++ b/.gitignore @@ -53,6 +53,7 @@ ChangeLog *~ .*.swp .*sw? +.idea # Files created by releasenotes build releasenotes/build \ No newline at end of file diff --git a/almanachclient/v1/client.py b/almanachclient/v1/client.py index 9a13504..a57cd7f 100644 --- a/almanachclient/v1/client.py +++ b/almanachclient/v1/client.py @@ -27,35 +27,95 @@ class Client(HttpClient): return self.url def get_info(self): + """Display information about the current version and counts of entities in the database. + + @:returns dict + """ return self._get('{}/{}/info'.format(self.url, self.api_version)) def get_volume_types(self): + """List volume types. + + @:returns dict + """ return self._get('{}/{}/volume_types'.format(self.url, self.api_version)) def get_volume_type(self, volume_type_id): + """Get a volume type. + + :arg str volume_type_id: Volume Type Uuid + + :raises ClientError + @:returns dict + """ return self._get('{}/{}/volume_type/{}'.format(self.url, self.api_version, volume_type_id)) def create_volume_type(self, volume_type_id, volume_type_name): + """Create a volume type. + + :arg str volume_type_id: The Volume Type id + :arg str volume_type_name: The Volume Type name + + :raises ClientError + @:returns bool + """ url = '{}/{}/volume_type'.format(self.url, self.api_version) data = {'type_id': volume_type_id, 'type_name': volume_type_name} self._post(url, data) return True def delete_volume_type(self, volume_type_id): + """Delete the volume type. + + :arg str volume_type_id: Volume Type Uuid + + :raises ClientError + @:returns bool + """ self._delete('{}/{}/volume_type/{}'.format(self.url, self.api_version, volume_type_id)) return True def get_volumes(self, tenant_id, start, end): + """List volumes for a tenant. + + :arg str tenant_id: The Tenant Uuid + :arg DateTime start + :arg DateTime end + + :raises ClientError + @:returns dict + """ url = '{}/{}/project/{}/volumes'.format(self.url, self.api_version, tenant_id) params = {'start': self._format_qs_datetime(start), 'end': self._format_qs_datetime(end)} return self._get(url, params) def get_instances(self, tenant_id, start, end): + """List instances for a tenant. + + :arg str tenant_id: The Tenant Uuid + :arg DateTime start + :arg DateTime end + + :raises ClientError + @:returns dict + """ url = '{}/{}/project/{}/instances'.format(self.url, self.api_version, tenant_id) params = {'start': self._format_qs_datetime(start), 'end': self._format_qs_datetime(end)} return self._get(url, params) def create_instance(self, tenant_id, instance_id, name, flavor, start, image_meta=None): + """Create an instance for a tenant. + + :arg str tenant_id: The Tenant Uuid + :arg str instance_id: The instance uuid + :arg str name: The instance name + :arg str flavor: The flavor uuid + :arg DateTime start + :arg dict image_meta: The OS type, distro and version of the image + + :raises ClientError + @:returns bool + """ url = '{}/{}/project/{}/instance'.format(self.url, self.api_version, tenant_id) image_meta = image_meta or {} self._post(url, data={ @@ -70,16 +130,44 @@ class Client(HttpClient): return True def delete_instance(self, instance_id, end=None): + """Delete the instance. + + :arg str instance_id: Instance Uuid + :arg DateTime end + + :raises ClientError + @:returns bool + """ data = {'date': self._format_body_datetime(end or datetime.now())} self._delete('{}/{}/instance/{}'.format(self.url, self.api_version, instance_id), data=data) return True def get_tenant_entities(self, tenant_id, start, end): + """List instances and volumes for a tenant. + + :arg str tenant_id: Tenant Uuid + :arg DateTime start + :arg DateTime end + + :raises ClientError + @:returns dict + """ url = '{}/{}/project/{}/entities'.format(self.url, self.api_version, tenant_id) params = {'start': self._format_qs_datetime(start), 'end': self._format_qs_datetime(end)} return self._get(url, params) def update_instance_entity(self, instance_id, **kwargs): + """Update an instance entity. + + :arg str instance_id: Instance Uuid + :arg DateTime start + :arg DateTime end + :arg str flavor: The flavor uuid + :arg str name: The instance name + + :raises ClientError + @:returns dict + """ url = '{}/{}/entity/instance/{}'.format(self.url, self.api_version, instance_id) for param in ['start', 'end']: diff --git a/doc/python_api.rst b/doc/python_api.rst new file mode 100644 index 0000000..032e46b --- /dev/null +++ b/doc/python_api.rst @@ -0,0 +1,50 @@ +The :mod:`almanachclient` Python API +==================================== + +.. module:: almanachclient +:synopsis: A python client for the Almanach API. + +Usage +----- + +First, create an Almanach Client instance with your credentials:: + + >>> from almanachclient.v1.client import Client + >>> almanach = Client(URL, AUTH_TOKEN) + +Here ``URL`` will be a string that represents the url of your API. +``AUTH_TOKEN`` will be the authorization token you use to acces the API. + + +You can also create a Keystone Client instance and access the API with it:: + + >>> from almanachclient.keystone_client import KeystoneClient + >>> keystone_client = KeystoneClient(KEYSTONE_URL, USERNAME, PASSWORD, SERVICE, REGION) + >>> keystone_client.get_endpoint_url('admin') + +In this case ``KEYSTONE_URL`` will be a string that represents the url of your keystone catalog. +The nature of ``USERNAME`` and ``PASSWORD`` speak for themselves. ``SERVICE`` will be a string +you use to identify the "almanach" service. ``REGION`` is used to determine which region the +"almanach" service is being used in. + + +Examples +-------- +>>> import datetime +>>> from almanachclient.v1.client import Client + +>>> start_date = datetime.datetime(2017,01,05) +>>> end_date = datetime.datetime(2017,02,05) + +>>> almanach = Client('http://api.region.example.org', 'myApiAuthorizationToken') +>>> almanach.get_info() + +>>> almanach.get_volume_types() +>>> almanach.get_volume_type('f1c2db7b-946e-47a4-b443-914a669a6673') +>>> almanach.create_volume_type('f1c2db7b-946e-47a4-b443-914a669a5555', 'VolumeTypeName') +>>> almanach.delete_volume_type('f1c2db7b-946e-47a4-b443-914a669a5555') + +>>> almanach.get_tenant_entities('my-tenant-uuid', start_date, end_date) + +>>> almanach.delete_instance('f1c2db7b-946e-47a4-b443-914a669a3333') +>>> almanach.update_instance_entity(instance_id='f1c2db7b-946e-47a4-b443-914a669a2222', start=start_date, end=end_date)