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个部分，每个部分都有自己的语义和特殊字符：

• scheme

• username

• password

• host

• port

• path

• query_params (查询字符串参数)

• fragment

每个都作为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

参数:

• full_quote (bool) -- 是否应用IDNA编码。默认为 False 。

• with_userinfo (bool) -- 是否包括用户名和密码，从技术上讲，这是授权的一部分。默认为 False 。

normalize(with_case=True)

解决任何问题“。和“..”路径中的引用，以及归一化方案和主机壳。要关闭大小写规范化，请传递 with_case=False 。

有关更多信息，请参阅 Section 6.2.2 of RFC 3986 。

navigate(dest)

工厂方法，它返回 _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 。

相关功能

boltons.urlutils.find_all_links(text, with_text=False, default_scheme='https', schemes=())

此函数使用试探法在纯文本中搜索看起来像URL的字符串，并返回 list 的 URL 物体。它支持限制接受的方案，也支持返回交错文本。

>>> find_all_links('Visit https://boltons.rtfd.org!')
[URL(u'https://boltons.rtfd.org')]
>>> find_all_links('Visit https://boltons.rtfd.org!', with_text=True)
[u'Visit ', URL(u'https://boltons.rtfd.org'), u'!']

参数:

• text (str) -- 要搜索的文本。

• with_text (bool) -- 是否将明文块与返回的URL对象交织。拥有所有令牌对于转换文本非常有用，例如，用HTML等效项替换链接。默认为 False 。

• default_scheme (str) -- 许多URL是在没有方案组件的情况下编写的。此函数可以匹配这些函数的合理子集，前提是 default_scheme 设置为字符串。设为 False 要禁用无匹配方案URL，请执行以下操作。默认为 'https' 。

• schemes (list) -- URL的方案必须匹配的字符串列表，才能包含在结果中。默认为空，与所有方案匹配。

备注

目前，此功能不支持查找具有无netloc方案的IPv6地址或URL，如mailto。

boltons.urlutils.register_scheme(text, uses_netloc=None, default_port=None)

注册新的方案信息，从而从URL对象中产生正确的端口和斜杠行为。有数十个标准方案已预先注册，因此此功能主要用于专有的内部定制或对缺失的标准信息进行权宜之计。如果一个计划似乎丢失了，请 file an issue 好了！

参数:

• text (str) -- 表示方案的文本。(‘http://hatnote.com’)‘中的’http‘

• uses_netloc (bool) -- 该方案是否支持指定网络主机？例如，“http”可以，“mailto”不可以。

• default_port (int) -- Netloc使用方案的默认端口(如果有)。

低级函数

内部使用的一系列函数 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.parse_qsl(qs, keep_blank_values=True, encoding='utf8')

将查询字符串转换为(键、值)对的列表。

boltons.urlutils.resolve_path_parts(path_parts)

通过解析“”的段来标准化URL路径。和‘..’，生成无点路径。请参阅RFC 3986第5.2.4节，删除网点段。

class boltons.urlutils.QueryParamDict(*a, **kw)

的一个子类 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 。

to_text(full_quote=False)

呈现并返回查询字符串。

参数:

full_quote (bool) -- 是否对特殊字符使用百分号引号或对其进行解码以提高可读性。

报价

URL有很多部分，几乎同样多的是单独的“引用”(编码)策略。

boltons.urlutils.quote_userinfo_part(text, full_quote=True)

在URL的用户名或密码部分引用特殊字符。请注意，URL中的用户信息在许多圈子(特别是浏览器)中被认为是不受欢迎的，并且对百分比编码的用户信息的支持可能参差不齐。

boltons.urlutils.quote_path_part(text, full_quote=True)

对URL路径的单个数据段进行百分比编码。

boltons.urlutils.quote_query_part(text, full_quote=True)

百分比-对单个查询字符串键或值进行编码。

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 。

boltons.urlutils.NO_NETLOC_SCHEMES

这是一个 set 的方案明确不支持网络解析，例如“mailto”和“urn”。