1uritemplate
2===========
3
4Release v\ |version|.
5
6Examples
7--------
8
9This first example shows how simple the API can be when using for a one-off
10item in a script or elsewhere.
11
12.. code-block:: python
13
14    from requests import get
15    from uritemplate import expand
16
17    uri = 'https://api.github.com{/user}'
18
19    user = get(expand(uri, user='sigmavirus24')).json()
20
21This second example shows how using the class will save you time for template
22parsing and object creation. Making the template once means the URI is parsed
23once which decreases the number of :class:`URITemplate
24<uritemplate.URITemplate>` objects created and usage of the ``re`` module.
25This means that as soon as the file is parsed, the ``User.github_url`` and
26``Repository.github_url`` variables are made once and only once. They're then
27usable in every instance of those classes.
28
29.. code-block:: python
30
31    from uritemplate import URITemplate
32
33    class User(object):
34        github_url = URITemplate('https://api.github.com{/user}')
35        def __init__(self, name):
36            self.uri = self.github_url.expand({'user': name})
37            self.name = name
38
39    class Repository(object):
40        github_url = URITemplate('https://api.github.com{/user}{/repo}')
41        def __init__(self, name):
42            self.uri = self.github_url.expand(
43                dict(zip(['user', 'repo'], name.split('/')))
44            )
45            self.name = name
46
47API
48---
49
50.. module:: uritemplate
51
52.. autofunction:: uritemplate.expand
53
54.. autofunction:: uritemplate.partial
55
56.. autofunction:: uritemplate.variables
57
58.. autoclass:: uritemplate.URITemplate
59    :members:
60
61Implementation Details
62----------------------
63
64Classes, their methods, and functions in this section are not part of the API
65and as such are not meant to be used by users of ``uritemplate.py``. These are
66documented here purely for reference as they are inadvertently exposed via the
67public API.
68
69For example::
70
71    t = URITemplate('https://api.github.com/users{/user}')
72    t.variables
73    # => [URIVariable(/user)]
74
75Users can interact with :class:`URIVariable` objects as they see fit, but
76their API may change and are not guaranteed to be consistent across versions.
77Code relying on methods defined on :class:`URIVariable` and other classes,
78methods, and functions in this section may break in future releases.
79
80.. autoclass:: uritemplate.template.URIVariable
81    :members: expand
82