1"""
2
3uritemplate.api
4===============
5
6This module contains the very simple API provided by uritemplate.
7
8"""
9
10from uritemplate.orderedset import OrderedSet
11from uritemplate.template import URITemplate
12
13
14def expand(uri, var_dict=None, **kwargs):
15    """Expand the template with the given parameters.
16
17    :param str uri: The templated URI to expand
18    :param dict var_dict: Optional dictionary with variables and values
19    :param kwargs: Alternative way to pass arguments
20    :returns: str
21
22    Example::
23
24        expand('https://api.github.com{/end}', {'end': 'users'})
25        expand('https://api.github.com{/end}', end='gists')
26
27    .. note:: Passing values by both parts, may override values in
28              ``var_dict``. For example::
29
30                  expand('https://{var}', {'var': 'val1'}, var='val2')
31
32              ``val2`` will be used instead of ``val1``.
33
34    """
35    return URITemplate(uri).expand(var_dict, **kwargs)
36
37
38def partial(uri, var_dict=None, **kwargs):
39    """Partially expand the template with the given parameters.
40
41    If all of the parameters for the template are not given, return a
42    partially expanded template.
43
44    :param dict var_dict: Optional dictionary with variables and values
45    :param kwargs: Alternative way to pass arguments
46    :returns: :class:`URITemplate`
47
48    Example::
49
50        t = URITemplate('https://api.github.com{/end}')
51        t.partial()  # => URITemplate('https://api.github.com{/end}')
52
53    """
54    return URITemplate(uri).partial(var_dict, **kwargs)
55
56
57def variables(uri):
58    """Parse the variables of the template.
59
60    This returns all of the variable names in the URI Template.
61
62    :returns: Set of variable names
63    :rtype: set
64
65    Example::
66
67        variables('https://api.github.com{/end})
68        # => {'end'}
69        variables('https://api.github.com/repos{/username}{/repository}')
70        # => {'username', 'repository'}
71
72    """
73    return OrderedSet(URITemplate(uri).variable_names)
74