Merge lp:~leonardr/lazr.restful/use-bleedthrough-for-methods into lp:lazr.restful

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This branch creates the 'operation_for_version' annotation, used to publish a named operation in different ways for different versions of the web service. Currently 'operation_for_version' lets you define different versions of the methods, but it doesn't really matter, because the bleed-through stack means that only the most recent version is visible.

I made some changes to BleedThroughDict, implementing additional bits of the dict interface, so that the code in declarations.py could treat a BTD like a normal dict.

Not every annotation works with operation_for_version. For instance, the rename_parameters_as annotation directly modifies an object in the bleed-through stack, instead of putting new values in there. This means that using rename_parameters_as will modify every version of the annotation at once. In subsequent branches I'll be changing the BleedThroughDict data structure to work with this kind of annotation.

[Brad Crittenden (bac)]

Very nice branch Leonard. On IRC I suggested adding a comment about the use of None on the stack and you proposed a nice solution. With that change it looks great.

review: Approve (code)

=== modified file 'src/lazr/restful/declarations.py'
--- src/lazr/restful/declarations.py	2010-01-11 18:27:43 +0000
+++ src/lazr/restful/declarations.py	2010-01-19 20:04:14 +0000
@@ -27,6 +27,7 @@
     'generate_entry_interface',
     'generate_operation_adapter',
     'mutator_for',
+    'operation_for_version',
     'operation_parameters',
     'operation_returns_entry',
     'operation_returns_collection_of',
@@ -56,7 +57,9 @@
 from lazr.restful import (
     Collection, Entry, EntryAdapterUtility, ResourceOperation, ObjectLink)
 from lazr.restful.security import protect_schema
-from lazr.restful.utils import camelcase_to_underscore_separated, get_current_browser_request
+from lazr.restful.utils import (
+    BleedThroughDict, camelcase_to_underscore_separated,
+    get_current_browser_request)
 
 LAZR_WEBSERVICE_EXPORTED = '%s.exported' % LAZR_WEBSERVICE_NS
 COLLECTION_TYPE = 'collection'
@@ -294,7 +297,17 @@
         """Annotates the function with the fixed arguments."""
         # Everything in the function dictionary ends up as tagged value
         # in the interface method specification.
-        annotations = method.__dict__.setdefault(LAZR_WEBSERVICE_EXPORTED, {})
+        annotations = method.__dict__.get(LAZR_WEBSERVICE_EXPORTED, None)
+        if annotations is None:
+            # Create a new bleed-through dict which associates
+            # annotation data with the earliest active version of the
+            # web service. Future @webservice_version annotations will
+            # push later versions onto the BleedThroughDict, allowing
+            # new versions to specify annotation data that conflicts
+            # with old versions.
+            annotations = BleedThroughDict()
+            annotations.push(None)
+            method.__dict__[LAZR_WEBSERVICE_EXPORTED] = annotations
         self.annotate_method(method, annotations)
         return method
 
@@ -442,6 +455,27 @@
                set(annotations.get('call_with', {}).keys()))
 
 
+class operation_for_version(_method_annotator):
+    """Decorator specifying which version of the webservice is defined.
+
+    Decorators processed after this one will decorate the given web
+    service version and, by default, subsequent versions will inherit
+    their values. Subsequent versions may provide conflicting values,
+    but those values will not affect this version.
+    """
+    def __init__(self, version):
+        _check_called_from_interface_def('%s()' % self.__class__.__name__)
+        self.version = version
+
+    def annotate_method(self, method, annotations):
+        """See `_method_annotator`."""
+        # The annotations dict is a BleedThroughDict. Push a new dict
+        # onto its stack, labeled with the version number, so that
+        # future annotations can override old annotations without
+        # destroying them.
+        annotations.push(self.version)
+
+
 class export_operation_as(_method_annotator):
     """Decorator specifying the name to export the method as."""
 

=== modified file 'src/lazr/restful/docs/utils.txt'
--- src/lazr/restful/docs/utils.txt	2010-01-14 10:00:38 +0000
+++ src/lazr/restful/docs/utils.txt	2010-01-19 20:04:14 +0000
@@ -57,6 +57,9 @@
     >>> print stack.get('key', 'default')
     value
 
+    >>> 'key' in stack
+    True
+
     >>> sorted(stack.items())
     [('key', 'value')]
 

=== modified file 'src/lazr/restful/docs/webservice-declarations.txt'
--- src/lazr/restful/docs/webservice-declarations.txt	2010-01-11 18:27:43 +0000
+++ src/lazr/restful/docs/webservice-declarations.txt	2010-01-19 20:04:14 +0000
@@ -267,11 +267,12 @@
 Exporting methods
 =================
 
-Entries and collections can support operations on the webservice. The
-operations supported are defined by tagging methods in the content
-interface with special decorators.
+Entries and collections can publish named operations on the
+webservice. Every named operation corresponds to some method defined
+on the content interface. To publish a method as a named operation,
+you tag it with special decorators.
 
-Three different decorators are used based on the kind of method
+Four different decorators are used based on the kind of method
 exported.
 
 1. @export_read_operation
@@ -295,6 +296,11 @@
     creating and the name of the fields in the schema that are passed as
     parameters.
 
+4. @export_destructor_operation
+
+    This will mark the method as available as a DELETE operation on the
+    exported resource.
+
 The specification of the web service's acceptable method parameters
 should be described using the @operation_parameters decorator, which
 takes normal IField instances.
@@ -444,6 +450,9 @@
     return_type: <lazr.restful._operation.ObjectLink object...>
     type: 'factory'
 
+Default values and required parameters
+--------------------------------------
+
 Parameters default and required attributes are set automatically based
 on the method signature.
 
@@ -494,6 +503,75 @@
     >>> param_defs['optional2'].default
     u'Default2'
 
+Versioning
+----------
+
+Different versions of the webservice can publish the same interface
+method in totally different ways. Here's a simple example. This method
+appears differently in three versions of the web service: 2.0, 1.0,
+and in an unnamed pre-1.0 version.
+
+    >>> from lazr.restful.declarations import operation_for_version
+    >>> class MultiVersionMethod(Interface):
+    ...     export_as_webservice_entry()
+    ...
+    ...     @call_with(fixed='2.0 value')
+    ...     @operation_for_version('2.0')
+    ...
+    ...     @call_with(fixed='1.0 value')
+    ...     @export_operation_as('new_name')
+    ...     @operation_for_version('1.0')
+    ...
+    ...     @call_with(fixed='pre-1.0 value')
+    ...     @operation_parameters(
+    ...         required=TextLine(),
+    ...         fixed=TextLine()
+    ...         )
+    ...     @export_read_operation()
+    ...     def a_method(required, fixed='Fixed value'):
+    ...         """Method demonstrating multiversion publication."""
+
+The tagged value containing the annotations looks like a dictionary,
+but it's actually a stack of dictionaries named after the versions.
+
+    >>> dictionary = MultiVersionMethod['a_method'].getTaggedValue(
+    ...     'lazr.restful.exported')
+    >>> dictionary.dict_names
+    [None, '1.0', '2.0']
+
+The dictionary on top of the stack is for the 2.0 version of the web
+service. In 2.0, the method is published as 'new_name' and its 'fixed'
+argument is fixed to the string '2.0 value'.
+
+    >>> print dictionary['as']
+    new_name
+    >>> dictionary['call_with']
+    {'fixed': '2.0 value'}
+
+Let's pop the 2.0 version off the stack. Now we can see how the method
+looks in 1.0. It's still called 'new_name', but its 'fixed' argument
+is fixed to the string '1.0 value'.
+
+    >>> ignored = dictionary.pop()
+    >>> print dictionary['as']
+    new_name
+    >>> dictionary['call_with']
+    {'fixed': '1.0 value'}
+
+Let's pop one more time to see how the method looks in the pre-1.0
+version. It hasn't yet been renamed to 'new_name', and its 'fixed'
+argument is fixed to the string 'pre-1.0 value'.
+
+    >>> ignored = dictionary.pop()
+    >>> print dictionary.get('as')
+    None
+    >>> dictionary['call_with']
+    {'fixed': 'pre-1.0 value'}
+    >>> print dictionary.items()
+
+Error handling
+--------------
+
 All these decorators can only be used from within an interface
 definition:
 

=== modified file 'src/lazr/restful/utils.py'
--- src/lazr/restful/utils.py	2010-01-14 17:08:20 +0000
+++ src/lazr/restful/utils.py	2010-01-19 20:04:14 +0000
@@ -41,9 +41,11 @@
     """
     missing = object()
 
-    def __init__(self):
+    def __init__(self, name=None, dictionary=None, opaque=False):
         """Initialize the bleed-through dictionary."""
         self.stack = []
+        if name is not None and dictionary is not None:
+            self.push(name, dictionary, opaque)
 
     def push(self, name, dictionary=None, opaque=False):
         """Pushes a dictionary onto the stack.
@@ -53,9 +55,6 @@
         :arg opaque: If True, values will not 'bleed through' from
                      dictionaries lower on the stack.
         """
-        if name is None:
-            self.stack.append(name)
-            return
         if dictionary is None:
             dictionary = {}
         self.stack.append((name, dict(dictionary), opaque))
@@ -83,6 +82,14 @@
         """Is the stack empty?"""
         return len(self.stack) == 0
 
+    def setdefault(self, key, value):
+        """Get a from the top of the stack, setting it if not present."""
+        return self.stack[0][1].setdefault(key, value)
+
+    def __contains__(self, key):
+        """Check whether a key is visible in the stack."""
+        return self.get(key, missing) is not missing
+
     def __getitem__(self, key):
         """Look up an item somewhere in the stack."""
         if self.is_empty: