aiocoap.util.vendored.link_header module

Parse and format link headers according to RFC 5988 “Web Linking”.

Usage (assuming a suitable headers object in the environment):

>>> headers['Link'] = str(LinkHeader([Link("http://example.com/foo", rel="self"),
...                                   Link("http://example.com", rel="up")]))
>>> headers['Link']
'<http://example.com/foo>; rel=self, <http://example.com>; rel=up'
>>> parse(headers['Link'])
LinkHeader([Link('http://example.com/foo', rel='self'), Link('http://example.com', rel='up')])

Blank and missing values roundtrip correctly:

>>> format_link(parse('</s/1>; obs; if="core.s"; foo=""'))
'<</s/1>; obs; if=core.s; foo="">'

Conversions to and from json-friendly list-based structures are also provided:

>>> parse(headers['Link']).to_py()
[['http://example.com/foo', [['rel', 'self']]], ['http://example.com', [['rel', 'up']]]]
>>> str(LinkHeader([['http://example.com/foo', [['rel', 'self']]],
...                 ['http://example.com', [['rel', 'up']]]]))
'<http://example.com/foo>; rel=self, <http://example.com>; rel=up'

For further information see parse(), LinkHeader and Link.

aiocoap.util.vendored.link_header.parse(header)

Parse a link header string, returning a LinkHeader object:

>>> parse('<http://example.com/foo>; rel="foo bar", <http://example.com>; rel=up; type=text/html')
LinkHeader([Link('http://example.com/foo', rel='foo bar'), Link('http://example.com', rel='up', type='text/html')])

ParseException is raised in the event that the input string is not parsed completely:

>>> parse('<http://example.com/foo> error')
Traceback (most recent call last):
    ...
ParseException: ('link_header.parse() failed near %s', "'error'")

aiocoap.util.vendored.link_header.format_links(*args, **kwargs)

aiocoap.util.vendored.link_header.format_link(*args, **kwargs)

class aiocoap.util.vendored.link_header.LinkHeader(links=None)

Bases: object

Represents a sequence of links that can be formatted together as a link header.

to_py()

Supports list conversion:

>>> LinkHeader([Link('http://example.com/foo', rel='foo'), Link('http://example.com', rel='up')]).to_py()
[['http://example.com/foo', [['rel', 'foo']]], ['http://example.com', [['rel', 'up']]]]

links_by_attr_pairs(pairs)

Lists links that have attribute pairs matching all the supplied pairs:

>>> parse('<http://example.com/foo>; rel="foo", <http://example.com>; rel="up"'
...      ).links_by_attr_pairs([('rel', 'up')])
[Link('http://example.com', rel='up')]

class aiocoap.util.vendored.link_header.Link(href, attr_pairs=None, **kwargs)

Bases: object

Represents a single link.

to_py()

Convert to a json-friendly list-based structure:

>>> Link('http://example.com', rel='foo').to_py()
['http://example.com', [['rel', 'foo']]]

get_context(requested_resource_address)

Return the absolute URI of the context of a link. This is usually equals the base address the statement is about (eg. the requested URL if the link header was served in a successful HTTP GET request), but can be overridden by the anchor parameter.

>>> Link('../', rel='index').get_context('http://www.example.com/book1/chapter1/')
'http://www.example.com/book1/chapter1/'
>>> Link('', rel='next', anchor='../').get_context('http://www.example.com/book1/chapter1/')
'http://www.example.com/book1/'

get_target(requested_resource_address)

Return the absolute URI of the target of a link. It is determined by joining the address from which the link header was retrieved with the link-value (inside angular brackets) according to RFC3986 section 5.

>>> Link('../', rel='index').get_target('http://www.example.com/book1/chapter1/')
'http://www.example.com/book1/'
>>> Link('', rel='next', anchor='../').get_target('http://www.example.com/book1/chapter1/')
'http://www.example.com/book1/chapter1/'

exception aiocoap.util.vendored.link_header.ParseException

Bases: Exception