20.16. urlparse —将 URL 解析为组件

源代码： Lib/urlparse.py

---

该模块定义了一个标准接口，用于分解组件中的统一资源定位符(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，_22，sip _ ，telnet，wais。

2.5 版的新Function：支持sftp和sips方案。

urlparse模块定义以下Function：

• urlparse. urlparse(* urlstring * [，* scheme * [，* allow_fragments *]])
  • 将 URL 解析为六个部分，返回一个 6Tuples。这对应于 URL 的一般结构：scheme://netloc/path;parameters?query#fragment。每个 Tuples 项目都是一个字符串，可能为空。组件不会分成较小的部分(例如，网络位置是单个字符串)，并且％转义符不会扩展。上面显示的定界符不是结果的一部分，除了* path *组件中的前导斜线(如果存在的话，将保留)。例如：

>>> from urlparse 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 才识别它。否则，假定 Importing 为相对 URL，因此从路径组件开始。

>>> from urlparse 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='')

如果指定了* scheme *参数，它将提供默认的寻址方案，仅在 URL 未指定一个方案时才使用。此参数的默认值为空字符串。

如果* allow_fragments *参数为 false，则即使 URL 的寻址方案通常支持片段标识符，也不会识别片段标识符并将其解析为前述组件的一部分。此参数的默认值为True。

返回值实际上是tuple的子类的实例。此类具有以下附加的只读便捷属性：

Attribute	Index	Value	值(如果不存在)
scheme	0	URL 方案说明符	* scheme *参数
netloc	1	网络位置部分	empty string
path	2	Hierarchical path	empty string
params	3	最后路径元素的参数	empty string
query	4	Query component	empty string
fragment	5	Fragment identifier	empty string
username		User name	None
password		Password	None
hostname		主机名(小写)	None
port		端口号为整数(如果存在)	None

有关结果对象的更多信息，请参见urlparse()和 urlsplit()的结果部分。

netloc属性中的字符在 NFKC 规范下(由 IDNA 编码使用)分解为/，?，#，@或:中的任何一个，将引发ValueError。如果 URL 在解析之前已分解，或者不是 Unicode 字符串，则不会引发任何错误。

在版本 2.5 中进行了更改：添加了属性以返回值。

在 2.7 版中进行了更改：添加了 IPv6 URL 解析Function。

在版本 2.7.17 中更改：在 NFKC 规范下影响 netloc 解析的字符现在将引发ValueError。

• urlparse. parse_qs(* qs * [，* keep_blank_values * [，* strict_parsing * [，* max_num_fields *]]])
  • 解析作为字符串参数给出的查询字符串(类型为* application/x-www-form-urlencoded *的数据)。数据作为字典返回。字典键是唯一的查询变量名称，而值是每个名称的值列表。

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

可选参数* strict_parsing *是一个标志，指示如何处理解析错误。如果为 false(默认值)，错误将被忽略。如果为 true，则错误会引发ValueError异常。

可选参数* max_num_fields 是要读取的最大字段数。如果设置，则如果读取的 max_num_fields *个字段以上，则抛出ValueError。

使用urllib.urlencode()函数可将此类词典转换为查询字符串。

2.6 版的新Function：从cgi模块复制。

在版本 2.7.16 中进行了更改：添加了* max_num_fields *参数。

• urlparse. parse_qsl(* qs * [，* keep_blank_values * [，* strict_parsing * [，* max_num_fields *]]])
  • 解析作为字符串参数给出的查询字符串(类型为* application/x-www-form-urlencoded *的数据)。数据作为名称，值对的列表返回。

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

可选参数* strict_parsing *是一个标志，指示如何处理解析错误。如果为 false(默认值)，错误将被忽略。如果为 true，则错误会引发ValueError异常。

可选参数* max_num_fields 是要读取的最大字段数。如果设置，则如果读取的 max_num_fields *个字段以上，则抛出ValueError。

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

2.6 版的新Function：从cgi模块复制。

在版本 2.7.16 中进行了更改：添加了* max_num_fields *参数。

• urlparse. urlunparse(* parts *)

  • 根据urlparse()返回的 Tuples 构造 URL。 * parts *参数可以是任何六项可迭代的。如果最初解析的 URL 包含不必要的定界符(例如，带空查询的？； RFC 语句它们是等效的)，则这可能会导致稍微不同但等效的 URL。

• urlparse. urlsplit(* urlstring * [，* scheme * [，* allow_fragments *]])

  • 这类似于urlparse()，但不会从 URL 拆分参数。如果需要将参数应用于 URL 的* path *部分的每个段(请参见 RFC 2396)的最新 URL 语法，通常应使用urlparse()代替。需要单独的Function来分隔路径段和参数。该函数返回一个 5Tuples：(寻址方案，网络位置，路径，查询，片段标识符)。

返回值实际上是tuple的子类的实例。此类具有以下附加的只读便捷属性：

Attribute	Index	Value	值(如果不存在)
scheme	0	URL 方案说明符	* scheme *参数
netloc	1	网络位置部分	empty string
path	2	Hierarchical path	empty string
query	3	Query component	empty string
fragment	4	Fragment identifier	empty string
username		User name	None
password		Password	None
hostname		主机名(小写)	None
port		端口号为整数(如果存在)	None

有关结果对象的更多信息，请参见urlparse()和 urlsplit()的结果部分。

netloc属性中的字符在 NFKC 规范下(由 IDNA 编码使用)分解为/，?，#，@或:中的任何一个，将引发ValueError。如果 URL 在解析之前已分解，或者不是 Unicode 字符串，则不会引发任何错误。

2.2 版中的新Function。

在版本 2.5 中进行了更改：添加了属性以返回值。

在版本 2.7.17 中更改：在 NFKC 规范下影响 netloc 解析的字符现在将引发ValueError。

• urlparse. urlunsplit(* parts *)
  • 将urlsplit()返回的 Tuples 元素合并为完整的 URL 作为字符串。 * parts *参数可以是任何五项可迭代的。如果最初解析的 URL 包含不必要的定界符(例如，带空查询的？； RFC 语句它们是等效的)，则这可能会导致稍微不同但等效的 URL。

2.2 版中的新Function。

• urlparse. urljoin(* base ， url * [，* allow_fragments *])
  • pass将“基本 URL”(* base )与另一个 URL( url *)组合来构造完整的(“绝对”)URL。非正式地，这使用基本 URL 的组件，特别是寻址方案，网络位置和路径(的一部分)来提供相对 URL 中缺少的组件。例如：

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

• allow_fragments *参数的含义和默认值与urlparse()相同。

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

如果您不希望出现这种情况，请使用urlsplit()和urlunsplit()预处理* url ，并删除可能的 scheme 和 netloc *部分。

• urlparse. urldefrag(* url *)
  • 如果* url 包含片段标识符，则返回 url 的修改版本，不包含片段标识符，并将片段标识符作为单独的字符串。如果 url 中没有片段标识符，则返回 url *未经修改且为空字符串。

20.16.1. urlparse()和 urlsplit()的结果

urlparse()和urlsplit()函数的结果对象是tuple类型的子类。这些子类添加了这些函数中描述的属性，并提供了其他方法：

• ParseResult. geturl ( )
  • 以字符串形式返回原始 URL 的重新组合版本。这可能与原始 URL 有所不同，因为该方案将始终规范化为小写，并且可能会丢弃空的组件。具体来说，将删除空参数，查询和片段标识符。

如果pass原始解析函数返回，则此方法的结果是一个固定点：

>>> import urlparse
>>> url = 'HTTP://www.Python.org/doc/#'

>>> r1 = urlparse.urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'

>>> r2 = urlparse.urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'

2.5 版的新Function。

以下类提供了解析结果的实现：

• • class * urlparse. ParseResult(* scheme ， netloc ， path ， params ， query ， fragment *)
  • urlparse()个结果的具体类别。
• • class * urlparse. SplitResult(* scheme ， netloc ， path ， query ， fragment *)
  • urlsplit()个结果的具体类别。