Merge trunk

doc/source/architecture.rst

@@ -0,0 +1,75 @@
+..
+      Copyright 2010 OpenStack, LLC
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Glance Architecture
+===================
+
+Glance is designed to be as adaptable as possible for various back-end storage
+and registry database solutions. There is a main Glance API server
+(the ``glance-api`` program) that serves as the communications hub between
+various client programs, the registry of image metadata, and the storage
+systems that actually contain the virtual machine image data.
+
+From a birdseye perspective, one can visualize the Glance architectural model
+like so:
+
+.. graphviz::
+
+  digraph birdseye {
+    node [fontsize=10 fontname="Monospace"]
+    a [label="Client A"]
+    b [label="Client B"]
+    c [label="Client C"]
+    d [label="Glance API Server"]
+    e [label="Registry Server"]
+    f [label="Store Adapter"]
+    g [label="S3 Store"]
+    h [label="Swift Store"]
+    i [label="Filesystem Store"]
+    j [label="HTTP Store"]
+    a -> d [dir=both]
+    b -> d [dir=both]
+    c -> d [dir=both]
+    d -> e [dir=both]
+    d -> f [dir=both]
+    f -> g [dir=both]
+    f -> h [dir=both]
+    f -> i [dir=both]
+    f -> j [dir=both]
+
+  }
+
+What is a Registry Server?
+==========================
+
+A registry server is any service that publishes image metadata that conforms
+to the Glance Registry REST-ful API. Glance comes with a reference
+implementation of a registry server called ``glance-registry``, but this is
+only a reference implementation that uses a SQL database for its metdata
+storage.
+
+What is a Store?
+================
+
+A store is a Python class that inherits from ``glance.store.Backend`` and
+conforms to that class' API for reading, writing, and deleting virtual
+machine image data.
+
+Glance currently ships with stores for S3, Swift, a simple filesystem store,
+and a read-only HTTP(S) store.
+
+Implementors are encouraged to create stores for other backends, including
+other distributed storage systems like Sheepdog or Ceph.

doc/source/client.rst

@@ -36,7 +36,9 @@ Requesting a List of Public VM Images
 We want to see a list of available virtual machine images that the Glance
 server knows about.
 
-Using Glance's Client, we can do this using the following code::
+Using Glance's Client, we can do this using the following code
+
+.. code-block:: python
 
   from glance.client import Client
 
@@ -51,7 +53,9 @@ Requesting Detailed Metadata on Public VM Images
 We want to see more detailed information on available virtual machine images
 that the Glance server knows about.
 
-Using Glance's Client, we can do this using the following code::
+Using Glance's Client, we can do this using the following code
+
+.. code-block:: python
 
   from glance.client import Client
 
@@ -72,7 +76,9 @@ data returned includes the `uri` field for each available image. This
 for a specific image.
 
 Continuing the example from above, in order to get metadata about the
-first public image returned, we can use the following code::
+first public image returned, we can use the following code
+
+.. code-block:: python
 
   from glance.client import Client
 
@@ -93,7 +99,9 @@ data returned includes the `uri` field for each available image. This
 for a specific image.
 
 Continuing the example from above, in order to get both the metadata about the
-first public image returned and its image data, we can use the following code::
+first public image returned and its image data, we can use the following code
+
+.. code-block:: python
 
   from glance.client import Client
 
@@ -222,7 +230,9 @@ The list of metadata that `image_meta` can contain are listed below.
   set to the value `queued`.
 
 As a complete example, the following code would add a new machine image to
-Glance::
+Glance
+
+.. code-block:: python
 
   from glance.client import Client
 

doc/source/conf.py

@@ -47,6 +47,7 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.ifconfig',
               'sphinx.ext.intersphinx',
               'sphinx.ext.pngmath',
+              'sphinx.ext.graphviz',
               'sphinx.ext.todo']
 
 todo_include_todos = True
@@ -117,9 +118,9 @@ pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 modindex_common_prefix = ['glance.']
 
-# -- Options for man page output -----------------------------------------------
+# -- Options for man page output ----------------------------------------------
 
-# Grouping the document tree for man pages. 
+# Grouping the document tree for man pages.
 # List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
 
 man_pages = [

doc/source/index.rst

@@ -67,6 +67,7 @@ Developer Docs
 .. toctree::
    :maxdepth: 1
 
+   architecture
    community
 
 Outstanding Documentation Tasks

setup.py

@@ -19,15 +19,6 @@ import subprocess
 
 from setuptools import setup, find_packages
 from setuptools.command.sdist import sdist
-from sphinx.setup_command import BuildDoc
-
-
-class local_BuildDoc(BuildDoc):
-    def run(self):
-        for builder in ['html', 'man']:
-            self.builder = builder
-            self.finalize_options()
-            BuildDoc.run(self)
 
 
 class local_sdist(sdist):
@@ -44,12 +35,25 @@ class local_sdist(sdist):
                 changelog_file.write(changelog)
         sdist.run(self)
 
+cmdclass = {'sdist': local_sdist}
+
+try:
+    from sphinx.setup_command import BuildDoc
+    class local_BuildDoc(BuildDoc):
+        def run(self):
+            for builder in ['html', 'man']:
+                self.builder = builder
+                self.finalize_options()
+                BuildDoc.run(self)
+    cmdclass['build_sphinx'] = local_BuildDoc
+
+except:
+    pass
+
 
 name = 'glance'
 version = '0.1.5'
 
-cmdclass = {'sdist': local_sdist,
-            'build_sphinx': local_BuildDoc}
 
 setup(
     name=name,

tests/stubs.py

@@ -117,6 +117,7 @@ def stub_out_s3_backend(stubs):
 
     class FakeSwiftAuth(object):
         pass
+
     class FakeS3Connection(object):
         pass
 
@@ -134,8 +135,8 @@ def stub_out_s3_backend(stubs):
 
             def chunk_it():
                 for i in xrange(0, len(cls.DATA), cls.CHUNK_SIZE):
-                    yield cls.DATA[i:i+cls.CHUNK_SIZE]
-            
+                    yield cls.DATA[i:i + cls.CHUNK_SIZE]
+
             return chunk_it()
 
     fake_swift_backend = FakeS3Backend()

tests/unit/test_clients.py

@@ -388,7 +388,7 @@ class TestClient(unittest.TestCase):
                    'is_public': True,
                    'type': 'kernel'
                   }
-       
+
         image_meta = self.client.add_image(fixture)
         self.assertEquals('queued', image_meta['status'])
         self.assertEquals(0, image_meta['size'])
@@ -401,7 +401,7 @@ class TestClient(unittest.TestCase):
                    'size': 19,
                    'location': "file:///tmp/glance-tests/2",
                   }
-        
+
         new_image = self.client.add_image(fixture)
         new_image_id = new_image['id']
 
@@ -434,7 +434,7 @@ class TestClient(unittest.TestCase):
                     'location': "file:///tmp/glance-tests/2",
                     'properties': {'distro': 'Ubuntu 10.04 LTS'}
                   }
-        
+
         new_image = self.client.add_image(fixture)
         new_image_id = new_image['id']
 

tests/unit/test_stores.py

@@ -96,17 +96,16 @@ class TestS3Backend(TestBackend):
     def test_get(self):
         s3_uri = "s3://user:password@localhost/bucket1/file.tar.gz"
 
-        expected_returns = ['I ', 'am', ' a', ' t', 'ea', 'po', 't,', ' s', 
+        expected_returns = ['I ', 'am', ' a', ' t', 'ea', 'po', 't,', ' s',
                             'ho', 'rt', ' a', 'nd', ' s', 'to', 'ut', '\n']
-        fetcher = get_from_backend(s3_uri, 
-                                   expected_size=8, 
+        fetcher = get_from_backend(s3_uri,
+                                   expected_size=8,
                                    conn_class=S3Backend)
 
         chunks = [c for c in fetcher]
         self.assertEqual(chunks, expected_returns)
 
 
-
 class TestSwiftBackend(TestBackend):
 
     def setUp(self):