yarl 1.13.1

简介

URL 由 str 构建

>>> from yarl import URL
>>> url = URL('https://pythonlang.cn/~guido?arg=1#frag')
>>> url
URL('https://pythonlang.cn/~guido?arg=1#frag')

所有 URL 部分：方案、用户、密码、主机、端口、路径、查询 和 片段 都可以通过属性访问

>>> url.scheme
'https'
>>> url.host
'www.python.org'
>>> url.path
'/~guido'
>>> url.query_string
'arg=1'
>>> url.query
<MultiDictProxy('arg': '1')>
>>> url.fragment
'frag'

所有 URL 操作都会生成一个新的 URL 对象

>>> url = URL('https://pythonlang.cn')
>>> url / 'foo' / 'bar'
URL('https://pythonlang.cn/foo/bar')
>>> url / 'foo' % {'bar': 'baz'}
URL('https://pythonlang.cn/foo?bar=baz')

传递给构造函数和修改方法的字符串将自动编码，以得到规范表示的结果

>>> url = URL('https://pythonlang.cn/шлях')
>>> url
URL('https://pythonlang.cn/%D1%88%D0%BB%D1%8F%D1%85')

常规属性会被 百分比解码，使用 raw_ 版本来获取 编码 字符串

>>> url.path
'/шлях'

>>> url.raw_path
'/%D1%88%D0%BB%D1%8F%D1%85'

URL 的人类可读表示形式可以通过 .human_repr() 获取

>>> url.human_repr()
'https://pythonlang.cn/шлях'

有关完整文档，请参阅 https://yarl.aio-libs.org。

安装

$ pip install yarl

该库仅支持 Python 3！

PyPI 包含适用于 Linux、Windows 和 MacOS 的二进制轮子。如果您想在其他操作系统（例如不兼容 manylinux 的 Alpine Linux，因为它缺少 glibc，因此不能使用我们的轮子）上安装 yarl，则需要使用 tarball 从源代码编译库。它需要一个 C 编译器和安装 Python 头文件。

要跳过编译，您必须通过使用 PEP 517 配置设置 pure-python 或将 YARL_NO_EXTENSIONS 环境变量设置为非空值来明确选择，例如

$ pip install yarl --config-settings=pure-python=false

请注意，纯 Python（未编译）版本要慢得多。然而，PyPy 总是使用纯 Python 实现的，因此不受此变量的影响。

依赖项

YARL 需要 multidict 库。

API 文档

文档位于 https://yarl.aio-libs.org。

为什么 URL 查询 API 不支持布尔值？

没有布尔值的布尔表示标准。

一些系统喜欢 true/false，其他系统喜欢 yes/no、on/off、Y/N、1/0 等。

yarl 无法明确决定如何序列化 bool 值，因为这取决于最终用户的应用程序构建方式，并且对于不同的应用程序而言会有所不同。库不接受 API 中的布尔值；用户应使用自己的首选翻译协议将布尔值转换为字符串。

与其他 URL 库的比较

• furl (https://pypi.python.org/pypi/furl)

  该库功能丰富，但 furl 对象是可变的。

  我害怕将此对象传递给外部代码：谁知道代码是否会以可怕的方式修改我的 URL，而我只想发送带有方便的 URL 属性访问器的 URL。

  furl 有其他非直观的棘手问题，但主要反对意见是可变性。

• URLObject (https://pypi.python.org/pypi/URLObject)

  URLObject 是不可变的，这很好。

  每次 URL 更改都会生成一个新的 URL 对象。

  但该库不执行任何解码/编码转换，将这些令人不快的细节留给最终用户处理。

源代码

该项目托管在GitHub上。

如果您发现了错误或有改进库的建议，请在错误追踪器上提交问题。

讨论列表

aio-libs Google 群组：https://groups.google.com/forum/#!forum/aio-libs

在此处自由发表您的问题和想法。

作者和许可证

“yarl”包由Andrew Svetlov编写。

它是Apache 2许可证，免费提供。

一些内部更改

• 通过@bdraco改进了使用authority调用yarl.URL.build()的性能。

  GitHub上的相关问题和拉取请求： #1163.

错误修复

• 开始拒绝具有无效字符的ASCII主机名。对于看起来像授权字符串的主机字符串，异常信息包括有关如何采取替代措施的说明 – 通过@mjpieters。

  GitHub上的相关问题和拉取请求： #880，#954.

• 修复了将~yarl.URL转换为字符串时IPv6地址缺少括号的问题 – 通过@bdraco。

  GitHub上的相关问题和拉取请求： #1157，#1158.

功能

• 添加了~yarl.URL.host_subcomponent，它返回3986#section-3.2.2主机子组件 – 通过@bdraco。

  在~yarl.URL.raw_host和~yarl.URL.host_subcomponent之间，目前唯一实际的差异是IPv6地址以括号返回。

  GitHub上的相关问题和拉取请求： #1159.

功能

• 添加了~yarl.URL.path_safe，以便可以获取不进行%2F（斜杠）和%25（百分号）解码的路径 – 通过@bdraco。

  GitHub上的相关问题和拉取请求： #1150.

移除和向后不兼容的更改

• 在URL.path中恢复解码%2F（斜杠） – 通过@bdraco。

  此更改恢复了#1057之前的操作。

  GitHub上的相关问题和拉取请求： #1151.

一些内部更改

• 通过@bdraco提高了处理路径的性能。

  GitHub上的相关问题和拉取请求： #1143.

错误修复

• 如果方案不需要主机，则允许替换相对URL的方案 – 通过@bdraco。

  GitHub上的相关问题和拉取请求： #280，#1138.

• 对于除了WHATWG URL规范中列出的特殊方案之外的其他URL方案，允许空主机 – 通过@bdraco。

  GitHub上的相关问题和拉取请求： #1136.

功能

• 通过@bdraco放宽了对查询字符串值作为整数的限制，以允许实现__int__的类。

  GitHub上的相关问题和拉取请求： #1139.

一些内部更改

• 通过@bdraco提高了规范路径的性能。

  GitHub上的相关问题及Pull请求： #1137.

功能

• 添加了URL.extend_query()()方法，通过@bdraco，可以在不替换同名键的情况下扩展参数。

  此方法主要添加是为了替换当前在#1128中使用的低效手动方法。

  GitHub上的相关问题及Pull请求： #1122.

一些内部更改

• 改进了Cython cached_property实现的性能 – 由@bdraco。

  GitHub上的相关问题及Pull请求： #1123.

• 通过删除不必要的代码简化了计算端口 – 由@bdraco。

  GitHub上的相关问题及Pull请求： #1125.

• 改进了编码非IPv6主机的性能 – 由@bdraco。

  GitHub上的相关问题及Pull请求： #1126.

• 当路径、查询字符串或片段为空字符串时，改进了URL.build()()的性能 – 由@bdraco。

  GitHub上的相关问题及Pull请求： #1128.

• 改进了URL.update_query()()方法的性能 – 由@bdraco。

  GitHub上的相关问题及Pull请求： #1130.

• 当参数为str时，改进了处理查询字符串更改的性能 – 由@bdraco。

  GitHub上的相关问题及Pull请求： #1131.

错误修复

• 修复了当现有路径为空时路径拼接的问题 – 由@bdraco。

  在#1082中引入了#1118的回归。

  GitHub上的相关问题及Pull请求： #774，#898，#1010。

功能

• 添加了URL.without_query_params()()方法，用于从查询字符串中删除一些参数 – 由@hongquan。

  GitHub上的相关问题及Pull请求： #1050，#1113。

• 之前受保护的类型_SimpleQuery、_QueryVariable和_Query现在可以作为SimpleQuery、QueryVariable和Query在外部使用 – 由@bdraco。

  GitHub上的相关问题及Pull请求： #1050，#1113。

面向贡献者的更改

• 将所有~typing.Optional替换为~typing.Union – 由@bdraco。

  GitHub上的相关问题及Pull请求： #1095。

一些内部更改

• 显著提高了解析网络位置的性能 – 由@bdraco。

  GitHub上的相关问题及Pull请求： #1112。

• 向缓存中添加了内部类型以防止未来的重构错误 - 由 @bdraco 完成。

  GitHub上的相关问题和拉取请求： #1117。

错误修复

• 修复了与 MultiDictProxy 和 Python 3.8 相关的 TypeError - 由 @bdraco 完成。

  GitHub上的相关问题和拉取请求： #1084、#1105、#1107。

一些内部更改

• 提高了编码主机的性能 - 由 @bdraco 完成。

  之前，库会无条件尝试将主机解析为 IP 地址。现在，如果字符串不在 3986#section-3.2.2 中描述的格式之一，库将避免尝试将主机解析为 IP 地址。

  GitHub上的相关问题和拉取请求： #1104。

错误修复

• URL.join()() 已更改为符合 3986 并与 / operation() 和 URL.joinpath()() 对齐，当连接具有空段的 URL 时。之前使用了 urllib.parse.urljoin，它存在与空段相关的已知问题（python/cpython#84774）。

  由于 URL.join()() 的语义，连接具有方案的 URL 需要将其设置为相对路径，并在前面加上 ./。

  >>> URL("https://web.archive.org/web/").join(URL("./https://github.com/aio-libs/yarl"))
  URL('https://web.archive.org/web/https://github.com/aio-libs/yarl')

  在基础部分以及连接的部分都会尊重空段。

  >>> URL("https://web.archive.org/web/https://").join(URL("github.com/aio-libs/yarl"))
  URL('https://web.archive.org/web/https://github.com/aio-libs/yarl')

  – 由 @commonism

  此更改最初出现在 1.9.5 中，但在 1.9.6 中被回滚，以解决查询字符串处理的问题。

  GitHub上的相关问题和拉取请求： #1039、#1082。

功能

• 添加了 ~yarl.URL.absolute，现在它比 URL.is_absolute() 更受青睐 – 由 @bdraco 完成。

  GitHub上的相关问题和拉取请求： #1100。

错误修复

• 在 ~yarl.URL.port 上添加了缺失的类型 – 由 @bdraco 完成。

  GitHub上的相关问题和拉取请求： #1097。

功能

• 用类型覆盖了 ~yarl.URL 对象 – 由 @bdraco 完成。

  GitHub上的相关问题和拉取请求： #1084。

• 在编码主机时缓存 IP 地址的解析 – 由 @bdraco 完成。

  GitHub上的相关问题和拉取请求： #1086。

面向贡献者的更改

• 用类型覆盖了 ~yarl.URL 对象 – 由 @bdraco 完成。

  GitHub上的相关问题和拉取请求： #1084。

一些内部更改

• 提高了处理端口的性能 – 由 @bdraco 完成。

  GitHub上的相关问题和拉取请求： #1081。

移除和向后不兼容的更改

• 当方案不是 http、https、wss 或 ws 时，移除了对 3986#section-3.2.3 端口规范的支持 – 由 @bdraco 完成。

  最近在 #1033 中添加了对端口规范化的支持，并且包含了一段如果方案不是上述四种之一，就会执行阻塞 I/O 的代码。已经删除了这段代码，因为此库旨在与 asyncio 安全使用。

  GitHub上的相关问题和拉取请求： #1076。

一些内部更改

• 提高了属性缓存的性能 – 由 @bdraco 完成。

  从 aiohttp 中适配了 reify 实现，用于替换内部 cached_property 实现。

  GitHub 上的相关问题和拉取请求： #1070.

错误修复

• 撤销了对 3986 兼容的 URL.join()() 的修改，该修改在 #1039 中引入了空段。

  此更改引入了对连接的 URL 处理查询字符串参数的回归。更改已撤销以保持与先前行为的兼容性。

  GitHub 上的相关问题和拉取请求： #1067.

错误修复

• 连接 URL 并带有空段已更改为与 3986 匹配。

  之前，空段将从路径中删除，破坏了如

  URL("https://web.archive.org/web/") / "https://github.com/"

  现在，/ operation() 和 URL.joinpath()() 保留空段，但不会引入新的空段。例如：

  URL("https://example.org/") / ""

  不会引入一个空段。

  – 由 @commonism 和 @youtux 提供

  GitHub 上的相关问题和拉取请求： #1026.

• 现在在根据 3986#section-3.2.3 标准化 URL 字符串表示时，考虑了知名 URI 方案的默认协议端口。

  如果端口与方案的默认端口匹配，则从 ~yarl.URL 的 str 表示中删除指定的端口 – 由 @commonism 提供。

  GitHub 上的相关问题和拉取请求： #1033.

• URL.join()() 已更改为符合 3986 并与 / operation() 和 URL.joinpath()() 对齐，当连接具有空段的 URL 时。之前使用了 urllib.parse.urljoin，它存在与空段相关的已知问题（python/cpython#84774）。

  由于 URL.join()() 的语义，连接具有方案的 URL 需要将其设置为相对路径，并在前面加上 ./。

  >>> URL("https://web.archive.org/web/").join(URL("./https://github.com/aio-libs/yarl"))
  URL('https://web.archive.org/web/https://github.com/aio-libs/yarl')

  在基础部分以及连接的部分都会尊重空段。

  >>> URL("https://web.archive.org/web/https://").join(URL("github.com/aio-libs/yarl"))
  URL('https://web.archive.org/web/https://github.com/aio-libs/yarl')

  – 由 @commonism

  GitHub 上的相关问题和拉取请求： #1039.

移除和向后不兼容的更改

• 停止在 URL.path 中解码 %2F (/)，因为这可能导致代码错误地将它视为路径分隔符 – 由 @Dreamsorcerer 提供。

  GitHub 上的相关问题和拉取请求： #1057.

• 删除了对 Python 3.7 的支持 – 由 @Dreamsorcerer 提供。

  GitHub 上的相关问题和拉取请求： #1016.

改进了文档

• 在 Contributing docs 页面上，已修复指向 Towncrier philosophy 的链接。

  GitHub 上的相关问题和拉取请求： #981.

• 在 API 参考 中记录了现有的 / magic method() – 由 @commonism 提供。

  GitHub 上的相关问题和拉取请求： #1026.

打包更新和下游说明

• 在将项目目录复制到临时文件夹的逻辑中存在缺陷，这导致当 TMPDIR 设置为项目子目录路径时发生无限递归。这是在 Fedora 及其下游由于使用 pyproject-rpm-macros 而发生的。仅在 pip wheel 中可重现，并且不会影响 pyproject-build 用户。

  – 由 @hroncok 和 @webknjaz 提供

  GitHub 上的相关问题和拉取请求： #992，#1014.

• 支持 Python 3.13 并发布非线程安全的轮子

  GitHub 上的相关问题和拉取请求： #1054.

面向贡献者的更改

• CI/CD配置已更新，以在macOS 14下测试arm64轮文件，但Python 3.7在该环境中不受支持 - 由@webknjaz提供。

  GitHub上的相关问题和拉取请求： #1015.

• 移除了未使用的类型忽略和转换操作 - 由@hauntsaninja提供。

  GitHub上的相关问题和拉取请求： #1031.

一些内部更改

• 端口、方案和原始主机现在是cached_property - 由@bdraco提供。

  aiohttp经常访问这些属性，这会导致urllib每次都构建_hostinfo属性。现在端口、方案和原始主机是缓存属性，这将提高性能。

  GitHub上的相关问题和拉取请求： #1044，#1058.

错误修复

• 当将字符串值传递给yarl.URL.build()作为端口参数时，开始抛出TypeError - 由@commonism提供。

  之前，作为字符串表示形式渲染时，空字符串作为端口会创建格式不正确的URL。(#883)

打包更新和下游说明

• 已从PEP 517树内构建后端配置设置名称中删除了前导破折号。--pure-python现在是pure-python - 由@webknjaz提供。

  现在的使用方法如下

  $ python -m build \
      --config-setting=pure-python=true \
      --config-setting=with-cython-tracing=true

  (#963)

面向贡献者的更改

• 已添加一个逐步的发布指南，描述如何发布yarl - 由@webknjaz提供。

  这主要针对维护者。(#960)

• 为Cython模块实现了覆盖率收集 - 由@webknjaz提供。

  它还将报告给Codecov中的任何非发布CI作业。

  要在一个开发环境中测量覆盖率，可以将yarl以可编辑模式安装

  $ python -Im pip install -e .

  可编辑安装生成C文件，这些文件对于Cython覆盖率插件将测量映射回PYX文件是必需的。

  #961

• 现在可以通过使用with-cython-tracing PEP 517配置设置在Cython构建中请求行跟踪 - @webknjaz。

  这可以在CI和开发环境中用于测量Cython模块的覆盖率，但对于最终用户或下游打包者通常没有用。

  以下是一个使用示例

  $ python -Im pip install . --config-settings=with-cython-tracing=true

  对于可编辑安装，此设置默认为开启。否则，除非明确请求，否则为关闭。

  以下生成C文件，这些文件对于Cython覆盖率插件将测量映射回PYX文件是必需的

  $ python -Im pip install -e .

  或者，可以将环境变量YARL_CYTHON_TRACING=1设置，以与PEP 517配置设置相同。

  #962

错误修复

• 已停止在yarl.URL.joinpath()中删除尾部斜杠 - 由@gmacon提供。(#862，#866)

• 在 yarl.URL.__truediv__() 操作（URL / segment）中开始接受字符串子类 – 由 @mjpieters 实现。（#871，#884）

• 修复了用户名和密码中带方括号的URL的人类表示形式 – 由 @mjpieters 实现。（#876，#882）

• 更新了类型提示，包括 URL.missing_port()、URL.__bytes__() 以及 yarl.URL.joinpath() 的 encoding 参数 – 由 @mjpieters 实现。（#891）

打包更新和下游说明

• 集成了Cython 3，以支持在Python 3.12下构建 yarl – 由 @mjpieters 实现。（#829，#881）

• 在 pyproject.toml 中明确声明现代 setuptools.build_meta 为 PEP 517 构建后端 – 由 @webknjaz 实现。（#886）

• 将大部分打包设置转换为声明性 setup.cfg 配置 – 由 @webknjaz 实现。（#890）

• 将打包从旧的 setup.py 替换为树内 PEP 517 构建后端 – 由 @webknjaz 实现。

  当最终用户或下游打包者需要从源代码（Git检出或sdist）构建 yarl 时，他们可以传递一个 config_settings 标志 --pure-python。如果没有设置此标志，则会构建并包含C扩展。

  以下是使用 pip 实现的方法

  $ python -m pip install . --config-settings=--pure-python=false

  这也可以与 -e | --editable 一起使用。

  这也可以通过 pypa/build 实现

  $ python -m build --config-setting=--pure-python=false

  添加 -w | --wheel 可以强制 pypa/build 直接从源代码生成wheel，而不是先构建sdist然后从它构建。(#893)

• 在发行版包元数据中正式声明支持Python 3.12 – 由 @edgarrmondragon 实现。（#942）

面向贡献者的更改

• 根据 #821 和 3986 添加了对无主机URL的回归测试 – 由 @kenballus 实现。（#821，#822）

• 开始对Python 3.12进行CI测试 yarl – 由 @mjpieters 实现。（#881）

• 现在所有Python 3.12作业都标记为在CI中必须通过 – 由 @edgarrmondragon 实现。（#942）

• MyST 现已集成到 Sphinx 中 – 由 @webknjaz 实现。

  这允许贡献者在遇到直接使用RST困难时，使用Markdown编写新文档。（#953）

功能

• 添加了 URL.joinpath(*elements)，用于创建附加多个路径元素的新URL。（#704）

• 当使用不支持的类型调用时，URL.__truediv__() 返回 NotImplemented —— 由 @michaeljpeters 实现。（#832）

错误修复

• 对于绝对URL的路径归一化，当 .. 段落会超出URL路径根时，不再引发 ValueError 异常。（#536）

• 修复了 update_query() 在参数为 None 时无法去除查询的问题。（#792）

• 在 with_port() 函数上添加了一些输入限制，以防止无效的布尔输入或超出有效端口输入；处理了不正确的 0 端口表示。（#793）

• 如果 host 参数为 None，则 yarl.URL.build() 会引发 TypeError —— 由 @paulpapacz 实现。（#808）

• 修复了当参数为空但不是 None 时，update_query() 无法去除查询的问题。（#845）

杂项

• #220

功能

• 添加了 URL.raw_suffix、URL.suffix、URL.raw_suffixes、URL.suffixes、URL.with_suffix。（#613）

改进了文档

• 修复了对 yarl.URL.human_repr() 的内部引用错误。（#665）

• 修复了对 multidict:index 文档的外部引用错误。（#665）

弃用和移除

• 弃用了对 Python 3.6 的支持。（#672）

杂项

• #646, #699, #701

功能

• 为Linux上的aarch64、i686、ppc64le、s390x和x86_64架构提供轮子。 #507

• 为Python 3.9提供轮子。 #526

错误修复

• human_repr()现在总是生成与原始URL等效的有效表示（如果原始URL有效）。 #511

• 在Cython实现中修复了对单个百分号后面跟有编码字符的重引用。 #514

• 修复了解码未后跟两个十六进制数字的%时产生的ValueError。 #516

• 修复了解码后跟空格和十六进制数字的%。 #520

• 修复了with_query()/update_query()方法对key=[val1, val2]情况下的注释。 #528

删除

• 放弃对Python 3.5的支持；Python 3.6是最小支持的Python版本。

功能

• 允许在查询中使用int和float子类，同时仍然拒绝bool。 #492

错误修复

• 在URL.build()、with_xxx()和/a运算符中不重新引用参数。 #502

• 在origin()中保留IPv6括号。 #504

错误修复

• 修复了将重新定位的内部yarl._quoting_c C扩展包含到发布的PyPI分发的错误。 #485

杂项

• #484

功能

• 在构建URL时将主机转换为小写。 #386

• 允许使用mod运算符（%）更新查询字符串（update_query()方法的别名）。 #435

• 允许在映射的值中使用如list和tuple等序列，以表示一个键具有多个值

  url = URL("http://example.com")
  assert url.with_query({"a": [1, 2]}) == URL("http://example.com/?a=1&a=2")

  #443

• 支持带有方案和路径的URL.build()（创建相对URL）。 #464

• 缓存慢速的IDNA编码/解码调用。 #476

• 添加@final / Final类型提示 #477

• 支持URL权威性/原始权威性属性和URL.build()方法的权威性参数。 #478

• 隐藏库实现细节，使公开的列表非常干净。 #483

错误修复

• 修复了与较新Python版本（3.7.6、3.8.1和3.9.0+）的测试。 #409

• 修复了一个问题，其中查询组件，以映射或序列的形式传递，以意外的方式未引用。 #426

• 在__init__.pyi中隐藏Query和QueryVariable类型别名，现在它们以下划线开头。 #431

• 在更新端口/用户/密码后保留IPv6括号。 #451