Merge "Add pydocs in client and examples in documentation"

.gitignore

@@ -53,6 +53,7 @@ ChangeLog
 *~
 .*.swp
 .*sw?
+.idea
 
 # Files created by releasenotes build
 releasenotes/build

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']:

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)