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

**源码：** Lib/urllib/request.py

======================================================================

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

也參考:

  The Requests package is recommended for a higher-level HTTP client
  interface.

"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* 将被忽略。

   This function always returns an object which can work as a *context
   manager* and has methods such as

   * "geturl()" --- return the URL of the resource retrieved, commonly
     used to determine if a redirect was followed

   * "info()" --- return the meta-information of the page, such as
     headers, in the form of an "email.message_from_string()" instance
     (see Quick Reference to HTTP Headers)

   * "getcode()" -- return the HTTP status code of the response.

   对于 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" 对象获取到代理处理函数。

   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 安装有 SLL 支持（指可以导入 "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* 应该是是一个含有一个有效的统一资源定位地址的字符串。

   *data* must be an object specifying additional data to send to the
   server, or "None" if no such data is needed.  Currently HTTP
   requests are the only ones that use *data*.  The supported object
   types include bytes, file-like objects, and iterables.  If no
   "Content-Length" nor "Transfer-Encoding" header field has been
   provided, "HTTPHandler" will set these headers according to the
   type of *data*.  "Content-Length" will be used to send bytes
   objects, while "Transfer-Encoding: chunked" as specified in **RFC
   7230**, Section 3.3.1 will be used to send files and other
   iterables.

   对于 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" 的默认用户代理字符串则是 ""Python-
   urllib/2.6"" (在 Python 2.6 上)。

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

   The final two arguments are only of interest for correct handling
   of third-party HTTP cookies:

   *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 统一资源定位地址。

class urllib.request.CacheFTPHandler

   打开 FTP URL，并将打开的 FTP 连接存入缓存，以便最大程度减少延迟。

class urllib.request.UnknownHandler

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

class urllib.request.HTTPErrorProcessor

   处理出错的 HTTP 响应。


21.6.1. Request 对象
====================

以下方法介绍了 "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" 的子类中给出默认值，也可以通过 *method* 参
   数给 "Request" 构造函数传入一个值。

   3.3 版新加入.

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

Request.get_method()

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

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

Request.add_header(key, val)

   向请求添加一项头部信息。目前只有 HTTP handler 才会处理头部信息，将
   其加入发给服务器的头部信息列表中。请注意，同名的头部信息只能出现一
   次，如果 *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* 将会取代本实例
   中的对应值，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 。


21.6.2. OpenerDirector 对象
===========================

"OpenerDirector" 实例有以下方法：

OpenerDirector.add_handler(handler)

   *handler* should be an instance of "BaseHandler".  The following
   methods are searched, and added to the possible chains (note that
   HTTP errors are a special case).

   * "protocol_open()" --- signal that the handler knows how to open
     *protocol* URLs.

   * "http_error_type()" --- signal that the handler knows how to
     handle HTTP errors with HTTP error code *type*.

   * "protocol_error()" --- signal that the handler knows how to
     handle errors from (non-"http") *protocol*.

   * "protocol_request()" --- signal that the handler knows how to
     pre-process *protocol* requests.

   * "protocol_response()" --- signal that the handler knows how to
     post-process *protocol* responses.

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

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

OpenerDirector.error(proto, *args)

   Handle an error of the given protocol.  This will call the
   registered error handlers for the given protocol with the given
   arguments (which are protocol specific).  The HTTP protocol is a
   special case which uses the HTTP response code to determine the
   specific error handler; refer to the "http_error_*()" methods of
   the handler classes.

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

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

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

1. Every handler with a method named like "protocol_request()" has
   that method called to pre-process the request.

2. Handlers with a method named like "protocol_open()" are called to
   handle the request. This stage ends when a handler either returns a
   non-"None" value (ie. a response), or raises an exception (usually
   "URLError").  Exceptions are allowed to propagate.

   In fact, the above algorithm is first tried for methods named
   "default_open()".  If all such methods return "None", the algorithm
   is repeated for methods named like "protocol_open()".  If all such
   methods return "None", the algorithm is repeated for methods named
   "unknown_open()".

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

3. Every handler with a method named like "protocol_response()" has
   that method called to post-process the response.


21.6.3. BaseHandler 对象
========================

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

BaseHandler.add_parent(director)

   将 director 加为父 handler。

BaseHandler.close()

   移除所有父 OpenerDirector。

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

備註:

  The convention has been adopted that subclasses defining
  "protocol_request()" or "protocol_response()" methods are named
  "*Processor"; all others are named "*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()" 返回值相同的接口。


21.6.4. HTTPRedirectHandler 对象
================================

備註:

  某些 HTTP 重定向操作需要用到本模块的客户端代码。这时会触发
  "HTTPError"。有关各种重定向代码的确切含义，请参阅 **RFC 2616** 。如
  果 HTTPRedirectHandler 呈现的重定向 URL 不是 HTTP、HTTPS 或 FTP URL
  ，则出于安全考虑将触发 "HTTPError" 异常。

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

   返回 "Request" 或 "None" 对象作为重定向行为的响应。当服务器接收到重
   定向请求时， "http_error_30*()" 方法的默认实现代码将会调用本方法。
   如果确实应该发生重定向，则返回一个新的 "Request" 对象，使得
   "http_error_30*()" 能重定向至 *newurl*。否则，若没有 handler 会处理
   此 URL，则会引发 "HTTPError"；或者本方法不能处理但或许会有其他
   handler 会处理，则返回 "None" 。

   備註:

     本方法的默认实现代码并未严格遵循 **RFC 2616**，即 "POST" 请求的
     301 和 302 响应不得在未经用户确认的情况下自动进行重定向。现实情况
     下，浏览器确实允许自动重定向这些响应，将 POST 更改为 "GET" ，于是
     默认实现代码就复现了这种处理方式。

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

   重定向到 "Location:" 或 "URI:" URL。 这个方法会在得到 HTTP 'moved
   permanently' 响应时由上级 "OpenerDirector" 来调用。

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

   与  "http_error_301()" 相同，不过是发生“found”响应时的调用。

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

   与  "http_error_301()" 相同，不过是发生“see other”响应时的调用。

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

   与  "http_error_301()" 相同，不过是发生“temporary redirect”响应时的
   调用。


21.6.5. HTTPCookieProcessor 对象
================================

"HTTPCookieProcessor" 的实例具备一个属性：

HTTPCookieProcessor.cookiejar

   cookie 存放在 "http.cookiejar.CookieJar" 中。


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


21.6.7. HTTPPasswordMgr 对象
============================

以下方法 "HTTPPasswordMgr" 和 "HTTPPasswordMgrWithDefaultRealm" 对象均
有提供。

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

   *uri* 可以是单个 URI，也可以是 URI 列表。*realm*、*user* 和
   *passwd* 必须是字符串。这使得在为 *realm* 和超级 URI 进行身份认证时
   ，"(user, passwd)" 可用作认证令牌。

HTTPPasswordMgr.find_user_password(realm, authuri)

   为给定 realm 和 URI 获取用户名和密码。如果没有匹配的用户名和密码，
   本方法将会返回 "(None, None)" 。

   对于 "HTTPPasswordMgrWithDefaultRealm" 对象，如果给定 *realm* 没有
   匹配的用户名和密码，将搜索 realm  "None"。


21.6.8. HTTPPasswordMgrWithPriorAuth 对象
=========================================

这是 "HTTPPasswordMgrWithDefaultRealm" 的扩展，以便对那些需要一直发送
认证凭证的 URI 进行跟踪。

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

   *realm*、*uri*、*user*、*passwd* 的含义与
   "HTTPPasswordMgr.add_password()" 的相同。*is_authenticated* 为给定
   URI 或 URI 列表设置 "is_authenticated" 标志的初始值。如果
   *is_authenticated* 设为 "True" ，则会忽略 *realm*。

HTTPPasswordMgr.find_user_password(realm, authuri)

   与 "HTTPPasswordMgrWithDefaultRealm" 对象的相同。

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

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

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)

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


21.6.9. AbstractBasicAuthHandler 对象
=====================================

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

   通过获取用户名和密码并重新尝试请求，以处理身份认证请求。 *authreq*
   应该是请求中包含 realm 的头部信息名称，*host* 指定了需要进行身份认
   证的 URL 和路径，*req* 应为 (已失败的) "Request" 对象 ,  *headers*
   应该是出错的头部信息。

   *host* 要么是一个认证信息（例如 ""python.org"" ），要么是一个包含认
   证信息的 URL（如``"http://python.org/"`` ）。 不论是哪种格式，认证
   信息中都不能包含用户信息（因此，""python.org"" 和 ""python.org:80""
   没问题，而 ""joe:password@python.org"" 则不行）。


21.6.10. HTTPBasicAuthHandler 对象
==================================

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

   如果可用的话，请用身份认证信息重试请求。


21.6.11. ProxyBasicAuthHandler 对象
===================================

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

   如果可用的话，请用身份认证信息重试请求。


21.6.12. AbstractDigestAuthHandler 对象
=======================================

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

   *authreq* 应为请求中有关 realm 的头部信息名称，*host* 应为需要进行
   身份认证的主机，*req* 应为（已失败的） "Request" 对象， *headers*
   则应为出错的头部信息。


21.6.13. HTTPDigestAuthHandler 对象
===================================

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

   如果可用的话，请用身份认证信息重试请求。


21.6.14. ProxyDigestAuthHandler 对象
====================================

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

   如果可用的话，请用身份认证信息重试请求。


21.6.15. HTTPHandler 对象
=========================

HTTPHandler.http_open(req)

   发送 HTTP 请求，根据 "req.has_data()" 的结果，可能是 GET 或 POST 格
   式。


21.6.16. HTTPSHandler 对象
==========================

HTTPSHandler.https_open(req)

   发送 HTTPS 请求，根据 "req.has_data()" 的结果，可能是 GET 或 POST
   格式。


21.6.17. FileHandler 对象
=========================

FileHandler.file_open(req)

   若无主机名或主机名为 "'localhost'" ，则打开本地文件。

   3.2 版更變: 本方法仅适用于本地主机名。如果给出的是远程主机名，将会
   触发 "URLError" 。


21.6.18. DataHandler 对象
=========================

DataHandler.data_open(req)

   读取内含数据的 URL。这种 URL 本身包含了经过编码的数据。 **RFC
   2397** 中给出了数据 URL 的语法定义。目前的代码库将忽略经过 base64
   编码的数据 URL 中的空白符，因此 URL 可以放入任何源码文件中。如果数
   据 URL 的 base64 编码尾部缺少填充，即使某些浏览器不介意，但目前的代
   码库仍会引发 "ValueError"。


21.6.19. FTPHandler 对象
========================

FTPHandler.ftp_open(req)

   打开由 *req* 给出的 FTP 文件。登录时的用户名和密码总是为空。


21.6.20. CacheFTPHandler 对象
=============================

"CacheFTPHandler" 对象即为加入以下方法的 "FTPHandler" 对象：

CacheFTPHandler.setTimeout(t)

   设置连接超时为 *t* 秒。

CacheFTPHandler.setMaxConns(m)

   设置已缓存的最大连接数为 *m* 。


21.6.21. UnknownHandler 对象
============================

UnknownHandler.unknown_open()

   触发 "URLError" 异常。


21.6.22. HTTPErrorProcessor 对象
================================

HTTPErrorProcessor.http_response(request, response)

   处理出错的 HTTP 响应。

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

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

HTTPErrorProcessor.https_response(request, response)

   HTTPS 出错响应的处理。

   与 "http_response()" 方法相同。


21.6.23. 例子
=============

如何使用urllib套件取得網路資源 中给出了更多的示例。

以下示例将读取 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 将返回字节对象。这是因为 urlopen 无法自动确定由 HTTP
服务器收到的字节流的编码。通常，只要能确定或猜出编码格式，就应将返回的
字节对象解码为字符串。

下述 W3C 文档 https://www.w3.org/International/O-charset列出了可用于指
明（X）HTML 或 XML 文档编码信息的多种方案。

python.org 网站已在 meta 标签中指明，采用的是 *utf-8* 编码，因此这里将
用同样的格式对字节串进行解码。

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

下面是利用 "Request" 发送``PUT`` 请求的示例：

   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()" 默认提供了很多现成的 handler，包括 "ProxyHandler"。
默认情况下，"ProxyHandler" 会使用名为 "<scheme>_proxy" 的环境变量，其
中的 "<scheme>" 是相关的 URL 协议。 例如，可以读取 "http_proxy" 环境变
量来获取 HTTP 代理的 URL。

以下示例将默认的 "ProxyHandler" 替换为自己的 handler，由程序提供代理
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 头部信息：

可利用 "Request" 构造函数的 *headers* 参数，或者是：

   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" 自动会在每个 "Request" 中加入一项 *User-Agent* 头部信
息。若要修改，请参见以下语句：

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

另请记得，当 "Request" 传给  "urlopen()"  （或 "OpenerDirector.open()"
）时，会加入一些标准的头部信息（ *Content-Length* 、 *Content-Type* 和
*Host*）。

以下会话示例用 "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 输出结果先被编码为字节串
data，再送入 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')
   ...


21.6.24. 已停用的接口
=====================

以下函数和类是由 Python 2 模块 "urllib``（相对早于 ``urllib2" ）移植过
来的。将来某个时候可能会停用。

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

   将 URL 形式的网络对象复制为本地文件。如果 URL 指向本地文件，则必须
   提供文件名才会执行复制。返回值为元组 "(filename, headers)" ，其中
   *filename* 是保存网络对象的本地文件名， *headers* 是由 "urlopen()"
   返回的远程对象 "info()" 方法的调用结果。可能触发的异常与
   "urlopen()" 相同。

   第二个参数指定文件的保存位置（若未给出，则会是名称随机生成的临时文
   件）。第三个参数是个可调用对象，在建立网络连接时将会调用一次，之后
   每次读完数据块后会调用一次。该可调用对象将会传入 3 个参数：已传输的
   块数、块的大小（以字节为单位）和文件总的大小。如果面对的是老旧 FTP
   服务器，文件大小参数可能会是 "-1" ，这些服务器响应读取请求时不会返
   回文件大小。

   以下例子演示了大部分常用场景：

      >>> 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()".

   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.


21.6.25. "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.


21.7. "urllib.response" --- urllib 使用的 Response 类
*****************************************************

The "urllib.response" module defines functions and classes which
define a minimal file like interface, including "read()" and
"readline()". The typical response object is an addinfourl instance,
which defines an "info()" method and that returns headers and a
"geturl()" method that returns the url. Functions defined by this
module are used internally by the "urllib.request" module.
