urllib.request ---用于打开URL的可扩展库

源代码： Lib/urllib/request.py

这个 urllib.request 模块定义的函数和类有助于在复杂的环境中打开URL（主要是HTTP）——基本和摘要式身份验证、重定向、cookie等等。

参见

这个 Requests package 建议用于更高级别的HTTP客户端接口。

这个 urllib.request 模块定义以下功能：

urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)

打开URL url ，可以是字符串或 Request 对象。

data 必须是指定要发送到服务器的其他数据的对象，或者 None 如果不需要此类数据。见 Request 有关详细信息。

urllib.request模块使用http/1.1，包括 Connection:close 其HTTP请求中的头。

可选的 timeout 参数指定阻塞操作（如连接尝试）的超时（以秒为单位）（如果未指定，将使用全局默认超时设置）。这实际上只适用于HTTP、HTTPS和FTP连接。

如果 context 是指定的，它必须是 ssl.SSLContext 描述各种SSL选项的实例。参见 HTTPSConnection 了解更多详细信息。

可选的 卡菲尔 和 卡普斯 参数为HTTPS请求指定一组受信任的CA证书。 卡菲尔 应该指向包含CA证书束的单个文件，而 卡普斯 应指向hash证书文件的目录。更多信息可在 ssl.SSLContext.load_verify_locations() .

这个 缺省 参数被忽略。

此函数始终返回一个可以作为 context manager 并具有 url ， 报头 和 地位 . 见 urllib.response.addinfourl 有关这些属性的详细信息。

对于HTTP和HTTPS URL，此函数返回 http.client.HTTPResponse 对象稍有修改。除了上述三种新方法外，msg属性还包含与 reason 属性---服务器返回的原因短语---而不是在文档中指定的响应头 HTTPResponse .

对于由旧版显式处理的ftp、文件和数据URL和请求 URLopener 和 FancyURLopener 类，此函数返回 urllib.response.addinfourl 对象。

引发 URLError 在协议错误时。

注意 None 如果没有处理程序处理该请求（尽管默认安装的全局 OpenerDirector 使用 UnknownHandler 以确保不会发生这种情况）。

此外，如果检测到代理设置（例如，当 *_proxy 环境变量 http_proxy 设置） ProxyHandler 默认安装，并确保通过代理处理请求。

遗产 urllib.urlopen python 2.6及更早版本的函数已经停止使用； urllib.request.urlopen() 与旧的相对应 urllib2.urlopen . 代理处理，通过将字典参数传递给 urllib.urlopen ，可以通过使用 ProxyHandler 物体。

提出一个 auditing event urllib.Request 带着论据 fullurl ， data ， headers ， method .

在 3.2 版更改: 卡菲尔 和 卡普斯 加入。

在 3.2 版更改: 如果可能，现在支持HTTPS虚拟主机（即，如果 ssl.HAS_SNI 是真的）。

3.2 新版功能: data 可以是不可重复的对象。

在 3.3 版更改: 缺省 加入。

在 3.4.3 版更改: context 加入。

在 3.10 版更改: HTTPS连接现在发送带有协议指示符ALPN扩展 http/1.1 当没有 上下文 给出了。自定义 上下文 应将ALPN协议设置为 set_alpn_protocol() 。

3.6 版后已移除: 卡菲尔 ， 卡普斯 和 缺省 被否决，赞成 context . 请使用 ssl.SSLContext.load_cert_chain() 相反，还是让 ssl.create_default_context() 为您选择系统的可信CA证书。

urllib.request.install_opener(opener)

安装一个 OpenerDirector 实例作为默认全局开启器。只有希望urlopen使用开放器时才需要安装开放器；否则，只需调用 OpenerDirector.open() 而不是 urlopen() . 代码不能检查 OpenerDirector ，任何具有适当接口的类都可以工作。

urllib.request.build_opener([handler, ...])

返回一 OpenerDirector 实例，它按给定的顺序链接处理程序。 处理程序 s可以是 BaseHandler 或 BaseHandler （在这种情况下，必须可以调用不带任何参数的构造函数）。以下类的实例将位于 处理程序 s，除非 处理程序 s包含它们、它们的实例或它们的子类： ProxyHandler （如果检测到代理设置）， UnknownHandler ， HTTPHandler ， HTTPDefaultErrorHandler ， HTTPRedirectHandler ， FTPHandler ， FileHandler ， HTTPErrorProcessor .

如果python安装有SSL支持（即 ssl 模块可以导入）。 HTTPSHandler 也将添加。

A BaseHandler 子类也可以更改其 handler_order 属性来修改其在处理程序列表中的位置。

urllib.request.pathname2url(path)

转换路径名 path 从路径的本地语法到URL的路径组件中使用的表单。这不会生成完整的URL。返回值将已使用 quote() 功能。

urllib.request.url2pathname(path)

转换路径组件 path 从百分比编码的URL到路径的本地语法。这不接受完整的URL。此函数使用 unquote() 译码 path .

urllib.request.getproxies()

此助手函数返回方案到代理服务器URL映射的字典。它在环境中扫描名为 <scheme>_proxy 在不区分大小写的方法中，首先对所有操作系统，如果找不到，则从Mac OS X的Mac OSX系统配置和Windows的Windows系统注册表中查找代理信息。如果同时存在小写和大写环境变量（并且不一致），则首选小写。

注解

如果环境变量 REQUEST_METHOD 设置，通常表示脚本在CGI环境中运行，环境变量 HTTP_PROXY （大写字母） _PROXY ）将被忽略。这是因为客户机可以使用“proxy:”http头注入该变量。如果需要在CGI环境中使用HTTP代理，请使用 ProxyHandler 显式地，或确保变量名为小写（或至少 _proxy 后缀）。

提供以下类别：

class urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)

此类是URL请求的抽象。

url 应该是包含有效URL的字符串。

data 必须是指定要发送到服务器的其他数据的对象，或者 None 如果不需要此类数据。目前只有HTTP请求使用 data . 支持的对象类型包括字节、类文件对象和类字节的iterables。如果没有 Content-Length 也不 Transfer-Encoding 已提供标题字段， HTTPHandler 将根据 data . Content-Length 将用于发送字节对象，而 Transfer-Encoding: chunked 如中所述 RFC 7230 ，第3.3.1节将用于发送文件和其他文件。

对于HTTP Post请求方法， data 应该是标准中的缓冲区 application/x-www-form-urlencoded 格式。这个 urllib.parse.urlencode() 函数接受2个元组的映射或序列，并返回此格式的ASCII字符串。在用作 data 参数。

headers 应该是一本字典，并且将被视为 add_header() 以每个键和值作为参数调用。这经常被用来“欺骗” User-Agent 头值，由浏览器用来标识自身——一些HTTP服务器只允许来自普通浏览器的请求，而不允许来自脚本的请求。例如，Mozilla Firefox可以将自己标识为 "Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11" ，同时 urllib 的默认用户代理字符串为 "Python-urllib/2.6" （在python 2.6上）。

适当的 Content-Type 如果 data 存在参数。如果没有提供此标题，并且 data 不是没有， Content-Type: application/x-www-form-urlencoded 将作为默认值添加。

接下来的两个参数只对正确处理第三方HTTP cookies感兴趣：

origin_req_host 应该是源事务的请求主机，定义如下 RFC 2965 . 它默认为 http.cookiejar.request_host(self) . 这是由用户启动的原始请求的主机名或IP地址。例如，如果请求是针对HTML文档中的图像，那么它应该是包含图像的页面请求的请求主机。

不可验证的 应指示请求是否不可验证，如 RFC 2965 . 它默认为 False . 无法验证的请求是用户没有可供批准的URL的请求。例如，如果请求是针对HTML文档中的图像，并且用户没有批准自动提取图像的选项，那么这应该是真的。

方法 应该是一个指示将要使用的HTTP请求方法的字符串（例如 'HEAD' ）如果提供，则其值存储在 method 属性，由使用 get_method() . 默认值为 'GET' 如果 data 是 None 或 'POST' 否则。子类可以通过设置 method 类本身的属性。

注解

如果数据对象无法多次传递其内容（例如，只能生成一次内容的文件或可ITerable），并且为HTTP重定向或身份验证重试请求，则请求将无法按预期工作。这个 data 在头之后立即发送到HTTP服务器。类库不支持100个持续期望。

在 3.3 版更改: Request.method 参数被添加到请求类中。

在 3.4 版更改: 违约 Request.method 可在类级别显示。

在 3.6 版更改: 如果 Content-Length 尚未提供，以及 data 既不是 None 也不是字节对象。返回使用分块传输编码。

class urllib.request.OpenerDirector

这个 OpenerDirector 类通过打开URL BaseHandler S被锁在一起。它管理处理程序的链接和错误恢复。

class urllib.request.BaseHandler

这是所有已注册处理程序的基类，只处理简单的注册机制。

class urllib.request.HTTPDefaultErrorHandler

定义HTTP错误响应的默认处理程序的类；所有响应都转换为 HTTPError 例外情况。

class urllib.request.HTTPRedirectHandler

用于处理重定向的类。

class urllib.request.HTTPCookieProcessor(cookiejar=None)

处理HTTP cookie的类。

class urllib.request.ProxyHandler(proxies=None)

使请求通过代理。如果 proxies 它必须是一个字典，将协议名映射到代理的URL。默认值是从环境变量中读取代理列表 <protocol>_proxy .如果未设置代理环境变量，则在Windows环境中，代理设置从注册表的Internet设置部分获取，在Mac OS X环境中，代理信息从OS X系统配置框架中检索。

要禁用自动检测的代理，请传递空字典。

这个 no_proxy 环境变量可用于指定不应通过代理访问的主机；如果设置了该变量，则该变量应是以逗号分隔的主机名后缀列表，也可以使用 :port 例如，附加的 cern.ch,ncsa.uiuc.edu,some.host:8080 .

注解

HTTP_PROXY 如果变量 REQUEST_METHOD 已设置；请参阅上的文档 getproxies() .

class urllib.request.HTTPPasswordMgr

保留数据库 (realm, uri) -> (user, password) 映射。

class urllib.request.HTTPPasswordMgrWithDefaultRealm

保留数据库 (realm, uri) -> (user, password) 映射。一个王国 None 被认为是一个捕获所有领域，如果没有其他领域适合搜索。

class urllib.request.HTTPPasswordMgrWithPriorAuth

一种变体 HTTPPasswordMgrWithDefaultRealm 还有一个数据库 uri -> is_authenticated 映射。basicauth处理程序可以使用它来确定何时立即发送身份验证凭据，而不是等待 401 首先回答。

3.5 新版功能.

class urllib.request.AbstractBasicAuthHandler(password_mgr=None)

这是一个混合类，它有助于对远程主机和代理进行HTTP身份验证。 password_mgr 如果给定，应该是与 HTTPPasswordMgr ；参考章节 httppasswordmgr对象 有关必须支持的接口的信息。如果 passwd_mgr 还提供 is_authenticated 和 update_authenticated 方法（见） httpPasswordMgrWithPriorAuth对象 ，然后处理程序将使用 is_authenticated 用于确定是否随请求发送身份验证凭据的给定URI的结果。如果 is_authenticated 返回 True 对于URI，将发送凭据。如果 is_authenticated 是 False ，不发送凭据，然后如果 401 接收到响应。使用身份验证凭据重新发送请求。如果验证成功， update_authenticated 调用以设置 is_authenticated True 对于URI，这样对URI或其任何超级URI的后续请求将自动包括身份验证凭据。

3.5 新版功能: 补充 is_authenticated 支持。

class urllib.request.HTTPBasicAuthHandler(password_mgr=None)

处理远程主机的身份验证。 password_mgr 如果给定，应该是与 HTTPPasswordMgr ；参考章节 httppasswordmgr对象 有关必须支持的接口的信息。httpbasicAuthHandler将引发 ValueError 当出现错误的身份验证方案时。

class urllib.request.ProxyBasicAuthHandler(password_mgr=None)

使用代理处理身份验证。 password_mgr 如果给定，应该是与 HTTPPasswordMgr ；参考章节 httppasswordmgr对象 有关必须支持的接口的信息。

class urllib.request.AbstractDigestAuthHandler(password_mgr=None)

这是一个混合类，它有助于对远程主机和代理进行HTTP身份验证。 password_mgr 如果给定，应该是与 HTTPPasswordMgr ；参考章节 httppasswordmgr对象 有关必须支持的接口的信息。

class urllib.request.HTTPDigestAuthHandler(password_mgr=None)

处理远程主机的身份验证。 password_mgr 如果给定，应该是与 HTTPPasswordMgr ；参考章节 httppasswordmgr对象 有关必须支持的接口的信息。当同时添加摘要式身份验证处理程序和基本身份验证处理程序时，总是先尝试摘要式身份验证。如果摘要式身份验证再次返回40x响应，则将其发送到基本身份验证处理程序进行处理。此处理程序方法将引发 ValueError 与摘要式或基本式以外的身份验证方案一起提供时。

在 3.3 版更改: 提高 ValueError 在不支持的身份验证方案上。

class urllib.request.ProxyDigestAuthHandler(password_mgr=None)

使用代理处理身份验证。 password_mgr 如果给定，应该是与 HTTPPasswordMgr ；参考章节 httppasswordmgr对象 有关必须支持的接口的信息。

class urllib.request.HTTPHandler

用于处理打开HTTP URL的类。

class urllib.request.HTTPSHandler(debuglevel=0, context=None, check_hostname=None)

用于处理打开HTTPS URL的类。 context 和 check_hostname 与中的含义相同 http.client.HTTPSConnection .

在 3.2 版更改: context 和 check_hostname 加入。

class urllib.request.FileHandler

打开本地文件。

class urllib.request.DataHandler

打开数据URL。

3.4 新版功能.

class urllib.request.FTPHandler

打开FTP URL。

class urllib.request.CacheFTPHandler

打开ftp URL，保存打开的ftp连接的缓存，以最小化延迟。

class urllib.request.UnknownHandler

一个catch all类来处理未知的URL。

class urllib.request.HTTPErrorProcessor

处理HTTP错误响应。

请求对象

以下方法描述 Request 的公共接口，因此所有这些都可以在子类中重写。它还定义了几个公共属性，客户机可以使用这些属性来检查解析的请求。

Request.full_url

传递给构造函数的原始URL。

在 3.4 版更改.

request.full_url是一个带有setter、getter和deleter的属性。得到 full_url 返回带有片段的原始请求URL（如果存在）。

Request.type

URI方案。

Request.host

URI颁发机构，通常是主机，但也可以包含由冒号分隔的端口。

Request.origin_req_host

请求的原始主机，没有端口。

Request.selector

URI路径。如果 Request 使用代理，则选择器将是传递给代理的完整URL。

Request.data

请求的实体实体，或 None 如果未指定。

在 3.4 版更改: 更改的值 Request.data 现在删除“content-length”头段，如果它是以前设置或计算的。

Request.unverifiable

布尔值，指示请求是否无法验证，定义如下 RFC 2965 .

Request.method

要使用的HTTP请求方法。默认情况下，其值为 None 也就是说 get_method() 将对所使用的方法进行常规计算。它的值可以设置（从而覆盖 get_method() ）通过在 Request 子类，或通过将值传入 Request 通过 方法 参数。

3.3 新版功能.

在 3.4 版更改: 现在可以在子类中设置默认值；以前只能通过构造函数参数设置默认值。

Request.get_method()

返回一个指示HTTP请求方法的字符串。如果 Request.method 不是 None ，返回其值，否则返回 'GET' 如果 Request.data 是 None 或 'POST' 如果不是。这只对HTTP请求有意义。

在 3.3 版更改: get_方法现在查看 Request.method .

Request.add_header(key, val)

向请求添加另一个头。除HTTP处理程序外，所有处理程序当前都忽略了头，这些头将添加到发送到服务器的头列表中。请注意，不能有多个标题具有相同的名称，如果 key 碰撞。目前，这并没有失去HTTP功能，因为所有在多次使用时具有意义的头都有一种（特定于头的）方法，只使用一个头获得相同的功能。

Request.add_unredirected_header(key, header)

添加不会添加到重定向请求的头。

Request.has_header(header)

返回实例是否具有命名头（同时检查常规头和未定向头）。

Request.remove_header(header)

从请求实例中移除命名头（从常规头和未定向头）。

3.4 新版功能.

Request.get_full_url()

返回构造函数中给定的URL。

在 3.4 版更改.

返回 Request.full_url

Request.set_proxy(host, type)

通过连接到代理服务器来准备请求。这个 host 和 type 将替换实例的那些，实例的选择器将是构造函数中给定的原始URL。

Request.get_header(header_name, default=None)

返回给定头的值。如果头不存在，则返回默认值。

Request.header_items()

返回请求头的元组列表（头名称，头值）。

在 3.4 版更改: 请求方法add_data、has_data、get_data、get_type、get_host、get_selector、get_origin_req_host，并且是不可验证的，自从3.3被删除后就被弃用了。

OpenerDirector对象

OpenerDirector 实例具有以下方法：

OpenerDirector.add_handler(handler)

处理程序 应该是 BaseHandler . 搜索以下方法并将其添加到可能的链中（请注意，HTTP错误是一种特殊情况）。注意，在下面， 协议 例如，应该用要处理的实际协议替换 http_response() 将是HTTP协议响应处理程序。阿尔索 type 例如，应该用实际的HTTP代码替换 http_error_404() 将处理HTTP 404错误。

  • <protocol>_open() ---表示处理程序知道如何打开 协议 网址。

    见 BaseHandler.<protocol>_open() 更多信息。

  • http_error_<type>() ---表示处理程序知道如何用HTTP错误代码处理HTTP错误 type .

    见 BaseHandler.http_error_<nnn>() 更多信息。

  • <protocol>_error() ---表示处理程序知道如何处理来自（非-http ） 协议 .

  • <protocol>_request() ---表示处理程序知道如何预处理 协议 请求。

    见 BaseHandler.<protocol>_request() 更多信息。

  • <protocol>_response() ---表示处理程序知道如何发布进程 协议 响应。

    见 BaseHandler.<protocol>_response() 更多信息。

OpenerDirector.open(url, data=None[, timeout])

打开给定 url （可以是请求对象或字符串），可以选择传递给定的 data . 参数、返回值和引发的异常与 urlopen() （简单地称为 open() 当前安装的全局方法 OpenerDirector ）可选的 timeout 参数指定阻塞操作（如连接尝试）的超时（以秒为单位）（如果未指定，将使用全局默认超时设置）。超时功能实际上只适用于HTTP、HTTPS和FTP连接）。

OpenerDirector.error(proto, *args)

处理给定协议的错误。这将使用给定的参数（特定于协议）调用给定协议的注册错误处理程序。HTTP协议是一种特殊情况，它使用HTTP响应代码来确定特定的错误处理程序；请参阅 http_error_<type>() 处理程序类的方法。

引发的返回值和异常与 urlopen() .

OpenerDirector对象分三个阶段打开URL:

这些方法在每个阶段中的调用顺序是通过对处理程序实例进行排序来确定的。

  1. 每个处理程序都有一个名为like的方法 <protocol>_request() 已调用该方法以预处理请求。

  2. 名为like的方法的处理程序 <protocol>_open() 调用以处理请求。当处理程序返回非-None 值（即响应），或引发异常（通常 URLError ）允许传播异常。

    实际上，上面的算法首先是针对名为 default_open() .如果所有这些方法都返回 None ，对于名为like的方法重复该算法 <protocol>_open() .如果所有这些方法都返回 None ，对于名为 unknown_open() .

    注意，这些方法的实现可能涉及到父级的调用 OpenerDirector 实例 open() 和 error() 方法。

  3. 每个处理程序都有一个名为like的方法 <protocol>_response() 已调用该方法以后期处理响应。

BaseHandler对象

BaseHandler 对象提供了两个直接有用的方法，以及其他要由派生类使用的方法。这些是直接使用的：

BaseHandler.add_parent(director)

添加导演作为父级。

BaseHandler.close()

移除任何家长。

以下属性和方法只能由派生自 BaseHandler .

注解

该公约已被通过，其子类规定 <protocol>_request() 或 <protocol>_response() 方法已命名 *Processor ；所有其他名称 *Handler .

BaseHandler.parent

有效的 OpenerDirector ，可用于使用其他协议打开，或处理错误。

BaseHandler.default_open(req)

这种方法是 not 定义在 BaseHandler 但是如果子类想要捕获所有的URL，就应该定义它。

此方法（如果实现）将由父级调用 OpenerDirector .它应该返回一个类似文件的对象，如 open() 属于 OpenerDirector 或 None . 应该提高 URLError 除非真的发生了异常的事情（例如， MemoryError 不应映射到 URLError ）

此方法将在任何协议特定的打开方法之前调用。

BaseHandler.<protocol>_open(req)

这种方法是 not 定义在 BaseHandler 但是，如果子类想要使用给定的协议处理URL，则应该定义它。

此方法（如果定义）将由父级调用 OpenerDirector . 返回值应与 default_open() .

BaseHandler.unknown_open(req)

这种方法是 not 定义在 BaseHandler 但是，如果子类想要捕获没有特定注册处理程序的所有URL来打开它，则应该定义它。

如果实现此方法，则将由 parent OpenerDirector . 返回值应与 default_open() .

BaseHandler.http_error_default(req, fp, code, msg, hdrs)

这种方法是 not 定义在 BaseHandler 但是，如果子类打算为其他未处理的HTTP错误提供catch all，则应重写它。它将由自动调用 OpenerDirector 获取错误，通常在其他情况下不应调用。

req 将是 Request 对象， fp 将是一个具有HTTP错误主体的类似文件的对象， code 将是错误的三位数代码， msg 将是用户可见的代码解释和 hdrs 将是带有错误头的映射对象。

引发的返回值和异常应与 urlopen() .

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

nnn 应该是三位数的HTTP错误代码。此方法也未在中定义 BaseHandler ，但在子类的实例上，如果存在HTTP错误（代码为），则将调用它。 nnn 发生。

子类应重写此方法以处理特定的HTTP错误。

引发的参数、返回值和异常应与 http_error_default() .

BaseHandler.<protocol>_request(req)

这种方法是 not 定义在 BaseHandler 但是，如果子类想要预处理给定协议的请求，就应该定义它。

此方法（如果定义）将由父级调用 OpenerDirector . req 将是 Request 对象。返回值应为 Request 对象。

BaseHandler.<protocol>_response(req, response)

这种方法是 not 定义在 BaseHandler 但是，如果子类想要发布给定协议的进程响应，就应该定义它。

此方法（如果定义）将由父级调用 OpenerDirector . req 将是 Request 对象。 响应 将是实现与返回值相同接口的对象 urlopen() . 返回值应实现与的返回值相同的接口 urlopen() .

httpRedirectHandler对象

注解

某些HTTP重定向需要从该模块的客户端代码执行操作。如果是这样的话， HTTPError 被引发。参见 RFC 2616 有关各种重定向代码的确切含义的详细信息。

安 HTTPError 如果httpRedirectHandler具有非http、https或ftp URL的重定向URL，则作为安全考虑引发异常。

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)

返回A Request 或 None 以响应重定向。这是由 http_error_30*() 方法在从服务器接收重定向时。如果发生重定向，则返回新的 Request 允许 http_error_30*() 执行重定向到 新网址 . 否则，升高 HTTPError 如果没有其他处理程序应尝试处理此URL，或返回 None 如果你不能，那么另一个处理程序也可以。

注解

此方法的默认实现并不严格遵循 RFC 2616 也就是说301和302对 POST 未经用户确认，不得自动重定向请求。实际上，浏览器允许自动重定向这些响应，将post更改为 GET ，默认实现复制了此行为。

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)

重定向到 Location: 或 URI: 网址。此方法由父级调用 OpenerDirector 获取HTTP“永久移动”响应时。

HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)

一样 http_error_301() ，但调用了“已找到”响应。

HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)

一样 http_error_301() 但要求“查看其他”响应。

HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)

一样 http_error_301() ，但调用了“临时重定向”响应。

httpCookieProcessor对象

HTTPCookieProcessor 实例有一个属性：

HTTPCookieProcessor.cookiejar

这个 http.cookiejar.CookieJar 存储cookie的位置。

proxyhandler对象

ProxyHandler.<protocol>_open(request)

这个 ProxyHandler 会有一个方法 <protocol>_open() 对于每一个 协议 其中有一个代理 proxies 构造函数中提供的字典。方法将通过调用 request.set_proxy() ，并调用链中的下一个处理程序以实际执行协议。

httppasswordmgr对象

这些方法在 HTTPPasswordMgr 和 HTTPPasswordMgrWithDefaultRealm 物体。

HTTPPasswordMgr.add_password(realm, uri, user, passwd)

uri 可以是单个URI，也可以是一系列URI。 realm ， user 和 passwd 必须是字符串。这一原因 (user, passwd) 在对进行身份验证时用作身份验证令牌 realm 并且给出了任意给定URI的超级URI。

HTTPPasswordMgr.find_user_password(realm, authuri)

获取给定领域和URI的用户/密码（如果有）。此方法将返回 (None, None) 如果没有匹配的用户/密码。

为了 HTTPPasswordMgrWithDefaultRealm 对象，领域 None 如果给定的 realm 没有匹配的用户/密码。

httpPasswordMgrWithPriorAuth对象

此密码管理器扩展 HTTPPasswordMgrWithDefaultRealm 以支持跟踪应该始终为其发送身份验证凭据的URI。

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)

realm ， uri ， user ， passwd 至于 HTTPPasswordMgr.add_password() . is_authenticated 设置的初始值 is_authenticated 给定URI或URI列表的标志。如果 is_authenticated 指定为 True ， realm 被忽略。

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)

同为 HTTPPasswordMgrWithDefaultRealm 物体

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)

更新 is_authenticated 给定的标志 uri 或URI列表。

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)

返回的当前状态 is_authenticated 给定URI的标志。

AbstractBasicAuthHandler对象

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

通过获取用户/密码对来处理身份验证请求，然后重新尝试该请求。 奥瑟雷克 应该是请求中包含领域信息的头的名称， host 指定要验证的URL和路径， req 应该是（失败的） Request 对象，以及 headers 应该是错误头。

host 是一个权威（例如 "python.org" ）或包含权限组件的URL（例如 "http://python.org/" ）在这两种情况下，权限都不能包含userinfo组件（因此， "python.org" 和 "python.org:80" 很好， "joe:password@python.org" 不是）。

httpbasicAuthHandler对象

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)

如果可用，请使用身份验证信息重试请求。

proxybasicauthhandler对象

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)

如果可用，请使用身份验证信息重试请求。

AbstractDigestAuthHandler对象

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

奥瑟雷克 应该是请求中包含领域信息的头的名称， host 应该是要验证的主机， req 应该是（失败的） Request 对象，以及 headers 应该是错误头。

httpDigestAuthHandler对象

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)

如果可用，请使用身份验证信息重试请求。

proxyDigeStauthHandler对象

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)

如果可用，请使用身份验证信息重试请求。

httphandler对象

HTTPHandler.http_open(req)

发送HTTP请求，根据 req.has_data() .

httpshandler对象

HTTPSHandler.https_open(req)

发送一个HTTPS请求，根据 req.has_data() .

文件处理程序对象

FileHandler.file_open(req)

如果没有主机名或主机名是 'localhost' .

在 3.2 版更改: 此方法仅适用于本地主机名。当给定远程主机名时，一个 URLError 提高了。

数据处理程序对象

DataHandler.data_open(req)

读取数据URL。这种URL包含在URL本身中编码的内容。数据URL语法在中指定 RFC 2397 . 此实现忽略base64编码的数据URL中的空格，因此该URL可能被封装在它来自的任何源文件中。但是，尽管有些浏览器不介意base64编码的数据URL末尾缺少填充，但此实现将引发 ValueError 在这种情况下。

ftphandler对象

FTPHandler.ftp_open(req)

打开由指示的ftp文件 req . 登录总是以空用户名和密码完成。

cacheftphandler对象

CacheFTPHandler 对象是 FTPHandler 具有以下附加方法的对象：

CacheFTPHandler.setTimeout(t)

将连接超时设置为 t 秒。

CacheFTPHandler.setMaxConns(m)

将缓存连接的最大数目设置为 m .

未知的handler对象

UnknownHandler.unknown_open()

举起一个 URLError 例外。

httpErrorProcessor对象

HTTPErrorProcessor.http_response(request, response)

处理HTTP错误响应。

对于200个错误代码，立即返回响应对象。

对于非200错误代码，这只需将任务传递到 http_error_<type>() 处理程序方法，通过 OpenerDirector.error() .最终， HTTPDefaultErrorHandler 将提高 HTTPError 如果没有其他处理程序处理错误。

HTTPErrorProcessor.https_response(request, response)

处理HTTPS错误响应。

行为与 http_response() .

实例

除了下面的例子外，在 如何使用urllib包获取Internet资源 .

此示例获取python.org主页并显示其前300个字节。地址：

>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(300))
...
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
<meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
<title>Python Programming '

注意，urlopen返回一个bytes对象。这是因为urlopen无法自动确定从HTTP服务器接收的字节流的编码。通常，一旦程序确定或猜测适当的编码，它就会将返回的bytes对象解码为字符串。

以下W3C文档https://www.w3.org/international/o-charset列出了（x）HTML或XML文档指定其编码信息的各种方式。

正如python.org网站使用的 utf-8 按照其meta标记中指定的编码方式，我们将使用相同的方法对bytes对象进行解码。：：

>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(100).decode('utf-8'))
...
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

也可以在不使用 context manager 方法。：：

>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> print(f.read(100).decode('utf-8'))
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

在下面的示例中，我们将向CGI的stdin发送数据流，并读取它返回给我们的数据。请注意，此示例仅在Python安装支持SSL时有效。地址：

>>> import urllib.request
>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data=b'This data is passed to stdin of the CGI')
>>> with urllib.request.urlopen(req) as f:
...     print(f.read().decode('utf-8'))
...
Got Data: "This data is passed to stdin of the CGI"

上面示例中使用的示例CGI的代码是：

#!/usr/bin/env python
import sys
data = sys.stdin.read()
print('Content-type: text/plain\n\nGot Data: "%s"' % data)

下面是一个例子 PUT 请求使用 Request ：：

import urllib.request
DATA = b'some data'
req = urllib.request.Request(url='http://localhost:8080', data=DATA, method='PUT')
with urllib.request.urlopen(req) as f:
    pass
print(f.status)
print(f.reason)

基本HTTP身份验证的使用：

import urllib.request
# Create an OpenerDirector with support for Basic HTTP Authentication...
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
                          uri='https://mahler:8092/site-updates.py',
                          user='klem',
                          passwd='kadidd!ehopper')
opener = urllib.request.build_opener(auth_handler)
# ...and install it globally so it can be used with urlopen.
urllib.request.install_opener(opener)
urllib.request.urlopen('http://www.example.com/login.html')

build_opener() 默认情况下提供许多处理程序，包括 ProxyHandler . 默认情况下， ProxyHandler 使用名为的环境变量 <scheme>_proxy 在哪里 <scheme> 是否涉及URL方案。例如， http_proxy 读取环境变量以获取HTTP代理的URL。

此示例替换默认值 ProxyHandler 使用以编程方式提供的代理URL，并添加代理授权支持 ProxyBasicAuthHandler . ：：

proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
# This time, rather than install the OpenerDirector, we use it directly:
opener.open('http://www.example.com/login.html')

添加HTTP头：

使用 headers 参数 Request 构造函数，或：

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
r = urllib.request.urlopen(req)

OpenerDirector 自动添加 User-Agent 每个的标题 Request . 要更改此内容：

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')

另外，请记住一些标准头文件 (Content-Length ， Content-Type 和 Host ）当 Request 传递给 urlopen() （或） OpenerDirector.open() ）

下面是一个使用 GET 检索包含参数的URL的方法：

>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> url = "http://www.musi-cal.com/cgi-bin/query?%s" % params
>>> with urllib.request.urlopen(url) as f:
...     print(f.read().decode('utf-8'))
...

以下示例使用 POST 方法。注意，从urlencode输出的参数在作为数据发送到urlopen之前被编码为字节：

>>> import urllib.request
>>> import urllib.parse
>>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> data = data.encode('ascii')
>>> with urllib.request.urlopen("http://requestb.in/xrbl82xr", data) as f:
...     print(f.read().decode('utf-8'))
...

以下示例使用显式指定的HTTP代理，覆盖环境设置：

>>> import urllib.request
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.FancyURLopener(proxies)
>>> with opener.open("http://www.python.org") as f:
...     f.read().decode('utf-8')
...

以下示例根本不使用代理，覆盖环境设置：

>>> import urllib.request
>>> opener = urllib.request.FancyURLopener({})
>>> with opener.open("http://www.python.org/") as f:
...     f.read().decode('utf-8')
...

传统接口

以下函数和类是从python 2模块移植的 urllib （而不是 urllib2 ）在将来的某个时候，它们可能会被弃用。

urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)

将由URL表示的网络对象复制到本地文件。如果该URL指向本地文件，则除非提供文件名，否则不会复制该对象。返回元组 (filename, headers) 在哪里？ filename 是可以在其中找到对象的本地文件名，以及 headers 无论是什么 info() 返回对象的方法 urlopen() 返回（对于远程对象）。例外情况与 urlopen() .

第二个参数（如果存在）指定要复制到的文件位置（如果不存在，该位置将是具有生成名称的tempfile）。第三个参数（如果存在）是一个可调用参数，在建立网络连接时调用一次，然后在每个块读取之后调用一次。可调用文件将传递三个参数：到目前为止传输的块数、以字节为单位的块大小和文件的总大小。第三个参数可能是 -1 在旧的FTP服务器上，该服务器不会响应检索请求返回文件大小。

以下示例说明了最常见的使用场景：

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
>>> html = open(local_filename)
>>> html.close()

如果 url 使用 http: 方案标识符，可选 data 可以提供参数来指定 POST 请求（通常请求类型为 GET ）这个 data 参数必须是标准中的bytes对象 application/x-www-form-urlencoded 格式；参见 urllib.parse.urlencode() 功能。

urlretrieve() 将提高 ContentTooShortError 当它检测到可用数据量小于预期量（即 Content-Length 标题）。例如，当下载中断时，可能会发生这种情况。

这个 Content-Length 被视为一个下限：如果有更多的数据需要读取，那么urlretrieve将读取更多的数据，但是如果可用的数据更少，则会引发异常。

您仍然可以检索下载的数据，在这种情况下，它存储在 content 异常实例的属性。

如果没有 Content-Length 提供了头，UrlRetrieve无法检查已下载数据的大小，只返回该数据。在这种情况下，您只需假设下载成功。

urllib.request.urlcleanup()

清除以前调用时可能留下的临时文件 urlretrieve() .

class urllib.request.URLopener(proxies=None, **x509)

3.3 版后已移除.

用于打开和读取URL的基类。除非您需要支持使用方案以外的其他方案打开对象 http: ， ftp: 或 file: ，您可能想使用 FancyURLopener .

默认情况下， URLopener 类发送一个 User-Agent 标题 urllib/VVV 在哪里 VVV 是 urllib 版本号。应用程序可以定义自己的 User-Agent 按子类划分的标题 URLopener 或 FancyURLopener 设置class属性 version 到子类定义中适当的字符串值。

可选的 proxies 参数应该是将方案名称映射到代理URL的字典，其中空字典将完全关闭代理。其默认值为 None ，在这种情况下，将使用环境代理设置（如果存在），如定义中所述 urlopen() ，上面。

其他关键字参数，收集于 x509 ，当使用 https: 方案。关键词 key_file 和 cert_file 支持提供SSL密钥和证书；两者都需要支持客户端身份验证。

URLopener 对象将引发 OSError 如果服务器返回错误代码，则出现异常。

open(fullurl, data=None)

正常开放 全网址 使用适当的协议。此方法设置缓存和代理信息，然后用其输入参数调用相应的open方法。如果方案未被认可， open_unknown() 被称为。这个 data 参数的含义与 data 的参数 urlopen() .

全网址 使用 quote() .

open_unknown(fullurl, data=None)

用于打开未知URL类型的可重写接口。

retrieve(url, filename=None, reporthook=None, data=None)

检索的内容 url 把它放进去 filename . 返回值是一个由本地文件名和 email.message.Message 包含响应头的对象（用于远程URL）或 None （对于本地URL）。然后调用方必须打开并读取 filename . 如果 filename 未给定，且URL引用本地文件，将返回输入文件名。如果URL不是本地的，并且 filename 未给定，文件名是 tempfile.mktemp() 后缀与输入URL的最后一个路径组件的后缀匹配。如果 报告书 如果给定，它必须是一个接受三个数字参数的函数：一个块编号、读取的最大块大小和下载的总大小（如果未知，则为-1）。它将在开始时和从网络中读取每个数据块后调用一次。 报告书 对于本地URL忽略。

如果 url 使用 http: 方案标识符，可选 data 可以提供参数来指定 POST 请求（通常请求类型为 GET ）这个 data 参数必须在标准中 application/x-www-form-urlencoded 格式；参见 urllib.parse.urlencode() 功能。

version

指定Opener对象的用户代理的变量。得到 urllib 若要告诉服务器它是一个特定的用户代理，请在调用基本构造函数之前，在子类中将其设置为类变量或在构造函数中。

class urllib.request.FancyURLopener(...)

3.3 版后已移除.

FancyURLopener 子类 URLopener 为以下HTTP响应代码提供默认处理：301、302、303、307和401。对于上面列出的30x响应代码， Location header用于获取实际的URL。对于401响应代码（需要身份验证），执行基本HTTP身份验证。对于30x响应代码，递归由 最大值 属性，默认为10。

对于所有其他响应代码，该方法 http_error_default() 可以在子类中重写以适当地处理错误的调用。

注解

根据 RFC 2616 未经用户确认，不得自动重定向对POST请求的、301和302响应。实际上，浏览器允许这些响应的自动重定向，将post更改为get，以及 urllib 复制这种行为。

构造函数的参数与 URLopener .

注解

在执行基本身份验证时， FancyURLopener 实例调用其 prompt_user_passwd() 方法。默认实现要求用户在控制终端上获取所需的信息。如果需要，子类可以重写此方法以支持更合适的行为。

这个 FancyURLopener 类提供了一个应重载以提供适当行为的附加方法：

prompt_user_passwd(host, realm)

返回在指定安全领域中对给定主机上的用户进行身份验证所需的信息。返回值应该是一个元组， (user, password) ，可用于基本身份验证。

实现在终端上提示输入此信息；应用程序应重写此方法，以便在本地环境中使用适当的交互模型。

urllib.request 限制

  • 目前，仅支持以下协议：http（版本0.9和1.0）、ftp、本地文件和数据URL。

    在 3.4 版更改: 添加了对数据URL的支持。

  • 的缓存功能 urlretrieve() 已被禁用，直到有人找到正确处理过期时间头的时间。

  • 应该有一个函数来查询某个特定的URL是否在缓存中。

  • 为了向后兼容，如果URL似乎指向本地文件，但无法打开该文件，则使用ftp协议重新解释该URL。这有时会导致混淆的错误消息。

  • 这个 urlopen() 和 urlretrieve() 函数在等待建立网络连接时可能导致任意长的延迟。这意味着很难在不使用线程的情况下使用这些函数构建交互式Web客户机。

  • 返回的数据 urlopen() 或 urlretrieve() 是服务器返回的原始数据。这可能是二进制数据（例如图像）、纯文本或（例如）HTML。HTTP协议在回复头中提供了类型信息，可以通过查看 Content-Type 标题。如果返回的数据是HTML，则可以使用该模块 html.parser 解析它。

  • 处理ftp协议的代码不能区分文件和目录。当试图读取指向不可访问文件的URL时，这可能会导致意外行为。如果URL以 / ，假定它引用一个目录，并将进行相应的处理。但是，如果试图读取文件导致550错误（这意味着找不到URL或由于权限原因无法访问该URL），则该路径将被视为一个目录，以便处理由URL指定目录但后面是 / 已经离开了。当您试图获取的文件的读取权限使其不可访问时，这可能会导致误导性结果；ftp代码将尝试读取该文件，失败并出现550个错误，然后对不可读取的文件执行目录列表。如果需要细粒度控制，请考虑使用 ftplib 模块，子类化 FancyURLopener 或改变 _urlopener 满足你的需求。

urllib.response ---Urllib使用的响应类

这个 urllib.response 模块定义函数和类，这些函数和类定义一个最小的类文件接口，包括 read() 和 readline() . 此模块定义的函数由 urllib.request 模块。典型的响应对象是 urllib.response.addinfourl 实例：

class urllib.response.addinfourl
url

检索到的资源的URL，通常用于确定是否遵循了重定向。

headers

以 EmailMessage 实例。

status

3.9 新版功能.

服务器返回的状态代码。

geturl()

3.9 版后已移除: 反对赞成 url .

info()

3.9 版后已移除: 反对赞成 headers .

code

3.9 版后已移除: 反对赞成 status .

getstatus()

3.9 版后已移除: 反对赞成 status .