Navigate HTTP resources using WADL files as guides.

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for barry from gravatar.com barry Avatar for benji from gravatar.com benji Avatar for cjwatson from gravatar.com cjwatson Avatar for gavinpanella from gravatar.com gavinpanella Avatar for jugmac00 from gravatar.com jugmac00 Avatar for mitechie from gravatar.com mitechie Avatar for wgrant from gravatar.com wgrant

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: GNU Library or Lesser General Public License (LGPL) (LGPL v3)
  • Maintainer: LAZR Developers
  • Requires: Python >=3.8
  • Provides-Extra: docs, test
Classifiers

Project description

wadllib

An Application object represents a web service described by a WADL file.

>>> try:
...     import importlib.resources as importlib_resources
...     _ = importlib_resources.files  # missing on Python 3.8
... except (ImportError, AttributeError):
...     import importlib_resources
>>> import os
>>> from wadllib.application import Application

The first argument to the Application constructor is the URL at which the WADL file was found. The second argument may be raw WADL markup.

>>> def get_test_resource(filename):
...     return importlib_resources.files('wadllib.tests.data').joinpath(
...         filename)

>>> wadl_bytes = get_test_resource('launchpad-wadl.xml').read_bytes()
>>> wadl = Application("http://api.launchpad.dev/beta/", wadl_bytes)

Or the second argument may be an open filehandle containing the markup.

>>> def application_for(filename, url="http://www.example.com/"):
...    with get_test_resource(filename).open('rb') as wadl_stream:
...        return Application(url, wadl_stream)
>>> wadl = application_for("launchpad-wadl.xml",
...                        "http://api.launchpad.dev/beta/")

Creating a Resource from a representation definition

Although every representation is a representation of some HTTP resource, an HTTP resource doesn’t necessarily correspond directly to a WADL <resource> or <resource_type> tag. Sometimes a representation is defined within a WADL <method> tag.

>>> find_method = personset_resource.get_method(
...     query_params={'ws.op' : 'find'})
>>> find_method.id
'people-find'

>>> representation_definition = (
...     find_method.response.get_representation_definition(
...     'application/json'))

There may be no WADL <resource> or <resource_type> tag for the representation defined here. That’s why wadllib makes it possible to instantiate an anonymous Resource object using only the representation definition.

>>> from wadllib.application import Resource
>>> anonymous_resource = Resource(
...     wadl, "http://foo/", representation_definition.tag)

We can bind this resource to a representation, as long as we explicitly pass in the representation definition.

>>> anonymous_resource = anonymous_resource.bind(
...     get_testdata('personset'), 'application/json',
...     representation_definition=representation_definition)

Once the resource is bound to a representation, we can get its parameter values.

>>> print(anonymous_resource.get_parameter(
...     'total_size', 'application/json').get_value())
63

Resource instantiation

If you happen to have the URL to an object lying around, and you know its type, you can construct a Resource object directly instead of by following links.

>>> from wadllib.application import Resource
>>> limi_person = Resource(wadl, "http://api.launchpad.dev/beta/~limi",
...     "http://api.launchpad.dev/beta/#person")
>>> sorted([method.id for method in limi_person.method_iter])[:3]
['person-acceptInvitationToBeMemberOf', 'person-addMember', 'person-declineInvitationToBeMemberOf']

>>> bound_limi = bind_to_testdata(limi_person, 'person-limi')
>>> sorted(bound_limi.parameter_names())[:3]
['admins_collection_link', 'confirmed_email_addresses_collection_link',
 'date_created']
>>> languages_link = bound_limi.get_parameter("languages_collection_link")
>>> print(languages_link.get_value())
http://api.launchpad.dev/beta/~limi/languages

You can bind a Resource to a representation when you create it.

>>> limi_data = get_testdata('person-limi')
>>> bound_limi = Resource(
...     wadl, "http://api.launchpad.dev/beta/~limi",
...     "http://api.launchpad.dev/beta/#person", limi_data,
...     "application/json")
>>> print(bound_limi.get_parameter(
...     "languages_collection_link").get_value())
http://api.launchpad.dev/beta/~limi/languages

By default the representation is treated as a string and processed according to the media type you pass into the Resource constructor. If you’ve already processed the representation, pass in False for the ‘representation_needs_processing’ argument.

>>> processed_limi_data = json.loads(limi_data.decode())
>>> bound_limi = Resource(wadl, "http://api.launchpad.dev/beta/~limi",
...     "http://api.launchpad.dev/beta/#person", processed_limi_data,
...     "application/json", False)
>>> print(bound_limi.get_parameter(
...     "languages_collection_link").get_value())
http://api.launchpad.dev/beta/~limi/languages

Most of the time, the representation of a resource is of the type you’d get by sending a standard GET to that resource. If that’s not the case, you can specify a RepresentationDefinition as the ‘representation_definition’ argument to bind() or the Resource constructor, to show what the representation really looks like. Here’s an example.

There’s a method on a person resource such as bound_limi that’s identified by a distinctive query argument: ws.op=getMembersByStatus.

>>> method = bound_limi.get_method(
...     query_params={'ws.op' : 'findPathToTeam'})

Invoke this method with a GET request and you’ll get back a page from a list of people.

>>> people_page_repr_definition = (
...     method.response.get_representation_definition('application/json'))
>>> people_page_repr_definition.tag.attrib['href']
'http://api.launchpad.dev/beta/#person-page'

As it happens, we have a page from a list of people to use as test data.

>>> people_page_repr = get_testdata('personset')

If we bind the resource to the result of the method invocation as happened above, we don’t be able to access any of the parameters we’d expect. wadllib will think the representation is of type ‘person-full’, the default GET type for bound_limi.

>>> bad_people_page = bound_limi.bind(people_page_repr)
>>> print(bad_people_page.get_parameter('total_size'))
None

Since we don’t actually have a ‘person-full’ representation, we won’t be able to get values for the parameters of that kind of representation.

>>> bad_people_page.get_parameter('name').get_value()
Traceback (most recent call last):
...
KeyError: 'name'

So that’s a dead end. But, if we pass the correct representation type into bind(), we can access the parameters associated with a ‘person-page’ representation.

>>> people_page = bound_limi.bind(
...     people_page_repr,
...     representation_definition=people_page_repr_definition)
>>> people_page.get_parameter('total_size').get_value()
63

If you invoke the method and ask for a media type other than JSON, you won’t get anything.

>>> print(method.response.get_representation_definition('text/html'))
None

Data type conversion

The values of date and dateTime parameters are automatically converted to Python datetime objects.

>>> data_type_wadl = application_for('data-types-wadl.xml')
>>> service_root = data_type_wadl.get_resource_by_path('')

>>> representation = json.dumps(
...     {'a_date': '2007-10-20',
...      'a_datetime': '2005-06-06T08:59:51.619713+00:00'})
>>> bound_root = service_root.bind(representation, 'application/json')

>>> bound_root.get_parameter('a_date').get_value()
datetime.datetime(2007, 10, 20, 0, 0)
>>> bound_root.get_parameter('a_datetime').get_value()
datetime.datetime(2005, 6, 6, 8, ...)

A ‘date’ field can include a timestamp, and a ‘datetime’ field can omit one. wadllib will turn both into datetime objects.

>>> representation = json.dumps(
...     {'a_date': '2005-06-06T08:59:51.619713+00:00',
...      'a_datetime': '2007-10-20'})
>>> bound_root = service_root.bind(representation, 'application/json')

>>> bound_root.get_parameter('a_datetime').get_value()
datetime.datetime(2007, 10, 20, 0, 0)
>>> bound_root.get_parameter('a_date').get_value()
datetime.datetime(2005, 6, 6, 8, ...)

If a date or dateTime parameter has a null value, you get None. If the value is a string that can’t be parsed to a datetime object, you get a ValueError.

>>> representation = json.dumps(
...     {'a_date': 'foo', 'a_datetime': None})
>>> bound_root = service_root.bind(representation, 'application/json')
>>> bound_root.get_parameter('a_date').get_value()
Traceback (most recent call last):
...
ValueError: foo
>>> print(bound_root.get_parameter('a_datetime').get_value())
None

Representation creation

You must provide a representation when invoking certain methods. The representation() method helps you build one without knowing the details of how a representation is put together.

>>> create_team_method.build_representation(
...     display_name='Joe Bloggs', name='joebloggs')
('application/x-www-form-urlencoded', 'display_name=Joe+Bloggs&name=joebloggs&ws.op=newTeam')

The return value of build_representation is a 2-tuple containing the media type of the built representation, and the string representation itself. Along with the resource’s URL, this is all you need to send the representation to a web server.

>>> bound_limi.get_method('patch').build_representation(name='limi2')
('application/json', '{"name": "limi2"}')

Representations may require values for certain parameters.

>>> create_team_method.build_representation()
Traceback (most recent call last):
...
ValueError: No value for required parameter 'display_name'

>>> bound_limi.get_method('put').build_representation(name='limi2')
Traceback (most recent call last):
...
ValueError: No value for required parameter 'mugshot_link'

Some representations may safely include binary data.

>>> with get_test_resource('multipart-binary-wadl.xml').open(
...         'rb') as binary_stream:
...     binary_wadl = Application(
...         "http://www.example.com/", binary_stream)
>>> service_root = binary_wadl.get_resource_by_path('')

Define a helper that processes the representation the same way zope.publisher would. (We simplify handling of the parsed form data, since we only care about form values and file contents.)

>>> import io
>>> import multipart
>>> def assert_message_parts(media_type, doc, expected):
...     environ = {
...         'wsgi.input': io.BytesIO(doc),
...         'REQUEST_METHOD': 'POST',
...         'CONTENT_TYPE': media_type,
...         'CONTENT_LENGTH': str(len(doc)),
...         }
...     forms, files = multipart.parse_form_data(
...         environ, charset="UTF-8", memfile_limit=0)
...     values = []
...     for _, value in forms.iterallitems():
...         values.append(value)
...     for _, item in files.iterallitems():
...         values.append(item.file.read())
...     assert values == expected, (
...         'Expected %s, got %s' % (expected, values))

>>> method = service_root.get_method('post', 'multipart/form-data')
>>> media_type, doc = method.build_representation(
...     text_field="text", binary_field=b"\x01\x02\r\x81\r")
>>> print(media_type)
multipart/form-data; boundary=...
>>> assert_message_parts(media_type, doc, ['text', b'\x01\x02\r\x81\r'])

>>> method = service_root.get_method('post', 'multipart/form-data')
>>> media_type, doc = method.build_representation(
...     text_field="text", binary_field=b"\x01\x02\r\x81\r")
>>> print(media_type)
multipart/form-data; boundary=...
>>> assert_message_parts(media_type, doc, ['text', b'\x01\x02\r\x81\r'])

>>> method = service_root.get_method('post', 'multipart/form-data')
>>> media_type, doc = method.build_representation(
...     text_field="text\n", binary_field=b"\x01\x02\r\x81\n\r")
>>> print(media_type)
multipart/form-data; boundary=...
>>> assert_message_parts(
...     media_type, doc, ['text\r\n', b'\x01\x02\r\x81\n\r'])

>>> method = service_root.get_method('post', 'multipart/form-data')
>>> media_type, doc = method.build_representation(
...     text_field="text\n", binary_field=b"\x01\x02\r\x81\n\r")
>>> print(media_type)
multipart/form-data; boundary=...
>>> assert_message_parts(
...     media_type, doc, ['text\r\n', b'\x01\x02\r\x81\n\r'])

>>> method = service_root.get_method('post', 'multipart/form-data')
>>> media_type, doc = method.build_representation(
...     text_field="text\r\nmore\r\n",
...     binary_field=b"\x01\x02\r\n\x81\r\x82\n")
>>> print(media_type)
multipart/form-data; boundary=...
>>> assert_message_parts(
...     media_type, doc, ['text\r\nmore\r\n', b'\x01\x02\r\n\x81\r\x82\n'])

>>> method = service_root.get_method('post', 'multipart/form-data')
>>> media_type, doc = method.build_representation(
...     text_field="text\r\nmore\r\n",
...     binary_field=b"\x01\x02\r\n\x81\r\x82\n")
>>> print(media_type)
multipart/form-data; boundary=...
>>> assert_message_parts(
...     media_type, doc, ['text\r\nmore\r\n', b'\x01\x02\r\n\x81\r\x82\n'])

>>> method = service_root.get_method('post', 'text/unknown')
>>> method.build_representation(field="value")
Traceback (most recent call last):
...
ValueError: Unsupported media type: 'text/unknown'

Options

Some parameters take values from a predefined list of options.

>>> option_wadl = application_for('options-wadl.xml')
>>> definitions = option_wadl.representation_definitions
>>> service_root = option_wadl.get_resource_by_path('')
>>> definition = definitions['service-root-json']
>>> param = definition.params(service_root)[0]
>>> print(param.name)
has_options
>>> sorted([option.value for option in param.options])
['Value 1', 'Value 2']

Such parameters cannot take values that are not in the list.

>>> definition.validate_param_values(
...     [param], {'has_options': 'Value 1'})
{'has_options': 'Value 1'}

>>> definition.validate_param_values(
...     [param], {'has_options': 'Invalid value'})
Traceback (most recent call last):
...
ValueError: Invalid value 'Invalid value' for parameter
'has_options': valid values are: "Value 1", "Value 2"

Error conditions

You’ll get None if you try to look up a nonexistent resource.

>>> print(wadl.get_resource_by_path('nosuchresource'))
None

You’ll get an exception if you try to look up a nonexistent resource type.

>>> print(wadl.get_resource_type('#nosuchtype'))
Traceback (most recent call last):
KeyError: 'No such XML ID: "#nosuchtype"'

You’ll get None if you try to look up a method whose parameters don’t match any defined method.

>>> print(bound_limi.get_method(
...     'post', representation_params={ 'foo' : 'bar' }))
None

NEWS for wadllib

2.0.0 (2024-10-11)

  • Drop support for Python < 3.8.

1.3.9 (2024-09-23)

  • legacy-cgi is only a test dependency. Make it an optional dependency.

1.3.8 (2024-09-23)

  • Add support for Python 3.11-3.13.

1.3.7 (2021-11-02)

  • Add support for Python 3.9 and 3.10.

  • Add basic pre-commit configuration.

  • Publish documentation on Read the Docs.

1.3.6 (2021-09-13)

  • Remove buildout support in favour of tox. [bug=922605]

  • Adjust versioning strategy to avoid importing pkg_resources, which is slow in large environments.

1.3.5 (2021-01-20)

  • Drop support for Python 3.2, 3.3, and 3.4.

  • Accept Unicode parameter values again when performing multipart/form-data encoding on Python 2 (broken in 1.3.3).

1.3.4 (2020-04-29)

  • Advertise support for Python 3.8.

  • Add Python 3.9 compatibility by using xml.etree.ElementTree if xml.etree.cElementTree does not exist. [bug=1870294]

1.3.3 (2018-07-20)

  • Drop support for Python < 2.6.

  • Add tox testing support.

  • Implement a subset of MIME multipart/form-data encoding locally rather than using the standard library’s email module, which doesn’t have good handling of binary parts and corrupts bytes in them that look like line endings in various ways depending on the Python version. [bug=1729754]

1.3.2 (2013-02-25)

  • Impose sort order to avoid test failures due to hash randomization. LP: #1132125

  • Be sure to close streams opened by pkg_resources.resource_stream() to avoid test suite complaints.

1.3.1 (2012-03-22)

  • Correct the double pass through _from_string causing datetime issues

1.3.0 (2012-01-27)

  • Add Python 3 compatibility

  • Add the ability to inspect links before following them.

  • Ensure that the sample data is packaged.

1.2.0 (2011-02-03)

  • It’s now possible to examine a link before following it, to see whether it has a WADL description or whether it needs to be fetched with a general HTTP client.

  • It’s now possible to iterate over a resource’s Parameter objects with the .parameters() method.

1.1.8 (2010-10-27)

  • This revision contains no code changes, but the build system was changed (yet again). This time to include the version.txt file used by setup.py.

1.1.7 (2010-10-26)

  • This revision contains no code changes, but the build system was changed (again) to include the sample data used in tests.

1.1.6 (2010-10-21)

  • This revision contains no code changes, but the build system was changed to include the sample data used in tests.

1.1.5 (2010-05-04)

  • Fixed a bug (Launchpad bug 274074) that prevented the lookup of parameter values in resources associated directly with a representation definition (rather than a resource type with a representation definition). Bug fix provided by James Westby.

1.1.4 (2009-09-15)

  • Fixed a bug that crashed wadllib unless all parameters of a multipart representation were provided.

1.1.3 (2009-08-26)

  • Remove unnecessary build dependencies.

  • Add missing dependencies to setup file.

  • Remove sys.path hack from setup.py.

1.1.2 (2009-08-20)

  • Consistently handle different versions of simplejson.

1.1.1 (2009-07-14)

  • Make wadllib aware of the <option> tags that go beneath <param> tags.

1.1 (2009-07-09)

  • Make wadllib capable of recognizing and generating multipart/form-data representations, including representations that incorporate binary parameters.

1.0 (2009-03-23)

  • Initial release on PyPI

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for barry from gravatar.com barry Avatar for benji from gravatar.com benji Avatar for cjwatson from gravatar.com cjwatson Avatar for gavinpanella from gravatar.com gavinpanella Avatar for jugmac00 from gravatar.com jugmac00 Avatar for mitechie from gravatar.com mitechie Avatar for wgrant from gravatar.com wgrant

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: GNU Library or Lesser General Public License (LGPL) (LGPL v3)
  • Maintainer: LAZR Developers
  • Requires: Python >=3.8
  • Provides-Extra: docs, test
Classifiers

Release history Release notifications | RSS feed

This version

2.0.0

1.3.9

1.3.8

1.3.6

1.3.5

1.3.4

1.3.3

1.3.2

1.3.1

1.3.0

1.2.0

1.1.8

1.1.7

1.1.6

1.1.5

1.1.4

1.1.3

1.1.2

1.1.1

1.1

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wadllib-2.0.0.tar.gz (66.0 kB view details)

Uploaded Source

Built Distribution

wadllib-2.0.0-py3-none-any.whl (61.7 kB view details)

Uploaded Python 3

File details

Details for the file wadllib-2.0.0.tar.gz.

File metadata

  • Download URL: wadllib-2.0.0.tar.gz
  • Upload date:
  • Size: 66.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for wadllib-2.0.0.tar.gz
Algorithm Hash digest
SHA256 1edbaf23e4fa34fea70c9b380baa2a139b1086ae489ebcccc4b3b65fc9737427
MD5 e951a5bb86c912fcf4bef29ccc3848f0
BLAKE2b-256 da5482866d8c2bf602ed9df52c8f8b7a45e94f8c2441b3d1e9e46d34f0e3270f

See more details on using hashes here.

File details

Details for the file wadllib-2.0.0-py3-none-any.whl.

File metadata

  • Download URL: wadllib-2.0.0-py3-none-any.whl
  • Upload date:
  • Size: 61.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for wadllib-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f8e0fc4f19c2c96b3ca8a091f04c86ca196ec9590d44c4d864320aa9533473ea
MD5 daf46fb65a798774e42d4f90d2e6b4b4
BLAKE2b-256 27a13789e82241db565f25e2c6a69c6ebe79f3db84431e93760a4abb451822bd

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page