1
=== added file 'src/lazr/restful/docs/multiversion.txt'
2
--- src/lazr/restful/docs/multiversion.txt	1970-01-01 00:00:00 +0000
3
+++ src/lazr/restful/docs/multiversion.txt	2009-11-18 16:46:09 +0000
4
@@ -0,0 +1,292 @@
5
1
Publishing multiple versions of a web service
6
2
*********************************************
7
3
8
4
A single data model can yield many different lazr.restful web
9
5
services. Typically these different services represent successive
10
6
versions of a single web service, improved over time.
11
7
12
8
Example model objects
13
9
=====================
14
10
15
11
First let's define the data model. The model in webservice.txt is
16
12
pretty complicated; this model will be just complicated enough to
17
13
illustrate how to publish multiple versions of a web service.
18
14
19
15
    # All classes defined in this test are new-style classes.
20
16
    >>> __metaclass__ = type
21
17
22
18
    >>> from zope.interface import Interface, Attribute
23
19
    >>> from zope.schema import Bool, Bytes, Int, Text, TextLine, Object
24
20
25
21
    >>> class ITestDataObject(Interface):
26
22
    ...     """A marker interface for data objects."""
27
23
    ...     path = Attribute("The path portion of this object's URL. "
28
24
    ...                      "Defined here for simplicity of testing.")
29
25
30
26
    >>> class IContact(ITestDataObject):
31
27
    ...     name = TextLine(title=u"Name", required=True)
32
28
    ...     phone = TextLine(title=u"Phone number", required=True)
33
29
    ...     fax = TextLine(title=u"Fax number", required=False)
34
30
35
31
Here's the interface for the 'set' object that manages the contacts.
36
32
37
33
    >>> from lazr.restful.interfaces import ITraverseWithGet
38
34
    >>> class IContactSet(ITestDataObject, ITraverseWithGet):
39
35
    ...     def getAll(self):
40
36
    ...         "Get all contacts."
41
37
    ...
42
38
    ...     def get(self, name):
43
39
    ...         "Retrieve a single contact by name."
44
40
45
41
Before we can define any classes, a bit of web service setup. Let's
46
42
make all component lookups use the global site manager.
47
43
48
44
    >>> from zope.component import getSiteManager
49
45
    >>> sm = getSiteManager()
50
46
51
47
    >>> from zope.component import adapter
52
48
    >>> from zope.component.interfaces import IComponentLookup
53
49
    >>> from zope.interface import implementer, Interface
54
50
    >>> @implementer(IComponentLookup)
55
51
    ... @adapter(Interface)
56
52
    ... def everything_uses_the_global_site_manager(context):
57
53
    ...     return sm
58
54
    >>> sm.registerAdapter(everything_uses_the_global_site_manager)
59
55
60
56
Here's a simple implementation of IContact.
61
57
62
58
    >>> from urllib import quote
63
59
    >>> from zope.interface import implements
64
60
    >>> from lazr.restful.security import protect_schema
65
61
    >>> class Contact:
66
62
    ...     implements(IContact)
67
63
    ...     def __init__(self, name, phone, fax):
68
64
    ...         self.name = name
69
65
    ...         self.phone = phone
70
66
    ...         self.fax = fax
71
67
    ...
72
68
    ...     @property
73
69
    ...     def path(self):
74
70
    ...         return 'contacts/' + quote(self.name)
75
71
    >>> protect_schema(Contact, IContact)
76
72
77
73
Here's a simple ContactSet with a predefined list of contacts.
78
74
79
75
    >>> from lazr.restful.simple import TraverseWithGet
80
76
    >>> from zope.publisher.interfaces.browser import IBrowserRequest
81
77
    >>> class ContactSet(TraverseWithGet):
82
78
    ...     implements(IContactSet)
83
79
    ...     path = "contact"
84
80
    ...
85
81
    ...     def __init__(self):
86
82
    ...         self.contacts = CONTACTS
87
83
    ...
88
84
    ...     def get(self, name):
89
85
    ...         contacts = [contact for contacts in self.contacts
90
86
    ...                     if pair.name == name]
91
87
    ...         if len(contacts) == 1:
92
88
    ...             return contacts[0]
93
89
    ...         return None
94
90
    >>> sm.registerAdapter(TraverseWithGet, [ITestDataObject, IBrowserRequest])
95
91
96
92
Here are the "model objects" themselves:
97
93
98
94
    >>> C1 = Contact("Cleo Python", "555-1212", "111-2121")
99
95
    >>> C2 = Contact("Oliver Bluth", "10-1000000", "22-2222222")
100
96
    >>> CONTACTS = [C1, C2]
101
97
102
98
Web service infrastructure initialization
103
99
=========================================
104
100
105
101
The lazr.restful package contains a set of default adapters and
106
102
definitions to implement the web service.
107
103
108
104
    >>> from zope.configuration import xmlconfig
109
105
    >>> zcmlcontext = xmlconfig.string("""
110
106
    ... <configure xmlns="http://namespaces.zope.org/zope">
111
107
    ...   <include package="lazr.restful" file="basic-site.zcml"/>
112
108
    ...   <utility
113
109
    ...       factory="lazr.restful.example.base.filemanager.FileManager" />
114
110
    ... </configure>
115
111
    ... """)
116
112
117
113
A IWebServiceConfiguration utility is also expected to be defined which
118
114
defines common configuration option for the webservice.
119
115
120
116
    >>> from lazr.restful import directives
121
117
    >>> from lazr.restful.interfaces import IWebServiceConfiguration
122
118
    >>> from lazr.restful.simple import BaseWebServiceConfiguration
123
119
    >>> from lazr.restful.testing.webservice import WebServiceTestPublication
124
120
125
121
    >>> class WebServiceConfiguration(BaseWebServiceConfiguration):
126
122
    ...     use_https = False
127
123
    ...     active_versions = ['beta', '1.0']
128
124
    ...     latest_version_uri_prefix = 'dev'
129
125
    ...     code_revision = 'test'
130
126
    ...     max_batch_size = 100
131
127
    ...     directives.publication_class(WebServiceTestPublication)
132
128
133
129
    >>> from grokcore.component.testing import grok_component
134
130
    >>> ignore = grok_component(
135
131
    ...     'WebServiceConfiguration', WebServiceConfiguration)
136
132
137
133
    >>> from zope.component import getUtility
138
134
    >>> webservice_configuration = getUtility(IWebServiceConfiguration)
139
135
140
136
Defining the web service data model
141
137
===================================
142
138
143
139
We've defined an underlying data model (IContact), and now we're going
144
140
to define the evolution of a web service through three versions, by
145
141
defining three derivative data models. In a real application, these
146
142
IEntry subclasses would be generated from lazr.restful decorators
147
143
present in IContact but for testing purposes we're going to just
148
144
define the three IEntry subclasses manually.
149
145
150
146
The "beta" version of the web service publishes the IContact interface
151
147
exactly as it is defined.
152
148
153
149
    >>> from lazr.restful.interfaces import IEntry
154
150
    >>> class IContactEntry(IEntry):
155
151
    ...     """Marker for a contact published through the web service."""
156
152
157
153
    >>> from zope.interface import taggedValue
158
154
    >>> from lazr.restful.interfaces import IEntry, LAZR_WEBSERVICE_NAME
159
155
    >>> class IContactEntryBeta(IContactEntry, IContact):
160
156
    ...     """The part of an author we expose through the web service."""
161
157
    ...     taggedValue(LAZR_WEBSERVICE_NAME,
162
158
    ...                 dict(singular="contact", plural="contacts"))
163
159
164
160
The "1.0" version publishes the IContact interface as is, but renames
165
161
two of the fields.
166
162
167
163
    >>> class IContactEntry10(IContactEntry):
168
164
    ...     name = TextLine(title=u"Name", required=True)
169
165
    ...     phone_number = TextLine(title=u"Phone number", required=True)
170
166
    ...     fax_number = TextLine(title=u"Fax number", required=False)
171
167
    ...     taggedValue(LAZR_WEBSERVICE_NAME,
172
168
    ...                 dict(singular="contact", plural="contacts"))
173
169
174
170
The "dev" version drops the "fax_number" field because fax machines
175
171
are obsolete.
176
172
177
173
    >>> class IContactEntryDev(IContactEntry):
178
174
    ...     name = TextLine(title=u"Name", required=True)
179
175
    ...     phone_number = TextLine(title=u"Phone number", required=True)
180
176
    ...     taggedValue(LAZR_WEBSERVICE_NAME,
181
177
    ...                 dict(singular="contact", plural="contacts"))
182
178
183
179
Implementing the resources
184
180
==========================
185
181
186
182
The Contact class defined above implements the IContact interface, but
187
183
IContact just describes the data model, not any particular web
188
184
service. The IContactEntry subclasses above -- IContactEntryBeta,
189
185
IContactEntry10, IContactEntryDev -- describe the three versions of
190
186
the web service. Each of these interfaces must be implemented by a
191
187
subclass of Entry.
192
188
193
189
In a real application, the Entry subclasses would be generated from
194
190
lazr.restful decorators present in IContact (just like the IEntry
195
191
subclasses), but for testing purposes we're going to define the three
196
192
Entry subclasses manually.
197
193
198
194
    >>> from zope.component import adapts
199
195
    >>> from zope.interface import implements
200
196
    >>> from lazr.delegates import delegates
201
197
    >>> from lazr.restful import Entry
202
198
203
199
    >>> class ContactEntryBeta(Entry):
204
200
    ...     """A contact, as exposed through the 'beta' web service."""
205
201
    ...     adapts(IContact)
206
202
    ...     implements(IContactEntryBeta)
207
203
    ...     delegates(IContactEntryBeta)
208
204
    ...     schema = IContactEntryBeta
209
205
    >>> sm.registerAdapter(
210
206
    ...     ContactEntryBeta, provided=IContactEntry, name="beta")
211
207
212
208
By wrapping one of our predefined Contacts in a ContactEntryBeta
213
209
object, we can verify that it implements IContactEntryBeta and
214
210
IContactEntry.
215
211
216
212
    >>> entry = ContactEntryBeta(C1)
217
213
    >>> IContactEntry.validateInvariants(entry)
218
214
    >>> IContactEntryBeta.validateInvariants(entry)
219
215
220
216
Here's the implemenation of IContactEntry10, which defines Python
221
217
properties to implement the different field names.
222
218
223
219
    >>> class ContactEntry10(Entry):
224
220
    ...    adapts(IContact)
225
221
    ...    implements(IContactEntry10)
226
222
    ...    schema = IContactEntry10
227
223
    ...
228
224
    ...    def __init__(self, contact):
229
225
    ...        self.contact = contact
230
226
    ...
231
227
    ...    @property
232
228
    ...    def phone_number(self):
233
229
    ...        return self.contact.phone
234
230
    ...
235
231
    ...    @property
236
232
    ...    def fax_number(self):
237
233
    ...        return self.contact.fax
238
234
    >>> sm.registerAdapter(
239
235
    ...     ContactEntry10, provided=IContactEntry, name="1.0")
240
236
241
237
    >>> entry = ContactEntry10(C1)
242
238
    >>> IContactEntry.validateInvariants(entry)
243
239
    >>> IContactEntry10.validateInvariants(entry)
244
240
245
241
Finally, here's the implementation of IContactEntry for the "dev" version of
246
242
the web service.
247
243
248
244
    >>> class ContactEntryDev(Entry):
249
245
    ...    adapts(IContact)
250
246
    ...    implements(IContactEntryDev)
251
247
    ...    schema = IContactEntryDev
252
248
    ...
253
249
    ...    def __init__(self, contact):
254
250
    ...        self.contact = contact
255
251
    ...
256
252
    ...    @property
257
253
    ...    def phone_number(self):
258
254
    ...        return self.contact.phone
259
255
    >>> sm.registerAdapter(
260
256
    ...     ContactEntryDev, provided=IContactEntry, name="dev")
261
257
262
258
    >>> entry = ContactEntryDev(C1)
263
259
    >>> IContactEntry.validateInvariants(entry)
264
260
    >>> IContactEntryDev.validateInvariants(entry)
265
261
266
262
Looking up the appropriate implementation
267
263
=========================================
268
264
269
265
Because there is no single IEntry implementation for Contact objects,
270
266
you can't just adapt Contact to IEntry.
271
267
272
268
    >>> from zope.component import getAdapter
273
269
274
270
    >>> getAdapter(C1, IEntry)
275
271
    Traceback (most recent call last):
276
272
    ...
277
273
    ComponentLookupError: ...
278
274
279
275
When adapting Contact to IEntry you must specify a version number as
280
276
the name of the adapter. The object you get back will implement the
281
277
appropriate version of the web service.
282
278
283
279
    >>> beta_entry = getAdapter(C1, IEntry, name="beta")
284
280
    >>> print beta_entry.fax
285
281
    111-2121
286
282
287
283
    >>> one_oh_entry = getAdapter(C1, IEntry, name="1.0")
288
284
    >>> print one_oh_entry.fax_number
289
285
    111-2121
290
286
291
287
    >>> dev_entry = getAdapter(C1, IEntry, name="dev")
292
288
    >>> print dev_entry.fax
293
289
    Traceback (most recent call last):
294
290
    ...
295
291
    AttributeError: 'ContactEntryDev' object has no attribute 'fax'
296
292
297
0
293
298
=== modified file 'src/lazr/restful/docs/webservice.txt'
299
--- src/lazr/restful/docs/webservice.txt	2009-11-12 19:08:10 +0000
300
+++ src/lazr/restful/docs/webservice.txt	2009-11-18 16:46:09 +0000
301
@@ -74,28 +74,32 @@
302
74
Here's the interface for the 'set' objects that manage the authors,
74
Here's the interface for the 'set' objects that manage the authors,
303
75
cookbooks, and dishes. The inconsistent naming is intentional.
75
cookbooks, and dishes. The inconsistent naming is intentional.
304
76
76
306
77
    >>> class IAuthorSet(ITestDataObject):
77
    >>> from lazr.restful.interfaces import ITraverseWithGet
307
78
    >>> class ITestDataSet(ITestDataObject, ITraverseWithGet):
308
79
    ...     """A marker interface."""
309
80
310
81
    >>> class IAuthorSet(ITestDataSet):
311
78
    ...     def getAllAuthors(self):
82
    ...     def getAllAuthors(self):
312
79
    ...         "Get all authors."
83
    ...         "Get all authors."
313
80
    ...
84
    ...
315
81
    ...     def get(self, name):
85
    ...     def get(self, request, name):
316
82
    ...         "Retrieve a single author by name."
86
    ...         "Retrieve a single author by name."
317
83
87
319
84
    >>> class ICookbookSet(ITestDataObject):
88
    >>> class ICookbookSet(ITestDataSet):
320
85
    ...     def getAll(self):
89
    ...     def getAll(self):
321
86
    ...         "Get all cookbooks."
90
    ...         "Get all cookbooks."
322
87
    ...
91
    ...
324
88
    ...     def get(self, name):
92
    ...     def get(self, request, name):
325
89
    ...         "Retrieve a single cookbook by name."
93
    ...         "Retrieve a single cookbook by name."
326
90
    ...
94
    ...
327
91
    ...     def findRecipes(self, name):
95
    ...     def findRecipes(self, name):
328
92
    ...         "Find recipes with a given name, across cookbooks."
96
    ...         "Find recipes with a given name, across cookbooks."
329
93
97
331
94
    >>> class IDishSet(ITestDataObject):
98
    >>> class IDishSet(ITestDataSet):
332
95
    ...     def getAll(self):
99
    ...     def getAll(self):
333
96
    ...         "Get all dishes."
100
    ...         "Get all dishes."
334
97
    ...
101
    ...
336
98
    ...     def get(self, name):
102
    ...     def get(self, request, name):
337
99
    ...         "Retrieve a single dish by name."
103
    ...         "Retrieve a single dish by name."
338
100
104
339
101
105
340
@@ -143,23 +147,6 @@
341
143
    ...     BaseAbsoluteURL, [ITestDataObject, IBrowserRequest],
147
    ...     BaseAbsoluteURL, [ITestDataObject, IBrowserRequest],
342
144
    ...     IAbsoluteURL)
148
    ...     IAbsoluteURL)
343
145
149
344
146
    >>> from urllib import unquote
345
147
    >>> class Traversable:
346
148
    ...     """A default IPublishTraverse that uses the get() method."""
347
149
    ...     implements(IPublishTraverse)
348
150
    ...     adapts(ITestDataObject, IBrowserRequest)
349
151
    ...
350
152
    ...     def __init__(self, context, request):
351
153
    ...         self.context = context
352
154
    ...
353
155
    ...     def publishTraverse(self, request, name):
354
156
    ...         name = unquote(name)
355
157
    ...         value = self.context.get(name)
356
158
    ...         if value is None:
357
159
    ...             raise NotFound(self, name)
358
160
    ...         return value
359
161
    >>> sm.registerAdapter(Traversable)
360
162
361
163
    >>> class Author:
150
    >>> class Author:
362
164
    ...     implements(IAuthor)
151
    ...     implements(IAuthor)
363
165
    ...     def __init__(self, name):
152
    ...     def __init__(self, name):
364
@@ -219,6 +206,7 @@
365
219
206
366
220
    >>> protect_schema(Cookbook, ICookbook, write_permission=CheckerPublic)
207
    >>> protect_schema(Cookbook, ICookbook, write_permission=CheckerPublic)
367
221
208
368
209
    >>> from urllib import unquote
369
222
    >>> class CookbookTraversal:
210
    >>> class CookbookTraversal:
370
223
    ...     implements(IPublishTraverse)
211
    ...     implements(IPublishTraverse)
371
224
    ...     adapts(ICookbook, IBrowserRequest)
212
    ...     adapts(ICookbook, IBrowserRequest)
372
@@ -358,7 +346,8 @@
373
358
346
374
359
Here's a simple CookbookSet with a predefined list of cookbooks.
347
Here's a simple CookbookSet with a predefined list of cookbooks.
375
360
348
377
361
    >>> class CookbookSet(BaseAbsoluteURL):
349
    >>> from lazr.restful.simple import TraverseWithGet
378
350
    >>> class CookbookSet(BaseAbsoluteURL, TraverseWithGet):
379
362
    ...     implements(ICookbookSet)
351
    ...     implements(ICookbookSet)
380
363
    ...     path = 'cookbooks'
352
    ...     path = 'cookbooks'
381
364
    ...
353
    ...
382
@@ -367,7 +356,7 @@
383
367
    ...
356
    ...
384
368
    ...     def newCookbook(self, author_name, title, cuisine):
357
    ...     def newCookbook(self, author_name, title, cuisine):
385
369
    ...         authors = AuthorSet()
358
    ...         authors = AuthorSet()
387
370
    ...         author = authors.get(author_name)
359
    ...         author = authors.get(None, author_name)
388
371
    ...         if author is None:
360
    ...         if author is None:
389
372
    ...             author = authors.newAuthor(author_name)
361
    ...             author = authors.newAuthor(author_name)
390
373
    ...         cookbook = Cookbook(title, author, cuisine)
362
    ...         cookbook = Cookbook(title, author, cuisine)
391
@@ -377,7 +366,7 @@
392
377
    ...     def getAll(self):
366
    ...     def getAll(self):
393
378
    ...         return self.cookbooks
367
    ...         return self.cookbooks
394
379
    ...
368
    ...
396
380
    ...     def get(self, name):
369
    ...     def get(self, request, name):
397
381
    ...         match = [c for c in self.cookbooks if c.name == name]
370
    ...         match = [c for c in self.cookbooks if c.name == name]
398
382
    ...         if len(match) > 0:
371
    ...         if len(match) > 0:
399
383
    ...             return match[0]
372
    ...             return match[0]
400
@@ -402,7 +391,7 @@
401
402
391
402
403
Here's a simple AuthorSet with predefined authors.
392
Here's a simple AuthorSet with predefined authors.
403
404
393
405
405
    >>> class AuthorSet(BaseAbsoluteURL):
394
    >>> class AuthorSet(BaseAbsoluteURL, TraverseWithGet):
406
406
    ...     implements(IAuthorSet)
395
    ...     implements(IAuthorSet)
407
407
    ...     path = 'authors'
396
    ...     path = 'authors'
408
408
    ...
397
    ...
409
@@ -417,16 +406,15 @@
410
417
    ...     def getAllAuthors(self):
406
    ...     def getAllAuthors(self):
411
418
    ...         return self.authors
407
    ...         return self.authors
412
419
    ...
408
    ...
414
420
    ...     def get(self, name):
409
    ...     def get(self, request, name):
415
421
    ...         match = [p for p in self.authors if p.name == name]
410
    ...         match = [p for p in self.authors if p.name == name]
416
422
    ...         if len(match) > 0:
411
    ...         if len(match) > 0:
417
423
    ...             return match[0]
412
    ...             return match[0]
418
424
    ...         return None
413
    ...         return None
419
425
414
420
415
    >>> sm.registerAdapter(TraverseWithGet, [ITestDataObject, IBrowserRequest])
421
426
    >>> protect_schema(AuthorSet, IAuthorSet)
416
    >>> protect_schema(AuthorSet, IAuthorSet)
422
427
    >>> sm.registerUtility(AuthorSet(), IAuthorSet)
417
    >>> sm.registerUtility(AuthorSet(), IAuthorSet)
423
428
    >>> sm.registerAdapter(
424
429
    ...     Traversable, [IAuthorSet, IBrowserRequest])
425
430
418
426
431
Here's a vocabulary of authors, for a field that presents a Choice
419
Here's a vocabulary of authors, for a field that presents a Choice
427
432
among authors.
420
among authors.
428
@@ -448,7 +436,7 @@
429
448
436
430
449
Finally, a simple DishSet with predefined dishes.
437
Finally, a simple DishSet with predefined dishes.
431
450
438
433
451
    >>> class DishSet(BaseAbsoluteURL):
439
    >>> class DishSet(BaseAbsoluteURL, TraverseWithGet):
434
452
    ...     implements(IDishSet)
440
    ...     implements(IDishSet)
435
453
    ...     path = 'dishes'
441
    ...     path = 'dishes'
436
454
    ...     def __init__(self):
442
    ...     def __init__(self):
437
@@ -457,7 +445,7 @@
438
457
    ...     def getAll(self):
445
    ...     def getAll(self):
439
458
    ...         return self.dishes
446
    ...         return self.dishes
440
459
    ...
447
    ...
442
460
    ...     def get(self, name):
448
    ...     def get(self, request, name):
443
461
    ...         match = [d for d in self.dishes if d.name == name]
449
    ...         match = [d for d in self.dishes if d.name == name]
444
462
    ...         if len(match) > 0:
450
    ...         if len(match) > 0:
445
463
    ...             return match[0]
451
    ...             return match[0]
446
@@ -546,27 +534,20 @@
447
546
interface and ``IEntry``. Since ``IAuthor`` and ``IComment`` are so simple, we
534
interface and ``IEntry``. Since ``IAuthor`` and ``IComment`` are so simple, we
448
547
can define ``IAuthorEntry`` and ``ICommentEntry`` very simply.
535
can define ``IAuthorEntry`` and ``ICommentEntry`` very simply.
449
548
536
451
549
    >>> from lazr.restful.interfaces import IEntry
537
The only extra and unusual step we have to take is to annotate the interfaces
452
538
with human-readable names for the objects we're exposing.
453
539
454
540
    >>> from zope.interface import taggedValue
455
541
    >>> from lazr.restful.interfaces import IEntry, LAZR_WEBSERVICE_NAME
456
550
    >>> class IAuthorEntry(IAuthor, IEntry):
542
    >>> class IAuthorEntry(IAuthor, IEntry):
457
551
    ...     """The part of an author we expose through the web service."""
543
    ...     """The part of an author we expose through the web service."""
458
544
    ...     taggedValue(LAZR_WEBSERVICE_NAME, dict(singular="author",
459
545
    ...                                            plural="authors"))
460
552
546
461
553
    >>> class ICommentEntry(IComment, IEntry):
547
    >>> class ICommentEntry(IComment, IEntry):
462
554
    ...     """The part of a comment we expose through the web service."""
548
    ...     """The part of a comment we expose through the web service."""
478
555
549
    ...     taggedValue(LAZR_WEBSERVICE_NAME,
479
556
The only extra and unusual step we have to take is to annotate the interfaces
550
    ...         dict(singular="comment", plural="comments"))
465
557
with human-readable names for the objects we're exposing.
466
558
467
559
    >>> from lazr.restful.interfaces import LAZR_WEBSERVICE_NAME
468
560
469
561
    # XXX leonardr 2008-07-09 bug=145746
470
562
    # Once we're using Zope 3.4 we can call
471
563
    # zope.interface.taggedValue(LAZR_WEBSERVICE_NAME, dict(...))
472
564
    # from within the interface declaration.
473
565
    >>> def tag_with_names(interface, singular, plural):
474
566
    ...     interface.setTaggedValue(
475
567
    ...         LAZR_WEBSERVICE_NAME, dict(singular=singular, plural=plural))
476
568
    >>> tag_with_names(IAuthorEntry, 'author', 'authors')
477
569
    >>> tag_with_names(ICommentEntry, 'comment', 'comments')
480
570
551
481
571
Most of the time, it doesn't work to expose to the web service the same data
552
Most of the time, it doesn't work to expose to the web service the same data
482
572
model we expose internally. Usually there are fields we don't want to expose,
553
model we expose internally. Usually there are fields we don't want to expose,
483
@@ -586,7 +567,8 @@
484
586
    >>> class IDishEntry(IEntry):
567
    >>> class IDishEntry(IEntry):
485
587
    ...     "The part of a dish that we expose through the web service."
568
    ...     "The part of a dish that we expose through the web service."
486
588
    ...     recipes = CollectionField(value_type=Object(schema=IRecipe))
569
    ...     recipes = CollectionField(value_type=Object(schema=IRecipe))
488
589
    >>> tag_with_names(IDishEntry, 'dish', 'dishes')
570
    ...     taggedValue(LAZR_WEBSERVICE_NAME,
489
571
    ...         dict(singular="dish", plural="dishes"))
490
590
572
491
591
In the following code block we define an interface that exposes the underlying
573
In the following code block we define an interface that exposes the underlying
492
592
``Recipe``'s name but not its ID. References to associated objects (like the
574
``Recipe``'s name but not its ID. References to associated objects (like the
493
@@ -599,7 +581,8 @@
494
599
    ...     dish = Object(schema=IDish)
581
    ...     dish = Object(schema=IDish)
495
600
    ...     instructions = Text(title=u"Name", required=True)
582
    ...     instructions = Text(title=u"Name", required=True)
496
601
    ...     comments = CollectionField(value_type=Object(schema=IComment))
583
    ...     comments = CollectionField(value_type=Object(schema=IComment))
498
602
    >>> tag_with_names(IRecipeEntry, 'recipe', 'recipes')
584
    ...     taggedValue(LAZR_WEBSERVICE_NAME,
499
585
    ...         dict(singular="recipe", plural="recipes"))
500
603
586
501
604
    >>> from lazr.restful.fields import ReferenceChoice
587
    >>> from lazr.restful.fields import ReferenceChoice
502
605
    >>> class ICookbookEntry(IEntry):
588
    >>> class ICookbookEntry(IEntry):
503
@@ -610,7 +593,8 @@
504
610
    ...     recipes = CollectionField(value_type=Object(schema=IRecipe))
593
    ...     recipes = CollectionField(value_type=Object(schema=IRecipe))
505
611
    ...     comments = CollectionField(value_type=Object(schema=IComment))
594
    ...     comments = CollectionField(value_type=Object(schema=IComment))
506
612
    ...     cover = Bytes(0, 5000, title=u"An image of the cookbook's cover.")
595
    ...     cover = Bytes(0, 5000, title=u"An image of the cookbook's cover.")
508
613
    >>> tag_with_names(ICookbookEntry, 'cookbook', 'cookbooks')
596
    ...     taggedValue(LAZR_WEBSERVICE_NAME,
509
597
    ...         dict(singular="cookbook", plural="cookbooks"))
510
614
598
511
615
The ``author`` field is a choice between ``Author`` objects. To make sure
599
The ``author`` field is a choice between ``Author`` objects. To make sure
512
616
that the ``Author`` objects are properly marshalled to JSON, we need to
600
that the ``Author`` objects are properly marshalled to JSON, we need to
513
@@ -947,7 +931,7 @@
514
947
    >>> from lazr.restful import ServiceRootResource
931
    >>> from lazr.restful import ServiceRootResource
515
948
    >>> from zope.traversing.browser.interfaces import IAbsoluteURL
932
    >>> from zope.traversing.browser.interfaces import IAbsoluteURL
516
949
933
518
950
    >>> class MyServiceRootResource(ServiceRootResource):
934
    >>> class MyServiceRootResource(ServiceRootResource, TraverseWithGet):
519
951
    ...     implements(IAbsoluteURL)
935
    ...     implements(IAbsoluteURL)
520
952
    ...     path = ''
936
    ...     path = ''
521
953
    ...
937
    ...
522
@@ -956,7 +940,7 @@
523
956
    ...         'cookbooks': CookbookSet(),
940
    ...         'cookbooks': CookbookSet(),
524
957
    ...         'authors': AuthorSet()}
941
    ...         'authors': AuthorSet()}
525
958
    ...
942
    ...
527
959
    ...     def get(self, name):
943
    ...     def get(self, request, name):
528
960
    ...         return self.top_level_names.get(name)
944
    ...         return self.top_level_names.get(name)
529
961
945
530
962
It's the responsibility of each web service to provide an implementation of
946
It's the responsibility of each web service to provide an implementation of
531
@@ -964,8 +948,7 @@
532
964
948
533
965
    >>> sm.registerAdapter(
949
    >>> sm.registerAdapter(
534
966
    ...     BaseAbsoluteURL, [MyServiceRootResource, IBrowserRequest])
950
    ...     BaseAbsoluteURL, [MyServiceRootResource, IBrowserRequest])
537
967
    >>> sm.registerAdapter(
951
536
968
    ...     Traversable, [IServiceRootResource, IBrowserRequest])
538
969
    >>> app = MyServiceRootResource()
952
    >>> app = MyServiceRootResource()
539
970
    >>> sm.registerUtility(app, IServiceRootResource)
953
    >>> sm.registerUtility(app, IServiceRootResource)
540
971
954
Status:	Merged
Approved by:	Edwin Grubbs on 2009-11-18
Approved revision:	not available
Merged at revision:	not available
Proposed branch:	lp:~leonardr/lazr.restful/double-your-enjoyment
Merge into:	lp:lazr.restful
Diff against target:	539 lines (+330/-55) 2 files modified src/lazr/restful/docs/multiversion.txt (+292/-0) src/lazr/restful/docs/webservice.txt (+38/-55)
To merge this branch:	bzr merge lp:~leonardr/lazr.restful/double-your-enjoyment
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
Edwin Grubbs (community)	code	2009-11-17	Approve on 2009-11-18
Review via email: mp+14967@code.launchpad.net