Home | History | Annotate | Download | only in docs 
      1 uritemplate
      2 ===========
      3 
      4 Release v\ |version|.
      5 
      6 Examples
      7 --------
      8 
      9 This first example shows how simple the API can be when using for a one-off 
     10 item 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 
     21 This second example shows how using the class will save you time for template 
     22 parsing and object creation. Making the template once means the URI is parsed 
     23 once which decreases the number of :class:`URITemplate 
     24 <uritemplate.URITemplate>` objects created and usage of the ``re`` module.  
     25 This 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 
     27 usable 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 
     47 API
     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 
     61 Implementation Details
     62 ----------------------
     63 
     64 Classes, their methods, and functions in this section are not part of the API 
     65 and as such are not meant to be used by users of ``uritemplate.py``. These are 
     66 documented here purely for reference as they are inadvertently exposed via the 
     67 public API.
     68 
     69 For example::
     70 
     71     t = URITemplate('https://api.github.com/users{/user}')
     72     t.variables
     73     # => [URIVariable(/user)]
     74 
     75 Users can interact with :class:`URIVariable` objects as they see fit, but 
     76 their API may change and are not guaranteed to be consistent across versions.  
     77 Code relying on methods defined on :class:`URIVariable` and other classes, 
     78 methods, and functions in this section may break in future releases.
     79 
     80 .. autoclass:: uritemplate.template.URIVariable
     81     :members: expand
     82