urlutils
-结构化URL¶
urlutils
是一个专门用于软件中最通用、最成熟和最受欢迎的数据结构之一的模块:URL,也称为 Uniform Resource Locator 。
其中,该模块是URL的完全重新实现,不依赖于 urlparse
或 urllib
标准库模块。Urlutils的核心和顶级接口是 URL
键入。同样亮相的还有 find_all_links()
方便功能。下面还列出了一些低级函数和常量。
本模块中的实现在很大程度上基于 RFC 3986 和 RFC 3987 ,并结合了来自其他几个RFC和 W3C documents 。
在 17.2 版本加入.
URL类型¶
- class boltons.urlutils.URL(url='')[源代码]¶
URL是虚拟和物理环境中最普遍的数据结构之一。从博客到广告牌,URL是如此常见,以至于很容易忽视它们的复杂性和威力。
URL有8个部分,每个部分都有自己的语义和特殊字符:
每个都作为URL对象上的一个属性公开。RFC 3986提供了以下主要URL组件的简要结构摘要:
foo://user:pass@example.com:8042/over/there?name=ferret#nose \_/ \_______/ \_________/ \__/\_________/ \_________/ \__/ | | | | | | | scheme userinfo host port path query fragment
下面是如何使用URL类型操作该示例:
>>> url = URL('foo://example.com:8042/over/there?name=ferret#nose') >>> print(url.host) example.com >>> print(url.get_authority()) example.com:8042 >>> print(url.qp['name']) # qp is a synonym for query_params ferret
URL的编码方法是对输入进行尽可能多的解码,数据保持这种解码状态,直到使用
to_text()
方法。在这种情况下,它类似于当前的鼓励将字节立即解码为文本的方法。请注意,URL实例是可变对象。如果需要URL的不可变表示形式,则从
to_text()
可能会被使用。对于不变但功能几乎相同的URL对象,请查看 hyperlink package 。- scheme¶
该方案是一个ASCII字符串,通常为小写,它指定URL其余部分的语义,以及在许多情况下的网络协议。例如,“http://hatnote.com”.“中的”http“
- username¶
用户名是某些方案用于身份验证的字符串。例如,“ftp://public@example.com”.“中的”PUBLIC
- password¶
密码是也用于身份验证的字符串。从技术上讲已弃用 RFC 3986 Section 7.5 ,它们仍然用于URL为私有或密码为公共的情况。例如“db://Private:password@127.0.0.1”中的“password”。
- host¶
主机是用于解析资源的网络位置的字符串,可以是空的、域或IP地址(v4或v6)。“Example.com”、“127.0.0.1”和“::1”都是主机字符串的很好的例子。
根据规范,完全编码的输出
to_text()
是 IDNA encoded 与域名系统的兼容性。
- port¶
端口是一个使用的整数,以及
host
,在连接到网络位置时。8080
该端口是否在“http://localhost:8080/index.html”.“中备注
与HTTP的80和SSH的22的情况一样,许多方案都有默认端口,并且 Section 3.2.3 of RFC 3986 声明当URL的端口与其方案的默认端口相同时,不应发出该端口::
>>> URL(u'https://github.com:443/mahmoud/boltons').to_text() u'https://github.com/mahmoud/boltons'
自定义方案可以将其端口注册到
register_scheme()
。看见URL.default_port
更多信息。
- path¶
该字符串从URL的授权部分之后的第一个前导斜杠开始,以第一个问号结束。网络使用时通常按百分比报价。“/a/b/c”是http://example.com/a/b/c?d=e“.的路径
- path_parts¶
这个
tuple
表格path
,以斜杠拆分。保留空的斜杠段,包括前导斜杠::>>> url = URL(u'http://example.com/a/b/c') >>> url.path_parts (u'', u'a', u'b', u'c')
- query_params[源代码]¶
的一个实例
QueryParamDict
,一个OrderedMultiDict
子类型,映射后第一个问号后面的文本键和值path
。也可用作方便的别名qp
**>>> url = URL('http://boltons.readthedocs.io/en/latest/?utm_source=docs&sphinx=ok') >>> url.qp.keys() [u'utm_source', u'sphinx']
还针对网络使用案例进行了百分比编码。
- fragment¶
后的第一个‘#’之后的字符串
query_params
直到URL的末尾。它没有内在的内部结构,是按百分比报价的。
- classmethod from_parts(scheme=None, host=None, path_parts=(), query_params=(), fragment='', port=None, username=None, password=None)[源代码]¶
从部件构建新的URL。请注意,各个参数的顺序与它们在URL中的显示顺序不同:
- 参数:
scheme (str) -- URL的方案,例如‘http’
host (str) -- 主机字符串,例如‘hatnote.com’
path_parts (tuple) -- 路径的各个文本段,例如(‘POST’,‘123’)
query_params (dict) -- 表示URL查询参数的键和值的OMD、DICT或(键、值)对的列表。
fragment (str) -- URL的片段,例如‘angor1’
port (int) -- 已注册方案可使用URL的整数端口,自动默认为。
username (str) -- URL的UserInfo部分的用户名。
password (str) -- URL的用户信息部分的密码。
请注意,此方法进行的验证相对较少。
URL.to_text()
应用于检查在编写最终文本URL时是否产生任何错误。
- to_text(full_quote=False)[源代码]¶
呈现一个表示URL对象的当前状态的字符串。
>>> url = URL('http://listen.hatnote.com') >>> url.fragment = 'en' >>> print(url.to_text()) http://listen.hatnote.com#en
通过设置 full_quote 标志,URL可以用全引号引起来,也可以用最少引号引起来。编码URL的最常见特征是存在百分比编码的文本(例如,%60)。未加引号的URL更具可读性,也更适合显示,而带全引号的URL则更为保守,通常需要在网络上发送。
- default_port¶
返回当前设置方案的默认端口。退货
None
如果该计划无法识别。看见register_scheme()
上面。如果port
匹配此值,则不会在输出中发出端口to_text()
。应用相同的‘+’启发式,详见
URL.uses_netloc()
。
- uses_netloc¶
URL是否使用
:
或://
将方案与URL的其余部分分开取决于方案自己的标准定义。无法从URL的其他部分推断此行为。方案要么支持网络位置,要么不支持。URL类型的方法是检查显式注册的方案,以及像HTTP预注册这样的常见方案。这是采取的相同的方法
urlparse
。如果方案作为一个整体未注册,则URL添加了两个额外的启发式规则。首先,它尝试检查方案的最后一个子部分
+
性格。这为方案添加了直观的行为,例如git+ssh
。其次,如果加载的URL带有无法识别的方案,它将保留看到的分隔符。>>> print(URL('fakescheme://test.com').to_text()) fakescheme://test.com >>> print(URL('mockscheme:hello:world').to_text()) mockscheme:hello:world
- get_authority(full_quote=False, with_userinfo=False)[源代码]¶
由具有网络位置的URL方案使用,
get_authority()
联合收割机username
,password
,host
,及port
放入一个字符串中, authority ,它用于连接到网络可访问的资源。由内部使用
to_text()
并且可用于标记连接。>>> url = URL('ftp://user@ftp.debian.org:2121/debian/README') >>> print(url.get_authority()) ftp.debian.org:2121 >>> print(url.get_authority(with_userinfo=True)) user@ftp.debian.org:2121
- normalize(with_case=True)[源代码]¶
解决任何问题“。和“..”路径中的引用,以及归一化方案和主机壳。要关闭大小写规范化,请传递
with_case=False
。有关更多信息,请参阅 Section 6.2.2 of RFC 3986 。
工厂方法,它返回 _new_ :class:URL,根据给定的目的地, dest 。对于轻松导航这些相对链接非常有用。
新创建的
URL
在返回之前被规格化。>>> url = URL('http://boltons.readthedocs.io') >>> url.navigate('en/latest/') URL(u'http://boltons.readthedocs.io/en/latest/')
- 参数:
dest (str) -- 表示目标的字符串或URL对象
有关更多信息,请参阅 Section 5 of RFC 3986 。
低级函数¶
内部使用的一系列函数 URL
。
- boltons.urlutils.parse_url(url_text)[源代码]¶
用于将单个URL的文本解析为字典,该字典由
URL
键入。请注意,“URL”的定义非常狭窄,基于标准。而当
parse_url()
可能会提高URLParseError
在非常有限的条件下,例如非整型端口,数量惊人的字符串在技术上是有效的URL。例如,文本"url"
是有效的URL,因为它是相对路径。简而言之,不要期望该函数验证表单输入或URL的其他更通俗的用法。
>>> res = parse_url('http://127.0.0.1:3000/?a=1') >>> sorted(res.keys()) # res is a basic dictionary ['_netloc_sep', 'authority', 'family', 'fragment', 'host', 'password', 'path', 'port', 'query', 'scheme', 'username']
- boltons.urlutils.parse_host(host)[源代码]¶
用于解析URL的主机部分的低级别函数。
返回(Family,host)的元组,其中 family 是一种
socket
模常量或None
,而host是一个字符串。>>> parse_host('googlewebsite.com') == (None, 'googlewebsite.com') True >>> parse_host('[::1]') == (socket.AF_INET6, '::1') True >>> parse_host('192.168.1.1') == (socket.AF_INET, '192.168.1.1') True
由于py3从int切换到enum for,所以上面的doctest格式有些奇怪。
socket
常量。
- boltons.urlutils.resolve_path_parts(path_parts)[源代码]¶
通过解析“”的段来标准化URL路径。和‘..’,生成无点路径。请参阅RFC 3986第5.2.4节,删除网点段。
- class boltons.urlutils.QueryParamDict(*args, **kwargs)[源代码]¶
的一个子类
OrderedMultiDict
专门用于表示查询字符串值。在加载时,所有内容都是完全无引号的,默认情况下,所有解析的键和值都是字符串。顾名思义,支持多个值并保留插入顺序。
>>> qp = QueryParamDict.from_text(u'key=val1&key=val2&utm_source=rtd') >>> qp.getlist('key') [u'val1', u'val2'] >>> qp['key'] u'val2' >>> qp.add('key', 'val3') >>> qp.to_text() 'key=val1&key=val2&utm_source=rtd&key=val3'
看见
OrderedMultiDict
获取更多API功能。- classmethod from_text(query_string)[源代码]¶
解析 query_string 并返回一个新的
QueryParamDict
。
报价¶
URL有很多部分,几乎同样多的是单独的“引用”(编码)策略。
- boltons.urlutils.quote_userinfo_part(text, full_quote=True)[源代码]¶
在URL的用户名或密码部分引用特殊字符。请注意,URL中的用户信息在许多圈子(特别是浏览器)中被认为是不受欢迎的,并且对百分比编码的用户信息的支持可能参差不齐。
- boltons.urlutils.quote_fragment_part(text, full_quote=True)[源代码]¶
引用URL的片段部分。片段没有子分隔符,因此可以传递整个URL片段。
然而,只有一种不引用的策略:
- boltons.urlutils.unquote(string, encoding='utf-8', errors='replace')[源代码]¶
Percent-通过将%xx转义替换为其等效单字符来对字符串进行解码。可选的 encoding 和 errors 参数指定如何将百分比编码的序列解码为Unicode字符,这是
bytes.decode()
方法。默认情况下,使用UTF-8对百分比编码的序列进行解码,并用占位符替换无效的序列。>>> unquote(u'abc%20def') u'abc def'
有用的常量¶
- boltons.urlutils.SCHEME_PORT_MAP¶
将URL方案映射到其协议的默认端口。精心组装而成的 IANA scheme registry , port registry 和独立研究。
密钥为小写字符串,值为整数或无,无表示方案没有默认端口(或可能根本不支持端口):
>>> boltons.urlutils.SCHEME_PORT_MAP['http'] 80 >>> boltons.urlutils.SCHEME_PORT_MAP['file'] None
看见
URL.port
有关如何使用它的更多信息。看见NO_NETLOC_SCHEMES
了解更多方案信息。还有 available in JSON 。