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

源码： Lib/urllib/request.py

`urllib.request` 模块定义了适用于在各种复杂情况下打开 URL（主要为 HTTP）的函数和类 --- 例如基本认证、摘要认证、重定向、cookies 及其它。

参见

对于更高级别的 HTTP 客户端接口，建议使用 Requests 。

`urllib.request` 模块定义了以下函数：

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

  打开统一资源定位符 url，可以是一个字符串或一个 `Request` 对象。

  data 必须是一个对象，用于给出要发送到服务器的附加数据，若不需要发送数据则为 `None`。详情请参阅 `Request` 。

  urllib.request 模块采用 HTTP/1.1 协议，并且在其 HTTP 请求中包含 `Connection:close` 头部信息。

  timeout 为可选参数，用于指定阻塞操作（如连接尝试）的超时时间，单位为秒。如未指定，将使用全局默认超时参数）。本参数实际仅对 HTTP、HTTPS 和 FTP 连接有效。

  如果给定了 context 参数，则必须是一个 `ssl.SSLContext` 实例，用于描述各种 SSL 参数。更多详情请参阅 `HTTPSConnection` 。

  cafile 和 capath 为可选参数，用于为 HTTPS 请求指定一组受信 CA 证书。cafile 应指向包含CA 证书的单个文件， capath 则应指向哈希证书文件的目录。更多信息可参阅 `ssl.SSLContext.load_verify_locations()` 。

  参数 cadefault 将被忽略。

  本函数总会返回一个对象，该对象可作为 context manager 使用，带有 url、headers 和 status 属性。有关这些属性的更多详细信息，请参阅 `urllib.response.addinfourl` 。

  对于 HTTP 和 HTTPS 的 URL 而言，本函数将返回一个稍经修改的 `http.client.HTTPResponse` 对象。除了上述 3 个新的方法之外，还有 msg 属性包含了与 `reason` 属性相同的信息---服务器返回的原因描述文字，而不是 `HTTPResponse` 的文档所述的响应头部信息。

  对于 FTP、文件、数据的URL，以及由传统的 `URLopener` 和 `FancyURLopener` 类处理的请求，本函数将返回一个 `urllib.response.addinfourl` 对象。

  协议发生错误时，将会引发 `URLError` 。

  请注意，如果没有处理函数对请求进行处理，则有可能会返回 `None` 。尽管默认安装的全局 `OpenerDirector` 会用 `UnknownHandler` 来确保不会发生这种情况。

  此外，如果检测到设置了代理（比如设置了 `http_proxy` 之类的环境变量），默认会安装 `ProxyHandler` 并确保通过代理处理请求。

  Python 2.6 以下版本中留存的 `urllib.urlopen` 函数已停止使用了； `urllib.request.urlopen()` 对应于传统的 `urllib2.urlopen` 。对代理服务的处理是通过将字典参数传给 `urllib.urlopen` 来完成的，可以用 `ProxyHandler` 对象获取到代理处理函数。

  默认会触发一条 审计事件 `urllib.Request` ，参数 `fullurl` 、 `data` 、`headers` 、`method` 均取自请求对象。

  在 3.2 版更改: 增加了 cafile 与 capath。

  在 3.2 版更改: 只要条件允许（指 `ssl.HAS_SNI` 为真），现在能够支持 HTTPS 虚拟主机。

  3.2 新版功能: data 可以是一个可迭代对象。

  在 3.3 版更改: 增加了 cadefault。

  在 3.4.3 版更改: 增加了 context。

  3.6 版后已移除: cafile 、 capath 和 cadefault 已废弃，转而推荐使用 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` 实例，以给定顺序把处理函数串联起来。处理函数可以是 `BaseHandler` 的实例，也可以是 `BaseHandler` 的子类（这时构造函数必须允许不带任何参数的调用）。以下类的实例将位于 处理函数 之前，除非 处理函数 已包含这些类、其实例或其子类： `ProxyHandler` （如果检测到代理设置）、`UnknownHandler` 、`HTTPHandler` 、`HTTPDefaultErrorHandler` 、`HTTPRedirectHandler` 、 `FTPHandler` 、 `FileHandler` 、`HTTPErrorProcessor` 。

  若 Python 安装时已带了 SSL 支持（指可以导入 `ssl` 模块），则还会加入 `HTTPSHandler` 。

  A `BaseHandler` subclass may also change its `handler_order` attribute to modify its position in the handlers list.

`urllib.request.``pathname2url`(path)

  将路径名 path 从路径本地写法转换为 URL 路径部分所采用的格式。本函数不会生成完整的 URL。返回值将会用 `quote()` 函数加以编码。

`urllib.request.``url2pathname`(path)

  从百分号编码的 URL 中将 path 部分转换为本地路径的写法。本函数不接受完整的 URL，并利用 `unquote()` 函数对 path 进行解码。

`urllib.request.``getproxies`()

  本辅助函数将返回一个字典，表示各方案映射的代理服务器 URL。本函数扫描名为 `<scheme>_proxy` 的环境变量，不区分大小写，首先会考虑所有操作系统。如果环境变量无法找到，则会 从 Mac OS X 的 Mac OSX 系统配置或 Windows 系统的注册表查找代理服务器信息。如果同时存在小写和大写环境变量（且内容不一致），则首选小写。

  注解

  如果存在环境变量 `REQUEST_METHOD` ，通常表示脚本运行于 CGI 环境中，则环境变量 `HTTP_PROXY` （大写的 `_PROXY`）将会被忽略。这是因其可以由客户端用 HTTP 头部信息 “Proxy:”注入。若要在 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` 。 目前 唯一用到 data 的只有 HTTP 请求。支持的对象类型包括字节串、类文件对象和可遍历的类字节串对象。如果没有提供 `Content-Length` 和 `Transfer-Encoding` 头部字段， `HTTPHandler` 会根据 data 的类型设置这些头部字段。`Content-Length` 将用于发送字节对象，而 RFC 7230 第 3.3.1 节中定义的 `Transfer-Encoding: chunked` 将用于发送文件和其他可遍历对象。

  对于 HTTP POST 请求方法而言，data 应该是标准 application/x-www-form-urlencoded 格式的缓冲区。 `urllib.parse.urlencode()` 函数的参数为映射对象或二元组序列，并返回一个该编码格式的 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` 的默认 user agent 字符串则是 `"Python-urllib/2.6"` （在 Python 2.6 上）。

  如果给出了 data 参数，则应当包含合适的 `Content-Type` 头部信息。若未提供且 data 不是 None，则会把 `Content-Type: application/x-www-form-urlencoded` 加入作为默认值。

  接下来的两个参数，只对第三方 HTTP cookie 的处理才有用：

  origin_req_host 应为发起初始会话的请求主机，定义参见 RFC 2965 。默认指为``http.cookiejar.request_host(self)`` 。这是用户发起初始请求的主机名或 IP 地址。假设请求是针对 HTML 文档中的图片数据发起的，则本属性应为对包含图像的页面发起请求的主机。

  unverifiable 应该标示出请求是否无法验证，定义参见 RFC 2965 。默认值为 `False` 。所谓无法验证的请求，是指用户没有机会对请求的 URL 做验证。例如，如果请求是针对 HTML 文档中的图像，用户没有机会去许可能自动读取图像，则本参数应为 True。

  method 应为字符串，标示要采用的 HTTP 请求方法（例如 `'HEAD'` ）。如果给出本参数，其值会存储在 `method` 属性中，并由 `get_method()` 使用。如果 data 为``None`` 则默认值为 `'GET'` ，否则为 `'POST'`。子类可以设置 `method` 属性来标示不同的默认请求方法。

  注解

  如果 data 对象无法分多次传递其内容（比如文件或只能生成一次内容的可迭代对象）并且由于 HTTP 重定向或身份验证而发生请求重试行为，则该请求不会正常工作。 data 是紧挨着头部信息发送给 HTTP 服务器的。现有库不支持 HTTP 100-continue 的征询。

  在 3.3 版更改: Request 类增加了 `Request.method` 参数。

  在 3.4 版更改: 默认 `Request.method` 可以在类中标明。

  在 3.6 版更改: 如果给出了 `Content-Length` ，且 data 既不为 `None` 也不是字节串对象，则不会触发错误。而会退而求其次采用分块传输的编码格式。

class `urllib.request.``OpenerDirector`

  `OpenerDirector` 类通过串接在一起的 `BaseHandler` 打开 URL，并负责管理 handler 链及从错误中恢复。

class `urllib.request.``BaseHandler`

  这是所有已注册 handler 的基类，只做了简单的注册机制。

class `urllib.request.``HTTPDefaultErrorHandler`

  为 HTTP 错误响应定义的默认 handler，所有出错响应都会转为 `HTTPError` 异常。

class `urllib.request.``HTTPRedirectHandler`

  一个用于处理重定向的类。

class `urllib.request.``HTTPCookieProcessor`(cookiejar=None)

  一个用于处理 HTTP Cookies 的类。

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` 。

  > 注解

  > 如果设置了 `REQUEST_METHOD` 变量，则会忽略 `HTTP_PROXY` ；参阅 `getproxies()` 文档。

class `urllib.request.``HTTPPasswordMgr`

  维护 `(realm, uri) -> (user, password)` 映射数据库。

class `urllib.request.``HTTPPasswordMgrWithDefaultRealm`

  维护 `(realm, uri) -> (user, password)` 映射数据库。realm 为 `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 对象 对象的章节。如果 password_mgr 还提供 `is_authenticated` 和 `update_authenticated` 方法（请参阅 HTTPPasswordMgrWithPriorAuth 对象 对象），则 handler 将对给定 URI 用到 `is_authenticated` 的结果，来确定是否随请求发送身份认证凭据。如果该 URI 的 `is_authenticated` 返回 `True`，则发送凭据。如果 `is_authenticated` 为 `False` ，则不发送凭据，然后若收到 `401` 响应，则使用身份认证凭据重新发送请求。如果身份认证成功，则调用 `update_authenticated` 设置该 URI 的 `is_authenticated` 为 `True`，这样后续对该 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 对象 章节。如果同时添加了 digest 身份认证 handler 和basic 身份认证 handler，则会首先尝试 digest 身份认证。如果 digest 身份认证再返回 40x 响应，会再发送到 basic 身份验证 handler 进行处理。如果给出 Digest 和 Basic 之外的身份认证方式， 本 handler 方法将会触发 `ValueError` 。

  在 3.3 版更改: 碰到不支持的认证方式时，将会触发 `ValueError` 。

class `urllib.request.``ProxyDigestAuthHandler`(password_mgr=None)

  处理有代理服务时的身份认证。 password_mgr 应与 `HTTPPasswordMgr` 兼容；有关哪些接口是必须支持的，请参阅 HTTPPasswordMgr 对象 章节。

class `urllib.request.``HTTPHandler`

  用于打开 HTTP URL 的 handler 类。

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

  用于打开 HTTPS URL 的 handler 类。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`

  处理所有未知类型 URL 的兜底类。

class `urllib.request.``HTTPErrorProcessor`

  处理出错的 HTTP 响应。

## Request 对象

以下方法介绍了 `Request` 的公开接口，因此子类可以覆盖所有这些方法。这里还定义了几个公开属性，客户端可以利用这些属性了解经过解析的请求。

`Request.``full_url`

  传给构造函数的原始 URL。

  在 3.4 版更改.

  Request.full_url 是一个带有 setter、getter 和 deleter 的属性。读取 `full_url` 属性将会返回附带片段（fragment）的初始请求 URL。

`Request.``type`

  URI 方式。

`Request.``host`

  URI 权限，通常是整个主机，但也有可能带有冒号分隔的端口号。

`Request.``origin_req_host`

  请求的原始主机，不含端口。

`Request.``selector`

  URI 路径。若 `Request` 使用代理，selector 将会是传给代理的完整 URL。

`Request.``data`

  请求的数据体，未给出则为 `None` 。

  在 3.4 版更改: 现在如果修改 `Request.data` 的值，则会删除之前设置或计算过的“Content-Length”头部信息。

`Request.``unverifiable`

  布尔值，标识本请求是否属于 RFC 2965 中定义的无法验证的情况。

`Request.``method`

  要采用的 HTTP 请求方法。默认为 `None`，表示 `get_method()` 将对方法进行正常处理。设置本值可以覆盖 `get_method()` 中的默认处理过程，设置方式可以是在 `Request` 的子类中给出默认值，也可以通过 method 参数给 `Request` 构造函数传入一个值。

  3.3 新版功能.

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

`Request.``get_method`()

  返回表示 HTTP 请求方法的字符串。如果 `Request.method` 不为 `None` ，则返回其值。否则若 `Request.data` 为 则返回 `'GET'`，不为 `None` 则返回 `'POST'` 。只对 HTTP 请求有效。

  在 3.3 版更改: 现在 get_method 会兼顾 `Request.method` 的值。

`Request.``add_header`(key, val)

  向请求添加一项头部信息。目前只有 HTTP handler 才会处理头部信息，将其加入发给服务器的头部信息列表中。请注意，同名的头部信息只能出现一次，如果 键 发生冲突，后续的调用结果将会覆盖先前的。目前，这并不会减少 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 将会取代本实例中的对应值，selector 将会是构造函数中给出的初始 URL。

`Request.``get_header`(header_name, default=None)

  返回给定头部信息的数据。如果该头部信息不存在，返回默认值。

`Request.``header_items`()

  返回头部信息，形式为（名称, 数据）的元组列表。

在 3.4 版更改: 自 3.3 起已弃用的下列方法已被删除：add_data、has_data、get_data、get_type、get_host、get_selector、get_origin_req_host 和 is_unverifiable 。

## OpenerDirector 对象

`OpenerDirector` 实例有以下方法：

`OpenerDirector.``add_handler`(handler)

  handler 应为 `BaseHandler` 的实例。将检索以下类型的方法，并将其添加到对应的处理链中（注意 HTTP 错误是特殊情况）。请注意，下文中的 protocol 应替换为要处理的实际协议，例如 `http_response()` 将是 HTTP 协议响应处理函数。并且 type 也应替换为实际的 HTTP 代码，例如 `http_error_404()` 将处理 HTTP 404 错误。

  - `<protocol>_open()` — 表明该 handler 知道如何打开 protocol 协议的URL。

    更多信息请参阅 `BaseHandler.<protocol>_open()` 。

  - `http_error_<type>()` — 表明该 handler 知道如何处理代码为 type 的 HTTP 错误。

    更多信息请参阅 `BaseHandler.http_error_<nnn>()` 。

  - `<protocol>_error()` — 表明该 handler 知道如何处理来自协议为 protocol （非`http`）的错误。

  - `<protocol>_request()` — 表明该 handler 知道如何预处理协议为 protocol 的请求。

    更多信息请参阅 `BaseHandler.<protocol>_request()` 。

  - `<protocol>_response()` — 表明该 handler 知道如何后处理协议为 protocol 的响应。

    更多信息请参阅 `BaseHandler.<protocol>_response()` 。

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

  打开给定的 url*（可以是 request 对象或字符串），可以传入 *data 。参数、返回值和引发的异常均与 `urlopen()` 相同，其实只是去调用了当前安装的全局 `OpenerDirector` 中的 `open()` 方法。可选的 timeout 参数指定了阻塞操作（如尝试连接）的超时值（以秒为单位）（若未指定则采用全局默认的超时设置）。实际上，超时特性仅适用于 HTTP、HTTPS 和 FTP 连接。

`OpenerDirector.``error`(proto, *args)

  处理给定协议的错误。将用给定的参数（协议相关）调用已注册的给定协议的错误处理程序。HTTP 协议是特殊情况，采用 HTTP 响应码来确定具体的错误处理程序；请参考 handler 类的 `http_error_<type>()` 方法。

  返回值和异常均与 `urlopen()` 相同。

OpenerDirector 对象分 3 个阶段打开 URL：

每个阶段中调用这些方法的次序取决于 handler 实例的顺序。

1. 每个具有 `_request()` 这类方法的 handler 都会调用本方法对请求进行预处理。

2. 调用具有 `_open()` 这类方法的 handler 来处理请求。当 handler 返回非`None` 值（即响应）或引发异常（通常是 `URLError`）时，本阶段结束。本阶段能够传播异常。

   事实上，以上算法首先会尝试名为 `default_open()` 的。如果这些方法全都返回 `None`，则会对名为 `_open()` 的这类方法重复过程。如果又都返回 `None`，则再对名为 `unknown_open()` 的方法重复过程。

   请注意，这些方法的代码可能会调用 `OpenerDirector` 父实例的 `open()` 和 `error()` 方法。

3. 每个具有 `_response()` 这类方法的 handler 都会调用这些方法，以对响应进行后处理。

## BaseHandler 对象

`BaseHandler` 对象提供了一些直接可用的方法，以及其他一些可供派生类使用的方法。以下是可供直接使用的方法：

`BaseHandler.``add_parent`(director)

  将 director 加为父 OpenerDirector。

`BaseHandler.``close`()

  移除所有父 OpenerDirector。

以下属性和方法仅供 `BaseHandler` 的子类使用：

注解

以下约定已被采纳：定义 `<protocol>_request()` 或 `<protocol>_response()` 方法的子类应命名为 `*Processor`；所有其他子类都应命名为 `*Handler` 。

`BaseHandler.``parent`

  一个可用的 `OpenerDirector`，可用于以其他协议打开 URI，或处理错误。

`BaseHandler.``default_open`(req)

  本方法在 `BaseHandler` 中 未 予定义，但其子类若要捕获所有 URL 则应进行定义。

  若实现了本方法，则会被父类 `OpenerDirector` 调用。应返回一个文件类对象，类似于 `OpenerDirector` 的 `open()` 的返回值，或返回 `None` 。触发的异常应为 `URLError`，除非发生真的异常（比如 `MemoryError` 就不应变为 `URLError`）。

  本方法将会在所有协议的 open 方法之前被调用。

`BaseHandler.<protocol>_open(req)`

  本方法在 `BaseHandler` 中 未 予定义，但其子类若要处理给定协议的 URL 则应进行定义。

  若定义了本方法，将会被父 `OpenerDirector` 对象调用。返回值和 `default_open()` 的一样。

`BaseHandler.``unknown_open`(req)

  本方法在 `BaseHandler` 中 未 予定义，但其子类若要捕获并打开所有未注册 handler 的 URL，则应进行定义。

  若实现了本方法，将会被 `parent` 属性指向的父 `OpenerDirector` 调用。返回值和 `default_open()` 的一样。

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

  本方法在 `BaseHandler` 中 未 予定义，但其子类若要为所有未定义 handler 的 HTTP 错误提供一个兜底方法，则应进行重写。`OpenerDirector` 会自动调用本方法，获取错误信息，而通常在其他时候不应去调用。

  req 会是一个 `Request` 对象，fp 是一个带有 HTTP 错误体的文件类对象，code 是三位数的错误码，msg 是供用户阅读的解释信息，hdrs 则是一个包含出错头部信息的字典对象。

  返回值和触发的异常应与 `urlopen()` 的相同。

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

  nnn 应为三位数的 HTTP 错误码。本方法在 `BaseHandler` 中也未予定义，但当子类的实例发生代码为 nnn 的 HTTP 错误时，若方法存在则会被调用。

  子类应该重写本方法，以便能处理相应的 HTTP 错误。

  参数、返回值和触发的异常应与 `http_error_default()` 相同。

`BaseHandler.<protocol>_request(req)`

  本方法在 `BaseHandler` 中 未 予定义，但其子类若要对给定协议的请求进行预处理，则应进行定义。

  若实现了本方法，将会被父 `OpenerDirector` 调用。req 将为 `Request` 对象。返回值应为 `Request` 对象。

`BaseHandler.<protocol>_response(req, response)`

  本方法在 `BaseHandler` 中 未 予定义，但其子类若要对给定协议的请求进行后处理，则应进行定义。

  若实现了本方法，将会被父 `OpenerDirector` 调用。req 将为 `Request` 对象。response 应实现与 `urlopen()` 返回值相同的接口。返回值应实现与 `urlopen()` 返回值相同的接口。

## HTTPRedirectHandler 对象

注解

某些 HTTP 重定向操作需要本模块的客户端代码提供的功能。这时会触发 `HTTPError`。有关各种重定向代码的确切含义，请参阅 RFC 2616 。

如果给到 HTTPRedirectHandler 的重定向 URL 不是 HTTP、HTTPS 或 FTP URL，则出于安全考虑将触发 `HTTPError` 异常。

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

  Return a `Request` or `None` in response to a redirect. This is called by the default implementations of the `http_error_30*()` methods when a redirection is received from the server. If a redirection should take place, return a new `Request` to allow `http_error_30*()` to perform the redirect to newurl. Otherwise, raise `HTTPError` if no other handler should try to handle this URL, or return `None` if you can't but another handler might.

  注解

  The default implementation of this method does not strictly follow RFC 2616, which says that 301 and 302 responses to `POST` requests must not be automatically redirected without confirmation by the user. In reality, browsers do allow automatic redirection of these responses, changing the POST to a `GET`, and the default implementation reproduces this behavior.

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

  Redirect to the `Location:` or `URI:` URL. This method is called by the parent `OpenerDirector` when getting an HTTP 'moved permanently' response.

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

  The same as `http_error_301()`, but called for the 'found' response.

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

  The same as `http_error_301()`, but called for the 'see other' response.

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

  The same as `http_error_301()`, but called for the 'temporary redirect' response.

## HTTPCookieProcessor 对象

`HTTPCookieProcessor` instances have one attribute:

`HTTPCookieProcessor.``cookiejar`

  The `http.cookiejar.CookieJar` in which cookies are stored.

## ProxyHandler 对象

`ProxyHandler.<protocol>_open(request)`

  The `ProxyHandler` will have a method `<protocol>_open()` for every protocol which has a proxy in the proxies dictionary given in the constructor. The method will modify requests to go through the proxy, by calling `request.set_proxy()`, and call the next handler in the chain to actually execute the protocol.

## HTTPPasswordMgr 对象

These methods are available on `HTTPPasswordMgr` and `HTTPPasswordMgrWithDefaultRealm` objects.

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

  uri can be either a single URI, or a sequence of URIs. realm, user and passwd must be strings. This causes `(user, passwd)` to be used as authentication tokens when authentication for realm and a super-URI of any of the given URIs is given.

`HTTPPasswordMgr.``find_user_password`(realm, authuri)

  Get user/password for given realm and URI, if any. This method will return `(None, None)` if there is no matching user/password.

  For `HTTPPasswordMgrWithDefaultRealm` objects, the realm `None` will be searched if the given realm has no matching user/password.

## HTTPPasswordMgrWithPriorAuth 对象

This password manager extends `HTTPPasswordMgrWithDefaultRealm` to support tracking URIs for which authentication credentials should always be sent.

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

  realm, uri, user, passwd are as for `HTTPPasswordMgr.add_password()`. is_authenticated sets the initial value of the `is_authenticated` flag for the given URI or list of URIs. If is_authenticated is specified as `True`, realm is ignored.

`HTTPPasswordMgrWithPriorAuth.``find_user_password`(realm, authuri)

  Same as for `HTTPPasswordMgrWithDefaultRealm` objects

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

  Update the `is_authenticated` flag for the given uri or list of URIs.

`HTTPPasswordMgrWithPriorAuth.``is_authenticated`(self, authuri)

  Returns the current state of the `is_authenticated` flag for the given URI.

## AbstractBasicAuthHandler 对象

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

  Handle an authentication request by getting a user/password pair, and re-trying the request. authreq should be the name of the header where the information about the realm is included in the request, host specifies the URL and path to authenticate for, req should be the (failed) `Request` object, and headers should be the error headers.

  host is either an authority (e.g. `"python.org"`) or a URL containing an authority component (e.g. `"http://python.org/"`). In either case, the authority must not contain a userinfo component (so, `"python.org"` and `"python.org:80"` are fine, `"joe:password@python.org"` is not).

## HTTPBasicAuthHandler 对象

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

  Retry the request with authentication information, if available.

## ProxyBasicAuthHandler 对象

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

  Retry the request with authentication information, if available.

## AbstractDigestAuthHandler 对象

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

  authreq should be the name of the header where the information about the realm is included in the request, host should be the host to authenticate to, req should be the (failed) `Request` object, and headers should be the error headers.

## HTTPDigestAuthHandler 对象

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

  Retry the request with authentication information, if available.

## ProxyDigestAuthHandler 对象

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

  Retry the request with authentication information, if available.

## HTTPHandler 对象

`HTTPHandler.``http_open`(req)

  Send an HTTP request, which can be either GET or POST, depending on `req.has_data()`.

## HTTPSHandler 对象

`HTTPSHandler.``https_open`(req)

  Send an HTTPS request, which can be either GET or POST, depending on `req.has_data()`.

## FileHandler 对象

`FileHandler.``file_open`(req)

  Open the file locally, if there is no host name, or the host name is `'localhost'`.

  在 3.2 版更改: This method is applicable only for local hostnames. When a remote hostname is given, an `URLError` is raised.

## DataHandler 对象

`DataHandler.``data_open`(req)

  Read a data URL. This kind of URL contains the content encoded in the URL itself. The data URL syntax is specified in RFC 2397. This implementation ignores white spaces in base64 encoded data URLs so the URL may be wrapped in whatever source file it comes from. But even though some browsers don't mind about a missing padding at the end of a base64 encoded data URL, this implementation will raise an `ValueError` in that case.

## FTPHandler 对象

`FTPHandler.``ftp_open`(req)

  Open the FTP file indicated by req. The login is always done with empty username and password.

## CacheFTPHandler 对象

`CacheFTPHandler` objects are `FTPHandler` objects with the following additional methods:

`CacheFTPHandler.``setTimeout`(t)

  Set timeout of connections to t seconds.

`CacheFTPHandler.``setMaxConns`(m)

  Set maximum number of cached connections to m.

## UnknownHandler 对象

`UnknownHandler.``unknown_open`()

  Raise a `URLError` exception.

## HTTPErrorProcessor 对象

`HTTPErrorProcessor.``http_response`(request, response)

  处理出错的 HTTP 响应。

  For 200 error codes, the response object is returned immediately.

  For non-200 error codes, this simply passes the job on to the `http_error_<type>()` handler methods, via `OpenerDirector.error()`. Eventually, `HTTPDefaultErrorHandler` will raise an `HTTPError` if no other handler handles the error.

`HTTPErrorProcessor.``https_response`(request, response)

  Process HTTPS error responses.

  The behavior is same as `http_response()`.

## 示例

In addition to the examples below, more examples are given in 如何利用 urllib 包获取网络资源.

This example gets the python.org main page and displays the first 300 bytes of it.

    >>> 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 '

Note that urlopen returns a bytes object. This is because there is no way for urlopen to automatically determine the encoding of the byte stream it receives from the HTTP server. In general, a program will decode the returned bytes object to string once it determines or guesses the appropriate encoding.

The following W3C document, https://www.w3.org/International/O-charset, lists the various ways in which an (X)HTML or an XML document could have specified its encoding information.

As the python.org website uses utf-8 encoding as specified in its meta tag, we will use the same for decoding the bytes object.

    >>> 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

It is also possible to achieve the same result without using the context manager approach.

    >>> 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

In the following example, we are sending a data-stream to the stdin of a CGI and reading the data it returns to us. Note that this example will only work when the Python installation supports 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"

The code for the sample CGI used in the above example is:

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

Here is an example of doing a `PUT` request using `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)

Use of Basic HTTP Authentication:

    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()` provides many handlers by default, including a `ProxyHandler`. By default, `ProxyHandler` uses the environment variables named `<scheme>_proxy`, where `<scheme>` is the URL scheme involved. For example, the `http_proxy` environment variable is read to obtain the HTTP proxy's URL.

This example replaces the default `ProxyHandler` with one that uses programmatically-supplied proxy URLs, and adds proxy authorization support with `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')

Adding HTTP headers:

Use the headers argument to the `Request` constructor, or:

    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` automatically adds a User-Agent header to every `Request`. To change this:

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

Also, remember that a few standard headers (Content-Length, Content-Type and Host) are added when the `Request` is passed to `urlopen()` (or `OpenerDirector.open()`).

Here is an example session that uses the `GET` method to retrieve a URL containing parameters:

    >>> 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'))
    ...

The following example uses the `POST` method instead. Note that params output from urlencode is encoded to bytes before it is sent to urlopen as data:

    >>> 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'))
    ...

The following example uses an explicitly specified HTTP proxy, overriding environment settings:

    >>> 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')
    ...

The following example uses no proxies at all, overriding environment settings:

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

## Legacy interface

The following functions and classes are ported from the Python 2 module `urllib` (as opposed to `urllib2`). They might become deprecated at some point in the future.

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

  Copy a network object denoted by a URL to a local file. If the URL points to a local file, the object will not be copied unless filename is supplied. Return a tuple `(filename, headers)` where filename is the local file name under which the object can be found, and headers is whatever the `info()` method of the object returned by `urlopen()` returned (for a remote object). Exceptions are the same as for `urlopen()`.

  The second argument, if present, specifies the file location to copy to (if absent, the location will be a tempfile with a generated name). The third argument, if present, is a callable that will be called once on establishment of the network connection and once after each block read thereafter. The callable will be passed three arguments; a count of blocks transferred so far, a block size in bytes, and the total size of the file. The third argument may be `-1` on older FTP servers which do not return a file size in response to a retrieval request.

  The following example illustrates the most common usage scenario:

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

  If the url uses the `http:` scheme identifier, the optional data argument may be given to specify a `POST` request (normally the request type is `GET`). The data argument must be a bytes object in standard application/x-www-form-urlencoded format; see the `urllib.parse.urlencode()` function.

  `urlretrieve()` will raise `ContentTooShortError` when it detects that the amount of data available was less than the expected amount (which is the size reported by a Content-Length header). This can occur, for example, when the download is interrupted.

  The Content-Length is treated as a lower bound: if there's more data to read, urlretrieve reads more data, but if less data is available, it raises the exception.

  You can still retrieve the downloaded data in this case, it is stored in the `content` attribute of the exception instance.

  If no Content-Length header was supplied, urlretrieve can not check the size of the data it has downloaded, and just returns it. In this case you just have to assume that the download was successful.

`urllib.request.``urlcleanup`()

  Cleans up temporary files that may have been left behind by previous calls to `urlretrieve()`.

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

  3.3 版后已移除.

  Base class for opening and reading URLs. Unless you need to support opening objects using schemes other than `http:`, `ftp:`, or `file:`, you probably want to use `FancyURLopener`.

  By default, the `URLopener` class sends a User-Agent header of `urllib/VVV`, where VVV is the `urllib` version number. Applications can define their own User-Agent header by subclassing `URLopener` or `FancyURLopener` and setting the class attribute `version` to an appropriate string value in the subclass definition.

  The optional proxies parameter should be a dictionary mapping scheme names to proxy URLs, where an empty dictionary turns proxies off completely. Its default value is `None`, in which case environmental proxy settings will be used if present, as discussed in the definition of `urlopen()`, above.

  Additional keyword parameters, collected in x509, may be used for authentication of the client when using the `https:` scheme. The keywords key_file and cert_file are supported to provide an SSL key and certificate; both are needed to support client authentication.

  `URLopener` objects will raise an `OSError` exception if the server returns an error code.

  `open`(fullurl, data=None)

    Open fullurl using the appropriate protocol. This method sets up cache and proxy information, then calls the appropriate open method with its input arguments. If the scheme is not recognized, `open_unknown()` is called. The data argument has the same meaning as the data argument of `urlopen()`.

    This method always quotes fullurl using `quote()`.

  `open_unknown`(fullurl, data=None)

    Overridable interface to open unknown URL types.

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

    Retrieves the contents of url and places it in filename. The return value is a tuple consisting of a local filename and either an `email.message.Message` object containing the response headers (for remote URLs) or `None` (for local URLs). The caller must then open and read the contents of filename. If filename is not given and the URL refers to a local file, the input filename is returned. If the URL is non-local and filename is not given, the filename is the output of `tempfile.mktemp()` with a suffix that matches the suffix of the last path component of the input URL. If reporthook is given, it must be a function accepting three numeric parameters: A chunk number, the maximum size chunks are read in and the total size of the download (-1 if unknown). It will be called once at the start and after each chunk of data is read from the network. reporthook is ignored for local URLs.

    If the url uses the `http:` scheme identifier, the optional data argument may be given to specify a `POST` request (normally the request type is `GET`). The data argument must in standard application/x-www-form-urlencoded format; see the `urllib.parse.urlencode()` function.

  `version`

    Variable that specifies the user agent of the opener object. To get `urllib` to tell servers that it is a particular user agent, set this in a subclass as a class variable or in the constructor before calling the base constructor.

class `urllib.request.``FancyURLopener`(...)

  3.3 版后已移除.

  `FancyURLopener` subclasses `URLopener` providing default handling for the following HTTP response codes: 301, 302, 303, 307 and 401. For the 30x response codes listed above, the Location header is used to fetch the actual URL. For 401 response codes (authentication required), basic HTTP authentication is performed. For the 30x response codes, recursion is bounded by the value of the maxtries attribute, which defaults to 10.

  For all other response codes, the method `http_error_default()` is called which you can override in subclasses to handle the error appropriately.

  注解

  According to the letter of RFC 2616, 301 and 302 responses to POST requests must not be automatically redirected without confirmation by the user. In reality, browsers do allow automatic redirection of these responses, changing the POST to a GET, and `urllib` reproduces this behaviour.

  The parameters to the constructor are the same as those for `URLopener`.

  注解

  When performing basic authentication, a `FancyURLopener` instance calls its `prompt_user_passwd()` method. The default implementation asks the users for the required information on the controlling terminal. A subclass may override this method to support more appropriate behavior if needed.

  The `FancyURLopener` class offers one additional method that should be overloaded to provide the appropriate behavior:

  `prompt_user_passwd`(host, realm)

    Return information needed to authenticate the user at the given host in the specified security realm. The return value should be a tuple, `(user, password)`, which can be used for basic authentication.

    The implementation prompts for this information on the terminal; an application should override this method to use an appropriate interaction model in the local environment.

## `urllib.request` Restrictions

- Currently, only the following protocols are supported: HTTP (versions 0.9 and 1.0), FTP, local files, and data URLs.

  在 3.4 版更改: Added support for data URLs.

- The caching feature of `urlretrieve()` has been disabled until someone finds the time to hack proper processing of Expiration time headers.

- There should be a function to query whether a particular URL is in the cache.

- For backward compatibility, if a URL appears to point to a local file but the file can't be opened, the URL is re-interpreted using the FTP protocol. This can sometimes cause confusing error messages.

- The `urlopen()` and `urlretrieve()` functions can cause arbitrarily long delays while waiting for a network connection to be set up. This means that it is difficult to build an interactive Web client using these functions without using threads.

- The data returned by `urlopen()` or `urlretrieve()` is the raw data returned by the server. This may be binary data (such as an image), plain text or (for example) HTML. The HTTP protocol provides type information in the reply header, which can be inspected by looking at the Content-Type header. If the returned data is HTML, you can use the module `html.parser` to parse it.

- The code handling the FTP protocol cannot differentiate between a file and a directory. This can lead to unexpected behavior when attempting to read a URL that points to a file that is not accessible. If the URL ends in a `/`, it is assumed to refer to a directory and will be handled accordingly. But if an attempt to read a file leads to a 550 error (meaning the URL cannot be found or is not accessible, often for permission reasons), then the path is treated as a directory in order to handle the case when a directory is specified by a URL but the trailing `/` has been left off. This can cause misleading results when you try to fetch a file whose read permissions make it inaccessible; the FTP code will try to read it, fail with a 550 error, and then perform a directory listing for the unreadable file. If fine-grained control is needed, consider using the `ftplib` module, subclassing `FancyURLopener`, or changing _urlopener to meet your needs.

# `urllib.response` --- urllib 使用的 Response 类

The `urllib.response` module defines functions and classes which define a minimal file-like interface, including `read()` and `readline()`. Functions defined by this module are used internally by the `urllib.request` module. The typical response object is a `urllib.response.addinfourl` instance:

class `urllib.response.``addinfourl`
  `url`

    URL of the resource retrieved, commonly used to determine if a redirect was followed.

  `headers`

    Returns the headers of the response in the form of an `EmailMessage` instance.

  `status`

    3.9 新版功能.

    由服务器返回的状态码。

  `geturl`()

    3.9 版后已移除: Deprecated in favor of `url`.

  `info`()

    3.9 版后已移除: Deprecated in favor of `headers`.

  `code`

    3.9 版后已移除: Deprecated in favor of `status`.

  `getstatus`()

    3.9 版后已移除: Deprecated in favor of `status`.