API 文档#
使用 Sphinx 的 sphinx.ext.autodoc 插件，可以自动生成 Python 模块的文档。
提示
通过设置以下选项，避免使用 autodoc 时出现函数签名内类型注释
# -- Options for autodoc ----------------------------------------------------
# https://sphinx-doc.cn/en/master/usage/extensions/autodoc.html#configuration
# Automatically extract typehints when specified and place them in
# descriptions of the relevant function/method.
autodoc_typehints = "description"
# Don't show class signature with the class' name.
autodoc_class_signature = "separated"
解析（绝对和相对）URL。
urlparse 模块基于以下 RFC 规范。
RFC 3986 (STD66): T. Berners-Lee、R. Fielding 和 L. Masinter 于 2005 年 1 月撰写的“统一资源标识符”。
RFC 2732: R.Hinden、B.Carpenter 和 L.Masinter 于 1999 年 12 月撰写的“URL 中的 IPv6 地址文本格式”。
RFC 2396: T. Berners-Lee、R. Fielding 和 L. Masinter 于 1998 年 8 月撰写的“统一资源标识符 (URI)：通用语法”。
RFC 2368: P.Hoffman、L Masinter 和 J. Zawinski 于 1998 年 7 月撰写的“mailto URL 方案”。
RFC 1808: UC Irvine 的 R. Fielding 于 1995 年 6 月撰写的“相对统一资源定位符”。
RFC 1738: T. Berners-Lee、L. Masinter 和 M. McCahill 于 1994 年 12 月撰写的“统一资源定位符 (URL)”
RFC 3986 被认为是当前标准，urlparse 模块的任何未来更改都应符合该标准。由于解析的实际情况以及为了向后兼容，urlparse 模块目前并不完全符合此 RFC，保留了一些旧 RFC 的解析怪癖。test_urlparse.py 中的测试用例很好地指示了解析行为。
还应考虑 WHATWG URL 解析器规范。由于现有用户代码 API 行为预期（Hyrum 定律），我们也不符合它。它在进行更改时可作为有用的指南。
- class urllib.parse.DefragResult(url, fragment)[源代码]#
方法
count(value, /)返回 value 的出现次数。
index(value[, start, stop])返回 value 的第一个索引。
编码
获取 url
- class urllib.parse.DefragResultBytes(url, fragment)[源代码]#
方法
count(value, /)返回 value 的出现次数。
index(value[, start, stop])返回 value 的第一个索引。
解码
获取 url
- class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)[源代码]#
- 属性：
- 主机名
- 密码
- 端口
- 用户名
方法
count(value, /)返回 value 的出现次数。
index(value[, start, stop])返回 value 的第一个索引。
编码
获取 url
- class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)[源代码]#
- 属性：
- 主机名
- 密码
- 端口
- 用户名
方法
count(value, /)返回 value 的出现次数。
index(value[, start, stop])返回 value 的第一个索引。
解码
获取 url
- class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)[源代码]#
- 属性：
- 主机名
- 密码
- 端口
- 用户名
方法
count(value, /)返回 value 的出现次数。
index(value[, start, stop])返回 value 的第一个索引。
编码
获取 url
- class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)[源代码]#
- 属性：
- 主机名
- 密码
- 端口
- 用户名
方法
count(value, /)返回 value 的出现次数。
index(value[, start, stop])返回 value 的第一个索引。
解码
获取 url
- urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')[source]#
解析以字符串参数形式给出的查询。
参数
qs: 要解析的百分号编码的查询字符串
- keep_blank_values: 指示是否将百分号编码查询中的空值视为
空字符串的标志。值为 true 表示应将空白保留为空字符串。默认值 false 表示忽略空值，并将其视为未包含。
- strict_parsing: 指示如何处理解析错误的标志。
如果为 false（默认值），则静默忽略错误。如果为 true，则错误会引发 ValueError 异常。
- encoding 和 errors: 指定如何将百分号编码的序列解码为
Unicode 字符，与 bytes.decode() 方法接受的参数相同。
- max_num_fields: int。如果设置，则当 parse_qsl() 读取的字段数
超过 n 时，将引发 ValueError。
- separator: str。用于分隔查询参数的符号。
默认为 &。
返回一个字典。
- urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')[source]#
解析以字符串参数形式给出的查询。
参数
qs: 要解析的百分号编码的查询字符串
- keep_blank_values: 指示是否将百分号编码查询中的空值视为
空字符串的标志。值为 true 表示应将空白保留为空字符串。默认值 false 表示忽略空值，并将其视为未包含。
- strict_parsing: 指示如何处理解析错误的标志。如果为
false（默认值），则静默忽略错误。如果为 true，则错误会引发 ValueError 异常。
- encoding 和 errors: 指定如何将百分号编码的序列解码为
Unicode 字符，与 bytes.decode() 方法接受的参数相同。
- max_num_fields: int。如果设置，则当 parse_qsl() 读取的字段数
超过 n 时，将引发 ValueError。
- separator: str。用于分隔查询参数的符号。
默认为 &。
返回一个列表。
- urllib.parse.quote(‘abc def’) ‘abc%20def’[source]#
URL 的每个部分（例如路径信息、查询等）都有一组不同的保留字符，必须对其进行引用。 quote 函数提供了一种谨慎（并非最简化）的方式来引用大多数这些部分的字符串。
RFC 3986 统一资源标识符 (URI)：通用语法列出了以下（非）保留字符。
非保留字符 = 字母 / 数字 / “-” / “.” / “_” / “~” 保留字符 = gen-delims / sub-delims gen-delims = “:” / “/” / “?” / “#” / “[” / “]” / “@” sub-delims = “!” / “$” / “&” / “’” / “(” / “)”
/ “*” / “+” / “,” / “;” / “=”
每个保留字符都在 URL 的某些组件中保留，但不一定在所有组件中都保留。
quote 函数会对所有既不在非保留字符（“始终安全”）也不在通过 safe 参数设置的附加字符集中的字符进行百分号转义。
safe 参数的默认值为 ‘/’。该字符是保留的，但在典型用法中，quote 函数是在要保留现有斜杠字符的路径上调用的。
Python 3.7 已从使用 RFC 2396 更新为使用 RFC 3986 来引用 URL 字符串。现在，“~” 包含在非保留字符集中。
string 和 safe 可以是 str 或 bytes 对象。如果 string 是 bytes 对象，则不得指定 encoding 和 errors。
可选的 encoding 和 errors 参数指定如何处理非 ASCII 字符，与 str.encode 方法接受的参数相同。默认情况下，encoding='utf-8'（字符使用 UTF-8 编码），errors='strict'（不支持的字符会引发 UnicodeEncodeError）。
- urllib.parse.quote_from_bytes(bs, safe='/')[source]#
与 quote() 类似，但接受 bytes 对象而不是 str，并且不执行字符串到字节的编码。它始终返回 ASCII 字符串。 quote_from_bytes(b'abc def?') -> ‘abc%20def%3f’
- urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)[source]#
与 quote() 类似，但还会将 ‘ ’ 替换为 ‘+’，这是引用 HTML 表单值所必需的。原始字符串中的加号会被转义，除非它们包含在 safe 中。它的 safe 默认值也不是 ‘/’。
- urllib.parse.unquote(string, encoding='utf-8', errors='replace')#
将 %xx 转义序列替换为其对应的单字符。可选的 encoding 和 errors 参数指定如何将百分号编码的序列解码为 Unicode 字符，与 bytes.decode() 方法接受的参数相同。默认情况下，百分号编码的序列使用 UTF-8 解码，无效的序列将被替换为占位符。
unquote(‘abc%20def’) -> ‘abc def’。
- urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')#
类似于 unquote()，但还会将加号替换为空格，这是 HTML 表单值解码所必需的。
unquote_plus(‘%7e/abc+def’) -> ‘~/abc def’
- urllib.parse.unquote_to_bytes('abc%20def') b'abc def'.#
- urllib.parse.urldefrag(url)#
移除 URL 中的任何片段标识符。
返回一个由去除了片段标识符的 URL 和片段标识符组成的元组。如果 URL 不包含片段标识符，则第二个元素为空字符串。
- urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=<function quote_plus>)#
将字典或二元组序列编码为 URL 查询字符串。
如果 query 参数中的任何值是序列，并且 doseq 为 true，则每个序列元素都将转换为单独的参数。
如果 query 参数是二元组序列，则输出中参数的顺序将与输入中参数的顺序匹配。
query 参数的组成部分可以是字符串或字节类型。
safe、encoding 和 errors 参数将传递给 quote_via 指定的函数（仅当组件是 str 类型时才传递 encoding 和 errors）。
- urllib.parse.urljoin(base, url, allow_fragments=True)#
将基本 URL 和可能的相对 URL 连接起来，形成后者的绝对解释。
- urllib.parse.urlparse(url, scheme='', allow_fragments=True)#
将 URL 解析为 6 个组件： <scheme>://<netloc>/<path>;<params>?<query>#<fragment>
结果是一个包含与上述字段对应的 6 个元素的命名元组。它是一个 ParseResult 或 ParseResultBytes 对象，取决于 url 参数的类型。
netloc 的用户名、密码、主机名和端口子组件也可以作为返回对象的属性进行访问。
当在 url 中找不到 scheme 组件时，scheme 参数提供 scheme 组件的默认值。
如果 allow_fragments 为 False，则不会尝试将 fragment 组件与前一个组件（可以是 path 或 query）分开。
注意，% 转义序列不会被展开。
- urllib.parse.urlsplit(url, scheme='', allow_fragments=True)#
将 URL 解析为 5 个组件： <scheme>://<netloc>/<path>?<query>#<fragment>
结果是一个包含与上述字段对应的 5 个元素的命名元组。它是一个 SplitResult 或 SplitResultBytes 对象，取决于 url 参数的类型。
netloc 的用户名、密码、主机名和端口子组件也可以作为返回对象的属性进行访问。
当在 url 中找不到 scheme 组件时，scheme 参数提供 scheme 组件的默认值。
如果 allow_fragments 为 False，则不会尝试将 fragment 组件与前一个组件（可以是 path 或 query）分开。
注意，% 转义序列不会被展开。
- urllib.parse.urlunparse(components)#
将已解析的 URL 重新组合在一起。如果最初解析的 URL 具有冗余分隔符（例如带有空查询的 ?，草案声明这些是等效的），这可能会导致略有不同但等效的 URL。
- urllib.parse.urlunsplit(components)#
将 urlsplit() 返回的元组的元素组合成一个完整的 URL 字符串。data 参数可以是任何五项可迭代对象。如果最初解析的 URL 具有不必要的分隔符（例如，带有空查询的 ?；RFC 声明这些是等效的），这可能会导致略有不同但等效的 URL。