20.6. urllib2 —用于打开 URL 的可扩展库

Note

urllib2模块已在 Python 3 中分为几个名为urllib.request和urllib.error的模块。将您的源转换为 Python 3 时，2to3工具将自动适应导入。

urllib2模块定义了有助于在复杂环境中打开 URL(主要是 HTTP)的Function和类-基本身份验证和摘要身份验证，重定向，Cookie 等。

20.6.1. 请求对象

以下方法描述了Request的所有公共接口，因此所有这些都必须在子类中被覆盖。

Request. add_data(* data *)
- 将Request数据设置为* data *。除 HTTP 处理程序外，所有处理程序都将忽略此参数，并且该处理程序应为字节字符串，并将请求更改为POST而不是GET。
Request. get_method ( )
- 返回指示 HTTP 请求方法的字符串。这仅对 HTTP 请求有意义，并且当前始终返回'GET'或'POST'。
Request. has_data ( )
- 返回实例是否具有非None数据。
Request. get_data ( )
- 返回实例的数据。
Request. add_header(* key ， val *)
- 向请求添加另一个 Headers。目前，所有处理程序都会忽略 Headers，但 HTTP 处理程序除外，在 HTTP 处理程序中，Headers 被添加到发送到服务器的 Headers 列表中。请注意，具有相同名称的头不能超过一个，并且以后的调用将覆盖先前的调用，以防* key *冲突。当前，这不会丢失 HTTP Function，因为所有具有多次使用意义的 Headers 都具有一种(Headers 专用)方式，仅使用一个 Headers 即可获得相同的Function。
Request. add_unredirected_header(* key ， header *)
- 添加不会添加到重定向请求的 Headers。

2.4 版的新Function。

Request. has_header(* header *)
- 返回实例是否具有命名头(检查常规和未重定向)。

2.4 版的新Function。

Request. get_full_url ( )
- 返回构造函数中给定的 URL。
Request. get_type ( )
- 返回 URL 的类型-也称为方案。
Request. get_host ( )
- 返回将要构建连接的主机。
Request. get_selector ( )
- 返回 selectors-发送到服务器的 URL 的一部分。
Request. get_header(* header_name ， default = None *)
- 返回给定 Headers 的值。如果标题不存在，则返回默认值。
Request. header_items ( )
- 返回请求 Headers 的 Tuples 列表(header_name，header_value)。
Request. set_proxy(* host ， type *)
- pass连接到代理服务器来准备请求。 * host 和 type *将替换实例的实例，而实例的 selectors 将是构造函数中提供的原始 URL。
Request. get_origin_req_host ( )
- 返回由 RFC 2965定义的原始事务的请求主机。请参阅Request构造函数的文档。
Request. is_unverifiable ( )
- 返回请求是否不可验证，如 RFC 2965 所定义。请参见Request构造函数的文档。

20.6.2. OpenerDirector 对象

OpenerDirector个实例具有以下方法：

OpenerDirector. add_handler(* handler *)
- - handler *应该是BaseHandler的实例。搜索以下方法，并将其添加到可能的链中(请注意，HTTP 错误是一种特殊情况)。
protocol_open —表示处理程序知道如何打开协议 URL。
http_error_type —表示处理程序知道如何使用 HTTP 错误代码* type *处理 HTTP 错误。
protocol_error —表示处理程序知道如何处理(非http)协议中的错误。
protocol_request —表示处理程序知道如何预处理协议请求。
protocol_response —表示处理程序知道如何对协议响应进行后处理。
OpenerDirector. open(* url [，data] [，timeout] *)
- 打开给定的* url (可以是请求对象或字符串)，可以选择传递给定的 data 。引发的参数，返回值和异常与urlopen()相同(后者仅在当前安装的全局OpenerDirector上调用open()方法)。可选的 timeout *参数以秒为单位指定用于阻止诸如连接try之类的操作的超时(如果未指定，将使用全局默认超时设置)。超时Function实际上仅适用于 HTTP，HTTPS 和 FTP 连接)。

在 2.6 版中进行了更改：添加了“超时”。

OpenerDirector. error(* proto * [，* arg * [，* ... *]])
- 处理给定协议的错误。这将使用给定的参数(特定于协议)调用给定协议的已注册错误处理程序。 HTTP 协议是一种特殊情况，它使用 HTTP 响应代码来确定特定的错误处理程序。请参阅处理程序类的http_error_*()方法。

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

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

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

每个使用名为protocol_request的方法的处理程序都会调用该方法来预处理请求。
具有名为protocol_open的方法的处理程序将被调用以处理请求。当处理程序返回非None值(即响应)或引发异常(通常为URLError)时，此阶段结束。允许异常传播。

实际上，首先对名为default_open()的方法try了上述算法。如果所有此类方法都返回None，则对名为protocol_open的方法重复该算法。如果所有此类方法都返回None，则对名为unknown_open()的方法重复该算法。

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

每个使用名为protocol_response的方法的处理程序都会调用该方法以对响应进行后处理。

20.6.3. BaseHandler 对象

BaseHandler对象提供了一些直接有用的方法，以及其他一些供派生类使用的方法。这些旨在直接使用：

BaseHandler. add_parent(* director *)
- 添加一个导演作为 parent。
BaseHandler. close ( )
- 删除任何 parent。

以下属性和方法仅应由BaseHandler派生的类使用。

Note

已经采用了将定义protocol_request()或protocol_response()方法的子类命名为*Processor的约定。所有其他名称都称为*Handler。

BaseHandler. parent
- 有效的OpenerDirector，可用于使用其他协议打开或处理错误。
BaseHandler. default_open(* req *)
- 该方法未在BaseHandler中定义，但如果子类要捕获所有 URL，则应定义该方法。

如果实现此方法，则将由父级OpenerDirector调用。它应返回OpenerDirector或None的open()的返回值中所述的文件状对象。除非发生 true 的 exceptions，否则它应该提高URLError(例如，不应将MemoryErrorMap 到URLError)。

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

BaseHandler. protocol_open(* req *)
- (“协议”将由协议名称代替.)

该方法未在BaseHandler中定义，但如果子类要使用给定的协议来处理 URL，则应定义该方法。

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

BaseHandler. unknown_open(* req *)
- 该方法未在BaseHandler中定义，但如果子类要捕获所有没有特定注册处理程序打开它的 URL，则子类应定义该方法。

如果实施此方法，将由parent OpenerDirector调用。返回值应与default_open()相同。

BaseHandler. http_error_default(* req ， fp ， code ， msg ， hdrs *)
- 该方法未在BaseHandler中定义，但如果子类打算为其他未处理的 HTTP 错误提供全部保护，则子类应覆盖此方法。收到错误的OpenerDirector会自动调用它，通常在其他情况下不应调用。

req 将是Request对象， fp 将是具有 HTTP 错误正文的类似文件的对象， code 将是错误的三位数代码， msg 将是用户可见的解释代码和 hdrs *将是带有错误标题的 Map 对象。

返回的值和引发的异常应与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()的返回值相同的接口。

20.6.4. HTTPRedirectHandler 对象

Note

某些 HTTP 重定向需要此模块的 Client 端代码执行操作。在这种情况下，将引发HTTPError。有关各种重定向代码的确切含义的详细信息，请参见 RFC 2616。

HTTPRedirectHandler. redirect_request(* req ， fp ， code ， msg ， hdrs ， newurl *)
- 返回Request或None以响应重定向。从服务器收到重定向后，http_error_30*()方法的默认实现调用此方法。如果应该进行重定向，请返回一个新的Request以允许http_error_30*()执行重定向到* newurl *。否则，如果没有其他处理程序应try处理此 URL，请引发HTTPError；如果不能，则返回None，但可能会另一个处理程序。

Note

此方法的默认实现未严格遵循 RFC 2616，即 RFC 2616对POST请求的响应不得未经用户确认而自动重定向。实际上，浏览器确实允许这些响应的自动重定向，将 POST 更改为GET，并且默认实现会重现此行为。

HTTPRedirectHandler. http_error_301(* req ， fp ， code ， msg ， hdrs *)
- 重定向到Location:或URI: URL。当获得 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()相同，但要求“临时重定向”响应。

20.6.5. HTTPCookieProcessor 对象

2.4 版的新Function。

HTTPCookieProcessor个实例具有一个属性：

HTTPCookieProcessor. cookiejar
- 存储 Cookie 的cookielib.CookieJar。

20.6.6. ProxyHandler 对象

ProxyHandler. protocol_open(* request *)
- (“协议”将由协议名称代替.)

对于每个* protocol ，ProxyHandler都有一个方法protocol_open，该方法在构造函数中提供的 proxies *词典中有一个代理。该方法将pass调用request.set_proxy()来修改要pass代理的请求，并调用链中的下一个处理程序以实际执行协议。

20.6.7. HTTPPasswordMgr 对象

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

HTTPPasswordMgr. add_password(* realm ， uri ， user ， passwd *)
- - uri *可以是单个 URI 或 URI 序列。 * realm ， user 和 passwd 必须是字符串。当给出对 realm *的身份验证以及任何给定 URI 的超级 URI 时，这将使(user, passwd)用作身份验证令牌。
HTTPPasswordMgr. find_user_password(* realm ， authuri *)
- 获取给定领域和 URI(如果有)的用户/密码。如果没有匹配的用户/密码，此方法将返回(None, None)。

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

20.6.8. AbstractBasicAuthHandler 对象

AbstractBasicAuthHandler. http_error_auth_reqed(* authreq ， host ， req ， headers *)
- pass获取用户/密码对，然后重试请求来处理身份验证请求。 * authreq 应该是请求中包含有关领域信息的 Headers 的名称， host 指定要进行身份验证的 URL 和路径， req 应该是(失败的)Request对象，并且 headers *应该是错误标题。

host *是授权(例如"python.org")或包含授权组成部分的 URL(例如"http://python.org/")。无论哪种情况，授权机构都不得包含 userinfo 组件(因此"python.org"和"python.org:80"可以，而"joe:password@python.org"则可以)。

20.6.9. HTTPBasicAuthHandler 对象

HTTPBasicAuthHandler. http_error_401(* req ， fp ， code ， msg ， hdrs *)
- 重试带有身份验证信息的请求(如果有)。

20.6.10. ProxyBasicAuthHandler 对象

ProxyBasicAuthHandler. http_error_407(* req ， fp ， code ， msg ， hdrs *)
- 重试带有身份验证信息的请求(如果有)。

20.6.11. AbstractDigestAuthHandler 对象

AbstractDigestAuthHandler. http_error_auth_reqed(* authreq ， host ， req ， headers *)
- - authreq 应该是请求中包含有关领域信息的 Headers 名称， host 应该是要向其进行身份验证的主机， req 应该是(失败的)Request对象，而 headers *应该是错误标题。

20.6.12. HTTPDigestAuthHandler 对象

HTTPDigestAuthHandler. http_error_401(* req ， fp ， code ， msg ， hdrs *)
- 重试带有身份验证信息的请求(如果有)。

20.6.13. ProxyDigestAuthHandler 对象

ProxyDigestAuthHandler. http_error_407(* req ， fp ， code ， msg ， hdrs *)
- 重试带有身份验证信息的请求(如果有)。

20.6.14. HTTPHandler 对象

HTTPHandler. http_open(* req *)
- 发送 HTTP 请求，该请求可以是 GET 或 POST，具体取决于req.has_data()。

20.6.15. HTTPSHandler 对象

HTTPSHandler. https_open(* req *)
- 发送 HTTPS 请求，该请求可以是 GET 或 POST，具体取决于req.has_data()。

20.6.16. FileHandler 对象

FileHandler. file_open(* req *)
- 如果没有主机名，或者主机名是'localhost'，请在本地打开文件。否则，将协议更改为ftp，然后try使用parent打开它。

20.6.17. FTPHandler 对象

FTPHandler. ftp_open(* req *)
- 打开* req *指示的 FTP 文件。登录始终使用空的用户名和密码完成。

20.6.18. CacheFTPHandler 对象

CacheFTPHandler个对象是FTPHandler个对象，具有以下其他方法：

CacheFTPHandler. setTimeout(* t *)
- 将连接超时设置为* t *秒。
CacheFTPHandler. setMaxConns(* m *)
- 将最大缓存连接数设置为* m *。

20.6.19. UnknownHandler 对象

UnknownHandler. unknown_open ( )
- 引发URLError异常。

20.6.20. HTTPErrorProcessor 对象

2.4 版的新Function。

HTTPErrorProcessor. http_response ( )
- 处理 HTTP 错误响应。

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

对于非 200 错误代码，这只是passOpenerDirector.error()将作业传递给protocol_error_code处理程序方法。finally，如果没有其他处理程序处理该错误，则urllib2.HTTPDefaultErrorHandler将引发HTTPError。

HTTPErrorProcessor. https_response ( )
- 处理 HTTPS 错误响应。

行为与http_response()相同。

20.6.21. Examples

除以下示 exception，如何使用 urllib2 获取 Internet 资源中还提供了更多示例。

本示例获取 python.org 主页，并显示它的前 100 个字节：

>>> import urllib2
>>> f = urllib2.urlopen('http://www.python.org/')
>>> print f.read(100)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<?xml-stylesheet href="./css/ht2html

在这里，我们将数据流发送到 CGI 的标准 Importing，并读取返回给我们的数据。请注意，此示例仅在 Python 安装支持 SSL 时有效。

>>> import urllib2
>>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data='This data is passed to stdin of the CGI')
>>> f = urllib2.urlopen(req)
>>> print f.read()
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

基本 HTTP 验证的使用：

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

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

本示例将默认的ProxyHandler替换为使用以编程方式提供的代理 URL 的 URL，并使用ProxyBasicAuthHandler添加代理授权支持。

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

opener = urllib2.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')

添加 HTTPHeaders：

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

import urllib2
req = urllib2.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 = urllib2.urlopen(req)

OpenerDirector自动向每个Request添加* User-Agent *Headers。要更改此设置：

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

另外，请记住，当Request传递给urlopen()(或OpenerDirector.open())时，会添加一些标准 Headers(* Content-Length ， Content-Type 和 Host *)。

Docs

Docs4dev

Title here

20.6. urllib2 —用于打开 URL 的可扩展库

20.6.1. 请求对象

20.6.2. OpenerDirector 对象

20.6.3. BaseHandler 对象

20.6.4. HTTPRedirectHandler 对象

20.6.5. HTTPCookieProcessor 对象

20.6.6. ProxyHandler 对象

20.6.7. HTTPPasswordMgr 对象

20.6.8. AbstractBasicAuthHandler 对象

20.6.9. HTTPBasicAuthHandler 对象

20.6.10. ProxyBasicAuthHandler 对象

20.6.11. AbstractDigestAuthHandler 对象

20.6.12. HTTPDigestAuthHandler 对象

20.6.13. ProxyDigestAuthHandler 对象

20.6.14. HTTPHandler 对象

20.6.15. HTTPSHandler 对象

20.6.16. FileHandler 对象

20.6.17. FTPHandler 对象

20.6.18. CacheFTPHandler 对象

20.6.19. UnknownHandler 对象

20.6.20. HTTPErrorProcessor 对象

20.6.21. Examples