| 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 |