| 1 |
***************** |
| 2 |
Top-level objects |
| 3 |
***************** |
| 4 |
|
| 5 |
Every web service has a top-level "root" object. |
| 6 |
|
| 7 |
>>> from lazr.restfulclient.tests.example import CookbookWebServiceClient |
| 8 |
>>> service = CookbookWebServiceClient() |
| 9 |
|
| 10 |
The root object provides access to service-wide objects. |
| 11 |
|
| 12 |
>>> sorted(service.lp_entries) |
| 13 |
['featured_cookbook'] |
| 14 |
|
| 15 |
>>> sorted(service.lp_collections) |
| 16 |
['cookbooks', 'dishes', 'recipes'] |
| 17 |
|
| 18 |
|
| 19 |
Top-level entries |
| 20 |
================= |
| 21 |
|
| 22 |
You can access a top-level entry through attribute access. |
| 23 |
|
| 24 |
>>> print service.featured_cookbook.name |
| 25 |
Mastering the Art of French Cooking |
| 26 |
|
| 27 |
|
| 28 |
Top-level collections |
| 29 |
===================== |
| 30 |
|
| 31 |
You can access a top-level collection through attribute access. |
| 32 |
|
| 33 |
>>> len(service.dishes) |
| 34 |
3 |
| 35 |
|
| 36 |
Specific top-level collections may support key-based lookups. For |
| 37 |
instance, the recipe collection does lookups by recipe ID. This is |
| 38 |
custom code written for this specific web service, and it won't work |
| 39 |
in general. |
| 40 |
|
| 41 |
>>> print service.recipes[1].dish.name |
| 42 |
Roast chicken |
| 43 |
|
| 44 |
Looking up an object in a top-level collection triggers an HTTP |
| 45 |
request, and if the object does not exist on the server, a KeyError is |
| 46 |
raised. |
| 47 |
|
| 48 |
>>> import httplib2 |
| 49 |
>>> httplib2.debuglevel = 1 |
| 50 |
>>> debug_service = CookbookWebServiceClient() |
| 51 |
send: 'GET ...' |
| 52 |
... |
| 53 |
|
| 54 |
>>> recipe = debug_service.recipes[4] |
| 55 |
send: 'GET /1.0/recipes/4 ...' |
| 56 |
... |
| 57 |
|
| 58 |
>>> recipe = debug_service.recipes[1000] |
| 59 |
Traceback (most recent call last): |
| 60 |
... |
| 61 |
KeyError: 1000 |
| 62 |
|
| 63 |
If you want to look up an object without triggering an HTTP request, |
| 64 |
you can use parentheses instead of square brackets. |
| 65 |
|
| 66 |
>>> recipe = debug_service.recipes(4) |
| 67 |
>>> nonexistent_recipe = debug_service.recipes(1000) |
| 68 |
|
| 69 |
>>> sorted(recipe.lp_attributes) |
| 70 |
['http_etag', 'id', 'instructions', ...] |
| 71 |
|
| 72 |
The HTTP request, and any potential error, happens when you try to |
| 73 |
access one of the object's properties. |
| 74 |
|
| 75 |
>>> print recipe.instructions |
| 76 |
send: 'GET /1.0/recipes/4 ...' |
| 77 |
... |
| 78 |
Preheat oven to... |
| 79 |
|
| 80 |
>>> print nonexistent_recipe.instructions |
| 81 |
Traceback (most recent call last): |
| 82 |
... |
| 83 |
NotFound: HTTP Error 404: Not Found |
| 84 |
... |
| 85 |
|
| 86 |
This is useful if you plan to invoke a named operation on the object |
| 87 |
instead of accessing its properties--this can save you an HTTP request |
| 88 |
and speed up your applicaiton. |
| 89 |
|
| 90 |
Now, let's imagine that a top-level collection is misconfigured. We |
| 91 |
know that the top-level collection of recipes contains objects whose |
| 92 |
resource type is 'recipe'. But let's tell lazr.restfulclient that that |
| 93 |
collection contains objects of type 'cookbook'. |
| 94 |
|
| 95 |
>>> from lazr.restfulclient.tests.example import RecipeSet |
| 96 |
>>> print RecipeSet.collection_of |
| 97 |
recipe |
| 98 |
>>> RecipeSet.collection_of = 'cookbook' |
| 99 |
|
| 100 |
Looking up an object will give you something that presents the |
| 101 |
interface of a cookbook. |
| 102 |
|
| 103 |
>>> not_really_a_cookbook = debug_service.recipes(2) |
| 104 |
>>> sorted(not_really_a_cookbook.lp_attributes) |
| 105 |
['confirmed', 'copyright_date', 'cuisine'...] |
| 106 |
|
| 107 |
But once you try to access one of the object's properties, and the |
| 108 |
HTTP request is made... |
| 109 |
|
| 110 |
>>> print not_really_a_cookbook.resource_type_link |
| 111 |
send: 'GET /1.0/recipes/2 ...' |
| 112 |
... |
| 113 |
http://cookbooks.dev/1.0/#recipe |
| 114 |
|
| 115 |
...the server serves a recipe, and so the client-side object takes on |
| 116 |
the properties of a recipe. You can only fool lazr.restfulclient up to |
| 117 |
the point where it has real data to look at. |
| 118 |
|
| 119 |
>>> sorted(not_really_a_cookbook.lp_attributes) |
| 120 |
['http_etag', 'id', 'instructions', ...] |
| 121 |
|
| 122 |
>>> print not_really_a_cookbook.instructions |
| 123 |
Draw, singe, stuff, and truss... |
| 124 |
|
| 125 |
This isn't just a defense mechanism: it's a useful feature when a |
| 126 |
top-level collection contains mixed subclasses of some superclass. For |
| 127 |
instance, the launchpadlib library defines the 'people' collection as |
| 128 |
containing 'team' objects, even though it also contains 'person' |
| 129 |
objects, which expose a subset of a team's functionality. All objects |
| 130 |
looked up in that collection start out as team objects, but once an |
| 131 |
object's data is fetched, if it turns out to actually be a person, it |
| 132 |
switches from the "team" interface to the "people" interface. (This |
| 133 |
bit of hackery is necessary because WADL doesn't have an inheritance |
| 134 |
mechanism.) |
| 135 |
|
| 136 |
If you try to access a property based on a resource type the object |
| 137 |
doesn't really implement, you'll get an error. |
| 138 |
|
| 139 |
>>> not_really_a_cookbook = debug_service.recipes(3) |
| 140 |
>>> sorted(not_really_a_cookbook.lp_attributes) |
| 141 |
['confirmed', 'copyright_date', 'cuisine'...] |
| 142 |
>>> not_really_a_cookbook.cuisine |
| 143 |
Traceback (most recent call last): |
| 144 |
... |
| 145 |
AttributeError: http://cookbooks.dev/1.0/recipes/3 object has no attribute 'cuisine' |
| 146 |
|
| 147 |
Cleanup. |
| 148 |
|
| 149 |
>>> httplib2.debuglevel = 0 |
| 150 |
>>> RecipeSet.collection_of = 'recipe' |
| 151 |
|
| 152 |
Versioning |
| 153 |
========== |
| 154 |
|
| 155 |
By passing in a 'version' argument to the client constructor, you can |
| 156 |
access different versions of the web service. |
| 157 |
|
| 158 |
>>> print service.recipes[1].self_link |
| 159 |
http://cookbooks.dev/1.0/recipes/1 |
| 160 |
|
| 161 |
>>> devel_service = CookbookWebServiceClient(version="devel") |
| 162 |
>>> print devel_service.recipes[1].self_link |
| 163 |
http://cookbooks.dev/devel/recipes/1 |
| 164 |
|
| 165 |
You can also forgo the 'version' argument and pass in a service root |
| 166 |
that incorporates a version string. |
| 167 |
|
| 168 |
>>> devel_service = CookbookWebServiceClient( |
| 169 |
... service_root="http://cookbooks.dev/devel/", version=None) |
| 170 |
>>> print devel_service.recipes[1].self_link |
| 171 |
http://cookbooks.dev/devel/recipes/1 |
| 172 |
|
| 173 |
Error reporting |
| 174 |
=============== |
| 175 |
|
| 176 |
If there's an error communicating with the server, lazr.restfulclient |
| 177 |
raises HTTPError or an appropriate subclass. The error might be a |
| 178 |
client-side error (maybe you tried to access something that doesn't |
| 179 |
exist) or a server-side error (maybe the server crashed due to a |
| 180 |
bug). The string representation of the error should have enough |
| 181 |
information to help you figure out what happened. |
| 182 |
|
| 183 |
This example demonstrates NotFound, the HTTPError subclass used when |
| 184 |
the server sends a 404 error For detailed information about the |
| 185 |
different HTTPError subclasses, see tests/test_error.py. |
| 186 |
|
| 187 |
>>> from lazr.restfulclient.errors import HTTPError |
| 188 |
>>> try: |
| 189 |
... service.load("http://cookbooks.dev/") |
| 190 |
... except Exception, e: |
| 191 |
... pass |
| 192 |
|
| 193 |
>>> raise e |
| 194 |
Traceback (most recent call last): |
| 195 |
... |
| 196 |
NotFound: HTTP Error 404: Not Found |
| 197 |
Response headers: |
| 198 |
--- |
| 199 |
... |
| 200 |
content-type: text/plain |
| 201 |
... |
| 202 |
--- |
| 203 |
Response body: |
| 204 |
--- |
| 205 |
... |
| 206 |
--- |
| 207 |
|
| 208 |
>>> print isinstance(e, HTTPError) |
| 209 |
True |