rfc3987 1.3.3

API

match (string, rule=’IRI_reference’)

Returns a match object or None.

parse (string, rule=’IRI_reference’)

Parses string according to rule into a dict of subcomponents.

If rule is None, parse an IRI_reference without validation.

If regex is available, any rule is supported; with re, rule must be ‘IRI_reference’ or some special case thereof (‘IRI’, ‘absolute_IRI’, ‘irelative_ref’, ‘irelative_part’, ‘URI_reference’, ‘URI’, ‘absolute_URI’, ‘relative_ref’, ‘relative_part’).

>>> d = parse('http://tools.ietf.org/html/rfc3986#appendix-A',
...           rule='URI')
>>> assert all([ d['scheme'] == 'http',
...              d['authority'] == 'tools.ietf.org',
...              d['path'] == '/html/rfc3986',
...              d['query'] == None,
...              d['fragment'] == 'appendix-A' ])

compose (**parts)

Returns an URI composed from named parts.

resolve (base, uriref, strict=True, return_parts=False)

Resolves an URI reference relative to a base URI.

Test cases:

>>> base = resolve.test_cases_base
>>> for relative, resolved in resolve.test_cases.items():
...     assert resolve(base, relative) == resolved

If return_parts is True, returns a dict of named parts instead of a string.

Examples:

>>> assert resolve('urn:rootless', '../../name') == 'urn:name'
>>> assert resolve('urn:root/less', '../../name') == 'urn:/name'
>>> assert resolve('http://a/b', 'http:g') == 'http:g'
>>> assert resolve('http://a/b', 'http:g', strict=False) == 'http://a/g'

patterns

A dict of regular expressions with useful group names. Compilable (with regex only) without need for any particular compilation flag.

[bmp_][u]patterns[_no_names]

Alternative versions of patterns. [u]nicode strings without group names for the re module. BMP only for narrow builds.

get_compiled_pattern (rule, flags=0)

Returns a compiled pattern object for a rule name or template string.

Usage for validation:

>>> uri = get_compiled_pattern('^%(URI)s$')
>>> assert uri.match('http://tools.ietf.org/html/rfc3986#appendix-A')
>>> assert not get_compiled_pattern('^%(relative_ref)s$').match('#f#g')
>>> from unicodedata import lookup
>>> smp = 'urn:' + lookup('OLD ITALIC LETTER A')  # U+00010300
>>> assert not uri.match(smp)
>>> m = get_compiled_pattern('^%(IRI)s$').match(smp)

On narrow builds, non-BMP characters are (incorreclty) excluded:

>>> assert NARROW_BUILD == (not m)

For parsing, some subcomponents are captured in named groups (only if regex is available, otherwise see parse):

>>> match = uri.match('http://tools.ietf.org/html/rfc3986#appendix-A')
>>> d = match.groupdict()
>>> if REGEX:
...     assert all([ d['scheme'] == 'http',
...                  d['authority'] == 'tools.ietf.org',
...                  d['path'] == '/html/rfc3986',
...                  d['query'] == None,
...                  d['fragment'] == 'appendix-A' ])

>>> for r in patterns.keys():
...     assert get_compiled_pattern(r)

format_patterns (**names)

Returns a dict of patterns (regular expressions) keyed by rule names for URIs and rule names for IRIs.

See also the module level dicts of patterns, and get_compiled_pattern.

To wrap a rule in a named capture group, pass it as keyword argument: rule_name=’group_name’. By default, the formatted patterns contain no named groups.

Patterns are str instances (be it in python 2.x or 3.x) containing ASCII characters only.

Caveats:

• with re, named capture groups cannot occur on multiple branches of an alternation

• with re before python 3.3, \u and \U escapes must be preprocessed (see issue3665)

• on narrow builds, character ranges beyond BMP are not supported

What’s new

version 1.3.3:

• fixed a bug in resolve which left “../” at the begining of some paths

version 1.3.2:

• convenience function match

• patterns restricted to the BMP for narrow builds

• adapted doctests for python 3.3

• compatibility with python 2.6 (thanks to Thijs Janssen)

version 1.3.1:

• some re compatibility: get_compiled_pattern, parse

• dropped regex from setup.py requirements

version 1.3.0:

• python 3.x compatibility

• format_patterns

version 1.2.1:

• compose, resolve