Merge lp:~cjwatson/lazr.restful/range-factory into lp:lazr.restful

[Colin Watson]

Allow declaring a custom range factory for use with returned collections.

Integrating this into Launchpad's StormRangeFactory may still require a bit more care, and I'd like to have at least one use case there that definitely works before landing this, but I might as well get this up for review in the meantime.

Unmerged revisions

212. By Colin Watson on 2018-10-01

Get ScopedCollection.range_factory_class from the corresponding field.

211. By Colin Watson on 2018-10-01

Merge trunk.

210. By Colin Watson on 2018-09-28

Merge trunk.

209. By Colin Watson on 2015-04-09

Allow declaring a custom range factory for use with returned collections.

=== modified file 'setup.py'
--- setup.py	2018-02-21 14:46:13 +0000
+++ setup.py	2018-10-02 06:38:17 +0000
@@ -56,7 +56,7 @@
         'docutils>=0.3.7',
         'epydoc', # used by wadl generation
         'grokcore.component==1.6',
-        'lazr.batchnavigator>=1.2.0-dev',
+        'lazr.batchnavigator>=1.2.3',
         'lazr.delegates>=2.0.3',
         'lazr.enum',
         'lazr.lifecycle',
 
=== modified file 'src/lazr/restful/_operation.py'
--- src/lazr/restful/_operation.py	2018-04-23 12:42:00 +0000
+++ src/lazr/restful/_operation.py	2018-10-02 06:38:17 +0000
@@ -118,7 +118,9 @@
             if self.total_size_only:
                 result = self.get_total_size(result)
             else:
-                result = self.batch(result, self.request) + '}'
+                result = self.batch(
+                    result, self.request,
+                    range_factory=self.get_range_factory(result)) + '}'
         else:
             # Serialize the result to JSON. Any embedded entries will be
             # automatically serialized.
@@ -163,6 +165,13 @@
         # Any other objects (eg. Entries) are not batched.
         return False
 
+    def get_range_factory(self, result):
+        """The custom range factory to use for this response, if any."""
+        if (ICollectionField.providedBy(self.return_type) and
+                self.return_type.range_factory_class is not None):
+            return self.return_type.range_factory_class(result)
+        return None
+
     def validate(self):
         """Validate incoming arguments against the operation schema.
 
 
=== modified file 'src/lazr/restful/_resource.py'
--- src/lazr/restful/_resource.py	2018-10-01 08:55:53 +0000
+++ src/lazr/restful/_resource.py	2018-10-02 06:38:17 +0000
@@ -611,7 +611,7 @@
         return simplejson.dumps(len(entries))
 
 
-    def batch(self, entries, request):
+    def batch(self, entries, request, range_factory=None):
         """Prepare a batch from a (possibly huge) list of entries.
 
         :return: a JSON string representing a hash:
@@ -635,7 +635,8 @@
         """
         if not hasattr(entries, '__len__'):
             entries = IFiniteSequence(entries)
-        navigator = WebServiceBatchNavigator(entries, request)
+        navigator = WebServiceBatchNavigator(
+            entries, request, range_factory=range_factory)
 
         view_permission = getUtility(IWebServiceConfiguration).view_permission
         batch = { 'start' : navigator.batch.start }
@@ -1817,7 +1818,12 @@
             entries = self.collection.find()
         if request is None:
             request = self.request
-        result = super(CollectionResource, self).batch(entries, request)
+        if self.collection.range_factory_class is None:
+            range_factory = None
+        else:
+            range_factory = self.collection.range_factory_class(entries)
+        result = super(CollectionResource, self).batch(
+            entries, request, range_factory=range_factory)
         result += (
             ', "resource_type_link" : ' + simplejson.dumps(self.type_url))
         return result
@@ -2089,6 +2095,8 @@
 class Collection:
     """A collection of entries."""
 
+    range_factory_class = None
+
     def __init__(self, context, request):
         """Associate the entry with some database model object."""
         self.context = context
@@ -2124,6 +2132,11 @@
         return getGlobalSiteManager().adapters.lookup(
             (model_schema, request_interface), IEntry).schema
 
+    @property
+    def range_factory_class(self):
+        """See `ICollection`."""
+        return self.relationship.range_factory_class
+
     def find(self):
         """See `ICollection`."""
         return self.collection
 
=== modified file 'src/lazr/restful/declarations.py'
--- src/lazr/restful/declarations.py	2018-09-28 15:46:34 +0000
+++ src/lazr/restful/declarations.py	2018-10-02 06:38:17 +0000
@@ -354,7 +354,7 @@
     return field
 
 
-def export_as_webservice_collection(entry_schema):
+def export_as_webservice_collection(entry_schema, range_factory_class=None):
     """Mark the interface as exported on the web service as a collection.
 
     :raises TypeError: if the interface doesn't have a method decorated with
@@ -369,7 +369,8 @@
     # check it.
     tags = _get_interface_tags()
     tags[LAZR_WEBSERVICE_EXPORTED] = dict(
-        type=COLLECTION_TYPE, collection_entry_schema=entry_schema)
+        type=COLLECTION_TYPE, collection_entry_schema=entry_schema,
+        collection_range_factory_class=range_factory_class)
 
     def mark_collection(interface):
         """Class advisor that tags the interface once it is created."""
@@ -846,15 +847,18 @@
     """Specify that the exported operation returns a collection.
 
     The decorator takes one required argument, "schema", an interface that's
-    been exported as an entry.
+    been exported as an entry, and one optional argument,
+    "range_factory_class", which specifies a custom class implementing
+    IRangeFactory to be used to adapt results for this collection.
     """
-    def __init__(self, schema):
+    def __init__(self, schema, range_factory_class=None):
         _check_called_from_interface_def('%s()' % self.__class__.__name__)
         if not IInterface.providedBy(schema):
             raise TypeError('Collection value type %s does not provide '
                             'IInterface.' % schema)
         self.return_type = CollectionField(
-            value_type=Reference(schema=schema))
+            value_type=Reference(schema=schema),
+            range_factory_class=range_factory_class)
 
     def annotate_method(self, method, annotations):
         annotations['return_type'] = self.return_type
@@ -1355,8 +1359,10 @@
         "version '%s'." % (interface.__name__, version))
     method_name, params = default_content_by_version[version]
     entry_schema = tag['collection_entry_schema']
+    range_factory_class = tag['collection_range_factory_class']
     class_dict = {
         'entry_schema' : CollectionEntrySchema(entry_schema),
+        'range_factory_class': range_factory_class,
         'method_name': method_name,
         'params': params,
         '__doc__': interface.__doc__,
 
=== modified file 'src/lazr/restful/docs/webservice-declarations.txt'
--- src/lazr/restful/docs/webservice-declarations.txt	2018-09-28 15:41:05 +0000
+++ src/lazr/restful/docs/webservice-declarations.txt	2018-10-02 06:38:17 +0000
@@ -215,6 +215,7 @@
     >>> print_export_tag(IBookSet)
     collection_default_content: {None: ('getAllBooks', {})}
     collection_entry_schema: <InterfaceClass __builtin__.IBook>
+    collection_range_factory_class: None
     type: 'collection'
 
     >>> print_export_tag(ICheckedOutBookSet)
@@ -222,6 +223,7 @@
             {'title': '',
              'user': <class '...REQUEST_USER'>})}
     collection_entry_schema: <InterfaceClass __builtin__.IBook>
+    collection_range_factory_class: None
     type: 'collection'
 
 The entry schema for a collection must be provided and must be an
@@ -231,7 +233,7 @@
     ...     export_as_webservice_collection()
     Traceback (most recent call last):
       ...
-    TypeError: export_as_webservice_collection() takes exactly 1
+    TypeError: export_as_webservice_collection() takes at least 1
     argument (0 given)
 
     >>> class InvalidEntrySchema(Interface):
@@ -355,12 +357,25 @@
 a single entry; @operation_returns_collection_of is used when the
 operation returns a collection of entries.
 
+    >>> from lazr.batchnavigator import ListRangeFactory
     >>> from lazr.restful.declarations import (
     ...     export_operation_as, export_factory_operation,
     ...     export_read_operation, operation_parameters,
     ...     operation_returns_entry, operation_returns_collection_of,
     ...     rename_parameters_as)
     >>> from lazr.restful.interface import copy_field
+
+    >>> class RecordingRangeFactory(ListRangeFactory):
+    ...     calls = []
+    ...
+    ...     def getEndpointMemos(self, batch):
+    ...         self.calls.append('getEndpointMemos')
+    ...         return ListRangeFactory.getEndpointMemos(self, batch)
+    ...
+    ...     def getSlice(self, size, memo, forwards):
+    ...         self.calls.append(('getSlice', size, memo, forwards))
+    ...         return ListRangeFactory.getSlice(self, size, memo, forwards)
+
     >>> class IBookSetOnSteroids(IBookSet):
     ...     """IBookSet supporting some methods."""
     ...     export_as_webservice_collection(IBook)
@@ -375,6 +390,17 @@
     ...
     ...     @operation_parameters(
     ...         text=copy_field(IBook['title'], title=u'Text to search for.'))
+    ...     @operation_returns_collection_of(
+    ...         IBook, range_factory_class=RecordingRangeFactory)
+    ...     @export_read_operation()
+    ...     def searchBookTitlesCustomRange(text):
+    ...         """Return list of books whose titles contain 'text'.
+    ...
+    ...         This method uses a custom range factory.
+    ...         """
+    ...
+    ...     @operation_parameters(
+    ...         text=copy_field(IBook['title'], title=u'Text to search for.'))
     ...     @operation_returns_entry(IBook)
     ...     @export_read_operation()
     ...     def bestMatch(text):
@@ -442,6 +468,22 @@
     params: {'text': <...TextLine...>}
     return_type: <lazr.restful.fields.CollectionField object...>
     type: 'read_operation'
+    >>> print IBookSetOnSteroids['searchBookTitles'].getTaggedValue(
+    ...     'lazr.restful.exported')['return_type'].range_factory_class
+    None
+
+The 'searchBookTitlesCustomRange' method is just the same, except that it
+uses a custom range factory.
+
+    >>> print_export_tag(IBookSetOnSteroids['searchBookTitlesCustomRange'])
+    as: 'searchBookTitlesCustomRange'
+    call_with: {}
+    params: {'text': <...TextLine...>}
+    return_type: <lazr.restful.fields.CollectionField object...>
+    type: 'read_operation'
+    >>> print IBookSetOnSteroids['searchBookTitlesCustomRange'].getTaggedValue(
+    ...     'lazr.restful.exported')['return_type'].range_factory_class
+    <class 'RecordingRangeFactory'>
 
 The 'bestMatch' method returns an entry.
 
@@ -1187,6 +1229,9 @@
     ...     def searchBookTitles(self, text):
     ...         return self.result
     ...
+    ...     def searchBookTitlesCustomRange(self, text):
+    ...         return self.result
+    ...
     ...     def new(self, author, base_price, title):
     ...         return Book(author, title, base_price, "unknown")
 
@@ -2584,7 +2629,7 @@
 
     >>> print debug_proxy(ProxyFactory(collection_adapter))
     zope.security._proxy._Proxy (using zope.security.checker.Checker)
-        public: entry_schema, find
+        public: entry_schema, find, range_factory_class
 
     >>> print debug_proxy(ProxyFactory(read_method_adapter))
     zope.security._proxy._Proxy (using zope.security.checker.Checker)
 
=== modified file 'src/lazr/restful/docs/webservice.txt'
--- src/lazr/restful/docs/webservice.txt	2018-10-01 08:55:53 +0000
+++ src/lazr/restful/docs/webservice.txt	2018-10-02 06:38:17 +0000
@@ -609,13 +609,27 @@
     ...             singular="recipe", plural="recipes",
     ...             publish_web_link=True))
 
+    >>> from lazr.batchnavigator import ListRangeFactory
+    >>> class RecordingRangeFactory(ListRangeFactory):
+    ...     calls = []
+    ...
+    ...     def getEndpointMemos(self, batch):
+    ...         self.calls.append('getEndpointMemos')
+    ...         return ListRangeFactory.getEndpointMemos(self, batch)
+    ...
+    ...     def getSlice(self, size, memo, forwards):
+    ...         self.calls.append(('getSlice', size, memo, forwards))
+    ...         return ListRangeFactory.getSlice(self, size, memo, forwards)
+
     >>> from lazr.restful.fields import ReferenceChoice
     >>> class ICookbookEntry(IEntry):
     ...     name = TextLine(title=u"Name", required=True)
     ...     cuisine = TextLine(title=u"Cuisine", required=False, default=None)
     ...     author = ReferenceChoice(
     ...         schema=IAuthor, vocabulary=AuthorVocabulary())
-    ...     recipes = CollectionField(value_type=Reference(schema=IRecipe))
+    ...     recipes = CollectionField(
+    ...         value_type=Reference(schema=IRecipe),
+    ...         range_factory_class=RecordingRangeFactory)
     ...     comments = CollectionField(value_type=Reference(schema=IComment))
     ...     cover = Bytes(0, 5000, title=u"An image of the cookbook's cover.")
     ...     taggedValue(
@@ -785,10 +799,12 @@
     ...     """
     ...
     ...     entry_schema = ICookbookEntry
+    ...     range_factory_class = RecordingRangeFactory
     ...
     ...     def find(self):
-    ...        """Find all the cookbooks."""
-    ...        return self.context.getAll()
+    ...         """Find all the cookbooks."""
+    ...         return self.context.getAll()
+
     >>> sm.registerAdapter(CookbookCollection,
     ...                   (ICookbookSet, IWebServiceClientRequest),
     ...                   provided=ICollection)
@@ -1190,6 +1206,8 @@
 But if we ask for a page size of two, we can see how pagination
 works. Here's page one, with two cookbooks on it.
 
+    >>> RecordingRangeFactory.calls = []
+
     >>> request = create_web_service_request(
     ...     '/beta/cookbooks', environ={'QUERY_STRING' : 'ws.size=2'})
     >>> collection = request.traverse(app)
@@ -1222,6 +1240,36 @@
     >>> len(representation['entries'])
     1
 
+Serving this collection uses the custom range factory.
+
+    >>> 'getEndpointMemos' in RecordingRangeFactory.calls
+    True
+
+Similarly, serving a scoped collection uses the custom range factory, if one
+is defined.
+
+    >>> RecordingRangeFactory.calls = []
+
+    >>> request = create_web_service_request(
+    ...     '/beta/cookbooks/The Joy of Cooking/recipes',
+    ...     environ={'QUERY_STRING': 'ws.size=1'})
+    >>> collection = request.traverse(app)
+    >>> representation = load_json(collection())
+
+    >>> sorted(representation.keys())
+    [u'entries', u'next_collection_link', u'resource_type_link',
+     u'start', u'total_size']
+    >>> representation['next_collection_link']
+    u'http://api.cookbooks.dev/beta/cookbooks/The%20Joy%20of%20Cooking/recipes?ws.size=1&memo=1&ws.start=1'
+    >>> len(representation['entries'])
+    1
+    >>> representation['total_size']
+    2
+
+    >>> 'getEndpointMemos' in RecordingRangeFactory.calls
+    True
+
+
 Custom operations
 =================
 
 
=== modified file 'src/lazr/restful/fields.py'
--- src/lazr/restful/fields.py	2016-02-17 01:07:21 +0000
+++ src/lazr/restful/fields.py	2018-10-02 06:38:17 +0000
@@ -25,7 +25,7 @@
     # has a _type of list, and we don't want to have to implement list
     # semantics for this class.
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, range_factory_class=None, *args, **kwargs):
         """A generic collection field.
 
         The readonly property defaults to True since these fields are usually
@@ -34,6 +34,7 @@
         """
         kwargs.setdefault('readonly', True)
         super(CollectionField, self).__init__(*args, **kwargs)
+        self.range_factory_class = range_factory_class
 
 
 @implementer(IReference)
 
=== modified file 'src/lazr/restful/interfaces/_fields.py'
--- src/lazr/restful/interfaces/_fields.py	2011-01-19 22:29:32 +0000
+++ src/lazr/restful/interfaces/_fields.py	2018-10-02 06:38:17 +0000
@@ -34,6 +34,11 @@
     All iterables satisfy this collection field.
     """
 
+    range_factory_class = Attribute(
+        "A class implementing IRangeFactory to be used to adapt results "
+        "for this collection field, or None.")
+
+
 class IReference(IObject):
     """A reference to an object providing a particular schema.
 
 
=== modified file 'src/lazr/restful/interfaces/_rest.py'
--- src/lazr/restful/interfaces/_rest.py	2011-03-31 01:13:59 +0000
+++ src/lazr/restful/interfaces/_rest.py	2018-10-02 06:38:17 +0000
@@ -224,6 +224,9 @@
     """A collection, driven by an ICollectionResource."""
 
     entry_schema = Attribute("The schema for this collection's entries.")
+    range_factory_class = Attribute(
+        "A class implementing IRangeFactory to be used to adapt results "
+        "for this collection, or None.")
 
     def find():
         """Retrieve all entries in the collection under the given scope.