RFC 6570 URI Template Processor

1.3.0 verified Tue May 12 auth: no python install: verified quickstart: verified maintenance

The `uri-template` library provides an implementation of RFC 6570 URI Templates in Python. It supports template expansion in strict adherence to the RFC, while also introducing several extensions for handling non-string values, nested structures, and partial expansions. The current version is 1.3.0, released in June 2023. It appears to be maintained with a slower release cadence by a single maintainer.

pip install uri-template

Common errors

error ModuleNotFoundError: No module named 'uri_template' ↓

cause The `uri-template` Python package is not installed or not accessible in the current environment.

fix

pip install uri-template

error SyntaxError: invalid syntax ↓

cause Python import statements cannot contain hyphens; the correct import name for the `uri-template` package is `uri_template`.

fix

import uri_template

error AttributeError: 'int' object has no attribute 'items' ↓

cause The `variables` argument in `uri_template.expand()` must be a dictionary or a mapping-like object, not a scalar value.

fix

uri_template.expand("{name}", {"name": "value"})

error ValueError: Expected '}', got end of string ↓

cause The URI template string is malformed, specifically missing a closing brace `}` for a variable expression.

fix

uri_template.expand("{var_name}", {"var_name": "value"})

Warnings

gotcha There are two similarly named, but distinct, PyPI packages for URI templates: `uri-template` (this package, with a hyphen) and `uritemplate` (without a hyphen). They have different APIs, features, and maintenance statuses. Ensure you install and use the correct package according to your project's needs. ↓

fix Verify which package is required for your project. If you intend to use the `uritemplate` (no hyphen) package, install `pip install uritemplate` and import `from uritemplate import ...`.

gotcha The `uri-template` library extends RFC 6570 to handle non-string values and nested data structures (lists, dicts, booleans) by converting them or flattening them in specific ways. While convenient, this behaviour deviates from strict RFC 6570 and may lead to unexpected results if not understood. ↓

fix Refer to the library's documentation on 'RFC 6570 Extensions' to understand how different Python types are handled during expansion, especially for nested structures or non-standard primitive types.

gotcha The `URITemplate.expand()` and `uri_template.expand()` methods can raise an `ExpansionFailed` exception if a composite value (e.g., a list or dictionary) is provided for a variable that uses a prefix modifier (e.g., `{var:10}`). ↓

fix Avoid using prefix modifiers with composite values or handle the `ExpansionFailed` exception in your code. Ensure that the types of values passed to template variables are compatible with the specified modifiers.

gotcha This library only supports default *string* values for variables, as in `{foo=bar}`. It does not currently support default values for lists or associative arrays. ↓

fix If default values are needed for non-string types, you must provide them programmatically before calling the `expand` method, rather than relying on the template syntax.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 17.9M

3.10 alpine (musl) - - 0.01s 17.9M

3.10 slim (glibc) wheel 1.5s 0.01s 18M

3.10 slim (glibc) - - 0.01s 18M

3.11 alpine (musl) wheel - 0.02s 19.7M

3.11 alpine (musl) - - 0.02s 19.7M

3.11 slim (glibc) wheel 1.6s 0.02s 20M

3.11 slim (glibc) - - 0.02s 20M

3.12 alpine (musl) wheel - 0.01s 11.6M

3.12 alpine (musl) - - 0.02s 11.6M

3.12 slim (glibc) wheel 1.5s 0.01s 12M

3.12 slim (glibc) - - 0.01s 12M

3.13 alpine (musl) wheel - 0.01s 11.3M

3.13 alpine (musl) - - 0.01s 11.2M

3.13 slim (glibc) wheel 1.4s 0.01s 12M

3.13 slim (glibc) - - 0.01s 12M

3.9 alpine (musl) wheel - 0.01s 17.4M

3.9 alpine (musl) - - 0.01s 17.4M

3.9 slim (glibc) wheel 1.9s 0.01s 18M

3.9 slim (glibc) - - 0.01s 18M

Imports

expand
```
from uri_template import expand
```
partial
```
from uri_template import partial
```
URITemplate
```
from uri_template import URITemplate
```

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates basic URI template expansion using both the standalone `expand` function and the `URITemplate` class. It also shows how to perform partial template expansions.

from uri_template import URITemplate, expand

# Using the expand function for a simple, one-off expansion
uri_str = "http://example.com/api/{resource}/{id}"
expanded_uri_func = expand(uri_str, resource='users', id='123')
print(f"Function expanded: {expanded_uri_func}")

# Using the URITemplate class for repeated expansions or advanced features
template = URITemplate("http://example.com/search{?query,limit}")
expanded_uri_class = template.expand(query='python', limit=10)
print(f"Class expanded: {expanded_uri_class}")

# Example of partial expansion
partial_template = URITemplate("http://example.com/items/{category}/{item_id}")
partially_expanded = partial_template.partial(category='electronics')
print(f"Partially expanded: {partially_expanded}")
# Further expand the partially expanded template
final_expanded = partially_expanded.expand(item_id='laptop-x')
print(f"Further expanded: {final_expanded}")