Package: uri-template
uri-templateAn implementation of RFC 6570 URI Templates.This packages implements URI Template expansion in strict adherence to RFC 6570,
but adds a few extensions.RFC 6570 ExtensionsNon-string ValuesRFC 6570 is silent regarding variable values that are not strings, lists, associative arrays, or null.This package handles value types as follows:Values that are instances ofstrare treated as strings.Values implementingcollections.abc.Sequenceare treated as lists.Values implementingcollections.abc.Mappingare treated as associative arrays.Nonevalues are treated as null.Boolean values are converted to the lower case strings 'true' and 'false'.All other values will be converted to strings using the Pythonstr()function.Nested StructuresThis package handles variable values with nested structure,
for example, lists containing other lists or associative arrays,
or associative arrays containing lists or other associative arrays.Nested values for variables that do not use the array modifier ('[]') are treated as follows:Lists containing lists are flattened into a single list.Lists containing associative arrays are treated as a single combined associative array.Associative arrays represent nested data using dot notation (".") for the variable names.Nested values for variables that use the array modifier extend the variable name with
the value's index or key written as an array subscript, e.g. "foo[0]" or "foo[bar]".Default ValuesThis package allows default string values for variables per early drafts of RFC 6570.
e.g. "{foo=bar}" will expand to "bar" if a value forfoois not given.List and associtative array default values are not supported at this time.Specifying Value KeysSometimes a URI Template is used to provide glue between an API and a given set of data.
In this case, the names of values needed in the final URL may not match the data provided
for the expansion.This package allows specifying the key used to pass data into the template.
e.g. "{?foo/bar}" will expand to "?foo="Partial expansionThis package allows partial expansion of URI Templates.In a partial expansion, missing values preseve their expansion in the resultant output.
e.g. a partial expansion of "{one}/{two}" with a value foroneof "foo" andtwomissing will result in:
"foo/{two}".In order to allow partial expansions to preserve value joiners with expanded output,
expansions accept an optional "trailing joiner" of ",", ".", "/", ";", or "&",
if this joiner is present after all variables,
it will be appended to the output of the expansion and will suppress the output prefix.
e.g.: "{#one,two}" with a missing value foroneand a value of "bar" fortwo,
will partially expand to: "#{#one,}bar", which when provided with a value of "foo" foronewill expand to "#foo,bar"Some partial expansions that have some output, but have missing values,
will convert the remaining variables to a different type of expansion so that
further expansions will produce the same output as if all values were originally present.Partial Simple String Expansions will convert to Comma Expansions.Partial Reserved Expansions Partial Fragment Expansions will convert to Reserved Comma Expansions.Partial Form-Style Query Expansions will convert to Form-Style Query Continuations.In order to preserve the resultant value of templates that are paritally expanded,
the following additional Expression Expansions are supported:Comma Expansion: {,var}Similar to Label Expansion with Dot-Prefix,
Comma Expansion prefixes the expansion output with a single comma ",".Reserved Comma Expansion: {,+var}Similar to Comma Expansion,
Reserved Comma Expansion prefixes the expansion output with a single comma ",",
but otherwise performs a Reserved Expansion ({+var}).APIThe package provides three functions:uri_template.expand(template: str, **kwargs) -> (str | None): ...Expand the given template, skipping missing values per RFC 6570.ReturnsNoneif the template is invalid or expansion fails.uri_template.partial(template: str, **kwargs) -> (str | None): ...Partially expand the given template,
replacing missing variables with further expansions.ReturnsNoneif the template is invalid or expansion fails.uri_template.validate(template: str) -> bool: ...ReturnTrueif the template is valid.And the following classes:uri_template.URITemplateURITemplate(template: str)Construct a URITemplate for a given template string.RaisesExpansionInvalid,ExpansionReserved, orVariableInvalidif the template is invalid or unsupported.URITemplate.variables: Iterable[Variable]All variables present in the template.
Duplicates are returned once, order is preserved.URITemplate.variable_names: Iterable[str]The names of all variables present in the template.
Duplicates are returned once, order is preserved.URITemplate.expanded: boolDetermine if template is fully expanded.URITemplate.expand(**kwargs) -> strReturns the result of the expansion, skips missing variables.RaisesExpansionFailedif the expansion fails due to a composite value being passed to a variable with a prefix modifier.URITemplate.partial(**kwargs) -> URITemplateExpand the template, replacing missing variables with further expansions.RaisesExpansionFailedif the expansion fails due to a composite value being passed to a variable with a prefix modifier.URITemplate.str() -> strConvert the URITemplate object back into its original string form.uri_template.VariableVariable(var_spec: str)Construct a Variable.Variable.name: strThe name of the variableVariable.max_length: intThe speicified max length, or0.Variable.explode: boolExplode modifier is present.Variable.array: boolArray modifier is present.Variable.default: (str | None)Specified default value, orNone.Variable.str() -> strConvert the variable back to its original string form.And the following exceptions:uri_template.ExpansionInvalidExpansion specification is invalid.Raised by URITemplate constructor.uri_template.ExpansionReservedExpansion contains a reserved operator.Raised by URITemplate constructor.uri_template.VariableInvalidVariable specification is invalid.Raised by URITemplate constructor.uri_template.ExpansionFailedExpansion failed, currently only possible when a composite value is passed to a variable with a prefix modifier.Raised by URITemplate.expand() or URITemplate.partial() methods.InstallationInstall with pip:pip install uri-template