21.6. `urllib.request` —— 用于打开URL的可扩展库¶

urllib.request 模块定义了在基本和摘要式身份验证、重定向、 cookies等应用中打开 Url (主要是 HTTP) 的函数和类。

也可以看看

Requests 包建议用作高级的非底层的 HTTP 客户端接口。

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

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

打开url参数传进来的网址，既可以是一个字符串，又可以是一个Request对象。

当你有额外的数据要发送到服务器，那data参数必须是一个有数据的bytes对象，否则为None。其实data 也可以是一个可迭代的对象，若是，则headers中必须带 Content-Length 参数。若本次HTTP请求要用POST方法，data必须有数据；若为GET方法时， data写None就行。

data参数应该是一个标准的application/x-www-form-urlencoded 格式的缓冲区.urllib.parse.urlencode() 函数接受一个映射或者一个内含一个两元素元组的序列，并且返回一个该格式的ASCII字符串。data参数在使用之前应该被编码成bytes。

urllib.request 模块参照 HTTP/1.1 标准，并且在HTTP请求中，头信息可以有Connection:close。

timeout 参数是可选的。它指定一个超时时间。若超过该时间，任何操作都会被阻止，如链接超时（如果没有指定，则会默认值为socket._GLOBAL_DEFAULT_TIMEOUT）。其实这个参数仅仅对http、https和ftp连接有效。

如果指定了 context 参数，则它必须是一个描述了各种SSL选项的 ssl.SSLContext 实例。更详细内容，请点击 HTTPSConnection 。

cafile 和 capath 参数都是可选的。他们应该被指定一组“HTTPS请求”所需要的受信任的CA 证书。cafile 参数应该指向文件，该文件包含了一大堆CA证书，而capath 参数应该指向一个目录，该目录包含了散列过的证书。更多的信息，可以从 ssl.SSLContext.load_verify_locations() 里找到。

cadefault 参数不能用了，所以不用管它了，吼吼~~

这个urlopen函数总是返回一个对象，这个对象能被context manager（上下文管理器）中的一些方法使用，如：

geturl() — 返回一个资源索引的URL，通常重定向后的URL照样能get到。
info() — 返回页面的元信息，如头信息。像 email.message_from_string() 实例的格式一样。（请看 Quick Reference to HTTP Headers）
getcode() – 返回响应后，HTTP的状态码。

对于HTTP和HTTPS网址，此函数会返回稍微修改的http.client.HTTPResponse对象。除了上述的三种新方法外，还有一个叫msg的属性，包含着和reason属性一样的信息 — 原因短语从服务器上返回 — 代替了HTTPResponse文档里指定的那些响应头。

对于 FTP，文件，和数据的URL，都显式地由以前的 URLopener 和 FancyURLopener 类处理，处理它们的函数，返回一个 urllib.response.addinfourl 对象。

如果协议错误，则引发URLError。

注意：如果没有服务器来处理这个请求，那么可能会返回None 值。(尽管有默认被安装的全局 OpenerDirector 使用 UnknownHandler 来确保这种情况不发生)。

另外，当代理被检测到，(例如，当一个像http_proxy的*_proxy 环境变量被设置), ProxyHandler 会被默认安装以确保请求会通过代理来处理。

在python2.6或者更早版本中遗留的 urllib.urlopen函数已经被停用； urllib.request.urlopen() 函数和旧版本python中的urllib2.urlopen函数其实是相同的。通过向urllib.urlopen传递一个字典参数得到的Proxy handing，能够通过使用ProxyHandler 对象来获取。

在3.2版本中的更改：cafile 和capath 被增加。

在版本3.2中已更改：现在支持HTTPS虚拟主机（如果可能（即，如果ssl.HAS_SNI为true）。

3.2版本中新增功能：data参数可以是一个iterable对象。

在3.3版本中的更改：cadefault 被增加。

在3.4.3版本中的更改：context 被增加。

urllib.request.install_opener(opener)¶: 安装OpenerDirector实例作为默认全局启动器。安装启动器只有当你想要urlopen使用启动器；否则，只需调用OpenerDirector.open()而不是urlopen()。代码不检查真实的OpenerDirector，任何具有适当接口的类都可以工作。

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

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

如果 Python 安装了 SSL 支持（即，如果 ssl 模块可以导入），还将添加 HTTPSHandler。

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

urllib.request.pathname2url(path)¶: 将路径名path从本地语法转换为URL的路径组件中使用的形式。这不会产生一个完整的URL。返回值已使用quote()函数引用。

urllib.request.url2pathname(path)¶: 将路径组件路径从百分比编码的URL转换为路径的本地语法。这不接受完整的URL。该函数使用unquote()来解码路径。

urllib.request.getproxies()¶: 这个帮助函数返回一个方案到代理服务器URL映射的字典。它以大小写不敏感的方式为所有操作系统首先扫描名为<scheme>_proxy的变量的环境，并且当它找不到它时，查找Mac OSX System Configuration for Mac中的代理信息适用于Windows的OS X和Windows系统注册表。如果小写和大写环境变量都存在（并且不同意），则小写是首选。

Note

If the environment variable REQUEST_METHOD is set, which usually indicates your script is running in a CGI environment, the environment variable HTTP_PROXY (uppercase _PROXY) will be ignored. This is because that variable can be injected by a client using the “Proxy:” HTTP header. If you need to use an HTTP proxy in a CGI environment, either use ProxyHandler explicitly, or make sure the variable name is in lowercase (or at least the _proxy suffix).

提供以下类：

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

这个类是一个URL请求的抽象。

url应为包含有效网址的字符串。

data必须是指定要发送到服务器的附加数据的字节对象，如果不需要此类数据，则None。目前只有POST请求将data作为参数，GET请求不能使用data作为参数进行HTTP请求。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头与数据参数的示例将发送像{“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文档中的图像，并且用户无权批准自动获取图像，则应该是正确的。

method应为指示将使用的HTTP请求方法的字符串（例如，'HEAD'如果提供，它的值存储在method属性中，并由get_method()使用。子类可以通过在类本身中设置method属性来指示默认方法。

在版本3.3中改变： Request.method参数被添加到Request类中。

Changed in version 3.4: Default Request.method may be indicated at the class level.

class urllib.request.OpenerDirector¶: OpenerDirector类通过BaseHandler链接在一起打开网址。它管理处理程序的链接，并从错误中恢复。

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

导致请求通过代理。如果给出了代理，它必须是一个字典映射到代理的URL的协议名称。缺省值是从环境变量 <protocol>_proxy中读取代理列表。如果未设置代理环境变量，则在Windows环境中，代理设置可从注册表的“Internet设置”部分获得，而在Mac OS X环境中，将从OS X系统配置框架中检索代理信息。

禁用自动检测代理传递空字典。

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

Note

HTTP_PROXY will be ignored if a variable REQUEST_METHOD is set; see the documentation on getproxies().

class urllib.request.HTTPPasswordMgr¶: 保持（realm， uri） - >＆lt； / t3> （用户，密码）映射。

class urllib.request.HTTPPasswordMgrWithDefaultRealm¶: 保持（realm， uri） - >＆lt； / t3> （用户，密码）映射。一个None的领域被认为是一个通用领域，如果没有其他领域适合，就会搜索它。

class urllib.request.HTTPPasswordMgrWithPriorAuth¶: 一个HTTPPasswordMgrWithDefaultRealm的变体，它也有一个uri - >＆gt； is_authenticated映射。BasicAuth处理程序可以使用它来确定何时立即发送认证凭证，而不是先等待401响应。
版本3.5中的新功能。

class urllib.request.AbstractBasicAuthHandler(password_mgr=None)¶: 这是一个mixin类，可以帮助远程主机和代理的HTTP身份验证。password_mgr（如果给定）应该是与HTTPPasswordMgr兼容的内容；有关必须支持的接口的信息，请参阅HTTPPasswordMgr对象一节。如果passwd_mgr还提供is_authenticated和update_authenticated方法（请参阅HTTPPasswordMgrWithPriorAuth Objects），则处理程序将使用is_authenticated结果以确定是否发送认证凭证与请求。如果is_authenticated为URI返回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)¶: 这是一个mixin类，可以帮助远程主机和代理的HTTP身份验证。password_mgr（如果给定）应该是与HTTPPasswordMgr兼容的内容；有关必须支持的接口的信息，请参阅HTTPPasswordMgr对象一节。

class urllib.request.HTTPDigestAuthHandler(password_mgr=None)¶: 处理与远程主机的身份验证。password_mgr（如果给定）应该是与HTTPPasswordMgr兼容的内容；有关必须支持的接口的信息，请参阅HTTPPasswordMgr对象一节。当同时添加摘要式身份验证处理程序和基本身份验证处理程序时，首先会尝试摘要式身份验证。如果摘要认证再次返回40x响应，则将其发送到基本认证处理程序以处理。当使用Digest或Basic以外的身份验证方案时，此Handler方法将引发ValueError。
Changed in version 3.3: Raise ValueError on unsupported Authentication Scheme.

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中的含义相同。
Changed in version 3.2: context and check_hostname were added.

class urllib.request.FileHandler¶: 打开本地文件。

class urllib.request.DataHandler¶: 打开数据网址。
版本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错误响应。

21.6.1. 请求对象¶

以下方法描述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构造函数。
版本3.3中的新功能。
Changed in version 3.4: A default value can now be set in subclasses; previously it could only be set via the constructor argument.

Request.get_method()¶: 返回一个指示HTTP请求方法的字符串。如果Request.method不是None，则返回其值，否则返回'GET'，如果Request.data为None或'POST'（如果不是）。这只对HTTP请求有意义。
在版本3.3中更改： get_method现在查看Request.method的值。

Request.add_header(key, val)¶: 向请求中添加另一个标头。除了HTTP处理程序之外，所有处理程序当前都会忽略标头，并将其添加到发送到服务器的标头列表中。注意，不能有多个具有相同名称的标题，并且在键发生冲突的情况下，稍后的调用将覆盖以前的调用。目前，这不是HTTP功能的丢失，因为当使用多次时具有含义的所有head具有（head特定的）仅使用一个报头获得相同功能的方式。

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和类型将替换实例的实例，实例的选择器将是构造函数中给出的原始URL。

Request.get_header(header_name, default=None)¶: 返回给定头的值。如果头不存在，返回默认值。

Request.header_items()¶: 返回请求标头的元组列表（header_name，header_value）。

版本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 instances have the following methods:

OpenerDirector.add_handler(handler)¶

handler应该是BaseHandler的一个实例。搜索以下方法，并将其添加到可能的链中（请注意，HTTP错误是一种特殊情况）。

protocol_open() - 表示处理程序知道如何打开协议 URL。
http_error_type() - 表示处理程序知道如何使用HTTP错误代码键入来处理HTTP错误。
protocol_error() - 表示处理程序知道如何处理来自（非http）协议的错误。
protocol_request() - 表示处理程序知道如何预处理协议请求。
protocol_response() - 表示处理程序知道如何后处理协议响应。

OpenerDirector.open(url, data=None[, timeout])¶: 打开给定的url（可以是请求对象或字符串），可选地传递给定的数据。Arguments, return values and exceptions raised are the same as those of urlopen() (which simply calls the open() method on the currently installed global OpenerDirector). 可选的timeout参数指定阻塞操作（如连接尝试）的超时（以秒为单位）（如果未指定，将使用全局默认超时设置）。超时功能实际上仅适用于HTTP，HTTPS和FTP连接）。

OpenerDirector.error(proto, *args)¶

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

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

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

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

每个使用名为protocol_request()的方法的处理程序都会调用该方法来预处理请求。
调用带有名为protocol_open()的方法处理请求。当处理程序返回非None值（例如一个响应），或引发一个异常（通常是URLError）时，这个阶段结束。允许异常传播。
实际上，首先对名为default_open()的方法尝试了上述算法。如果所有这些方法都返回None，则对于名为protocol_open()的方法重复该算法。如果所有这些方法都返回None，则对于名为unknown_open()的方法重复该算法。
请注意，这些方法的实现可能涉及父对象OpenerDirector实例的open()和error()方法的调用。
每个使用名为protocol_response()的方法的处理程序都会调用该方法来后处理响应。

21.6.3. BaseHandler对象¶

BaseHandler objects provide a couple of methods that are directly useful, and others that are meant to be used by derived classes. 这些用于直接使用：

BaseHandler.add_parent(director)¶: 添加导演作为父项。

BaseHandler.close()¶: 删除任何父母。

以下属性和方法只能由派生自BaseHandler的类使用。

注意

该惯例已被采用，定义protocol_request()或protocol_response()方法的子类被命名为*Processor所有其他人都被命名为*Handler。

BaseHandler.parent¶: 一个有效的OpenerDirector，可用于使用其他协议打开或处理错误。

BaseHandler.default_open(req)¶

这个方法不是在BaseHandler中定义的，但是如果要捕获所有URL，子类应该定义它。

此方法（如果已实施）将由父OpenerDirector调用。它应该返回一个文件类对象，如OpenerDirector或None的open()的返回值所述。它应该引发URLError，除非发生真正的例外情况（例如，MemoryError不应映射到URLError）。

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

BaseHandler.protocol_open(req)

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

此方法（如果已定义）将由父OpenerDirector调用。返回值应该与default_open()相同。

BaseHandler.unknown_open(req)¶

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

This method, if implemented, will be called by the parent OpenerDirector. 返回值应该与default_open()相同。

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

这个方法在BaseHandler中定义not，但是如果它们打算提供一个catch-all来处理未处理的HTTP错误，则子类应该覆盖它。它会由OpenerDirector自动调用以获取错误，通常不应在其他情况下调用。

req will be a Request object, fp will be a file-like object with the HTTP error body, code will be the three-digit code of the error, msg will be the user-visible explanation of the code and hdrs will be a mapping object with the headers of the error.

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

BaseHandler.http_error_nnn(req, fp, code, msg, hdrs)¶

nnn应该是一个三位数的HTTP错误代码。这个方法在BaseHandler中也没有定义，但是如果存在的话，在一个子类的实例中，当发生带有代码nnn的HTTP错误时，它将被调用。

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

所引发的参数，返回值和异常应该与http_error_default()相同。

BaseHandler.protocol_request(req)

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

此方法（如果已定义）将由父OpenerDirector调用。req将是一个Request对象。返回值应该是一个Request对象。

BaseHandler.protocol_response(req, response)

这个方法在BaseHandler中定义not，但是如果子类想要后处理给定协议的响应，应该定义它。

此方法（如果已定义）将由父OpenerDirector调用。req将是一个Request对象。响应将是一个实现与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。否则，如果没有其他处理程序尝试处理此URL，则引发HTTPError；如果不能，则返回None。
注意
此方法的默认实现不严格遵循 RFC 2616，其中说明对POST请求的301和302响应不得自动重定向用户确认。实际上，浏览器确实允许自动重定向这些响应，将POST更改为GET，并且默认实现将重现此行为。

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)¶: 重定向到Location:或URI:网址。当获得HTTP'永久移动'响应时，此方法由父OpenerDirector调用。

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()相同，但要求“临时重定向”响应。

21.6.5. HTTPCookieProcessor对象¶

HTTPCookieProcessor实例有一个属性：

HTTPCookieProcessor。 T0> cookiejar T1> ¶ T2>: 存储cookie的http.cookiejar.CookieJar。

21.6.6. ProxyHandler对象¶

ProxyHandler.protocol_open(request): 对于每个协议，ProxyHandler都有一个方法protocol_open()，它在代理构造函数。该方法将通过调用request.set_proxy()修改通过代理的请求，并调用链中的下一个处理程序以实际执行协议。

21.6.7. HTTPPasswordMgr对象¶

这些方法在HTTPPasswordMgr和HTTPPasswordMgrWithDefaultRealm对象上可用。

HTTPPasswordMgr.add_password(realm, uri, user, passwd)¶: uri can be either a single URI, or a sequence of URIs. realm，user和passwd必须是字符串。这导致realm和超级URI认证时（user， passwd）用作认证令牌给出了任何给定的URI。

HTTPPasswordMgr.find_user_password(realm, authuri)¶

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

对于HTTPPasswordMgrWithDefaultRealm对象，如果给定的领域没有匹配的用户/密码，则搜索领域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应该是请求中包含领域信息的标题名称，host指定要验证的URL和路径，req t2>应该是（失败的）Request对象，并且标头应该是错误标头。

host是权威（例如，"python.org"）或包含授权组件的URL（例如，"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).

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应该是请求中包含领域信息的标头名称，host应该是要验证的主机，req t2 >应该是（失败的）Request对象，并且标题应该是错误标题。

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)¶: 根据req.has_data()发送HTTP请求，该请求可以是GET或POST。

21.6.16. HTTPSHandler对象¶

HTTPSHandler.https_open(req)¶: 根据req.has_data()发送HTTPS请求，该请求可以是GET或POST。

21.6.17. FileHandler对象¶

FileHandler.file_open(req)¶: 如果没有主机名，或者主机名是'localhost'，则在本地打开文件。
在版本3.2中更改：此方法仅适用于本地主机名。当给出远程主机名时，引发URLError。

21.6.18. DataHandler对象¶

DataHandler.data_open(req)¶: 阅读数据网址。这种URL包含URL本身编码的内容。数据URL语法在 RFC 2397中指定。这个实现忽略了base64编码数据URL中的空白，所以URL可以被包装在任何源文件中。但即使有些浏览器不介意在base64编码数据URL末尾丢失填充，此实现将在此情况下引发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()¶

处理HTTP错误响应。

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

对于非200错误代码，这只需通过OpenerDirector.error()将作业传递给protocol_error_code()处理程序方法。最终，如果没有其他处理程序处理该错误，那么HTTPDefaultErrorHandler将引发一个HTTPError。

HTTPErrorProcessor.https_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 网站使用 utf-8 编码作为其的 meta 标记中指定，我们将使用相同的解码的字节的对象。

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

它也是可能而无需使用上下文管理器方法实现相同的结果。

>>> 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的标准，并读取返回给我们的数据。请注意，此示例将只当 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请求的示例：

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。

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

添加HTTP标头：

使用请求构造函数的头参数，或：

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. 更改如下：

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

以下是使用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的params输出在作为数据发送到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()相同。

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

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

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

如果url使用http:方案标识符，则可以给出可选的data参数来指定一个POST请求（通常请求类型是GET）。data参数必须是标准application / x-www-form-urlencoded格式中的字节对象；请参阅urllib.parse.urlencode()函数。

urlretrieve() 将会触发ContentTooShortError 当它检测到可用的数据量小于预期量时(就是Content-Length header 返回的数据大小). 例如，当下载被中断时，会发生这种情况。

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.

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

如果未提供Content-Length标头，则urlretrieve无法检查其下载的数据大小，只是将其返回。在这种情况下，您只需假定下载成功。

urllib.request.urlcleanup()¶: 清除先前对urlretrieve()调用可能遗留的临时文件。

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

自版本3.3起已弃用。

打开和阅读URL的基类。除非需要使用http:，ftp:或file:以外的方案来支持打开对象，否则可能需要使用FancyURLopener

By default, the URLopener class sends a User-Agent header of urllib/VVV, where VVV is the urllib version number. 应用程序可以通过继承URLopener或FancyURLopener并将类属性version设置为一个User-Agent子类定义中适当的字符串值。

可选的代理参数应该是字典映射方案名称到代理URL，其中空字典完全关闭代理。它的缺省值是None，在这种情况下，如果存在环境代理设置，将使用上面的urlopen()定义中讨论的内容。

在x509中收集的其他关键字参数可用于在使用https:方案时对客户端进行身份验证。支持关键字key_file和cert_file以提供SSL密钥和证书；两者都需要支持客户端身份验证。

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子类URLopener为以下HTTP响应代码提供了默认处理：301,302,303,307和401。对于上面列出的30x响应代码，Location标头用于获取实际的URL。对于401响应代码（需要认证），执行基本的HTTP认证。对于30x响应代码，递归受到maxtries属性值的限制，默认值为10。

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

注意

根据 RFC 2616的字母，301和302对POST请求的响应不得在未经用户确认的情况下自动重定向。实际上，浏览器确实允许自动重定向这些响应，将POST更改为GET，并且urllib重现了这种行为。

构造函数的参数与URLopener的参数相同。

注意

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

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

prompt_user_passwd(host, realm)¶

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

实施提示在终端上提供这些信息；应用程序应该重写此方法以在本地环境中使用适当的交互模型。

21.6.25. `urllib.request` Restrictions¶

目前，仅支持以下协议：HTTP（版本0.9和1.0），FTP，本地文件和数据URL。
版本3.4已更改：增加了对数据网址的支持。
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以满足您的需求。

21.7. `urllib.response` - urllib使用的响应类¶

urllib.response 模块定义了方法和类，这些类和方法定义了一个最小的文件接口，其中包括 read() and readline()方法. 典型的响应对象是addinfourl实例，它定义了一个info()方法，并返回标头和一个返回url的geturl()方法。由该模块定义的函数由urllib.request模块内部使用。

21.6. `urllib.request` —— 用于打开URL的可扩展库¶

21.6.1. 请求对象¶

21.6.2. OpenerDirector对象¶

21.6.3. BaseHandler对象¶

21.6.4. HTTPRedirectHandler对象¶

21.6.5. HTTPCookieProcessor对象¶

21.6.6. ProxyHandler对象¶

21.6.7. HTTPPasswordMgr对象¶

21.6.8. HTTPPasswordMgrWithPriorAuth对象¶

21.6.9. AbstractBasicAuthHandler对象¶

21.6.10. HTTPBasicAuthHandler对象¶

21.6.11. ProxyBasicAuthHandler对象¶

21.6.12. AbstractDigestAuthHandler对象¶

21.6.13. HTTPDigestAuthHandler对象¶

21.6.14. ProxyDigestAuthHandler对象¶

21.6.15. HTTPHandler对象¶

21.6.16. HTTPSHandler对象¶

21.6.17. FileHandler对象¶

21.6.18. DataHandler对象¶

21.6.19. FTPHandler对象¶

21.6.20. CacheFTPHandler对象¶

21.6.21. UnknownHandler对象¶

21.6.22. HTTPErrorProcessor对象¶

21.6.23. 示例 ¶

21.6.24. 旧版接口¶

21.6.25. `urllib.request` Restrictions¶

21.7. `urllib.response` - urllib使用的响应类¶

目录

上一主题

下一主题

这一页

21.6. urllib.request —— 用于打开URL的可扩展库¶

21.6.1. 请求对象¶

21.6.2. OpenerDirector对象¶

21.6.3. BaseHandler对象¶

21.6.4. HTTPRedirectHandler对象¶

21.6.5. HTTPCookieProcessor对象¶

21.6.6. ProxyHandler对象¶

21.6.7. HTTPPasswordMgr对象¶

21.6.8. HTTPPasswordMgrWithPriorAuth对象¶

21.6.9. AbstractBasicAuthHandler对象¶

21.6.10. HTTPBasicAuthHandler对象¶

21.6.11. ProxyBasicAuthHandler对象¶

21.6.12. AbstractDigestAuthHandler对象¶

21.6.13. HTTPDigestAuthHandler对象¶

21.6.14. ProxyDigestAuthHandler对象¶

21.6.15. HTTPHandler对象¶

21.6.16. HTTPSHandler对象¶

21.6.17. FileHandler对象¶

21.6.18. DataHandler对象¶

21.6.19. FTPHandler对象¶

21.6.20. CacheFTPHandler对象¶

21.6.21. UnknownHandler对象¶

21.6.22. HTTPErrorProcessor对象¶

21.6.23. 示例 ¶

21.6.24. 旧版接口¶

21.6.25. urllib.request Restrictions¶

21.7. urllib.response - urllib使用的响应类¶

21.6. `urllib.request` —— 用于打开URL的可扩展库¶

21.6.25. `urllib.request` Restrictions¶

21.7. `urllib.response` - urllib使用的响应类¶