`urllib.parse` ---将URL解析为组件¶

该模块定义了一个标准接口，用于在组件（寻址方案、网络位置、路径等）中断开统一资源定位器（URL）字符串，将组件组合成URL字符串，并将“相对URL”转换为给定“基URL”的绝对URL。

该模块设计用于在相对统一的资源定位器上匹配Internet RFC。它支持以下URL方案： file ， ftp ， gopher ， hdl ， http ， https ， imap ， mailto ， mms ， news ， nntp ， prospero ， rsync ， rtsp ， rtspu ， sftp ， shttp ， sip ， sips ， snews ， svn ， svn+ssh ， telnet ， wais ， ws ， wss .

这个 urllib.parse 模块定义了两大类函数：URL解析和URL引用。以下章节将详细介绍这些内容。

URL解析¶

URL解析函数的重点是将URL字符串拆分为其组件，或将URL组件组合为URL字符串。

urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)¶

将URL解析为六个组件，返回一个6项 named tuple . 这对应于URL的一般结构： scheme://netloc/path;parameters?query#fragment . 每个元组项都是一个字符串，可能是空的。组件不会被分解成更小的部分（例如，网络位置是单个字符串），并且%escape不会展开。上面显示的分隔符不是结果的一部分，除了 path 组件，如果存在则保留。例如：

>>> from urllib.parse import urlparse
>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
>>> o   
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> o.scheme
'http'
>>> o.port
80
>>> o.geturl()
'http://www.cwi.nl:80/%7Eguido/Python.html'

遵循中的语法规范 RFC 1808 ，只有当netloc被“//”正确引入时，urlparse才识别它。否则，输入被假定为相对URL，因此从路径组件开始。

>>> from urllib.parse import urlparse
>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> urlparse('www.cwi.nl/%7Eguido/Python.html')
ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> urlparse('help/Python.html')
ParseResult(scheme='', netloc='', path='help/Python.html', params='',
            query='', fragment='')

这个方案参数提供默认的寻址方案，仅在URL未指定时使用。它的类型（文本或字节）应该与 URL字符串 ，除了默认值 '' 始终允许，并自动转换为 b'' 如果合适的话。

如果 allow_fragments 参数为false，无法识别片段标识符。相反，它们被解析为路径、参数或查询组件的一部分，并且 fragment 在返回值中设置为空字符串。

返回值为 named tuple ，这意味着可以通过索引或命名属性访问其项，这些属性是：

属性	索引	价值	值（如果不存在）
`scheme`	0	URL方案说明符	方案参数
`netloc`	1	网络位置部分	空字符串
`path`	2	分层路径	空字符串
`params`	3	最后一个路径元素的参数	空字符串
`query`	4	查询组件	空字符串
`fragment`	5	片段标识符	空字符串
`username`		用户名	`None`
`password`		密码	`None`
`hostname`		主机名（小写）	`None`
`port`		端口号为整数（如果存在）	`None`

阅读 port 属性将引发 ValueError 如果在URL中指定了无效端口。见节结构化分析结果有关结果对象的详细信息。

中的方括号不匹配 netloc 属性将引发 ValueError .

中的字符 netloc 在NFKC规范化（由IDNA编码使用）下分解为 / ， ? ， # ， @ 或 : 将提高 ValueError . 如果在解析之前对URL进行分解，则不会引发任何错误。

与所有命名元组一样，子类也有一些特别有用的附加方法和属性。其中一种方法是 _replace() . 这个 _replace() 方法将返回一个新的ParseResult对象，用新值替换指定的字段。

>>> from urllib.parse import urlparse
>>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> u._replace(scheme='http')
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')

在 3.2 版更改: 添加了IPv6 URL分析功能。

在 3.3 版更改: 现在对所有URL方案（除非 allow_fragment 是假的），根据 RFC 3986 . 以前，支持碎片的方案列表已经存在。

在 3.6 版更改: 超出范围的端口号现在上升 ValueError ，而不是返回 None .

在 3.8 版更改: 在nfkc规范化下影响netloc解析的字符现在将引发 ValueError .

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None)¶

分析作为字符串参数（数据类型为 application/x-www-form-urlencoded ）数据作为字典返回。字典键是唯一的查询变量名，值是每个名称的值列表。

可选参数 keep_blank_values 指示百分比编码查询中的空值是否应视为空字符串的标志。一个真值表示空格应保留为空字符串。默认的false值表示忽略空白值，并将其视为不包括在内。

可选参数 strict_parsing 指示如何处理分析错误的标志。如果为false（默认值），错误将被静默忽略。如果为真，错误会引发 ValueError 例外。

可选的 encoding 和 errors 参数指定如何将百分比编码序列解码为Unicode字符，如 bytes.decode() 方法。

可选参数 max_num_fields 是要读取的最大字段数。如果设置，则抛出 ValueError 如果有超过 max_num_fields 字段读取。

使用 urllib.parse.urlencode() 功能（与 doseq 参数设置为 True ）将这些字典转换为查询字符串。

在 3.2 版更改: 添加 encoding 和 errors 参数。

在 3.8 版更改: 补充 max_num_fields 参数。

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None)¶

分析作为字符串参数（数据类型为 application/x-www-form-urlencoded ）数据作为名称、值对的列表返回。

可选参数 keep_blank_values 指示百分比编码查询中的空值是否应视为空字符串的标志。一个真值表示空格应保留为空字符串。默认的false值表示忽略空白值，并将其视为不包括在内。

可选参数 strict_parsing 指示如何处理分析错误的标志。如果为false（默认值），错误将被静默忽略。如果为真，错误会引发 ValueError 例外。

可选的 encoding 和 errors 参数指定如何将百分比编码序列解码为Unicode字符，如 bytes.decode() 方法。

可选参数 max_num_fields 是要读取的最大字段数。如果设置，则抛出 ValueError 如果有超过 max_num_fields 字段读取。

使用 urllib.parse.urlencode() 函数将这些对列表转换为查询字符串。

在 3.2 版更改: 添加 encoding 和 errors 参数。

在 3.8 版更改: 补充 max_num_fields 参数。

urllib.parse.urlunparse(parts)¶: 从元组构造由返回的URL urlparse() . 这个 section 参数可以是任何六项不可数。如果最初解析的URL具有不必要的分隔符（例如 ? 使用空查询；RFC声明它们是等效的）。

urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)¶

这和 urlparse() ，但不从URL拆分参数。通常应使用此选项，而不是 urlparse() 如果最新的URL语法允许参数应用于 path URL的一部分（请参见 RFC 2396 被通缉。需要一个单独的函数来分离路径段和参数。此函数返回一个5项 named tuple ：：

(addressing scheme, network location, path, query, fragment identifier).

返回值为 named tuple ，其项可以通过索引或命名属性访问：

属性	索引	价值	值（如果不存在）
`scheme`	0	URL方案说明符	方案参数
`netloc`	1	网络位置部分	空字符串
`path`	2	分层路径	空字符串
`query`	3	查询组件	空字符串
`fragment`	4	片段标识符	空字符串
`username`		用户名	`None`
`password`		密码	`None`
`hostname`		主机名（小写）	`None`
`port`		端口号为整数（如果存在）	`None`

阅读 port 属性将引发 ValueError 如果在URL中指定了无效端口。见节结构化分析结果有关结果对象的详细信息。

中的方括号不匹配 netloc 属性将引发 ValueError .

中的字符 netloc 在NFKC规范化（由IDNA编码使用）下分解为 / ， ? ， # ， @ 或 : 将提高 ValueError . 如果在解析之前对URL进行分解，则不会引发任何错误。

在 3.6 版更改: 超出范围的端口号现在上升 ValueError ，而不是返回 None .

在 3.8 版更改: 在nfkc规范化下影响netloc解析的字符现在将引发 ValueError .

urllib.parse.urlunsplit(parts)¶: 结合元组的元素 urlsplit() 以字符串形式转换为完整的URL。这个 section 参数可以是任何五项不可数。如果最初解析的URL具有不必要的分隔符（例如，a），这可能会导致稍有不同但等价的URL。使用空查询；RFC声明它们是等效的）。

urllib.parse.urljoin(base, url, allow_fragments=True)¶

通过组合“基本URL”来构造完整的（“绝对”）URL（ base ）使用另一个URL（ url ）非正式地，它使用基本URL的组件，特别是寻址方案、网络位置和路径（路径的一部分）来提供相对URL中缺少的组件。例如：

>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'

这个 allow_fragments 参数的含义和默认值与 urlparse() .

注解

如果 url 是一个绝对的URL（即，它以 // 或 scheme:// ） url 的主机名和/或方案将出现在结果中。例如：

>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
...         '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'

如果不希望出现这种行为，请预处理 url 具有 urlsplit() 和 urlunsplit() ，可以删除方案和 奈特洛克 部分。

在 3.5 版更改: 更新行为以匹配中定义的语义 RFC 3986 .

urllib.parse.urldefrag(url)¶

如果 url 包含片段标识符，返回的修改版本 url 没有片断标识符，片断标识符作为单独的字符串。如果中没有片段标识符 url 返回 url 未修改和空字符串。

返回值为 named tuple ，其项可以通过索引或命名属性访问：

属性	索引	价值	值（如果不存在）
`url`	0	没有片段的URL	空字符串
`fragment`	1	片段标识符	空字符串

见节结构化分析结果有关结果对象的详细信息。

在 3.2 版更改: 结果是一个结构化对象，而不是一个简单的2元组。

urllib.parse.unwrap(url)¶: 从包装的URL（即格式为的字符串）中提取URL <URL:scheme://host/path> ， <scheme://host/path> ， URL:scheme://host/path 或 scheme://host/path ）如果 url 不是包装的URL，返回时不做任何更改。

分析ASCII编码字节¶

URL解析函数最初设计为只对字符串进行操作。在实践中，能够将正确引用和编码的URL作为ASCII字节序列进行操作是很有用的。因此，此模块中的URL解析函数都在 bytes 和 bytearray 对象 str 物体。

如果 str 数据已传入，结果也将只包含 str 数据。如果 bytes 或 bytearray 数据已传入，结果将仅包含 bytes 数据。

尝试混合 str 数据与 bytes 或 bytearray 在单个函数中，调用将导致 TypeError 当试图传递非ASCII字节值时，将触发 UnicodeDecodeError .

支持结果对象在 str 和 bytes ，URL解析函数的所有返回值都提供 encode() 方法（当结果包含 str 数据）或 decode() 方法（当结果包含 bytes 数据）。这些方法的签名与相应的 str 和 bytes 方法（除了默认编码是 'ascii' 而不是 'utf-8' ）每一个都产生一个对应类型的值，该值包含 bytes 数据（用于 encode() 方法）或 str 数据（用于 decode() 方法）。

需要对可能包含非ASCII数据的不正确引用的URL进行操作的应用程序将需要在调用URL分析方法之前进行自己的从字节到字符的解码。

本节中描述的行为仅适用于URL解析函数。当产生或使用字节序列时，URL引用函数使用它们自己的规则，如单个URL引用函数的文档中所述。

在 3.2 版更改: URL解析函数现在接受ASCII编码的字节序列

结构化分析结果¶

结果对象来自 urlparse() ， urlsplit() 和 urldefrag() 函数是 tuple 类型。这些子类为这些函数添加了文档中列出的属性、前一节中描述的编码和解码支持以及其他方法：

urllib.parse.SplitResult.geturl()¶

以字符串形式返回原始URL的重新组合版本。这可能与原始URL不同，因为方案可能被规范化为小写，空组件可能被删除。具体来说，将删除空参数、查询和片段标识符。

为了 urldefrag() 结果，只删除空的片段标识符。为了 urlsplit() 和 urlparse() 结果，所有注意到的更改都将对该方法返回的URL进行。

如果通过原始解析函数传递回来，此方法的结果将保持不变：

>>> from urllib.parse import urlsplit
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'

以下类在操作时提供结构化分析结果的实现 str 物体：

class urllib.parse.DefragResult(url, fragment)¶: 混凝土等级 urldefrag() 结果包含 str 数据。这个 encode() 方法返回 DefragResultBytes 实例。

3.2 新版功能.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)¶: 混凝土等级 urlparse() 结果包含 str 数据。这个 encode() 方法返回 ParseResultBytes 实例。

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)¶: 混凝土等级 urlsplit() 结果包含 str 数据。这个 encode() 方法返回 SplitResultBytes 实例。

以下类在操作时提供解析结果的实现 bytes 或 bytearray 物体：

class urllib.parse.DefragResultBytes(url, fragment)¶: 混凝土等级 urldefrag() 结果包含 bytes 数据。这个 decode() 方法返回 DefragResult 实例。

3.2 新版功能.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)¶: 混凝土等级 urlparse() 结果包含 bytes 数据。这个 decode() 方法返回 ParseResult 实例。

3.2 新版功能.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)¶: 混凝土等级 urlsplit() 结果包含 bytes 数据。这个 decode() 方法返回 SplitResult 实例。

3.2 新版功能.

URL引用¶

URL引用函数的重点是通过引用特殊字符和对非ASCII文本进行适当编码来获取程序数据并使其安全地用作URL组件。如果上面的URL解析函数还没有覆盖该任务，那么它们还支持反转这些操作，从URL组件的内容重新创建原始数据。

urllib.parse.quote(string, safe='/', encoding=None, errors=None)¶

替换中的特殊字符一串使用 %xx 逃走。字母、数字和字符 '_.-~' 从不被引用。默认情况下，此函数用于引用URL的路径部分。可选的 safe 参数指定不应引用的其他ASCII字符---其默认值为 '/' .

一串可能是 str 或A bytes 对象。

在 3.7 版更改: 移居 RFC 2396 到 RFC 3986 用于引用URL字符串。“~”现在包含在未保留字符集中。

可选的 encoding 和 errors 参数指定如何处理非ASCII字符，如 str.encode() 方法。 encoding 默认为 'utf-8' . errors 默认为 'strict' ，表示不支持的字符引发 UnicodeEncodeError . encoding 和 errors 在以下情况下不得提供： string 是一个 bytes ，或者 TypeError 提高了。

注意 quote(string, safe, encoding, errors) 等于 quote_from_bytes(string.encode(encoding, errors), safe) .

例子： quote('/El Niño/') 产量 '/El%20Ni%C3%B1o/' .

urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)¶

喜欢 quote() ，但也将空格替换为加号，这是在构建进入URL的查询字符串时引用HTML表单值所必需的。原始字符串中的加号将被转义，除非它们包含在 safe . 它也没有 safe 默认为 '/' .

例子： quote_plus('/El Niño/') 产量 '%2FEl+Ni%C3%B1o%2F' .

urllib.parse.quote_from_bytes(bytes, safe='/')¶

类似于 quote() 但接受 bytes 对象而不是 str ，并且不执行字符串到字节的编码。

例子： quote_from_bytes(b'a&\xef') 产量 'a%26%EF' .

urllib.parse.unquote(string, encoding='utf-8', errors='replace')¶

替换 %xx 与它们的单个字符等效。可选的编码和错误参数指定如何将百分比编码序列解码为Unicode字符，如 bytes.decode() 方法。

一串可能是 str 或A bytes 对象。

encoding 默认为 'utf-8' . errors 默认为 'replace' ，表示用占位符字符替换无效序列。

例子： unquote('/El%20Ni%C3%B1o/') 产量 '/El Niño/' .

在 3.9 版更改: 一串参数支持bytes和str对象（以前仅支持str）。

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')¶

喜欢 unquote() ，但也将加号替换为空格，这是取消引用HTML表单值所必需的。

string 必须是 str .

例子： unquote_plus('/El+Ni%C3%B1o/') 产量 '/El Niño/' .

urllib.parse.unquote_to_bytes(string)¶

替换 %xx 用它们的单八位元等价物逃逸，并返回 bytes 对象。

一串可能是 str 或A bytes 对象。

如果是 str ，中的未转义非ASCII字符 string 被编码成UTF-8字节。

例子： unquote_to_bytes('a%26%EF') 产量 b'a&\xef' .

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)¶

转换映射对象或两个元素元组的序列，其中可能包含 str 或 bytes 对象，以百分比编码的ASCII文本字符串。如果结果字符串用作 data 用于操作后 urlopen() 函数，然后将其编码为字节，否则将导致 TypeError .

结果字符串是一系列 key=value 由分隔的对 '&' 字符，其中 key 和 value 使用 quote_via 功能。默认情况下， quote_plus() 用于引用值，这意味着空格被引用为 '+' 字符和'/'字符编码为 %2F ，它遵循GET请求的标准 (application/x-www-form-urlencoded ）可作为 quote_via 是 quote() ，将空格编码为 %20 并且不编码'/'字符。为了最大限度地控制所引用的内容，请使用 quote 并为指定一个值 safe .

当两个元素元组的序列用作查询参数，每个元组的第一个元素是键，第二个元素是值。value元素本身可以是一个序列，在这种情况下，如果可选参数 多塞克 评估为 True 个人 key=value 由分隔的对 '&' 为键的值序列的每个元素生成。编码字符串中参数的顺序将与序列中参数元组的顺序匹配。

这个 safe ， encoding 和 errors 参数传递到 quote_via (the encoding 和 errors 仅当查询元素是 str ）

要反转此编码过程， parse_qs() 和 parse_qsl() 在该模块中提供，用于将查询字符串解析为python数据结构。

参照 urllib examples 以了解 urllib.parse.urlencode() 方法可用于为POST请求生成URL或数据的查询字符串。

在 3.2 版更改: 查询支持字节和字符串对象。

3.5 新版功能: quote_via 参数。

参见

RFC 3986 -统一资源标识符: 这是当前标准（std66）。对urllib.parse模块的任何更改都应符合此要求。可以观察到一些偏差，这些偏差主要是为了向后兼容的目的，以及一些实际的解析需求，正如在主要浏览器中常见的那样。
RFC 2732 -URL中的文本IPv6地址的格式。: 这指定了IPv6 URL的解析要求。
RFC 2396 -统一资源标识符（URI）：通用语法: 描述统一资源名称（URN）和统一资源定位器（URL）的通用语法要求的文档。
RFC 2368 -mailto url方案。: 分析mailto url方案的要求。
RFC 1808 -相对统一资源定位器: 这个征求意见的规则包括加入一个绝对和一个相对的网址，包括一个相当数量的“异常例子”，管理处理边境案例。
RFC 1738 -统一资源定位器（URL）: 这指定了绝对URL的形式语法和语义。

`urllib.parse` ---将URL解析为组件¶

URL解析¶

分析ASCII编码字节¶

结构化分析结果¶

URL引用¶

Table of Contents

上一个主题

下一个主题

urllib.parse ---将URL解析为组件¶

URL解析¶

分析ASCII编码字节¶

结构化分析结果¶

URL引用¶

`urllib.parse` ---将URL解析为组件¶