uri-template

RFC 6570 URI模板的实现。

此包实现了对RFC 6570的URI模板的严格遵循，但增加了一些扩展。

RFC 6570 扩展

非字符串值

RFC 6570 对非字符串、列表、关联数组或null类型的变量值保持沉默。

此包按照以下方式处理值类型：

• 实例为 str 的值被视为字符串。
• 实现 collections.abc.Sequence 的值被视为列表。
• 实现 collections.abc.Mapping 的值被视为关联数组。
• None 值被视为null。
• 布尔值转换为小写字符串 'true' 和 'false'。
• 所有其他值将使用Python str() 函数转换为字符串。

嵌套结构

此包处理具有嵌套结构的变量值，例如，包含其他列表或关联数组的列表，或包含列表或其他关联数组的关联数组。

对于不使用数组修改符（'[]'）的变量，嵌套值处理如下：

• 包含列表的列表将被展平为一个单一的列表。
• 包含关联数组的列表被视为一个单一的合并后的关联数组。
• 关联数组使用点符号（"."）表示变量名称来表示嵌套数据。

对于使用数组修改符的变量，嵌套值将变量名称扩展为值的索引或键，例如 "foo[0]" 或 "foo[bar]"。

默认值

此包允许根据RFC 6570早期草稿为变量设置默认字符串值。例如，"{foo=bar}"在没有为foo提供值的情况下将展开为"bar"。

目前不支持列表和关联数组默认值。

指定值键

有时URI模板用于在API和给定数据集之间提供粘合剂。在这种情况下，最终URL中需要的值名称可能不会与用于展开的数据相匹配。

此包允许指定传递到模板中的键。例如，"{?foo/bar}"将展开为"?foo="

部分展开

此包允许部分展开URI模板。

在部分展开中，缺失的值在最终输出中保留其展开形式。例如，"{one}/{two}"的部分展开，其中one的值为"foo"，而two缺失，将导致："foo/{two}"。

为了允许部分展开保留与展开输出连接的值，展开接受一个可选的逗号"、"点"、"/"、";"或"&"作为"尾部连接符"，如果所有变量之后存在此连接符，它将被附加到展开输出并抑制输出前缀。例如："#{#one,}bar"，其中one缺失值，而two的值为"bar"，将部分展开为："#{#one,}bar"，当为one提供值"foo"时，将展开为："#foo,bar"。

某些具有输出但缺失值的部分展开将把剩余的变量转换为不同类型的展开，以便进一步的展开产生与所有值最初都存在时相同的输出。

• 部分简单字符串展开将转换为逗号展开。
• 部分保留展开部分片段展开将转换为保留逗号展开。
• 部分表单样式查询展开将转换为表单样式查询连续展开。

为了保留部分展开模板的最终值，支持以下附加表达式展开

逗号展开：{,var}

类似于点前缀标签展开，逗号展开在展开输出前添加单个逗号","。

保留逗号展开：{,+var}

类似于逗号展开，保留逗号展开在展开输出前添加单个逗号","，但其他方面执行保留展开({+var})。

API

该包提供三个函数

uri_template.expand(template: str, **kwargs) -> (str | None): ...

根据RFC 6570跳过缺失值展开给定的模板。

如果模板无效或展开失败，则返回None。

uri_template.partial(template: str, **kwargs) -> (str | None): ...

部分展开给定的模板，用进一步的展开替换缺失的变量。

如果模板无效或展开失败，则返回None。

uri_template.validate(template: str) -> bool: ...

如果模板有效，则返回True。

---

以下类

uri_template.URITemplate

URITemplate(template: str)

根据给定的模板字符串构造URITemplate。

如果模板无效或不支持，则引发ExpansionInvalid、ExpansionReserved或VariableInvalid。

URITemplate.variables: Iterable[Variable]

模板中存在的所有变量。重复项只返回一次，顺序被保留。

URITemplate.variable_names: Iterable[str]

模板中存在的所有变量的名称。重复项只返回一次，顺序被保留。

URITemplate.expanded: bool

确定模板是否完全展开。

URITemplate.expand(**kwargs) -> str

返回展开的结果，跳过缺失的变量。

如果由于复合值传递给具有前缀修饰符的变量而导致展开失败，则引发ExpansionFailed。

URITemplate.partial(**kwargs) -> URITemplate

展开模板，用进一步的展开替换缺失的变量。

如果由于复合值传递给具有前缀修饰符的变量而导致展开失败，则引发ExpansionFailed。

URITemplate.str() -> str

将URITemplate对象转换回其原始字符串形式。

---

uri_template.Variable

Variable(var_spec: str)

构造变量。

Variable.name: str

变量的名称

Variable.max_length: int

指定的最大长度，或 0。

Variable.explode: bool

存在Explode修改器。

Variable.array: bool

存在Array修改器。

Variable.default: (str | None)

指定默认值，或 None。

Variable.str() -> str

将变量转换回其原始字符串形式。

---

以下异常

uri_template.ExpansionInvalid

扩展规范无效。

由URITemplate构造函数引发。

uri_template.ExpansionReserved

扩展包含保留操作符。

由URITemplate构造函数引发。

uri_template.VariableInvalid

变量规范无效。

由URITemplate构造函数引发。

uri_template.ExpansionFailed

扩展失败，目前仅在将复合值传递给具有前缀修改器的变量时可能发生。

由URITemplate.expand()或URITemplate.partial()方法引发。

安装

使用pip安装

pip install uri-template