← Back to branch summary

~ubuntu-branches/debian/stretch/python-wadllib/stretch

« back to all changes in this revision

Viewing changes to src/wadllib/README.txt

  • Committer: Bazaar Package Importer
  • Author(s): Luca Falavigna
  • Date: 2011-02-14 21:52:29 UTC
  • mfrom: (1.3.1 upstream) (13.1.1 experimental)
  • Revision ID: james.westby@ubuntu.com-20110214215229-uz82ooamqlinfghn
Tags: 1.2.0+ds-1
* New upstream release.
* Upload to unstable

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/wadllib/README.txt
43
43
   ...                        "http://api.launchpad.dev/beta/")
44
44
 
45
45
 
46
 
===============
47
46
Link navigation
48
47
===============
49
48
 
139
138
test data.
140
139
 
141
140
   >>> bound_service_root = bind_to_testdata(service_root, 'root')
 
141
   >>> sorted([param.name for param in bound_service_root.parameters()])
 
142
   ['bugs_collection_link', 'people_collection_link']
142
143
   >>> sorted(bound_service_root.parameter_names())
143
144
   ['bugs_collection_link', 'people_collection_link']
144
145
   >>> [method.id for method in bound_service_root.method_iter]
145
146
   ['service-root-get']
146
147
 
147
 
 
148
148
Now the bound resource object has a JSON representation, and now
149
149
'people_collection_link' makes sense. We can follow the
150
150
'people_collection_link' to a new Resource object.
183
183
   'people-get'
184
184
 
185
185
To invoke the special GET request, the client sets the 'ws.op' query
186
 
parameter to the fixed string 'find'.
 
186
parameter to the fixed string 'findPerson'.
187
187
 
188
188
   >>> find_method = personset_resource.get_method(
189
189
   ...     query_params={'ws.op' : 'findPerson'})
274
274
   >>> new_team.type_url
275
275
   'http://api.launchpad.dev/beta/#team'
276
276
 
277
 
======================
 
277
Examining links
 
278
---------------
 
279
 
 
280
The 'linked_resource' property of a parameter lets you follow a link
 
281
to another object. The 'link' property of a parameter lets you examine
 
282
links before following them.
 
283
 
 
284
    >>> import simplejson
 
285
    >>> links_wadl = application_for('links-wadl.xml')
 
286
    >>> service_root = links_wadl.get_resource_by_path('')
 
287
    >>> representation = simplejson.dumps(
 
288
    ...     {'scalar_value': 'foo',
 
289
    ...      'known_link': 'http://known/',
 
290
    ...      'unknown_link': 'http://unknown/'})
 
291
    >>> bound_root = service_root.bind(representation)
 
292
 
 
293
    >>> print bound_root.get_parameter("scalar_value").link
 
294
    None
 
295
 
 
296
    >>> known_resource = bound_root.get_parameter("known_link")
 
297
    >>> unknown_resource = bound_root.get_parameter("unknown_link")
 
298
 
 
299
    >>> print known_resource.link.can_follow
 
300
    True
 
301
    >>> print unknown_resource.link.can_follow
 
302
    False
 
303
 
 
304
A link whose type is unknown is a link to a resource not described by
 
305
WADL. Following this link using .linked_resource or .link.follow will
 
306
cause a wadllib error. You'll need to follow the link using a general
 
307
HTTP library or some other tool.
 
308
 
 
309
    >>> known_resource.link.follow
 
310
    <wadllib.application.Resource object ...>
 
311
    >>> known_resource.linked_resource
 
312
    <wadllib.application.Resource object ...>
 
313
 
 
314
    >>> unknown_resource.link.follow
 
315
    Traceback (most recent call last):
 
316
    ...
 
317
    WADLError: Cannot follow a link when the target has no WADL
 
318
    description. Try using a general HTTP client instead.
 
319
 
 
320
    >>> unknown_resource.linked_resource
 
321
    Traceback (most recent call last):
 
322
    ...
 
323
    WADLError: Cannot follow a link when the target has no WADL
 
324
    description. Try using a general HTTP client instead.
 
325
 
 
326
Creating a Resource from a representation definition
 
327
====================================================
 
328
 
 
329
Although every representation is a representation of some HTTP
 
330
resource, an HTTP resource doesn't necessarily correspond directly to
 
331
a WADL <resource> or <resource_type> tag. Sometimes a representation
 
332
is defined within a WADL <method> tag.
 
333
 
 
334
   >>> find_method = personset_resource.get_method(
 
335
   ...     query_params={'ws.op' : 'find'})
 
336
   >>> find_method.id
 
337
   'people-find'
 
338
 
 
339
   >>> representation_definition = (
 
340
   ...     find_method.response.get_representation_definition(
 
341
   ...     'application/json'))
 
342
 
 
343
There may be no WADL <resource> or <resource_type> tag for the
 
344
representation defined here. That's why wadllib makes it possible to
 
345
instantiate an anonymous Resource object using only the representation
 
346
definition.
 
347
 
 
348
   >>> from wadllib.application import Resource
 
349
   >>> anonymous_resource = Resource(
 
350
   ...     wadl, "http://foo/", representation_definition.tag)
 
351
 
 
352
We can bind this resource to a representation, as long as we
 
353
explicitly pass in the representation definition.
 
354
 
 
355
   >>> anonymous_resource = anonymous_resource.bind(
 
356
   ...     get_testdata('personset'), 'application/json',
 
357
   ...     representation_definition=representation_definition)
 
358
 
 
359
Once the resource is bound to a representation, we can get its
 
360
parameter values.
 
361
 
 
362
   >>> print anonymous_resource.get_parameter(
 
363
   ...     'total_size', 'application/json').get_value()
 
364
   63
 
365
 
278
366
Resource instantiation
279
367
======================
280
368
 
311
399
you've already processed the representation, pass in False for the
312
400
'representation_needs_processing' argument.
313
401
 
314
 
   >>> import simplejson
315
402
   >>> processed_limi_data = simplejson.loads(unicode(limi_data))
316
403
   >>> bound_limi = Resource(wadl, "http://api.launchpad.dev/beta/~limi",
317
404
   ...     "http://api.launchpad.dev/beta/#person", processed_limi_data,
379
466
   None
380
467
 
381
468
Data type conversion
382
 
====================
 
469
--------------------
383
470
 
384
471
The values of date and dateTime parameters are automatically converted to
385
472
Python datetime objects.
424
511
   >>> print bound_root.get_parameter('a_datetime').get_value()
425
512
   None
426
513
 
427
 
=======================
428
514
Representation creation
429
515
=======================
430
516
 
495
581
   ...
496
582
   ValueError: Unsupported media type: 'text/unknown'
497
583
 
498
 
=======
499
584
Options
500
585
=======
501
586
 
525
610
   'has_options': valid values are: "Value 1", "Value 2"
526
611
 
527
612
 
528
 
================
529
613
Error conditions
530
614
================
531
615