Merge lp:~leonardr/lazr.restful/generate-multiversion-collections into lp:lazr.restful

This branch makes the @collection_default_content annotation
version-aware. For different versions of the web service you can
specify different methods to be used as the collection's find()
implementation, and different values for that method's keyword
arguments.

I was able to refactor some code because this is the second branch
that makes our code generation version-aware. I also simplified the
implementation of register_adapter_for_version. Previously if the
version in question was None (indicating the earliest version), I
looked up which version was the earliest and then looked up its
version-specific marker interface. Now I simply use the generic web
service request interface, IWebServiceClientRequest. This prevents
test failures where all that changed is that a lookup that failed with
IWebServiceClientRequest needed to be changed to
IWebServiceBetaClientRequest.

Here are some questions I asked myself during development. They all had to do
with whether version differences were better solved with annotations
or left to navigation code.

Q: Do I need an analogue to @operation_removed_in_version?
A: No. If a collection disappears in a certain version, it needs to
   disappear from the navigation. Hiding the
   collection_default_content for that version won't solve anything.

   The reason we need @operation_removed_in_version is that lookup of
   named operation happens after the navigation is done. The
   navigation takes you to an entry or collection, and then the named
   operation lookup needs to succeed or fail depending on the version.

   If it turns out to be too much trouble to change the navigation, we
   could create a @collection_removed_in_version and make the
   lazr.restful behavior to raise a 404 instead of calling find(), but
   for now I say YAGNI.

Q: What happens if a collection changes its name between versions?
A: That, too is a navigation issue. And again, we had to deal with it
   specially for named operations because operation lookup is not
   navigation.

Q: What happens if a collection doesn't have a
   @collection_default_content for the earliest version? Don't I
   need to prevent that?
A: That corresponds to a case where the collection didn't exist in the
   earliest version and was added later. This is a legitimate case,
   and it will work fine if accompanied by appropriate navigation
   code.

Hi Leonard,

This is a nice refactoring and improvement. I only have minor comments below.

merge-conditional

-Edwin

>=== modified file 'src/lazr/restful/declarations.py'
>--- src/lazr/restful/declarations.py 2010-01-26 20:05:25 +0000
>+++ src/lazr/restful/declarations.py 2010-01-27 22:49:27 +0000
>@@ -202,7 +202,7 @@
> collection, or if used more than once in the same interface.
> """
>
>- def __init__(self, **params):
>+ def __init__(self, version=None, **params):
> """Create the decorator marking the default collection method.
>
> :param params: Optional parameter values to use when calling the

The docstring should explain how the version parameter should be used.

>@@ -891,20 +898,26 @@
> return method(**params)
>
>
>-def generate_collection_adapter(interface):
>+def generate_collection_adapter(interface, version=None):
> """Create a class adapting from interface to ICollection."""
> _check_tagged_interface(interface, 'collection')
>
> tag = interface.getTaggedValue(LAZR_WEBSERVICE_EXPORTED)
>- method_name = tag['collection_default_content']
>+ default_content_by_version = tag['collection_default_content']
>+ assert (version in default_content_by_version), (
>+ "'%s' isn't tagged for export to web service "
>+ "version '%s'." % (interface.__name__, version))
>+ method_name, params = default_content_by_version[version]
> entry_schema = tag['collection_entry_schema']
> class_dict = {
> 'entry_schema' : CollectionEntrySchema(entry_schema),
>- 'method_name': tag['collection_default_content'],
>- 'params': tag['collection_default_content_params'],
>+ 'method_name': method_name,
>+ 'params': params,
> '__doc__': interface.__doc__,
> }
>- classname = "%sCollectionAdapter" % interface.__name__[1:]
>+ classname =_versioned_class_name(

s/=_/= _/

>+ "%sCollectionAdapter" % interface.__name__[1:],
>+ version)
> factory = type(classname, (BaseCollectionAdapter,), class_dict)
>
> protect_schema(factory, ICollection)
>@@ -1016,8 +1029,9 @@
> if return_type is None:
> return_type = None
>
>- name = '%s_%s_%s_%s' % (prefix, method.interface.__name__, tag['as'],
>- version)
>+ name = _versioned_class_name(
>+ '%s_%s_%s' % (prefix, method.interface.__name__, tag['as']),
>+ version)
> class_dict = {'params' : tuple(tag['params'].values()),
> 'return_type' : return_type,
> '_export_info': tag,
>@@ -1026,8 +1040,20 @@
>
> if tag['type'] == 'write_operation':
> class_dict['send_modification_event'] = True
>- factory = type(make_identifier_safe(name), bases, class_dict)
>+ factory = type(name, bases, class_dict)
> classImplements(factory, provides)
> protect_schema(factory, provides)
>
> return factory
>+
>+
>+def _versioned_class_name(base_name, version):
>+ """Create a class name incorporating the given version string."""
>+ if version is None:
>+ # We need to incorporate the version into a Python class name,
>+ # but we won't find out t...