Debian Codegraph @

src/lazr/restfulclient/docs/entries.rst

raw
1 ******************
2 Entry manipulation
3 ******************
4
5 Objects available through the web interface, such as cookbooks, have a
6 readable interface which is available through direct attribute access.
7
8 >>> from lazr.restfulclient.tests.example import CookbookWebServiceClient
9 >>> service = CookbookWebServiceClient()
10
11 >>> recipe = service.recipes[1]
12 >>> print recipe.instructions
13 You can always judge...
14
15 These objects may have a number of attributes, as well as associated
16 entries and collections.
17
18 >>> cookbook = recipe.cookbook
19 >>> print cookbook.name
20 Mastering the Art of French Cooking
21
22 >>> len(cookbook.recipes)
23 2
24
25 The lp_* introspection methods let you know what you can do with an
26 object. You can also use dir(), but it'll be cluttered with all sorts
27 of other stuff.
28
29 >>> sorted(dir(cookbook))
30 [..., 'confirmed', 'copyright_date', 'cover', ... 'find_recipes',
31 ..., 'recipes', ...]
32 >>> sorted(cookbook.lp_attributes)
33 ['confirmed', 'copyright_date', ..., 'resource_type_link', ...,
34 'self_link', 'web_link']
35
36 >>> sorted(cookbook.lp_entries)
37 ['cover']
38 >>> sorted(cookbook.lp_collections)
39 ['recipes']
40 >>> sorted(cookbook.lp_operations)
41 ['find_recipe_for', 'find_recipes', 'make_more_interesting',
42 'replace_cover']
43
44 Some attributes can only take on certain values. The lp_values_for
45 method will show you these values.
46
47 >>> sorted(cookbook.lp_values_for('cuisine'))
48 ['American', 'Dessert', u'Fran\xe7aise', 'General', 'Vegetarian']
49
50 Some attributes don't have a predefined list of acceptable values. For
51 them, lp_values_for() returns None.
52
53 >>> print cookbook.lp_values_for('copyright_date')
54 None
55
56 Some of these attributes can be changed. For example, a client can
57 change a recipe's preparation instructions. When changing attribute values
58 though, the changes are not pushed to the web service until the entry
59 is explicitly saved. This allows the client to batch the changes over
60 the wire for efficiency.
61
62 >>> recipe.instructions = 'Modified instructions'
63 >>> print service.recipes[1].instructions
64 You can always judge...
65
66 Once the changes are saved though, they are propagated to the web
67 service.
68
69 >>> recipe.lp_save()
70 >>> print service.recipes[1].instructions
71 Modified instructions
72
73 An entry object is a normal Python object like any other. Attributes
74 of an entry, like 'cuisine' or 'cookbook', are available as attributes
75 on the resource, and may be set. Random strings that are not
76 attributes of the entry cannot be set or read as Python attributes.
77
78 >>> recipe.instructions = 'Different instructions'
79 >>> recipe.is_great = True
80 Traceback (most recent call last):
81 ...
82 AttributeError: 'Entry' object has no attribute 'is_great'
83
84 >>> recipe.is_great
85 Traceback (most recent call last):
86 ...
87 AttributeError: http://cookbooks.dev/1.0/recipes/1 object has no attribute 'is_great'
88
89 The client can set more than one attribute on an entry at a time:
90 they'll all be changed when the entry is saved.
91
92 >>> cookbook.cuisine
93 u'Fran\xe7aise'
94 >>> cookbook.description
95 u''
96
97 >>> cookbook.cuisine = 'Dessert'
98 >>> cookbook.description = "A new description"
99 >>> cookbook.lp_save()
100
101 >>> cookbook = service.recipes[1].cookbook
102
103 >>> print cookbook.cuisine
104 Dessert
105 >>> print cookbook.description
106 A new description
107
108 Some of an entry's attributes may take other resources as values.
109
110 >>> old_cookbook = recipe.cookbook
111 >>> other_cookbook = service.cookbooks['Everyday Greens']
112 >>> print other_cookbook.name
113 Everyday Greens
114 >>> recipe.cookbook = other_cookbook
115 >>> recipe.lp_save()
116 >>> print recipe.cookbook.name
117 Everyday Greens
118
119 >>> recipe.cookbook = old_cookbook
120 >>> recipe.lp_save()
121
122
123 Refreshing data
124 ---------------
125
126 Here are two objects representing recipe #1. We'll fetch a
127 representation for the first object right away...
128
129 >>> recipe_copy = service.recipes[1]
130 >>> print recipe_copy.instructions
131 Different instructions
132
133 ...but retrieve the second object in a way that doesn't fetch its
134 representation.
135
136 >>> recipe_copy_2 = service.recipes(1)
137
138 An entry is automatically refreshed after saving.
139
140 >>> recipe.instructions = 'Even newer instructions'
141 >>> recipe.lp_save()
142 >>> print recipe.instructions
143 Even newer instructions
144
145 If an old object representing that entry already has a representation,
146 it will still show the old data.
147
148 >>> print recipe_copy.instructions
149 Different instructions
150
151 If an old object representing that entry doesn't have a representation
152 yet, it will show the new data.
153
154 >>> print recipe_copy_2.instructions
155 Even newer instructions
156
157 You can also refresh a resource object manually.
158
159 >>> recipe_copy.lp_refresh()
160 >>> print recipe_copy.instructions
161 Even newer instructions
162
163 Bookmarking an entry
164 --------------------
165
166 You can get an entry's URL from the 'self_link' attribute, save the
167 URL for a while, and retrieve the entry later using the load()
168 function.
169
170 >>> bookmark = recipe.self_link
171 >>> new_recipe = service.load(bookmark)
172 >>> print new_recipe.dish.name
173 Roast chicken
174
175 You can bookmark a URI relative to the version of the web service
176 currently in use.
177
178 >>> cookbooks = service.load("cookbooks")
179 >>> assert isinstance(cookbooks._wadl_resource.url, basestring)
180 >>> print cookbooks._wadl_resource.url
181 http://cookbooks.dev/1.0/cookbooks
182 >>> print cookbooks['The Joy of Cooking'].self_link
183 http://cookbooks.dev/1.0/cookbooks/The%20Joy%20of%20Cooking
184
185 >>> cookbook = service.load("/cookbooks/The%20Joy%20of%20Cooking")
186 >>> assert isinstance(cookbook._wadl_resource.url, basestring)
187 >>> print cookbook._wadl_resource.url
188 http://cookbooks.dev/1.0/cookbooks/The%20Joy%20of%20Cooking
189 >>> print cookbook.self_link
190 http://cookbooks.dev/1.0/cookbooks/The%20Joy%20of%20Cooking
191
192 >>> service_root = service.load("")
193 >>> assert isinstance(service_root._wadl_resource.url, basestring)
194 >>> print service_root._wadl_resource.url
195 http://cookbooks.dev/1.0/
196 >>> print service_root.cookbooks['The Joy of Cooking'].name
197 The Joy of Cooking
198
199 But you can't provide the web service version and bookmark a URI
200 relative to the service root.
201
202 >>> cookbooks = service.load("/1.0/cookbooks")
203 Traceback (most recent call last):
204 ...
205 NotFound: HTTP Error 404: Not Found
206 ...
207
208 (That code attempts to load http://cookbooks.dev/1.0/1.0/cookbooks,
209 which doesn't exist.)
210
211 You can't bookmark an absolute or relative URI that has nothing to do
212 with the web service.
213
214 >>> bookmark = 'http://cookbooks.dev/'
215 >>> service.load(bookmark)
216 Traceback (most recent call last):
217 ...
218 NotFound: HTTP Error 404: Not Found
219 ...
220
221 >>> service.load("/no-such-url")
222 Traceback (most recent call last):
223 ...
224 NotFound: HTTP Error 404: Not Found
225 ...
226
227 You can't bookmark the return value of a named operation. This is not
228 really desirable, but that's how things work right now.
229
230 >>> url_without_type = ('http://cookbooks.dev/1.0/cookbooks' +
231 ... '?ws.op=find_recipes&search=a')
232 >>> service.load(url_without_type)
233 Traceback (most recent call last):
234 ...
235 ValueError: Couldn't determine the resource type of...
236
237 Moving an entry
238 ---------------
239
240 Some entries will move to different URLs when a client changes their
241 data attributes. For instance, a cookbook's URL is determined by its
242 name.
243
244 >>> cookbook = service.cookbooks['The Joy of Cooking']
245 >>> print cookbook.name
246 The Joy of Cooking
247 >>> old_link = cookbook.self_link
248 >>> print old_link
249 http://cookbooks.dev/1.0/cookbooks/The%20Joy%20of%20Cooking
250 >>> cookbook.name = "Another Name"
251 >>> cookbook.lp_save()
252
253 Change the name, and you change the URL.
254
255 >>> new_link = cookbook.self_link
256 >>> print new_link
257 http://cookbooks.dev/1.0/cookbooks/Another%20Name
258
259 Old bookmarks won't work anymore.
260
261 >>> print service.load(old_link)
262 Traceback (most recent call last):
263 ...
264 NotFound: HTTP Error 404: Not Found
265 ...
266
267 >>> print service.load(new_link).name
268 Another Name
269
270 Under the covers though, a refresh of the original object has been
271 retrieved from the web service, so it's safe to continue using, and
272 changing it.
273
274 >>> cookbook.description = u'This cookbook was renamed'
275 >>> cookbook.lp_save()
276 >>> print service.load(new_link).description
277 This cookbook was renamed
278
279 It's just as easy to move this cookbook back to the old name.
280
281 >>> cookbook.name = 'The Joy of Cooking'
282 >>> cookbook.lp_save()
283
284 Now the old bookmark works again, and the new bookmark no longer works.
285
286 >>> print service.load(old_link).name
287 The Joy of Cooking
288
289 >>> print service.load(new_link)
290 Traceback (most recent call last):
291 ...
292 NotFound: HTTP Error 404: Not Found
293 ...
294
295 Validation
296 ----------
297
298 Some attributes are subject to validation. For instance, a cookbook's
299 cuisine is limited to one of a few selections.
300
301 >>> from lazr.restfulclient.errors import HTTPError
302 >>> def print_error_on_save(entry):
303 ... try:
304 ... entry.lp_save()
305 ... except HTTPError, error:
306 ... for line in sorted(error.content.splitlines()):
307 ... print line.decode("utf-8")
308 ... else:
309 ... print 'Did not get expected HTTPError!'
310
311 >>> cookbook.cuisine = 'No such cuisine'
312 >>> print_error_on_save(cookbook)
313 cuisine: Invalid value "No such cuisine". Acceptable values are: ...
314 >>> cookbook.cuisine = 'General'
315
316 Some attributes can't be modified at all.
317
318 >>> cookbook.copyright_date = None
319 >>> print_error_on_save(cookbook)
320 copyright_date: You tried to modify a read-only attribute.
321
322 If the client tries to save an entry that has more than one problem,
323 it will get back an error message listing all the problems.
324
325 >>> cookbook.cuisine = 'No such cuisine'
326 >>> print_error_on_save(cookbook)
327 copyright_date: You tried to modify a read-only attribute.
328 cuisine: Invalid value "No such cuisine". Acceptable values are: ...
329
330
331 Server-side data massage
332 ------------------------
333
334 Send bad data and your request will be rejected. But if you send data
335 that's not quite what the server is expecting, the server may accept
336 it while tweaking it. This means that the state of your object after
337 you call lp_save() may be slightly different from the object before
338 you called lp_save().
339
340 >>> cookbook.lp_refresh()
341 >>> cookbook.description = " Some extraneous whitespace "
342 >>> cookbook.lp_save()
343 >>> cookbook.description
344 u'Some extraneous whitespace'
345
346 Data types
347 ----------
348
349 Incoming data is serialized from JSON, and all the JSON data types
350 appear to the end-user as native Python data types. But there's no
351 standard serialization for JSON dates, so those are handled
352 separately. From the perspective of the end-user, date and date-time
353 fields always look like Python datetime objects or None.
354
355 >>> cookbook.copyright_date
356 datetime.datetime(1995, 1, 1,...)
357
358 >>> from datetime import datetime
359 >>> cookbook.last_printing = datetime(2009, 1, 1)
360 >>> cookbook.lp_save()
361
362
363 Avoiding conflicts
364 ==================
365
366 lazr.restful and lazr.restfulclient work together to try to avoid
367 situations where one person unknowingly overwrites another's
368 work. Here, two different clients are interested in the same
369 lazr.restful object.
370
371 >>> first_client = CookbookWebServiceClient()
372 >>> first_cookbook = first_client.load(cookbook.self_link)
373 >>> first_description = first_cookbook.description
374
375 >>> second_client = CookbookWebServiceClient()
376 >>> second_cookbook = second_client.load(cookbook.self_link)
377 >>> second_cookbook.description == first_description
378 True
379
380 The first client decides to change the description.
381
382 >>> first_cookbook.description = 'A description.'
383 >>> first_cookbook.lp_save()
384
385 The second client tries to make a conflicting change, but the server
386 detects that the second client doesn't have the latest information,
387 and rejects the request.
388
389 >>> second_cookbook.description = 'A conflicting description.'
390 >>> second_cookbook.lp_save()
391 Traceback (most recent call last):
392 ...
393 PreconditionFailed: HTTP Error 412: Precondition Failed
394 ...
395
396 Now the second client has a chance to look at the changes that were
397 made, before making their own changes.
398
399 >>> second_cookbook.lp_refresh()
400 >>> print second_cookbook.description
401 A description.
402
403 >>> second_cookbook.description = 'A conflicting description.'
404 >>> second_cookbook.lp_save()
405
406 Conflict detection works even when you operate on an object you
407 retrieved from a collection.
408
409 >>> first_cookbook = first_client.cookbooks[:10][0]
410 >>> second_cookbook = second_client.cookbooks[:10][0]
411 >>> first_cookbook.name == second_cookbook.name
412 True
413
414 >>> first_cookbook.description = "A description"
415 >>> first_cookbook.lp_save()
416
417 >>> second_cookbook.description = "A conflicting description"
418 >>> second_cookbook.lp_save()
419 Traceback (most recent call last):
420 ...
421 PreconditionFailed: HTTP Error 412: Precondition Failed
422 ...
423
424 >>> second_cookbook.lp_refresh()
425 >>> print second_cookbook.description
426 A description
427
428 >>> second_cookbook.description = "A conflicting description"
429 >>> second_cookbook.lp_save()
430
431 >>> first_cookbook.lp_refresh()
432 >>> print first_cookbook.description
433 A conflicting description
434
435
436 Comparing entries
437 -----------------
438
439 Two entries are equal if they represent the same state of the same
440 server-side resource.
441
442 >>> from lazr.restfulclient.tests.example import CookbookWebServiceClient
443 >>> service = CookbookWebServiceClient()
444
445 What does this mean? Well, two distinct objects that represent the
446 same resource are equal.
447
448 >>> recipe = service.recipes[1]
449 >>> recipe_2 = service.load(recipe.self_link)
450 >>> recipe is recipe_2
451 False
452
453 >>> recipe == recipe_2
454 True
455 >>> recipe != recipe_2
456 False
457
458 Two totally different entries are not equal.
459
460 >>> another_recipe = service.recipes[2]
461 >>> recipe == another_recipe
462 False
463
464 An entry can be compared to None, but the comparison never succeeds.
465
466 >>> recipe == None
467 False
468
469 If one entry represents the current state of the server, and the other
470 is out of date or has client-side modifications, they will not be
471 considered equal.
472
473 Here, 'recipe' has been modified and 'recipe_2' represents the current
474 state of the server.
475
476 >>> recipe.instructions = "Modified for equality testing."
477 >>> recipe == recipe_2
478 False
479
480 After a save, 'recipe' is up to date, and 'recipe_2' is out of date.
481
482 >>> recipe.lp_save()
483 >>> recipe == recipe_2
484 False
485
486 Refreshing 'recipe_2' brings it up to date, and equality succeeds again.
487
488 >>> recipe_2.lp_refresh()
489 >>> recipe == recipe_2
490 True
491
492 If you make the *exact same* client-side modifications to two objects
493 representing the same resource, the objects will be considered equal.
494
495 >>> recipe.instructions = "Modified again."
496 >>> recipe_2.instructions = recipe.instructions
497 >>> recipe == recipe_2
498 True
499
500 If you then save one of the objects, they will stop being equal,
501 because the saved object has a new ETag.
502
503 >>> recipe.lp_save()
504 >>> recipe == recipe_2
505 False
506
507 Server-side permissions
508 -----------------------
509
510 The server may hide some data from you because you lack the permission
511 to see it. To avoid objects that are mysteriously missing fields, the
512 server will serve a special "redacted" value that lets you know you
513 don't have permission to see the data.
514
515 >>> from lazr.restfulclient.tests.example import CookbookWebServiceClient
516 >>> service = CookbookWebServiceClient()
517
518 >>> cookbook = service.recipes[1].cookbook
519 >>> print cookbook.confirmed
520 tag:launchpad.net:2008:redacted
521
522 If you try to make an HTTP request for the "redacted" value (usually
523 by following a link that you don't know is redacted), you'll get a
524 helpful error.
525
526 >>> service.load("tag:launchpad.net:2008:redacted")
527 Traceback (most recent call last):
528 ...
529 ValueError: You tried to access a resource that you don't have the
530 server-side permission to see.
531
532 Deleting an entry
533 =================
534
535 Some entries can be deleted with the lp_delete method.
536
537 Before demonstrating this, let's acquire the underlying data model
538 objects so that we can restore the entry later. This is a bit of a
539 hack, but it's a lot less work than any alternative.
540
541 >>> from lazr.restful.example.base.interfaces import IRecipeSet
542 >>> from zope.component import getUtility
543 >>> recipe_set = getUtility(IRecipeSet)
544 >>> underlying_recipe = recipe_set.get(6)
545 >>> underlying_cookbook = underlying_recipe.cookbook
546
547 Now let's delete the entry.
548
549 >>> recipe = service.recipes[6]
550 >>> print recipe.lp_delete()
551 None
552
553 A deleted entry no longer exists.
554
555 >>> recipe.lp_refresh()
556 Traceback (most recent call last):
557 ...
558 NotFound: HTTP Error 404: Not Found
559 ...
560
561 Some entries can't be deleted.
562
563 >>> cookbook.lp_delete()
564 Traceback (most recent call last):
565 ...
566 MethodNotAllowed: HTTP Error 405: Method Not Allowed
567 ...
568
569 Cleanup: restore the deleted recipe.
570
571 >>> recipe_set.recipes.append(underlying_recipe)
572 >>> underlying_cookbook.recipes.append(underlying_recipe)
573
574 When are representations fetched?
575 =================================
576
577 To avoid unnecessary HTTP requests, a representation of an entry is
578 fetched at the last possible moment. Let's see what that means.
579
580 >>> import httplib2
581 >>> httplib2.debuglevel = 1
582
583 >>> service = CookbookWebServiceClient()
584 send: ...
585 ...
586
587 Here's an entry we got from a lookup operation on a top-level
588 collection. The default top-level lookup operation fetches a
589 representation of an entry immediately so as to immediately signal
590 errors.
591
592 >>> recipe = service.recipes[1]
593 send: 'GET /1.0/recipes/1 ...'
594 ...
595
596 But there's also a lookup operation that only triggers an HTTP request
597 when we try to get some data from the entry:
598
599 >>> recipe1 = service.recipes(1)
600
601 This gives a recipe object, because CookbookWebServiceClient happens
602 to know that the 'recipes' collection contains recipe objects.
603
604 Here's the dish associated with that original recipe entry. Traversing
605 from one entry to another causes an HTTP request for the first entry
606 (the recipe). Without this HTTP request, there's no way to know the
607 URL of the dish.
608
609 >>> dish = recipe1.dish
610 send: 'GET /1.0/recipes/1 ...'
611 ...
612
613 Note that this request is a request for the _recipe_, not the dish. We
614 don't need to know anything about the dish yet. And now that we have a
615 representation of the recipe, we can traverse from the recipe to its
616 cookbook without making another request.
617
618 >>> cookbook = recipe1.cookbook
619
620 Accessing any information about an entry we've traversed to _will_
621 cause an HTTP request.
622
623 >>> print dish.name
624 send: 'GET /1.0/dishes/Roast%20chicken ...'
625 ...
626 Roast chicken
627
628 Invoking a named operation also causes one (and only one) HTTP
629 request.
630
631 >>> recipes = cookbook.find_recipes(search="foo")
632 send: 'GET /1.0/cookbooks/...ws.op=find_recipes...'
633 ...
634
635 Even dereferencing an entry from another entry and then invoking a
636 named operation causes only one HTTP request.
637
638 >>> recipes = recipe1.cookbook.find_recipes(search="bar")
639 send: 'GET /1.0/cookbooks/...ws.op=find_recipes...'
640 ...
641
642 In all cases we are able to delay HTTP requests until the moment we
643 need data that can only be found by making those HTTP requests (even
644 if, as in the first example, that data is "does this object
645 exist?). If it turns out we never need that data, we've eliminated a
646 request entirely.
647
648 If CookbookWebServiceClient didn't know that the 'recipes' collection
649 contained recipe objects, then doing a lookup on that collection *would*
650 trigger an HTTP request. There'd simply be no other way to know what
651 kind of object was at the other end of the URL.
652
653 >>> from lazr.restfulclient.tests.example import RecipeSet
654 >>> old_collection_of = RecipeSet.collection_of
655 >>> RecipeSet.collection_of = None
656
657 >>> recipe1 = service.recipes[1]
658 send: 'GET /1.0/recipes/1 ...'
659 ...
660
661 On the plus side, at least accessing this object's properties doesn't
662 require _another_ HTTP request.
663
664 >>> print recipe1.instructions
665 Modified again.
666
667 Cleanup.
668
669 >>> RecipeSet.collection_of = old_collection_of
670 >>> httplib2.debuglevel = 0