1
=== modified file 'src/lazr/restful/docs/webservice-declarations.txt'
2
--- src/lazr/restful/docs/webservice-declarations.txt	2010-01-28 14:21:19 +0000
3
+++ src/lazr/restful/docs/webservice-declarations.txt	2010-01-28 18:11:15 +0000
4
@@ -888,7 +888,7 @@
5
888
    >>> class MyWebServiceConfiguration:
888
    >>> class MyWebServiceConfiguration:
6
889
    ...     implements(IWebServiceConfiguration)
889
    ...     implements(IWebServiceConfiguration)
7
890
    ...     view_permission = "lazr.View"
890
    ...     view_permission = "lazr.View"
9
891
    ...     active_versions = ["beta"]
891
    ...     active_versions = ["beta", "1.0", "2.0", "3.0"]
10
892
    ...     code_revision = "1.0b"
892
    ...     code_revision = "1.0b"
11
893
    ...     default_batch_size = 50
893
    ...     default_batch_size = 50
12
894
    ...     latest_version_uri_prefix = 'beta'
894
    ...     latest_version_uri_prefix = 'beta'
13
@@ -1855,11 +1855,7 @@
14
1855
    <lazr.restful.fields.CollectionField object...>
1855
    <lazr.restful.fields.CollectionField object...>
15
1856
1856
16
1857
[XXX leonardr mutator_for modifies the field, not the method, so it
1857
[XXX leonardr mutator_for modifies the field, not the method, so it
22
1858
won't work until I add multiversion support for fields. Also, it's
1858
won't work until I add multiversion support for fields.]
18
1859
possible to remove a named operation from a certain version and then
19
1860
uselessly annotate it some more. The best place to catch this error
20
1861
turns out to be when generating the adapter classes, not when
21
1862
collecting annotations.]
23
1863
1859
24
1864
Security
1860
Security
25
1865
========
1861
========
26
@@ -1895,7 +1891,6 @@
27
1895
    zope.security._proxy._Proxy (using zope.security.checker.Checker)
1891
    zope.security._proxy._Proxy (using zope.security.checker.Checker)
28
1896
        public: __call__, send_modification_event
1892
        public: __call__, send_modification_event
29
1897
1893
30
1898
=================
31
1899
ZCML Registration
1894
ZCML Registration
32
1900
=================
1895
=================
33
1901
1896
34
@@ -1908,23 +1903,34 @@
35
1908
1903
36
1909
    >>> import sys
1904
    >>> import sys
37
1910
    >>> from types import ModuleType
1905
    >>> from types import ModuleType
46
1911
    >>> bookexample = ModuleType('bookexample')
1906
    >>> def create_test_module(name, *contents):
47
1912
    >>> sys.modules['lazr.restful.bookexample'] = bookexample
1907
    ...     """Defines a new module and adds it to sys.modules."""
48
1913
    >>> bookexample.IBook = IBook
1908
    ...     new_module = ModuleType(name)
49
1914
    >>> bookexample.IBookSet = IBookSet
1909
    ...     sys.modules['lazr.restful.' + name] = new_module
50
1915
    >>> bookexample.IBookOnSteroids = IBookOnSteroids
1910
    ...     for object in contents:
51
1916
    >>> bookexample.IBookSetOnSteroids = IBookSetOnSteroids
1911
    ...         setattr(new_module, object.__name__, object)
52
1917
    >>> bookexample.ISimpleComment = ISimpleComment
1912
    ...     return new_module
45
1918
    >>> bookexample.InvalidEmail = InvalidEmail
53
1919
1913
54
1920
    >>> from zope.configuration import xmlconfig
1914
    >>> from zope.configuration import xmlconfig
62
1921
    >>> zcmlcontext = xmlconfig.string("""
1915
    >>> def register_test_module(name, *contents):
63
1922
    ... <configure
1916
    ...     new_module = create_test_module(name, *contents)
64
1923
    ...     xmlns:webservice="http://namespaces.canonical.com/webservice">
1917
    ...     try:
65
1924
    ...   <include package="lazr.restful" file="meta.zcml" />
1918
    ...         zcmlcontext = xmlconfig.string("""
66
1925
    ...   <webservice:register module="lazr.restful.bookexample" />
1919
    ...         <configure
67
1926
    ... </configure>
1920
    ...             xmlns:webservice=
68
1927
    ... """)
1921
    ...                 "http://namespaces.canonical.com/webservice">
69
1922
    ...           <include package="lazr.restful" file="meta.zcml" />
70
1923
    ...           <webservice:register module="lazr.restful.%s" />
71
1924
    ...         </configure>
72
1925
    ...         """ % name)
73
1926
    ...     except Exception, e:
74
1927
    ...         del sys.modules['lazr.restful.' + name]
75
1928
    ...         raise e
76
1929
    ...     return new_module
77
1930
78
1931
    >>> bookexample = register_test_module(
79
1932
    ...     'bookexample', IBook, IBookSet, IBookOnSteroids,
80
1933
    ...     IBookSetOnSteroids, ISimpleComment, InvalidEmail)
81
1928
1934
82
1929
After the registration, adapters from IBook to IEntry, and IBookSet to
1935
After the registration, adapters from IBook to IEntry, and IBookSet to
83
1930
ICollection are available:
1936
ICollection are available:
84
@@ -1980,3 +1986,60 @@
85
1980
1986
86
1981
    >>> del bookexample
1987
    >>> del bookexample
87
1982
    >>> del sys.modules['lazr.restful.bookexample']
1988
    >>> del sys.modules['lazr.restful.bookexample']
88
1989
89
1990
Error handling
90
1991
--------------
91
1992
92
1993
Some error handling happens in the ZCML registration phase. At this
93
1994
point, all the annotations have been processed, and the
94
1995
IWebServiceConfiguration utility (with its canonical list of versions)
95
1996
has become available. This lets us run checks on the versioning
96
1997
annotations that couldn't be run before.
97
1998
98
1999
Here's a class annotated by someone who believes that version 1.0 of
99
2000
the web service is a later version than version 2.0. (Or who believes
100
2001
that named operation annotations proceed from the top down rather than
101
2002
the bottom up.)
102
2003
103
2004
    >>> class WrongOrderVersions(Interface):
104
2005
    ...     export_as_webservice_entry()
105
2006
    ...     @export_operation_as('10_name')
106
2007
    ...     @operation_for_version("1.0")
107
2008
    ...     @operation_parameters(arg=Float())
108
2009
    ...     @export_read_operation()
109
2010
    ...     @operation_for_version("2.0")
110
2011
    ...     def method(arg):
111
2012
    ...         """A method."""
112
2013
113
2014
An attempt to register this module with ZCML results in an error
114
2015
explaining the problem.
115
2016
116
2017
    >>> register_test_module('wrongorder', WrongOrderVersions)
117
2018
    Traceback (most recent call last):
118
2019
    ...
119
2020
    ConfigurationExecutionError: <type 'exceptions.AssertionError'>:
120
2021
    Annotations on "WrongOrderVersions.method" put an earlier version
121
2022
    on top of a later version: "beta", "2.0", "1.0". The correct order
122
2023
    is: "beta", "1.0", "2.0".  ...
123
2024
124
2025
Here's a class in which a named operation is removed in version 1.0
125
2026
and then annotated without being reinstated.
126
2027
127
2028
    >>> class AnnotatingARemovedMethod(Interface):
128
2029
    ...     export_as_webservice_entry()
129
2030
    ...     @operation_parameters(arg=TextLine())
130
2031
    ...     @export_operation_as('already_been_removed')
131
2032
    ...     @operation_removed_in_version("1.0")
132
2033
    ...     @operation_parameters(arg=Float())
133
2034
    ...     @export_read_operation()
134
2035
    ...     @operation_for_version("2.0")
135
2036
    ...     def method(arg):
136
2037
    ...         """A method."""
137
2038
138
2039
    >>> register_test_module('annotatingremoved', AnnotatingARemovedMethod)
139
2040
    Traceback (most recent call last):
140
2041
    ...
141
2042
    ZopeXMLConfigurationError: ...
142
2043
    AssertionError: Method "method" contains annotations for version
143
2044
    "1.0", even though it's not published in that version. The bad
144
2045
    annotations are: "params", "as".
145
1983
2046
146
=== modified file 'src/lazr/restful/metazcml.py'
147
--- src/lazr/restful/metazcml.py	2010-01-27 17:33:32 +0000
148
+++ src/lazr/restful/metazcml.py	2010-01-28 18:11:15 +0000
149
@@ -34,6 +34,50 @@
150
34
        title=u'Module which will be inspected for webservice declarations')
34
        title=u'Module which will be inspected for webservice declarations')
151
35
35
152
36
36
153
37
def ensure_correct_version_ordering(name, version_list):
154
38
    """Make sure that a list mentions versions from earliest to latest.
155
39
156
40
    If an earlier version shows up after a later version, this is a
157
41
    sign that a developer was confused about version names when
158
42
    annotating the web service.
159
43
160
44
    :param name: The name of the object annotated with the
161
45
        possibly mis-ordered versions.
162
46
163
47
    :param version_list: The list of versions found in the interface.
164
48
165
49
    :raise AssertionError: If the given version list is not a
166
50
        earlier-to-later ordering of a subset of the web service's
167
51
        versions.
168
52
    """
169
53
    configuration = getUtility(IWebServiceConfiguration)
170
54
    actual_versions = configuration.active_versions + [
171
55
        configuration.latest_version_uri_prefix]
172
56
    # Replace None with the actual version number of the earliest
173
57
    # version.
174
58
    try:
175
59
        earliest_version_pos = version_list.index(None)
176
60
        version_list = list(version_list)
177
61
        version_list[earliest_version_pos] = actual_versions[0]
178
62
    except ValueError:
179
63
        # The earliest version was not mentioned in the version list.
180
64
        # Do nothing.
181
65
        pass
182
66
183
67
    # Sort version_list according to the list of actual versions.
184
68
    # If the sorted list is different from the unsorted list, at
185
69
    # least one version is out of place.
186
70
    def compare(x, y):
187
71
        return cmp (actual_versions.index(x), actual_versions.index(y))
188
72
    sorted_version_list = sorted(version_list, cmp=compare)
189
73
    if sorted_version_list != version_list:
190
74
        bad_versions = '", "'.join(version_list)
191
75
        good_versions = '", "'.join(sorted_version_list)
192
76
        msg = ('Annotations on "%s" put an earlier version on top of a '
193
77
               'later version: "%s". The correct order is: "%s".')
194
78
        raise AssertionError, msg % (name, bad_versions, good_versions)
195
79
196
80
197
37
def register_adapter_for_version(factory, interface, version_name,
81
def register_adapter_for_version(factory, interface, version_name,
198
38
                                 provides, name, info):
82
                                 provides, name, info):
199
39
    """A version-aware wrapper for the registerAdapter operation.
83
    """A version-aware wrapper for the registerAdapter operation.
200
@@ -147,6 +191,14 @@
201
147
            # This method is not published as a named operation.
191
            # This method is not published as a named operation.
202
148
            continue
192
            continue
203
149
193
204
194
        # First, make sure that this method was annotated with the
205
195
        # versions in the right order.
206
196
        context.action(
207
197
            discriminator=('webservice version ordering', method),
208
198
            callable=ensure_correct_version_ordering,
209
199
            args=(interface.__name__ + '.' + method.__name__, tag.dict_names)
210
200
        )
211
201
212
150
        operation_name = None
202
        operation_name = None
213
151
        # If an operation's name does not change between version n and
203
        # If an operation's name does not change between version n and
214
152
        # version n+1, we want lookups for requests that come in for
204
        # version n+1, we want lookups for requests that come in for
215
@@ -175,6 +227,26 @@
216
175
                operation_name = None
227
                operation_name = None
217
176
                operation_provides = None
228
                operation_provides = None
218
177
                factory = None
229
                factory = None
219
230
220
231
                # If there are any other tags besides 'type', it means
221
232
                # that the developer tried to annotate a method for a
222
233
                # version where the method isn't published. Let's warn
223
234
                # them about it.
224
235
                #
225
236
                # (We can't make this check when the annotation
226
237
                # happens, because it will reject a method that uses
227
238
                # an annotation like @export_operation_as before using
228
239
                # an annotation like @export_read_operation. That's a
229
240
                # little sloppy, but it's not bad enough to warrant an
230
241
                # exception.)
231
242
                tag_names = list(tag.keys())
232
243
                if tag_names != ['type']:
233
244
                    tag_names.remove('type')
234
245
                    raise AssertionError(
235
246
                        'Method "%s" contains annotations for version "%s", '
236
247
                        'even though it\'s not published in that version. '
237
248
                        'The bad annotations are: "%s".' % (
238
249
                            method.__name__, version, '", "'.join(tag_names)))
239
178
            else:
250
            else:
240
179
                if tag['type'] == 'read_operation':
251
                if tag['type'] == 'read_operation':
241
180
                    operation_provides = IResourceGETOperation
252
                    operation_provides = IResourceGETOperation
242
181
253
243
=== modified file 'src/lazr/restful/simple.py'
244
--- src/lazr/restful/simple.py	2010-01-12 15:06:15 +0000
245
+++ src/lazr/restful/simple.py	2010-01-28 18:11:15 +0000
246
@@ -32,8 +32,8 @@
247
32
32
248
33
from lazr.restful import EntryAdapterUtility, ServiceRootResource
33
from lazr.restful import EntryAdapterUtility, ServiceRootResource
249
34
from lazr.restful.interfaces import (
34
from lazr.restful.interfaces import (
252
35
    IServiceRootResource, ITraverseWithGet, IWebServiceConfiguration,
35
    IServiceRootResource, ITopLevelEntryLink, ITraverseWithGet,
253
36
    IWebServiceLayer)
36
    IWebServiceConfiguration, IWebServiceLayer)
254
37
from lazr.restful.publisher import (
37
from lazr.restful.publisher import (
255
38
    WebServicePublicationMixin, WebServiceRequestTraversal)
38
    WebServicePublicationMixin, WebServiceRequestTraversal)
256
39
from lazr.restful.utils import implement_from_dict
39
from lazr.restful.utils import implement_from_dict
Status:	Merged
Merged at revision:	not available
Proposed branch:	lp:~leonardr/lazr.restful/enforce-version-order
Merge into:	lp:lazr.restful
Diff against target:	256 lines (+159/-24) 3 files modified src/lazr/restful/docs/webservice-declarations.txt (+85/-22) src/lazr/restful/metazcml.py (+72/-0) src/lazr/restful/simple.py (+2/-2)
To merge this branch:	bzr merge lp:~leonardr/lazr.restful/enforce-version-order
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
Paul Hummer (community)		2010-01-28	Approve on 2010-01-28
Review via email: mp+18223@code.launchpad.net