Debian Codegraph @

src/lazr/restfulclient/docs/toplevel.rst

raw
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