Improved documentation for top-level interfaces and added examples.

README.rst

@@ -5,10 +5,6 @@ cloudbridge provides a layer of abstraction over different cloud providers.
 It's a straightforward implementation of the `bridge pattern`_. It is currently
 under development and is in a Pre-Alpha state.
 
-.. image:: https://codeclimate.com/github/gvlproject/cloudbridge/badges/gpa.svg
-   :target: https://codeclimate.com/github/gvlproject/cloudbridge
-   :alt: Code Climate
-
 .. image:: https://landscape.io/github/gvlproject/cloudbridge/master/landscape.svg?style=flat
    :target: https://landscape.io/github/gvlproject/cloudbridge/master
    :alt: Landscape Code Health
@@ -21,6 +17,10 @@ under development and is in a Pre-Alpha state.
    :target: https://travis-ci.org/gvlproject/cloudbridge
    :alt: Travis Build Status
 
+.. image:: https://codeclimate.com/github/gvlproject/cloudbridge/badges/gpa.svg
+   :target: https://codeclimate.com/github/gvlproject/cloudbridge
+   :alt: Code Climate
+
 .. image:: https://img.shields.io/pypi/status/cloudbridge.svg
    :target: https://pypi.python.org/pypi/cloudbridge/
    :alt: latest version available on PyPI

cloudbridge/cloud/interfaces/impl.py

@@ -5,25 +5,25 @@ from abc import ABCMeta, abstractmethod, abstractproperty
 
 
 class CloudProvider(object):
-
-    __metaclass__ = ABCMeta
-
     """
     Base interface for a cloud provider
     """
+    __metaclass__ = ABCMeta
 
     @abstractmethod
     def __init__(self, config):
         """
-        Create a new provider implementation given a dictionary of
+        Create a new provider instance given a dictionary of
         configuration attributes.
 
-        :type config: an object with required fields
-        :param config: This can be a Bunch or any other object whose fields can
-                       be accessed using dot notation. See specific provider
-                       implementation for the required fields.
+        :type config: :class:`dict`
+        :param config: A dictionary object containing provider initialization
+                       values. Alternatively, this can be a Bunch or any other
+                       object whose fields can be accessed as members. See
+                       specific provider implementation for the required
+                       fields.
 
-        :rtype: ``object`` of :class:`.CloudProvider`
+        :rtype: :class:`.CloudProvider`
         :return:  a concrete provider instance
         """
         pass
@@ -31,10 +31,27 @@ class CloudProvider(object):
     @abstractproperty
     def config(self):
         """
-        Returns the config object associated with this provider.
+        Returns the config object associated with this provider. This object
+        is a subclass of :class:`dict` and will contain the properties
+        provided at initialization time. In addition, it also contains extra
+        provider-wide properties such as the default result_limit for list()
+        queries.
+
+        Example:
+
+        .. code-block:: python
+
+            config = { 'aws_access_key' : '<my_key>' }
+            provider = factory.create_provider(ProviderList.AWS, config)
+            print(provider.config.get('aws_access_key'))
+            print(provider.config.result_limit))
+            # change provider result limit
+            provider.config.result_limit = 100
 
-        :rtype: ``object``
-        :return:  The config object used to initialize this provider
+        :rtype: :class:`.Configuration`
+        :return:  An object of class Configuration, which contains the values
+                  used to initialize the provider, as well as other global
+                  configuration properties.
         """
 
     @abstractmethod
@@ -42,10 +59,19 @@ class CloudProvider(object):
         """
         Checks whether this provider supports a given service.
 
-        :type service_type: str or :class:``.CloudProviderServiceType``
-        :param service_type: Type of service the check support for.
+        Example:
 
-        :rtype: bool
+        .. code-block:: python
+
+            if provider.has_service(CloudProviderServiceType.OBJECT_STORE):
+               print("Provider supports object store services")
+               provider.object_store.list()
+
+
+        :type service_type: :class:`.CloudProviderServiceType`
+        :param service_type: Type of service to check support for.
+
+        :rtype: :class:`bool`
         :return: ``True`` if the service type is supported.
         """
         pass
@@ -66,7 +92,20 @@ class CloudProvider(object):
         """
         Provides access to all compute related services in this provider.
 
-        :rtype: ``object`` of :class:`.ComputeService`
+        Example:
+
+        .. code-block:: python
+
+            regions = provider.compute.regions.list()
+            instance_types = provider.compute.instance_types.list()
+            instances = provider.compute.instances.list()
+            images = provider.compute.images.list()
+
+            # Alternatively
+            for instance in provider.compute.instances:
+               print(instance.name)
+
+        :rtype: :class:`.ComputeService`
         :return:  a ComputeService object
         """
         pass
@@ -76,6 +115,14 @@ class CloudProvider(object):
         """
         Provides access to keypair management and firewall control
 
+        Example:
+
+        .. code-block:: python
+
+            keypairs = provider.security.keypairs.list()
+            security_groups = provider.security.security_groups.list()
+
+
         :rtype: ``object`` of :class:`.SecurityService`
         :return: a SecurityService object
         """
@@ -87,7 +134,14 @@ class CloudProvider(object):
         Provides access to the volume and snapshot services in this
         provider.
 
-        :rtype: ``object`` of :class:`.BlockStoreService`
+        Example:
+
+        .. code-block:: python
+
+            volumes = provider.block_store.volumes.list()
+            snapshots = provider.block_store.snapshots.list()
+
+        :rtype: :class:`.BlockStoreService`
         :return: a BlockStoreService object
         """
         pass
@@ -97,6 +151,14 @@ class CloudProvider(object):
         """
         Provides access to object storage services in this provider.
 
+        Example:
+
+        .. code-block:: python
+
+            if provider.has_service(CloudProviderServiceType.OBJECT_STORE):
+               print("Provider supports object store services")
+               print(provider.object_store.list())
+
         :rtype: ``object`` of :class:`.ObjectStoreService`
         :return: an ObjectStoreService object
         """

cloudbridge/cloud/interfaces/services.py

@@ -8,7 +8,9 @@ from cloudbridge.cloud.interfaces.resources import PageableObjectMixin
 class ProviderService(object):
 
     """
-    Base interface for any service supported by a provider
+    Base interface for any service supported by a provider. This interface
+    has a  provider property that can be used to access the provider associated
+    with this service.
     """
     __metaclass__ = ABCMeta
 
@@ -17,16 +19,19 @@ class ProviderService(object):
         """
         Returns the provider instance associated with this service.
 
-        :rtype: ``object`` of :class:`.CloudProvider`
-        :return: a Provider object
+        :rtype: :class:`.CloudProvider`
+        :return: a CloudProvider object
         """
         pass
 
 
 class ComputeService(ProviderService):
-
     """
-    Base interface for compute service supported by a provider
+    The compute service interface is a collection of services that provides
+    access to the underlying compute related services in a provider. For
+    example, the compute.instances service can be used to launch a new
+    instance, and the compute.images service can be used to list available
+    machine images.
     """
     __metaclass__ = ABCMeta
 
@@ -36,7 +41,23 @@ class ComputeService(ProviderService):
         Provides access to all Image related services in this provider.
         (e.g. Glance in Openstack)
 
-        :rtype: ``object`` of :class:`.ImageService`
+        Example:
+
+        .. code-block:: python
+
+            # print all images
+            for image in provider.compute.images:
+                print(image.id, image.name)
+
+            # print only first 50 images
+            for image in provider.compute.images.list(limit=50):
+                print(image.id, image.name)
+
+            # find image by name
+            image = provider.compute.images.find(name='Ubuntu 14.04')
+            print(image.id, image.name)
+
+        :rtype: :class:`.ImageService`
         :return: an ImageService object
         """
         pass
@@ -46,8 +67,20 @@ class ComputeService(ProviderService):
         """
         Provides access to all Instance type related services in this provider.
 
-        :rtype: ``object`` of :class:`.InstanceTypeService`
-        :return:  an InstanceTypeService object
+        Example:
+
+        .. code-block:: python
+
+            # list all instance sizes
+            for inst_type in provider.compute.instance_types:
+                print(inst_type.id, inst_type.name)
+
+            # find a specific size by name
+            inst_type = provider.compute.instance_types.find(name='m1.small')
+            print(inst_type.vcpus)
+
+        :rtype: :class:`.InstanceTypeService`
+        :return: an InstanceTypeService object
         """
         pass
 
@@ -56,8 +89,18 @@ class ComputeService(ProviderService):
         """
         Provides access to all Instance related services in this provider.
 
-        :rtype: ``object`` of :class:`.InstanceService`
-        :return:  an InstanceService object
+        Example:
+
+        .. code-block:: python
+
+            # launch a new instance
+            image = provider.compute.images.find(name='Ubuntu 14.04')[0]
+            size = provider.compute.instance_types.find(name='m1.small')
+            instance = provider.compute.instances.create('Hello', image, size)
+            print(instance.id, instance.name)
+
+        :rtype: :class:`.InstanceService`
+        :return: an InstanceService object
         """
         pass
 
@@ -66,8 +109,17 @@ class ComputeService(ProviderService):
         """
         Provides access to all Region related services in this provider.
 
-        :rtype: ``object`` of :class:`.RegionService`
-        :return:  a RegionService object
+        Example:
+
+        .. code-block:: python
+
+            for region in provider.compute.regions:
+                print("Region: ", region.name)
+                for zone in region.zones:
+                   print("\\tZone: ", zone.name)
+
+        :rtype: :class:`.RegionService`
+        :return: a RegionService object
         """
         pass
 
@@ -159,7 +211,7 @@ class InstanceService(PageableObjectMixin, ProviderService):
 
         :type  image: ``MachineImage`` or ``str``
         :param image: The MachineImage object or id to boot the virtual machine
-        with
+                      with
 
         :type  instance_type: ``InstanceType`` or ``str``
         :param instance_type: The InstanceType or name, specifying the size of
@@ -170,7 +222,7 @@ class InstanceService(PageableObjectMixin, ProviderService):
 
         :type  keypair: ``KeyPair`` or ``str``
         :param keypair: The KeyPair object or its name, to set for the
-        instance.
+                        instance.
 
         :type  security_groups: A ``list`` of ``SecurityGroup`` objects or a
                                 list of ``str`` names
@@ -184,10 +236,10 @@ class InstanceService(PageableObjectMixin, ProviderService):
 
         :type  launch_config: ``LaunchConfig`` object
         :param launch_config: A ``LaunchConfig`` object which
-        describes advanced launch configuration options for an instance. This
-        include block_device_mappings and network_interfaces. To construct a
-        launch configuration object, call
-        provider.compute.instances.create_launch_config()
+               describes advanced launch configuration options for an instance.
+               This includes block_device_mappings and network_interfaces. To
+               construct a launch configuration object, call
+               provider.compute.instances.create_launch_config()
 
         :rtype: ``object`` of :class:`.Instance`
         :return:  an instance of Instance class
@@ -332,16 +384,29 @@ class SnapshotService(PageableObjectMixin, ProviderService):
 class BlockStoreService(ProviderService):
 
     """
-    Base interface for a Block Store Service
+    The Block Store Service interface provides access to block device services,
+    such as volume and snapshot services in the provider.
     """
     __metaclass__ = ABCMeta
 
     @abstractproperty
     def volumes(self):
         """
-        Provides access to the volumes (i.e., block storage) for this provider.
+        Provides access to volumes (i.e., block storage) for this provider.
+
+        Example:
+
+        .. code-block:: python
 
-        :rtype: ``object`` of :class:`.VolumeService`
+            # print all volumes
+            for vol in provider.block_store.volumes:
+                print(vol.id, vol.name)
+
+            # find volume by name
+            vol = provider.block_store.volumes.find(name='my_vol')[0]
+            print(vol.id, vol.name)
+
+        :rtype: :class:`.VolumeService`
         :return: a VolumeService object
         """
         pass
@@ -351,7 +416,19 @@ class BlockStoreService(ProviderService):
         """
         Provides access to volume snapshots for this provider.
 
-        :rtype: ``object`` of :class:`.SnapshotService`
+        Example:
+
+        .. code-block:: python
+
+            # print all snapshots
+            for snap in provider.block_store.snapshots:
+                print(snap.id, snap.name)
+
+            # find snapshot by name
+            snap = provider.block_store.snapshots.find(name='my_snap')[0]
+            print(snap.id, snap.name)
+
+        :rtype: :class:`.SnapshotService`
         :return: an SnapshotService object
         """
         pass
@@ -399,17 +476,28 @@ class ImageService(PageableObjectMixin, ProviderService):
 class ObjectStoreService(PageableObjectMixin, ProviderService):
 
     """
-    Base interface for an Object Storage Service
+    The Object Storage Service interface provides access to the underlying
+    object store capabilities of this provider. This service is optional and
+    the :func:`CloudProvider.has_service()` method should be used to verify its
+    availability before using the service.
     """
     __metaclass__ = ABCMeta
 
     @abstractmethod
     def get(self, container_id):
         """
-        Returns a container given its id. Returns None if the container
-        does not exist.
+        Returns a bucket given its id. Returns None if the bucket
+        does not exist. On some providers, such as AWS and Openstack,
+        the bucket id is the same as its name.
 
-        :rtype: ``object`` of :class:`.Container`
+        Example:
+
+        .. code-block:: python
+
+            bucket = provider.object_store.get('my_bucket_id')
+            print(bucket.id, bucket.name)
+
+        :rtype: :class:`.Container`
         :return:  a Container instance
         """
         pass
@@ -417,9 +505,17 @@ class ObjectStoreService(PageableObjectMixin, ProviderService):
     @abstractmethod
     def find(self, name):
         """
-        Searches for a container by a given list of attributes
+        Searches for a bucket by a given list of attributes
 
-        :rtype: ``object`` of :class:`.Container`
+        Example:
+
+        .. code-block:: python
+
+            buckets = provider.object_store.find(name='my_bucket_name')
+            for bucket in buckets:
+                print(bucket.id, bucket.name)
+
+        :rtype: :class:`.Container`
         :return:  a Container instance
         """
         pass
@@ -427,9 +523,17 @@ class ObjectStoreService(PageableObjectMixin, ProviderService):
     @abstractmethod
     def list(self, limit=None, marker=None):
         """
-        List all containers.
+        List all buckets.
+
+        Example:
+
+        .. code-block:: python
+
+            buckets = provider.object_store.find(name='my_bucket_name')
+            for bucket in buckets:
+                print(bucket.id, bucket.name)
 
-        :rtype: ``list`` of :class:`.Container`
+        :rtype: :class:`.Container`
         :return:  list of container objects
         """
         pass
@@ -439,6 +543,14 @@ class ObjectStoreService(PageableObjectMixin, ProviderService):
         """
         Create a new container.
 
+        Example:
+
+        .. code-block:: python
+
+            bucket = provider.object_store.create('my_bucket_name')
+            print(bucket.name)
+
+
         :type name: str
         :param name: The name of this container
 
@@ -454,7 +566,8 @@ class ObjectStoreService(PageableObjectMixin, ProviderService):
 class SecurityService(ProviderService):
 
     """
-    Base interface for a Security Service.
+    The security service interface can be used to access security related
+    functions in the provider, such as firewall control and keypairs.
     """
     __metaclass__ = ABCMeta
 
@@ -463,7 +576,19 @@ class SecurityService(ProviderService):
         """
         Provides access to key pairs for this provider.
 
-        :rtype: ``object`` of :class:`.KeyPairService`
+        Example:
+
+        .. code-block:: python
+
+            # print all keypairs
+            for kp in provider.security.keypairs:
+                print(kp.id, kp.name)
+
+            # find keypair by name
+            kp = provider.security.keypairs.find(name='my_key_pair')[0]
+            print(kp.id, kp.name)
+
+        :rtype: :class:`.KeyPairService`
         :return: a KeyPairService object
         """
         pass
@@ -473,7 +598,19 @@ class SecurityService(ProviderService):
         """
         Provides access to security groups for this provider.
 
-        :rtype: ``object`` of :class:`.SecurityGroupService`
+        Example:
+
+        .. code-block:: python
+
+            # print all security groups
+            for sg in provider.security.security_groups:
+                print(sg.id, sg.name)
+
+            # find security group by name
+            sg = provider.security.security_groups.find(name='my_sg')[0]
+            print(sg.id, sg.name)
+
+        :rtype: :class:`.SecurityGroupService`
         :return: a SecurityGroupService object
         """
         pass

docs/api_docs/cloud/provider_manager.rst → docs/api_docs/cloud/providers.rst

@@ -1,10 +1,11 @@
-Provider Manager
-================
+Providers
+=========
 
 CloudProvider
 -------------
 .. autoclass:: cloudbridge.cloud.interfaces.impl.CloudProvider
     :members:
+    :special-members: __init__
 
 ContainerProvider
 -----------------

docs/api_docs/ref.rst

@@ -7,6 +7,6 @@ This section includes the API documentation for the reference interface.
    :maxdepth: 2
    :glob:
 
-   cloud/provider_manager.rst
+   cloud/providers.rst
    cloud/services.rst
    cloud/resources.rst

docs/images/object_relationships_detailed.svg

@@ -332,7 +332,7 @@
      y="637.54797"
      x="627.85999">.objects</text>
   <a
-     xlink:href="../api_docs/cloud/provider_manager.html#cloudprovider"
+     xlink:href="../api_docs/cloud/providers.html#cloudprovider"
      target="_parent"
      id="svg_14">
     <path