You are here:  Home » Python » – 将URL解析为组件 – Internet协议和支持(Python教程)(参考资料)

urllib.parse– 将URL解析为组件

源代码: Lib / urllib / parse.py


此模块定义了一个标准接口来打破统一资源定位器(URL)字符串组件(寻址方案,网络位置,路径等),将组件重新组合成URL字符串,并将“相对URL”转换为给定“基本URL”的绝对URL .

模块具有被设计为匹配相对UniformResource定位器上的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.urlparseurlstring, scheme=””, allow_fragments=True

将URL解析为六个组件,返回一个6元组。这对应于URL的一般结构:scheme://netloc/path;parameters?query#fragment每个元组项都是一个字符串,可能是空的。组件不会分解为较小的部分(例如,网络位置是单个字符串),并且不会扩展%escapes。如上所示的分隔符不是结果的一部分,除了path组件中的前导斜杠,如果存在则保留。例如:

>>> from urllib.parse import urlparse>>> o = urlparse("http://www.cwi.nl:80/%7Eguido/Python.html")>>> o   # doctest: +NORMALIZE_WHITESPACEParseResult(scheme="http", netloc="www.cwi.nl:80", path="/%7Eguido/Python.html",            params="", query="", fragment="")>>> o.scheme"http">>> o.port80>>> o.geturl()"http://www.cwi.nl:80/%7Eguido/Python.html"

遵循 RFC 1808 中的语法规范,只有在’//’正确引入的情况下,urlparse才会识别netloc。否则,输入被假定为相对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="")

scheme参数给出默认的寻址方案,仅在URL未指定时才使用。它应该是与urlstring相同的类型(文本或字节),除了默认值""总是允许的,并且如果合适的话自动转换为b""

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

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

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

port属性会提升ValueError在URL中指定了ifan invalid port。见第节结构化解析结果有关结果对象的更多信息.

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

版本3.2中更改:添加了IPv6 URL解析功能

在版本3.3中更改:根据allow_fragment RFC 3986 ,现在为所有URL方案解析片段(除非 isfalse)。以前,存在支持碎片的软件白名单.

版本3.6:超出范围的端口号现在提升ValueError,而不是回复None.

urllib.parse.parse_qsqs, keep_blank_values=False, strict_parsing=False, encoding=”utf-8″, errors=”replace”, max_num_fields=None

解析作为字符串参数给出的查询字符串(类型为application/x-www-form-urlencoded的数据)。数据以adictionary的形式返回。字典键是唯一的查询变量名称,值是每个名称的值列表.

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

可选参数strict_parsing是一个标志,指示如何处理分析错误。如果为false(默认值),则会以静默方式忽略错误。如果为true,则错误会引发ValueError exception.

可选的encodingerrors参数指定如何将经过编码的序列解码为Unicode字符,如bytes.decode()方法

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

使用urllib.parse.urlencode()功能(用doseq参数设置为True)将这些词典转换为querystrings.

更改版本3.2:添加encodingerrors参数。

在版本3.7.2中更改:添加max_num_fields参数.

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

Parse a查询字符串作为字符串参数给出(数据类型为application/x-www-form-urlencoded)。数据作为名称,值对列表返回.

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

可选参数strict_parsing是一个标志,指示如何处理分析错误。如果为false(默认值),则会以静默方式忽略错误。如果为true,则错误会引发ValueError exception.

可选的encodingerrors参数指定如何将经过编码的序列解码为Unicode字符,如bytes.decode()方法

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

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

在版本3.2中更改:添加encodingerrors参数

在版本3.7.2中更改:添加max_num_fields参数

urllib.parse.urlunparse// (parts )

urlparse()返回的元组构造一个URL。parts参数可以是任何六项迭代。如果最初解析的URL没有必要的分隔符(例如,带有空查询的?;这些等价的RFC表示),这可能会导致稍微不同但等效的URL .

urllib.parse.urlspliturlstring, scheme=””, allow_fragments=True

这类似于urlparse(),但是没有从URL中拆分params。如果是这个,通常应该用来代替urlparse()需要更新的URLsyntax允许将参数应用于URL的path部分的每个段(请参阅 RFC 2396 )。需要单独的功能来分配路径段和参数。此函数返回一个5元组:(寻址方案,网络位置,路径,查询,片段标识符).

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

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

port属性会提升ValueError在URL中指定了ifan invalid port。见第节结构化解析结果有关结果对象的更多信息.

中无与伦比的方括号netloc属性会提升ValueError.

版本3.6更改:超出范围的端口号现在提高了ValueError而不是返回None.

urllib.parse.urlunsplitparts

urlsplit()返回的元组元素组合成一个完整的URL作为字符串。parts参数可以是任意五个项目。如果最初解析的URL具有不必要的分隔符(例如,带有空查询的?; RFC声明它们是等效的),这可能会导致略有不同但等效的URL .

urllib.parse.urljoinbase, url, allow_fragments=True

通过组合“基本URL”(base)和其他URL(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"

如果您不想要这种行为,请使用urlurlsplit()预处理urlunsplit(),删除可能的schemenetloc parts.

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

urllib.parse.urldefragurl

如果url包含片段标识符,则返回url的修改版本没有片段标识符,片段标识符作为separatestring。如果url中没有片段标识符,则返回url unmodified和空字符串.

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

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

参见结构化解析结果有关resultobject的更多信息.

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

解析ASCII编码字节

URL解析函数最初设计为仅对字符串进行操作。实际上,能够将正确引用和编码的URL作为ASCII字节序列进行操作是很有用的。因此,该模块中的URL解析功能都在bytesbytearray对象除str对象之外

如果str传入数据,结果也只包含str数据。如果bytesbytearray数据被通过,结果只包含bytesdata

在单个函数调用中调用str数据与bytesbytearray混合会导致TypeError被提升,尝试传入非ASCIIbyte值时会触发UnicodeDecodeError.

为了支持在strbytes之间更容易地转换结果对象,来自URL解析函数的所有返回值都提供了encode()方法(当结果包含str数据时))或decode()方法(当结果包含bytes数据时)。这些方法的签名与相应的strbytes方法的签名相匹配(除了默认编码是"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.DefragResulturl, fragment

urldefrag()的具体类结果包含str数据。encode()方法返回DefragResultBytesinstance.

版本3.2.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)

的新增urlparse()结果包含str数据。encode()方法返回ParseResultBytesinstance.

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)

urlsplit()的结果类包含str数据。encode()方法返回SplitResultBytesinstance.

以下类提供了在bytesbytearray对象上操作时的解析结果的实现:

class urllib.parse.DefragResultBytesurl, fragment

urldefrag()结果的具体类包含bytes数据。decode()方法返回DefragResultinstance.

新版本3.2.

class urllib.parse.ParseResultBytes (scheme, netloc, path, params, query, fragment )

Concreteurlparse()结果包含bytes数据的结果。decode()方法返回ParseResultinstance.

新版本3.2.

class urllib.parse.SplitResultBytes (scheme, netloc, path, query, fragment )

Concreteurlsplit()结果包含bytes数据的结果。decode()方法返回SplitResultinstance.

新版本3.2.

URL引用

URL引用功能侧重于获取程序数据,并通过引用特殊字符并适当地编码非ASCII文本使其可以安全地用作URL组件。如果上面的URL解析函数尚未涵盖该任务,它们还支持逆转这些操作以从URL组件的内容中重新创建原始数据.

urllib.parse.quotestring, safe=”/”, encoding=None, errors=None

使用string escape替换%xx中的特殊字符。字母,数字和字符"_.-~"永远不会引用。默认情况下,此函数用于引用URL的路径部分。可选safe参数指定不应引用的其他ASCII字符 – 其默认值为"/".

string可以是strbytes.

更改版本3.7:移动 RFC 2396 RFC 3986 引用URL字符串。“〜”现在包含在保留字符集中.

可选encodingerrors参数指定如何处理非ASCII字符,如str.encode()方法所接受的encoding默认为"utf-8".errors默认为"strict",表示不支持的字符引发UnicodeEncodeError.encodingerrors如果stringbytes,或者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_plusstring, safe=””, encoding=None, errors=None

喜欢quote(),还可以根据加号来替换空格,以便在构建查询字符串以进入URL时引用HTML表单值。原始字符串中的标记将被转义,除非它们包含在safe。它也没有safe默认为"/".

示例:quote_plus("/El Niño/")产生"%2FEl+Ni%C3%B1o%2F".

urllib.parse.quote_from_bytesbytes, safe=”/”

喜欢quote(),但接受bytes对象而不是str,并且不执行字符串到字节的编码.

例如:quote_from_bytes(b"a&\xef")产生"a%26%EF".

urllib.parse.unquotestring, encoding=”utf-8″, errors=”replace”

用它们的单字符等价来代替%xx逃脱。可选encodingerrors参数指定如何将经过编码的序列解码为Unicode字符,如bytes.decode()方法所接受的

string必须是str.

encoding默认为"utf-8".errors默认为"replace",意思是无效序列被占位符代替.

例如:unquote("/El%20Ni%C3%B1o/")产生"/El Niño/".

urllib.parse.unquote_plusstring, encoding=”utf-8″, errors=”replace”

喜欢unquote(),也可以用空格替换加号,按照HTML表格值的要求.

string必须是str.

示例:unquote_plus("/El+Ni%C3%B1o/")产生"/El Niño/".

urllib.parse.unquote_to_bytesstring

替换%xx以单八位字节等值逃脱,然后返回一个bytes object.

string可以是str或者bytes.

如果是strstring中未转义的非ASCII字符编码为UTF-8字节.

示例:unquote_to_bytes("a%26%EF")产生b"a&\xef".

urllib.parse.urlencodequery, doseq=False, safe=””, encoding=None, errors=None, quote_via=quote_plus

转换映射对象或一系列双元素元组,它们可能包含str要么 bytes对象,以百分比编码的ASCIItext字符串。如果使用data将结果字符串用作urlopen()函数,thenit应编码为字节,否则会导致TypeError.

结果字符串是一对key=value对由"&"字符分隔,其中keyvalue使用quote_via功能。默认情况下,quote_plus()用于引用值,其中空格被引用为"+"字符,而’/’字符被编码为%2F,符合GET请求的标准(application/x-www-form-urlencoded)。可以作为quote_via的另一个函数是quote(),它将空格编码为%20而不编码’/’字符。为了最大限度地控制引用的内容,使用quote并为safe.

指定一个值当一个两元素元组的序列被用作query参数时,第一个元素是每个元组都是一个密钥,第二个元组是avalue。值元素本身可以是一个序列,在这种情况下,如果可选参数doseq的计算结果为True,则由key=value分隔的"&"对是为密钥的值序列的每个元素生成。encodedstring中参数的顺序将与序列中参数元组的顺序相匹配.

safe, encodingerrors参数传递给quote_viaencodingerrors引用的参数仅在查询元素是str时才传递.

要反转这个编码过程,parse_qs()parse_qsl()在这个模块中提供了将查询字符串解析为Python数据结构.

参考 urllib例子找出urlencodemethod如何用于为POST或POST数据生成查询字符串.

在版本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 scheme.
对mailto URL方案的解析要求.
RFC 1808 – 相对统一资源定位器
此征求意见包括加入绝对和相对URL的规则,包括相当数量的“异常例子”,它们管理边境案件的处理.
RFC 1738 – 统一资源定位器(URL)
这指定了绝对URL的形式语法和语义.