Debian Codegraph @

src/lazr/restfulclient/docs/operations.rst

raw
1 ****************
2 Named operations
3 ****************
4
5 Entries and collections support named operations: one-off
6 functionality that's been given a name and a set of parameters.
7
8 >>> from lazr.restfulclient.tests.example import CookbookWebServiceClient
9 >>> service = CookbookWebServiceClient()
10
11 Arguments to named operations are automatically converted to JSON for
12 transmission over the wire. Here's a named operation that takes a
13 boolean argument.
14
15 >>> [recipe for recipe in service.cookbooks.find_recipes(
16 ... search="Chicken", vegetarian=True)]
17 []
18
19 Strings that happen to be numbers are handled properly. Here, if "1.234"
20 were converted into a number at any point in the chain, the 'search'
21 operation on the server wouldn't know how to handle it and the request
22 would fail.
23
24 >>> [people for people in service.cookbooks.find_recipes(search="1.234")]
25 []
26
27 Counts
28 ------
29
30 Named operations that return a collection return either a link that
31 lazr.restfulclient can follow to get the size of the collection or
32 (under some circumstances) the length itself. The len() function
33 hides this indirection from the end-user.
34
35 >>> results = service.cookbooks.find_recipes(search="Chicken")
36 >>> print len(results)
37 0
38
39 Special data types
40 ------------------
41
42 lazr.restfulclient uses some data types that don't directly correspond
43 to JSON data types. These data types can be used in named
44 operations. For instance, a named operation can take a date or
45 datetime object as one of its arguments.
46
47 >>> import datetime
48 >>> date = datetime.datetime(1994, 1, 1)
49 >>> cookbook = service.cookbooks.create(
50 ... name="New cookbook", cuisine="General",
51 ... copyright_date=date, price=1.23, last_printing=date)
52 >>> print cookbook.name
53 New cookbook
54
55 A named operation can take an entry as one of its arguments.
56 lazr.restfulclient lets you pass in the actual entry as the argument
57 value.
58
59 >>> dish = service.recipes[1].dish
60 >>> cookbook = service.recipes[1].cookbook
61 >>> print cookbook.find_recipe_for(dish=dish)
62 http://cookbooks.dev/1.0/recipes/1
63
64 A named operation can take binary data as one of its arguments.
65
66 >>> cookbook.replace_cover(cover="\x00\xe2\xe3")
67 >>> cookbook.cover.open().read()
68 '\x00\xe2\xe3'
69
70 A named operation that returns a null value corresponds to a Python
71 value of None.
72
73 >>> dish = service.recipes[4].dish
74 >>> print cookbook.find_recipe_for(dish=dish)
75 None
76
77 A named operation may change the resource's location so we get a 301 response
78 with the new URL.
79
80 >>> from urllib import quote
81 >>> from lazr.restful.testing.webservice import WebServiceCaller
82 >>> webservice = WebServiceCaller(domain='cookbooks.dev')
83 >>> url = quote("/cookbooks/New cookbook")
84 >>> print webservice.named_post(url, 'make_more_interesting')
85 HTTP/1.1 301 Moved Permanently
86 ...
87 Location: http://cookbooks.dev/devel/cookbooks/The%20New%20New%20cookbook
88 ...
89
90 JSON-encoding
91 -------------
92
93 lazr.restfulclient encodes most arguments (even string arguments) as
94 JSON before sending them over the wire. This way, a named operation
95 that takes a string argument can take a string that looks like a JSON
96 object without causing confusion.
97
98 >>> cookbooks = service.cookbooks.find_for_cuisine(cuisine="General")
99 >>> len([cookbook for cookbook in cookbooks]) > 0
100 True
101
102 >>> cookbook = service.cookbooks.create(
103 ... name="null", cuisine="General",
104 ... copyright_date=date, price=1.23, last_printing=date)
105 >>> cookbook.name
106 u'null'
107
108 >>> cookbook = service.cookbooks.create(
109 ... name="4.56", cuisine="General",
110 ... copyright_date=date, price=1.23, last_printing=date)
111 >>> cookbook.name
112 u'4.56'
113
114 >>> cookbook = service.cookbooks.create(
115 ... name='"foo"', cuisine="General",
116 ... copyright_date=date, price=1.23, last_printing=date)
117 >>> cookbook.name
118 u'"foo"'
119
120 A named operation that takes a non-string object (such as a float)
121 will not accept a string that's the JSON representation of the
122 object.
123
124 >>> try:
125 ... service.cookbooks.create(
126 ... name="Yet another 1.23 cookbook", cuisine="General",
127 ... copyright_date=date, last_printing=date, price="1.23")
128 ... except Exception, e:
129 ... print e.content
130 price: got 'unicode', expected float, int: u'1.23'
131
132 Named operations on collections don't fetch the collections
133 -----------------------------------------------------------
134
135 If you invoke a named operation on a collection, the only HTTP request
136 made is the one for the named operation. You don't have to get a
137 representation of the collection to invoke the operation.
138
139 >>> import httplib2
140 >>> httplib2.debuglevel = 1
141 >>> service = CookbookWebServiceClient()
142 send: ...
143 ...
144
145 >>> print service.cookbooks.find_recipes(
146 ... search="Chicken", vegetarian=True)
147 send: 'GET /1.0/cookbooks?...vegetarian=true...'
148 ...
149
150 Cleanup.
151
152 >>> httplib2.debuglevel = None