Merge lp:~benji/lazr.restful/deterministic-wadl-from-trunk into lp:lazr.restful

[Benji York]

Make the generated WADL consistent for a given input so it doesn't vary from one call to the next.

Make the generated WADL consistent for a given input so it doesn't vary from one call to the next.

[lp:~benji/lazr.restful/deterministic-wadl-from-trunk]

141. By Benji York on 2010-08-24

remove unneeded version pin

[Leonard Richardson (leonardr)]

Needs some minor changes:

1. Move sorted_named_things() to utils.py and its test to doc/utils.txt
2. Get rid of the 'distribute' line.
3. You don't need to use exec(). You can create your own InterfaceClass with a custom __dict__. Look at declarations.py for an example.

        entry_interface = InterfaceClass(
            class_name, bases=(IEntry, ), attrs=attrs,
            __doc__=interface.__doc__, __module__=interface.__module__)

review: Needs Fixing

[lp:~benji/lazr.restful/deterministic-wadl-from-trunk]

142. By Benji York on 2010-08-24

checkpoint review-inspired refactorings; it works but part of it is nasty

143. By Benji York on 2010-08-24

remove unneeded line

[Benji York (benji)]

On Tue, Aug 24, 2010 at 4:13 PM, Leonard Richardson
<email address hidden> wrote:
> Review: Needs Fixing
> Needs some minor changes:
>
> 1. Move sorted_named_things() to utils.py and its test to doc/utils.txt
> 2. Get rid of the 'distribute' line.

The above two are done.

> 3. You don't need to use exec(). You can create your own InterfaceClass with a custom __dict__. Look at declarations.py for an example.
>
>        entry_interface = InterfaceClass(
>            class_name, bases=(IEntry, ), attrs=attrs,
>            __doc__=interface.__doc__, __module__=interface.__module__)

To get the above to work I had to emulate the effects of
generate_entry_interfaces (by copying a big chunk of code out of it)
because it is only usable as an old-style class decorator.

This cure seems worse than the disease. We can 1) refactor the bits
that I need into a callable and call it or 2) put the exec back.

I'd rather go with number 2 because the test code is easier to
understand (despite the exec) because it is doing the same things a
"normal" piece of code would do to reach the same ends (i.e., using
generate_entry_interfaces as a class decorator), instead of calling a
function who's only call site is in a test.

Strong opinions one way or the other?
--
Benji York

[Leonard Richardson (leonardr)]

> To get the above to work I had to emulate the effects of
> generate_entry_interfaces (by copying a big chunk of code out of it)
> because it is only usable as an old-style class decorator.

I see. Although it would be nice to be able to create dynamic interfaces, but since only one test needs to do it right now, I'm fine with the exec(). Go ahead and change it back, and merge the branch.

[Leonard Richardson (leonardr)]

review: Approve

[lp:~benji/lazr.restful/deterministic-wadl-from-trunk]

144. By Benji York on 2010-08-25

restore slightly icky code that is better than the really icky code

=== modified file 'src/lazr/restful/_resource.py'
--- src/lazr/restful/_resource.py	2010-08-18 16:41:58 +0000
+++ src/lazr/restful/_resource.py	2010-08-25 13:24:44 +0000
@@ -28,16 +28,13 @@
     ]
 
 
+from datetime import datetime, date
+from email.Utils import formatdate
 import cgi
 import copy
-from cStringIO import StringIO
-from datetime import datetime, date
-from email.Utils import formatdate
-from gzip import GzipFile
 import os
 import simplejson
 import time
-import zlib
 
 # Import SHA in a way compatible with both Python 2.4 and Python 2.6.
 try:
@@ -90,7 +87,8 @@
     IUnmarshallingDoesntNeedValue, IWebServiceClientRequest,
     IWebServiceConfiguration, IWebServiceLayer, IWebServiceVersion,
     LAZR_WEBSERVICE_NAME)
-from lazr.restful.utils import get_current_web_service_request
+from lazr.restful.utils import (
+    get_current_web_service_request, sorted_named_things)
 
 
 # The path to the WADL XML Schema definition.
@@ -1900,11 +1898,12 @@
                     # We omit IScopedCollection because those are handled
                     # by the entry classes.
                     collection_classes.append(registration.factory)
+
         namespace = self.WADL_TEMPLATE.pt_getContext()
         namespace['service'] = self
         namespace['request'] = self.request
-        namespace['entries'] = entry_classes
-        namespace['collections'] = collection_classes
+        namespace['entries'] = sorted_named_things(entry_classes)
+        namespace['collections'] = sorted_named_things(collection_classes)
         return self.WADL_TEMPLATE.pt_render(namespace)
 
     def toDataForJSON(self):

=== modified file 'src/lazr/restful/tales.py'
--- src/lazr/restful/tales.py	2010-08-09 20:05:08 +0000
+++ src/lazr/restful/tales.py	2010-08-25 13:24:44 +0000
@@ -6,6 +6,7 @@
 
 all = ['entry_adapter_for_schema']
 
+import operator
 import simplejson
 import textwrap
 import urllib
@@ -17,7 +18,7 @@
     adapts, getGlobalSiteManager, getUtility, queryMultiAdapter)
 from zope.interface import implements
 from zope.interface.interfaces import IInterface
-from zope.schema import getFieldsInOrder
+from zope.schema import getFields
 from zope.schema.interfaces import IBytes, IChoice, IDate, IDatetime, IObject
 from zope.security.proxy import removeSecurityProxy
 from zope.publisher.interfaces.browser import IBrowserRequest
@@ -255,7 +256,7 @@
             resource_dicts.append({'name' : link_name,
                                    'path' : "$['%s']" % link_name,
                                    'resource' : resource})
-        return resource_dicts
+        return sorted(resource_dicts, key=operator.itemgetter('name'))
 
 
 class WadlResourceAdapterAPI(RESTUtilityBase):
@@ -387,7 +388,7 @@
     def all_fields(self):
         "Return all schema fields for the object."
         return [field for name, field in
-                getFieldsInOrder(self.adapter.schema)]
+                sorted(getFields(self.adapter.schema).items())]
 
     @property
     def all_writable_fields(self):

=== modified file 'src/lazr/restful/tests/test_utils.py'
--- src/lazr/restful/tests/test_utils.py	2010-08-05 19:06:49 +0000
+++ src/lazr/restful/tests/test_utils.py	2010-08-25 13:24:44 +0000
@@ -4,6 +4,7 @@
 
 __metaclass__ = type
 
+import random
 import unittest
 
 from zope.publisher.browser import TestRequest
@@ -11,7 +12,7 @@
     endInteraction, newInteraction, queryInteraction)
 
 from lazr.restful.utils import (get_current_browser_request,
-    is_total_size_link_active)
+    is_total_size_link_active, sorted_named_things)
 
 
 class TestUtils(unittest.TestCase):
@@ -50,6 +51,30 @@
         self.assertEqual(is_total_size_link_active('2.0', FakeConfig), True)
         self.assertEqual(is_total_size_link_active('3.0', FakeConfig), True)
 
+    def test_name_sorter(self):
+        # The WADL generation often sorts classes or functions by name; the
+        # sorted_named_things helper... helps.
+
+        # First we need some named things to sort.
+        class Thing:
+            pass
+
+        def make_named_thing():
+            thing = Thing()
+            thing.__name__ = random.choice('abcdefghijk')
+            return thing
+
+        # The function sorts on the object's __name__ attribute, which
+        # functions and classes have, see:
+        assert hasattr(Thing, '__name__')
+        assert hasattr(make_named_thing, '__name__')
+
+        # Now we can make a bunch of things with randomly ordered names and
+        # show that sorting them does order them by name.
+        things = sorted_named_things(make_named_thing() for i in range(10))
+        names = [thing.__name__ for thing in things]
+        self.assertEqual(names, sorted(names))
+
     # For the sake of convenience, test_get_current_web_service_request()
     # and tag_request_with_version_name() are tested in test_webservice.py.
 

=== modified file 'src/lazr/restful/tests/test_webservice.py'
--- src/lazr/restful/tests/test_webservice.py	2010-08-10 18:36:09 +0000
+++ src/lazr/restful/tests/test_webservice.py	2010-08-25 13:24:44 +0000
@@ -6,10 +6,14 @@
 
 from cStringIO import StringIO
 from operator import attrgetter
+from textwrap import dedent
+import random
+import re
 import unittest
 
 from zope.component import getGlobalSiteManager, getUtility
 from zope.interface import implements, Interface
+from zope.interface.interface import InterfaceClass
 from zope.publisher.browser import TestRequest
 from zope.schema import Date, Datetime, TextLine
 from zope.security.management import newInteraction, queryInteraction
@@ -22,14 +26,14 @@
     IWebServiceConfiguration, IWebServiceClientRequest, IWebServiceVersion)
 from lazr.restful import EntryResource, ResourceGETOperation
 from lazr.restful.declarations import (
-    exported, export_as_webservice_entry, LAZR_WEBSERVICE_NAME)
+    exported, export_as_webservice_entry, LAZR_WEBSERVICE_NAME, annotate_exported_methods)
 from lazr.restful.testing.webservice import (
     create_web_service_request, IGenericCollection, IGenericEntry,
     WebServiceTestCase)
 from lazr.restful.testing.tales import test_tales
 from lazr.restful.utils import (
     get_current_browser_request, get_current_web_service_request,
-    tag_request_with_version_name)
+    tag_request_with_version_name, sorted_named_things)
 from lazr.restful._resource import CollectionResource, BatchingResourceMixin
 
 
@@ -277,6 +281,52 @@
             self.assertEquals(str(e), expected_error_message)
 
 
+def make_entry(name):
+    """Make an entity with some attibutes to expose as a web service."""
+    code = """
+        class %(name)s(Interface):
+            export_as_webservice_entry(singular_name='%(name)s')
+        """ % locals()
+
+    for letter in 'rstuvwxyz':
+        code += """
+            %(letter)s_field = exported(TextLine(title=u'Field %(letter)s'))
+            """ % locals()
+
+    exec dedent(code)
+    return locals()[name]
+
+
+class TestWadlDeterminism(WebServiceTestCase):
+    """We want the WADL generation to be consistent for a given input."""
+
+    def __init__(self, *args, **kwargs):
+        # make some -- randomly ordered -- objects to use to build the WADL
+        self.testmodule_objects = [make_entry(name) for name in 'abcdefghijk']
+        random.shuffle(self.testmodule_objects)
+        super(TestWadlDeterminism, self).__init__(*args, **kwargs)
+
+    @property
+    def wadl(self):
+        resource = getUtility(IServiceRootResource)
+        request = create_web_service_request('/2.0')
+        request.traverse(resource)
+        return resource.toWADL()
+
+    def test_entity_order(self):
+        # The entities should be listed in alphabetical order by class.
+        self.assertEqual(
+            re.findall(r'<wadl:resource_type id="(.)">', self.wadl),
+            ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k'])
+
+    def test_attribute_order(self):
+        # The individual entity attributes should be listed in alphabetical
+        # order by class.
+        self.assertEqual(
+            re.findall(r'<wadl:param [^>]* name="(.)_field">', self.wadl)[:9],
+            ['r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'])
+
+
 class DuplicateSingularNameTestCase(DuplicateNameTestCase):
     """Test AssertionError when resource types share a singular name."""
 

=== modified file 'src/lazr/restful/utils.py'
--- src/lazr/restful/utils.py	2010-08-05 14:08:20 +0000
+++ src/lazr/restful/utils.py	2010-08-25 13:24:44 +0000
@@ -20,6 +20,7 @@
 
 import cgi
 import copy
+import operator
 import re
 import string
 import subprocess
@@ -282,3 +283,9 @@
             )
     (output, nothing) = p.communicate(input)
     return output
+
+
+def sorted_named_things(things):
+    """Return a list of things (functions and/or classes) sorted by name."""
+    name = operator.attrgetter('__name__')
+    return sorted(things, key=name)

=== modified file 'versions.cfg'
--- versions.cfg	2010-08-18 15:33:46 +0000
+++ versions.cfg	2010-08-25 13:24:44 +0000
@@ -6,13 +6,13 @@
 [versions]
 # Alphabetical, case-SENSITIVE, blank line after this comment
 
-distribute = 0.6.14
 Jinja2 = 2.5
 Pygments = 1.3.1
 RestrictedPython = 3.5.1
 Sphinx = 1.0.1
 ZConfig = 2.7.1
 ZODB3 = 3.9.2
+distribute = 0.6.14
 docutils = 0.5
 epydoc = 3.0.1
 grokcore.component = 1.6