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

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

OpenerDirector 对象¶

OpenerDirector 实例有以下方法：

OpenerDirector.add_handler(handler)¶

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

• <protocol>_open() — 句柄知道如何打开 protocol URLs 的信号。

  查看 BaseHandler.<protocol>_open() 以获取更多信息。

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

  查看 BaseHandler.http_error_<nnn>() 以获取更多信息。

• <protocol>_error() — 句柄知道如何处理来自（非-http）*protocol* 的错误的信号。

• <protocol>_request() — 句柄知道如何预处理 protocol 请求的信号。

  查看 BaseHandler.<protocol>_request() 以获取更多信息。

• <protocol>_response() — 句柄知道如何后处理 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，则会对名为 <protocol>_open() 的方法重复此算法。 如果这些方法也全都返回 None，则会继续对名为 unknown_open() 的方法重复此算法。

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

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

BaseHandler 对象¶

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

BaseHandler.add_parent(director)¶

将 director 加为父 handler。

BaseHandler.close()¶

移除所有父 OpenerDirector。

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

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 对象¶

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”响应时的调用。

HTTPCookieProcessor 对象¶

HTTPCookieProcessor 的实例具备一个属性：

HTTPCookieProcessor.cookiejar¶

cookie 存放在 http.cookiejar.CookieJar 中。

ProxyHandler 对象¶

ProxyHandler.<protocol>_open(request)

ProxyHandler 将为每种 protocol 准备一个 _open() 方法，在构造函数给出的 proxies 字典中包含对应的代理服务器信息。通过调用 request.set_proxy()，本方法将把请求转为通过代理服务器，并会调用 handler 链中的下一个 handler 来完成对应的协议处理。

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。

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 标志的当前状态。

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" 则不行）。

HTTPBasicAuthHandler 对象¶

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

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

ProxyBasicAuthHandler 对象¶

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

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

AbstractDigestAuthHandler 对象¶

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

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

HTTPDigestAuthHandler 对象¶

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

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

ProxyDigestAuthHandler 对象¶

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

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

HTTPHandler 对象¶

HTTPHandler.http_open(req)¶

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

HTTPSHandler 对象¶

HTTPSHandler.https_open(req)¶

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

FileHandler 对象¶

FileHandler.file_open(req)¶

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

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

DataHandler 对象¶

DataHandler.data_open(req)¶

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

FTPHandler 对象¶

FTPHandler.ftp_open(req)¶

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

CacheFTPHandler 对象¶

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

CacheFTPHandler.setTimeout(t)¶

设置连接超时为 t 秒。

CacheFTPHandler.setMaxConns(m)¶

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

UnknownHandler 对象¶

UnknownHandler.unknown_open()¶

触发 URLError 异常。

HTTPErrorProcessor 对象¶

HTTPErrorProcessor.http_response(request, response)¶

处理出错的 HTTP 响应。

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

对于 200 以外的错误码，只通过 OpenerDirector.error() 将任务传给 handler 的 http_error_<type>() 方法。如果最终没有 handler 处理错误， HTTPDefaultErrorHandler 将触发 HTTPError。

HTTPErrorProcessor.https_response(request, response)¶

HTTPS 出错响应的处理。

与 http_response() 方法相同。

例子¶

HOWTO 使用 urllib 包获取网络资源 中给出了更多的示例。

以下示例将读取 python.org 主页并显示前 300 个字节的内容：

>>> importurllib.request
>>> withurllib.request.urlopen('http://www.python.org/')asf:
... 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 编码，因此这里将用同样的格式对字节串进行解码。

>>> withurllib.request.urlopen('http://www.python.org/')asf:
... 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 方法也能获得同样的结果：

>>> importurllib.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 支持的环境。

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

上述示例中的 CGI 代码如下所示：

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

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

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

基本 HTTP 认证示例：

importurllib.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 参数，或者是：

importurllib.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 头部信息。若要修改，请参见以下语句：

importurllib.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。

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

以下示例换用 POST 方法。请注意 urlencode 输出结果先被编码为字节串 data，再送入 urlopen。

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

以下示例显式指定了 HTTP 代理，以覆盖环境变量中的设置：

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

以下示例根本不用代理，也覆盖了环境变量中的设置：

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