docstring cleanup, direct api, part of compute

2 files changed, 88 insertions, 4 deletions

diff --git a/nova/api/__init__.py b/nova/api/__init__.py
index 0fedbbfad..747015af5 100644
--- a/nova/api/__init__.py
+++ b/nova/api/__init__.py
@@ -15,5 +15,3 @@
 #    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 #    License for the specific language governing permissions and limitations
 #    under the License.
-
-"""No-op __init__ for directory full of api goodies."""
diff --git a/nova/api/direct.py b/nova/api/direct.py
index f487df7c7..8ceae299c 100644
--- a/nova/api/direct.py
+++ b/nova/api/direct.py
@@ -44,14 +44,33 @@ from nova import utils
 from nova import wsgi
 
 
+# Global storage for registering modules.
 ROUTES = {}
 
 
 def register_service(path, handle):
+    """Register a service handle at a given path.
+
+    Services registered in this way will be made available to any instances of
+    nova.api.direct.Router.
+
+    :param path: `routes` path, can be a basic string like "/path"
+    :param handle: an object whose methods will be made available via the api
+
+    """
     ROUTES[path] = handle
 
 
 class Router(wsgi.Router):
+    """A simple WSGI router configured via `register_service`.
+
+    This is a quick way to attach multiple services to a given endpoint.
+    It will automatically load the routes registered in the `ROUTES` global.
+
+    TODO(termie): provide a paste-deploy version of this.
+
+    """
+
     def __init__(self, mapper=None):
         if mapper is None:
             mapper = routes.Mapper()
@@ -66,6 +85,24 @@ class Router(wsgi.Router):
 
 
 class DelegatedAuthMiddleware(wsgi.Middleware):
+    """A simple and naive authentication middleware.
+
+    Designed mostly to provide basic support for alternative authentication
+    schemes, this middleware only desires the identity of the user and will
+    generate the appropriate nova.context.RequestContext for the rest of the
+    application. This allows any middleware above it in the stack to
+    authenticate however it would like while only needing to conform to a
+    minimal interface.
+
+    Expects two headers to determine identity:
+     - X-OpenStack-User
+     - X-OpenStack-Project
+
+    This middleware is tied to identity management and will need to be kept
+    in sync with any changes to the way identity is dealt with internally.
+
+    """
+
     def process_request(self, request):
         os_user = request.headers['X-OpenStack-User']
         os_project = request.headers['X-OpenStack-Project']
@@ -74,6 +111,20 @@ class DelegatedAuthMiddleware(wsgi.Middleware):
 
 
 class JsonParamsMiddleware(wsgi.Middleware):
+    """Middleware to allow method arguments to be passed as serialized JSON.
+
+    Accepting arguments as JSON is useful for accepting data that may be more
+    complex than simple primitives.
+
+    In this case we accept it as urlencoded data under the key 'json' as in
+    json=<urlencoded_json> but this could be extended to accept raw JSON
+    in the POST body.
+
+    Filters out the parameters `self`, `context` and anything beginning with
+    an underscore.
+
+    """
+
     def process_request(self, request):
         if 'json' not in request.params:
             return
@@ -92,6 +143,13 @@ class JsonParamsMiddleware(wsgi.Middleware):
 
 
 class PostParamsMiddleware(wsgi.Middleware):
+    """Middleware to allow method arguments to be passed as POST parameters.
+
+    Filters out the parameters `self`, `context` and anything beginning with
+    an underscore.
+
+    """
+
     def process_request(self, request):
         params_parsed = request.params
         params = {}
@@ -106,12 +164,21 @@ class PostParamsMiddleware(wsgi.Middleware):
 
 
 class Reflection(object):
-    """Reflection methods to list available methods."""
+    """Reflection methods to list available methods.
+
+    This is an object that expects to be registered via register_service.
+    These methods allow the endpoint to be self-describing. They introspect
+    the exposed methods and provide call signatures and documentation for
+    them allowing quick experimentation.
+
+    """
+
     def __init__(self):
         self._methods = {}
         self._controllers = {}
 
     def _gather_methods(self):
+        """Introspect available methods and generate documentation for them."""
         methods = {}
         controllers = {}
         for route, handler in ROUTES.iteritems():
@@ -185,6 +252,16 @@ class Reflection(object):
 
 
 class ServiceWrapper(wsgi.Controller):
+    """Wrapper to dynamically povide a WSGI controller for arbitrary objects.
+
+    With lightweight introspection allows public methods on the object to
+    be accesed via simple WSGI routing and parameters and serializes the
+    return values.
+
+    Automatically used be nova.api.direct.Router to wrap registered instances.
+
+    """
+
     def __init__(self, service_handle):
         self.service_handle = service_handle
 
@@ -260,7 +337,16 @@ class Limited(object):
 
 
 class Proxy(object):
-    """Pretend a Direct API endpoint is an object."""
+    """Pretend a Direct API endpoint is an object.
+
+    This is mostly useful in testing at the moment though it should be easily
+    extendable to provide a basic API library functionality.
+
+    In testing we use this to stub out internal objects to verify that results
+    from the API are serializable.
+
+    """
+
     def __init__(self, app, prefix=None):
         self.app = app
         self.prefix = prefix