Merge lp:~jaypipes/glance/docs into lp:~hudson-openstack/glance/trunk

[Jay Pipes]

Documentation for new results filtering in the API and client.

[Brian Waldon (bcwaldon)]

Looks good, Jay. Sorry I didn't do this in my original branch. I did find one typo

14: simple should be simply

review: Needs Fixing

[Jay Pipes (jaypipes)]

fixed typo.

[Brian Waldon (bcwaldon)]

Good to go

review: Approve

[Mark Washenberger (markwash)]

Looks good to me. It seems silly, but I feel weird about the use of the verb "to detail" right in the context of a URL resource called "/detail"--but I don't think its actually a problem.

review: Approve

=== modified file 'doc/source/client.rst'
--- doc/source/client.rst	2011-01-26 20:47:01 +0000
+++ doc/source/client.rst	2011-05-25 20:06:01 +0000
@@ -63,6 +63,57 @@
 
   print c.get_images_detailed()
 
+Filtering Images Returned via ``get_images()`` and ``get_images_detailed()``
+----------------------------------------------------------------------------
+
+Both the ``get_images()`` and ``get_images_detailed()`` methods take query
+parameters that serve to filter the returned list of images. 
+
+When calling, simply pass an optional dictionary to the method containing
+the filters by which you wish to limit results, with the filter keys being one
+or more of the below:
+
+* ``name: NAME``
+
+  Filters images having a ``name`` attribute matching ``NAME``.
+
+* ``container_format: FORMAT``
+
+  Filters images having a ``container_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``disk_format: FORMAT``
+
+  Filters images having a ``disk_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``status: STATUS``
+
+  Filters images having a ``status`` attribute matching ``STATUS``
+
+  For more information, see :doc:`About Image Statuses <statuses>`
+
+* ``size_min: BYTES``
+
+  Filters images having a ``size`` attribute greater than or equal to ``BYTES``
+
+* ``size_max: BYTES``
+
+  Filters images having a ``size`` attribute less than or equal to ``BYTES``
+
+Here's a quick example that will return all images less than or equal to 5G
+in size and in the `saving` status.
+
+.. code-block:: python
+
+  from glance.client import Client
+
+  c = Client("glance.example.com", 9292)
+
+  filters = {'status': 'saving', 'size_max': (5 * 1024 * 1024 * 1024)}
+  print c.get_images_detailed(filters)
 
 Requesting Detailed Metadata on a Specific Image
 ------------------------------------------------
@@ -86,7 +137,6 @@
 
   print c.get_image_meta("http://glance.example.com/images/1")
 
-
 Retrieving a Virtual Machine Image
 ----------------------------------
 

=== modified file 'doc/source/glanceapi.rst'
--- doc/source/glanceapi.rst	2011-04-12 21:45:16 +0000
+++ doc/source/glanceapi.rst	2011-05-25 20:06:01 +0000
@@ -92,6 +92,42 @@
 
   The `checksum` field is an MD5 checksum of the image file data
 
+Filtering Images Returned via ``GET /images`` and ``GET /images/detail``
+------------------------------------------------------------------------
+
+Both the ``GET /images`` and ``GET /images/detail`` requests take query
+parameters that serve to filter the returned list of images. The following
+list details these query parameters.
+
+* ``name=NAME``
+
+  Filters images having a ``name`` attribute matching ``NAME``.
+
+* ``container_format=FORMAT``
+
+  Filters images having a ``container_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``disk_format=FORMAT``
+
+  Filters images having a ``disk_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``status=STATUS``
+
+  Filters images having a ``status`` attribute matching ``STATUS``
+
+  For more information, see :doc:`About Image Statuses <statuses>`
+
+* ``size_min=BYTES``
+
+  Filters images having a ``size`` attribute greater than or equal to ``BYTES``
+
+* ``size_max=BYTES``
+
+  Filters images having a ``size`` attribute less than or equal to ``BYTES``
 
 Requesting Detailed Metadata on a Specific Image
 ------------------------------------------------

=== modified file 'doc/source/registries.rst'
--- doc/source/registries.rst	2011-02-25 14:55:26 +0000
+++ doc/source/registries.rst	2011-05-25 20:06:01 +0000
@@ -46,6 +46,43 @@
   PUT     /images/<ID>    Update metadata about an existing image
   DELETE  /images/<ID>    Remove an image's metadata from the registry
 
+Filtering Images Returned via ``GET /images`` and ``GET /images/detail``
+------------------------------------------------------------------------
+
+Both the ``GET /images`` and ``GET /images/detail`` requests take query
+parameters that serve to filter the returned list of images. The following
+list details these query parameters.
+
+* ``name=NAME``
+
+  Filters images having a ``name`` attribute matching ``NAME``.
+
+* ``container_format=FORMAT``
+
+  Filters images having a ``container_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``disk_format=FORMAT``
+
+  Filters images having a ``disk_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``status=STATUS``
+
+  Filters images having a ``status`` attribute matching ``STATUS``
+
+  For more information, see :doc:`About Image Statuses <statuses>`
+
+* ``size_min=BYTES``
+
+  Filters images having a ``size`` attribute greater than or equal to ``BYTES``
+
+* ``size_max=BYTES``
+
+  Filters images having a ``size`` attribute less than or equal to ``BYTES``
+
 ``POST /images``
 ----------------