Debian Codegraph @

src/lazr/restfulclient/docs/collections.rst

raw
1 ***********
2 Collections
3 ***********
4
5 lazr.restful makes collections of data available through Pythonic
6 mechanisms like slices.
7
8 >>> from lazr.restfulclient.tests.example import CookbookWebServiceClient
9 >>> service = CookbookWebServiceClient()
10
11 You can iterate through all the items in a collection.
12
13 >>> names = sorted([recipe.dish.name for recipe in service.recipes])
14 >>> len(names)
15 5
16 >>> names
17 [u'Baked beans', ..., u'Roast chicken']
18
19 But it's almost always better to slice them.
20
21 >>> sorted([recipe.dish.name for recipe in service.recipes[:2]])
22 [u'Roast chicken', u'Roast chicken']
23
24 You can get a slice of any collection, so long as you provide start
25 and end points keyed to the beginning of the list. You can't key a
26 slice to the end of the list because it might be expensive to
27 calculate how big the list is.
28
29 This set-up code creates a regular Python list of all recipes on the
30 site, for comparison with a lazr.restful Collection object
31 representing the same list.
32
33 >>> all_recipes = [recipe for recipe in service.recipes]
34 >>> recipes = service.recipes
35
36 Calling len() on the Collection object makes sure that the first page
37 of representations is cached, which forces this test to test an
38 optimization.
39
40 >>> ignored = len(recipes)
41
42 These tests demonstrate that slicing the collection resource gives the
43 same results as collecting all the entries in the collection, and
44 slicing an ordinary list.
45
46 >>> def slices_match(slice):
47 ... """Slice two lists of recipes, then make sure they're the same."""
48 ... list1 = recipes[slice]
49 ... list2 = all_recipes[slice]
50 ... if len(list1) != len(list2):
51 ... raise ("Lists are different sizes: %d vs. %d" %
52 ... (len(list1), len(list2)))
53 ... for index in range(0, len(list1)):
54 ... if list1[index].id != list2[index].id:
55 ... raise ("%s doesn't match %s in position %d" %
56 ... (list1[index].id, list2[index].id, index))
57 ... return True
58
59 >>> slices_match(slice(3))
60 True
61 >>> slices_match(slice(50))
62 True
63 >>> slices_match(slice(1,2))
64 True
65 >>> slices_match(slice(2,21))
66 True
67 >>> slices_match(slice(2,21,3))
68 True
69
70 >>> slices_match(slice(0, 200))
71 True
72 >>> slices_match(slice(30, 200))
73 True
74 >>> slices_match(slice(60, 100))
75 True
76
77 >>> recipes[5:]
78 Traceback (most recent call last):
79 ...
80 ValueError: Collection slices must have a definite, nonnegative end point.
81
82 >>> recipes[10:-1]
83 Traceback (most recent call last):
84 ...
85 ValueError: Collection slices must have a definite, nonnegative end point.
86
87 >>> recipes[-1:]
88 Traceback (most recent call last):
89 ...
90 ValueError: Collection slices must have a nonnegative start point.
91
92 >>> recipes[:]
93 Traceback (most recent call last):
94 ...
95 ValueError: Collection slices must have a definite, nonnegative end point.
96
97 You can slice a collection that's the return value of a named
98 operation.
99
100 >>> e_recipes = service.cookbooks.find_recipes(search='e')
101 >>> len(e_recipes[1:3])
102 2
103
104 You can also access individual items in this collection by index.
105
106 >>> print e_recipes[1].dish.name
107 Foies de voilaille en aspic
108
109 >>> e_recipes[1000]
110 Traceback (most recent call last):
111 ...
112 IndexError: list index out of range
113
114 When are representations fetched?
115 =================================
116
117 To avoid unnecessary HTTP requests, a representation of a collection
118 is fetched at the last possible moment. Let's see what that means.
119
120 >>> import httplib2
121 >>> httplib2.debuglevel = 1
122
123 >>> service = CookbookWebServiceClient()
124 send: ...
125 ...
126
127 Just accessing a top-level collection doesn't trigger an HTTP request.
128
129 >>> recipes = service.recipes
130 >>> dishes = service.dishes
131 >>> cookbooks = service.cookbooks
132
133 Getting the length of the collection, or any entry from the
134 collection, triggers an HTTP request.
135
136 >>> len(recipes)
137 send: 'GET /1.0/recipes...
138 ...
139
140 >>> dish = dishes[1]
141 send: 'GET /1.0/dishes...
142 ...
143
144 Invoking a named operation will also trigger an HTTP request.
145
146 >>> cookbooks.find_recipes(search="foo")
147 send: ...
148 ...
149
150 Scoped collections work the same way: just getting a reference to the
151 collection doesn't trigger an HTTP request.
152
153 >>> recipes = dish.recipes
154
155 But getting any information about the collection triggers an HTTP request.
156
157 >>> len(recipes)
158 send: 'GET /1.0/dishes/.../recipes ...
159 ...
160
161 Cleanup.
162
163 >>> httplib2.debuglevel = None