Merge "Add docs for Client instances"

doc/source/client.rst

@@ -0,0 +1,7 @@
+------
+Client
+------
+
+.. automodule:: zaqarclient.queues.client
+
+.. currentmodule:: zaqarclient.queues.client

doc/source/index.rst

@@ -35,6 +35,15 @@ end users and to communicate with guest agents that run in the
 .. _`OpenStack Wiki`: http://wiki.openstack.org
 .. _`docs.openstack.org`: http://docs.openstack.org
 
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   client
+
 Indices and tables
 ------------------
 

zaqarclient/queues/client.py

@@ -12,7 +12,62 @@
 # implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""
+A `Client` is a high-level abstraction on top of Zaqar features. It
+exposes the server features with an object-oriented interface, which
+encourages dot notation and automatic, but lazy, resources
+allocation. A `Client` allows you to control everything, from public
+interfaces to admin endpoints.
 
+To create a `Client` instance, you supply an url pointing to the
+server and a version number::
+
+    from zaqarclient.queues import client
+
+    cli = client.Client(\'http://zaqar.example.com:8888/\', version=1.1)
+
+which will load the appropriate client based on the specified
+version. Optionally, you can also supply a config dictionary::
+
+    from zaqarclient.queues import client
+
+    cli = client.Client(\'http://zaqar.example.com:8888/\',
+                        version=1.1, conf={})
+
+The arguments passed to this function will be passed to the client
+instances as well.
+
+It's recommended to use `Client` instances instead of accessing the
+lower level API as it has been designed to ease the interaction with
+the server and it gives enough control for the most common cases.
+
+A simple example for accessing an existing queue through a client
+instance - based on the API v1.1 - would look like::
+
+    from zaqarclient.queues import client
+
+    cli = client.Client(\'http://zaqar.example.com:8888/\', version=1.1)
+    queue = cli.queue(\'my_queue\')
+
+Through the queue instance will be then possible to access all the
+features associated with the queue itself like posting messages,
+getting message and deleting messages.
+
+As mentioned previously in this documentation, a client instance
+allows you to also access admin endpoints, for example::
+
+    from zaqarclient.queues import client
+
+    cli = client.Client(\'http://zaqar.example.com:8888/\', version=1.1)
+    flavor = cli.flavor(\'tasty\',
+                        pool=\'my-pool-group\',
+                        auto_create=True)
+    flavor.delete()
+
+`Client` uses the lower-level API to access the server, which means
+anything you can do with this client instance can be done by accessing
+the underlying API, although not recommended.
+"""
 from zaqarclient import errors
 from zaqarclient.queues.v1 import client as cv1