"""
uritemplate.variable
====================
This module contains the URIVariable class which powers the URITemplate class.
What treasures await you:
- URIVariable class
You see a hammer in front of you.
What do you do?
>
"""
import collections
import sys
if (2, 6) <= sys.version_info < (2, 8):
import urllib
elif (3, 3) <= sys.version_info < (4, 0):
import urllib.parse as urllib
class URIVariable(object):
"""This object validates everything inside the URITemplate object.
It validates template expansions and will truncate length as decided by
the template.
Please note that just like the :class:`URITemplate <URITemplate>`, this
object's ``__str__`` and ``__repr__`` methods do not return the same
information. Calling ``str(var)`` will return the original variable.
This object does the majority of the heavy lifting. The ``URITemplate``
object finds the variables in the URI and then creates ``URIVariable``
objects. Expansions of the URI are handled by each ``URIVariable``
object. ``URIVariable.expand()`` returns a dictionary of the original
variable and the expanded value. Check that method's documentation for
more information.
"""
operators = ('+', '#', '.', '/', ';', '?', '&', '|', '!', '@')
reserved = ":/?#[]@!$&'()*+,;="
def __init__(self, var):
#: The original string that comes through with the variable
self.original = var
#: The operator for the variable
self.operator = ''
#: List of safe characters when quoting the string
self.safe = ''
#: List of variables in this variable
self.variables = []
#: List of variable names
self.variable_names = []
#: List of defaults passed in
self.defaults = {}
# Parse the variable itself.
self.parse()
self.post_parse()
def __repr__(self):
return 'URIVariable(%s)' % self
def __str__(self):
return self.original
def parse(self):
"""Parse the variable.
This finds the:
- operator,
- set of safe characters,
- variables, and
- defaults.
"""
var_list = self.original
if self.original[0] in URIVariable.operators:
self.operator = self.original[0]
var_list = self.original[1:]
if self.operator in URIVariable.operators[:2]:
self.safe = URIVariable.reserved
var_list = var_list.split(',')
for var in var_list:
default_val = None
name = var
if '=' in var:
name, default_val = tuple(var.split('=', 1))
explode = False
if name.endswith('*'):
explode = True
name = name[:-1]
prefix = None
if ':' in name:
name, prefix = tuple(name.split(':', 1))
prefix = int(prefix)
if default_val:
self.defaults[name] = default_val
self.variables.append(
(name, {'explode': explode, 'prefix': prefix})
)
self.variable_names = [varname for (varname, _) in self.variables]
def post_parse(self):
"""Set ``start``, ``join_str`` and ``safe`` attributes.
After parsing the variable, we need to set up these attributes and it
only makes sense to do it in a more easily testable way.
"""
self.safe = ''
self.start = self.join_str = self.operator
if self.operator == '+':
self.start = ''
if self.operator in ('+', '#', ''):
self.join_str = ','
if self.operator == '#':
self.start = '#'
if self.operator == '?':
self.start = '?'
self.join_str = '&'
if self.operator in ('+', '#'):
self.safe = URIVariable.reserved
def _query_expansion(self, name, value, explode, prefix):
"""Expansion method for the '?' and '&' operators."""
if value is None:
return None
tuples, items = is_list_of_tuples(value)
safe = self.safe
if list_test(value) and not tuples:
if not value:
return None
if explode:
return self.join_str.join(
'%s=%s' % (name, quote(v, safe)) for v in value
)
else:
value = ','.join(quote(v, safe) for v in value)
return '%s=%s' % (name, value)
if dict_test(value) or tuples:
if not value:
return None
items = items or sorted(value.items())
if explode:
return self.join_str.join(
'%s=%s' % (
quote(k, safe), quote(v, safe)
) for k, v in items
)
else:
value = ','.join(
'%s,%s' % (
quote(k, safe), quote(v, safe)
) for k, v in items
)
return '%s=%s' % (name, value)
if value:
value = value[:prefix] if prefix else value
return '%s=%s' % (name, quote(value, safe))
return name + '='
def _label_path_expansion(self, name, value, explode, prefix):
"""Label and path expansion method.
Expands for operators: '/', '.'
"""
join_str = self.join_str
safe = self.safe
if value is None or (len(value) == 0 and value != ''):
return None
tuples, items = is_list_of_tuples(value)
if list_test(value) and not tuples:
if not explode:
join_str = ','
expanded = join_str.join(
quote(v, safe) for v in value if value is not None
)
return expanded if expanded else None
if dict_test(value) or tuples:
items = items or sorted(value.items())
format_str = '%s=%s'
if not explode:
format_str = '%s,%s'
join_str = ','
expanded = join_str.join(
format_str % (
quote(k, safe), quote(v, safe)
) for k, v in items if v is not None
)
return expanded if expanded else None
value = value[:prefix] if prefix else value
return quote(value, safe)
def _semi_path_expansion(self, name, value, explode, prefix):
"""Expansion method for ';' operator."""
join_str = self.join_str
safe = self.safe
if value is None:
return None
if self.operator == '?':
join_str = '&'
tuples, items = is_list_of_tuples(value)
if list_test(value) and not tuples:
if explode:
expanded = join_str.join(
'%s=%s' % (
name, quote(v, safe)
) for v in value if v is not None
)
return expanded if expanded else None
else:
value = ','.join(quote(v, safe) for v in value)
return '%s=%s' % (name, value)
if dict_test(value) or tuples:
items = items or sorted(value.items())
if explode:
return join_str.join(
'%s=%s' % (
quote(k, safe), quote(v, safe)
) for k, v in items if v is not None
)
else:
expanded = ','.join(
'%s,%s' % (
quote(k, safe), quote(v, safe)
) for k, v in items if v is not None
)
return '%s=%s' % (name, expanded)
value = value[:prefix] if prefix else value
if value:
return '%s=%s' % (name, quote(value, safe))
return name
def _string_expansion(self, name, value, explode, prefix):
if value is None:
return None
tuples, items = is_list_of_tuples(value)
if list_test(value) and not tuples:
return ','.join(quote(v, self.safe) for v in value)
if dict_test(value) or tuples:
items = items or sorted(value.items())
format_str = '%s=%s' if explode else '%s,%s'
return ','.join(
format_str % (
quote(k, self.safe), quote(v, self.safe)
) for k, v in items
)
value = value[:prefix] if prefix else value
return quote(value, self.safe)
def expand(self, var_dict=None):
"""Expand the variable in question.
Using ``var_dict`` and the previously parsed defaults, expand this
variable and subvariables.
:param dict var_dict: dictionary of key-value pairs to be used during
expansion
:returns: dict(variable=value)
Examples::
# (1)
v = URIVariable('/var')
expansion = v.expand({'var': 'value'})
print(expansion)
# => {'/var': '/value'}
# (2)
v = URIVariable('?var,hello,x,y')
expansion = v.expand({'var': 'value', 'hello': 'Hello World!',
'x': '1024', 'y': '768'})
print(expansion)
# => {'?var,hello,x,y':
# '?var=value&hello=Hello%20World%21&x=1024&y=768'}
"""
return_values = []
for name, opts in self.variables:
value = var_dict.get(name, None)
if not value and value != '' and name in self.defaults:
value = self.defaults[name]
if value is None:
continue
expanded = None
if self.operator in ('/', '.'):
expansion = self._label_path_expansion
elif self.operator in ('?', '&'):
expansion = self._query_expansion
elif self.operator == ';':
expansion = self._semi_path_expansion
else:
expansion = self._string_expansion
expanded = expansion(name, value, opts['explode'], opts['prefix'])
if expanded is not None:
return_values.append(expanded)
value = ''
if return_values:
value = self.start + self.join_str.join(return_values)
return {self.original: value}
def is_list_of_tuples(value):
if (not value or
not isinstance(value, (list, tuple)) or
not all(isinstance(t, tuple) and len(t) == 2 for t in value)):
return False, None
return True, value
def list_test(value):
return isinstance(value, (list, tuple))
def dict_test(value):
return isinstance(value, (dict, collections.MutableMapping))
try:
texttype = unicode
except NameError: # Python 3
texttype = str
stringlikes = (texttype, bytes)
def _encode(value, encoding='utf-8'):
if (isinstance(value, texttype) and
getattr(value, 'encode', None) is not None):
return value.encode(encoding)
return value
def quote(value, safe):
if not isinstance(value, stringlikes):
value = str(value)
return urllib.quote(_encode(value), safe)