urllib2

注意

这个urllib2模块已经被Python 3中的几个模块命名为urllib.request和urllib.error。将源代码转换为Python 3时，2to3工具将自动适应导入。

该urllib2模块定义了帮助在复杂世界中打开URL（主要是HTTP）的函数和类 - 基本和摘要式身份验证，重定向，cookie等等。

该urllib2模块定义了以下功能：

urllib2.urlopen(url[, data[, timeout[, cafile[, capath[, cadefault[, context]]]]])

打开URL url，它可以是一个字符串，也可以是一个Request对象。

数据可以是指定发送到服务器的附加数据的字符串，或者None如果不需要这样的数据。目前HTTP请求是唯一使用数据的请求; 当提供数据参数时，HTTP请求将成为POST而不是GET 。数据应该是标准应用程序/ x-www-form-urlencoded格式的缓冲区。该urllib.urlencode()函数采用2元组的映射或序列，并以此格式返回字符串。urllib2模块发送包含Connection:close头文件的HTTP / 1.1请求。

可选的timeout参数指定阻止诸如连接尝试（如果未指定，将使用全局默认超时设置）等操作的超时（以秒为单位）。这实际上只适用于HTTP，HTTPS和FTP连接。

如果指定了上下文，则它必须是ssl.SSLContext描述各种SSL选项的实例。查看HTTPSConnection更多细节。

可选的cafile和capath参数为HTTPS请求指定一组可信的CA证书。cafile应指向包含一系列CA证书的单个文件，而capath应指向散列证书文件的目录。更多信息可以在中找到ssl.SSLContext.load_verify_locations()。

该cadefault参数被忽略。

这个函数返回一个类似文件的对象和三个附加的方法：

• geturl() - 返回检索的资源的URL，通常用于确定是否遵循重定向

• info()- 以mimetools.Message实例的形式返回页面的元信息（如标题）（请参阅快速参考HTTP标题）

• getcode() - 返回响应的HTTP状态码。

引发URLError错误。

请注意，None如果没有处理程序处理请求，可能会返回（尽管默认安装的全局OpenerDirector使用UnknownHandler来确保永远不会发生这种情况）。

另外，如果检测到代理设置（例如，当设置了*_proxy类似环境变量时http_proxy），ProxyHandler则默认安装并确保通过代理处理请求。

在版本2.6中更改：添加了超时。

在版本2.7.9中进行了更改：添加了cafile，capath，cadefault和context。

urllib2.install_opener(opener)

安装一个OpenerDirector实例作为默认的全局开启器。如果你想让urlopen使用那个开罐器，只需要安装一个开罐器; 否则，简单地调用OpenerDirector.open()代替urlopen()。代码不检查真实的OpenerDirector，任何具有合适接口的类都可以工作。

urllib2.build_opener([handler, ...])

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

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

从Python 2.3开始，BaseHandler子类也可以改变它的handler_order属性来修改它在处理程序列表中的位置。

以下例外情况适当提出：

exception urllib2.URLError

处理程序遇到问题时会引发此异常（或派生的异常）。它是一个子类IOError。

reason

这个错误的原因。它可以是一个消息字符串或另一个异常实例（socket.error对于远程URL，OSError对于本地URL）。

exception urllib2.HTTPError

尽管是一个异常（的一个子类URLError），但HTTPError它也可以作为非例外的文件返回值（与返回值相同urlopen()）。这在处理异常的HTTP错误时很有用，例如验证请求。

code

RFC 2616中定义的HTTP状态代码。此数值对应于在中找到的代码字典中找到的值BaseHTTPServer.BaseHTTPRequestHandler.responses。

reason

这个错误的原因。它可以是一个消息字符串或另一个异常实例。

提供以下课程：

class urllib2.Request(url[, data][, headers][, origin_req_host][, unverifiable])

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

网址应该是包含有效网址的字符串。

数据可以是指定发送到服务器的附加数据的字符串，或者None如果不需要这样的数据。目前HTTP请求是唯一使用数据的请求; 当提供数据参数时，HTTP请求将成为POST而不是GET 。数据应该是标准应用程序/ x-www-form-urlencoded格式的缓冲区。该urllib.urlencode()函数采用2元组的映射或序列，并以此格式返回字符串。

标题应该是一个字典，并将被视为add_header()与每个键和值作为参数调用。这通常用于“欺骗” User-Agent头部值，浏览器用它来标识自己 - 一些HTTP服务器只允许来自普通浏览器而不是脚本的请求。例如，Mozilla Firefox可能会将自己标识为"Mozilla/5.0 (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"，而urllib2默认的用户代理字符串是"Python-urllib/2.6"（在Python 2.6上）。

最后两个参数只对正确处理第三方HTTP cookies感兴趣：

origin_req_host应该是RFC 2965定义的源事务的请求主机。它默认为cookielib.request_host(self)。这是用户发起的原始请求的主机名或IP地址。例如，如果请求是针对HTML文档中的图像的，则该请求应该是包含图像的页面请求的请求主机。

无法验证应该表明请求是否无法验证，如RFC 2965所定义。它默认为False。无法验证的请求是其用户没有选择批准的URL。例如，如果请求是针对HTML文档中的图像，并且用户无权批准自动获取图像，则应该是正确的。

class urllib2.OpenerDirector

该OpenerDirector课程通过BaseHandler链接打开URL 。它管理处理程序的链接，并从错误中恢复。

class urllib2.BaseHandler

这是所有注册处理程序的基类 - 并且只处理简单的注册机制。

class urllib2.HTTPDefaultErrorHandler

一个为HTTP错误响应定义默认处理程序的类; 所有的回应都会变成HTTPError例外。

class urllib2.HTTPRedirectHandler

一个类来处理重定向。

class urllib2.HTTPCookieProcessor([cookiejar])

一个类来处理HTTP Cookie。

class urllib2.ProxyHandler([proxies])

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

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

注意

HTTP_PROXY如果REQUEST_METHOD设置了变量，将被忽略; 请参阅文档getproxies()。

class urllib2.HTTPPasswordMgr

保持(realm, uri) -> (user, password)映射数据库。

class urllib2.HTTPPasswordMgrWithDefaultRealm

保持(realm, uri) -> (user, password)映射数据库。一个领域None被认为是一个全面的领域，如果没有其他领域适合，就会搜索这个领域。

class urllib2.AbstractBasicAuthHandler([password_mgr])

这是一个mixin类，可以帮助远程主机和代理进行HTTP身份验证。password_mgr，如果给出，应该是兼容的HTTPPasswordMgr; 有关必须支持的接口的信息，请参阅HTTPPasswordMgr对象部分。

class urllib2.HTTPBasicAuthHandler([password_mgr])

处理远程主机的身份验证。password_mgr，如果给出，应该是兼容的HTTPPasswordMgr; 有关必须支持的接口的信息，请参阅HTTPPasswordMgr对象部分。

class urllib2.ProxyBasicAuthHandler([password_mgr])

处理与代理的身份验证。password_mgr，如果给出，应该是兼容的HTTPPasswordMgr; 有关必须支持的接口的信息，请参阅HTTPPasswordMgr对象部分。

class urllib2.AbstractDigestAuthHandler([password_mgr])

这是一个mixin类，可以帮助远程主机和代理进行HTTP身份验证。password_mgr，如果给出，应该是兼容的HTTPPasswordMgr; 有关必须支持的接口的信息，请参阅HTTPPasswordMgr对象部分。

class urllib2.HTTPDigestAuthHandler([password_mgr])

处理远程主机的身份验证。password_mgr，如果给出，应该是兼容的HTTPPasswordMgr; 有关必须支持的接口的信息，请参阅HTTPPasswordMgr对象部分。

class urllib2.ProxyDigestAuthHandler([password_mgr])

处理与代理的身份验证。password_mgr，如果给出，应该是兼容的HTTPPasswordMgr; 有关必须支持的接口的信息，请参阅HTTPPasswordMgr对象部分。

class urllib2.HTTPHandler

一个处理HTTP URL打开的类。

class urllib2.HTTPSHandler([debuglevel[, context]])

一个处理HTTPS URL打开的类。上下文的含义与上述相同httplib.HTTPSConnection。

在版本2.7.9中更改：添加了上下文。

class urllib2.FileHandler

打开本地文件。

class urllib2.FTPHandler

打开FTP URL。

class urllib2.CacheFTPHandler

打开FTP URL，保持打开的FTP连接缓存，以尽量减少延迟。

class urllib2.UnknownHandler

一个全能的类来处理未知的URL。

class urllib2.HTTPErrorProcessor

处理HTTP错误响应。

1.请求对象

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

Request.add_data(data)

将Request数据设置为数据。除HTTP处理程序之外，所有处理程序都会忽略它 - 并且它应该是一个字节字符串，并且会将请求更改为POST不是GET。

Request.get_method()

返回一个指示HTTP请求方法的字符串。这只对HTTP请求有意义，目前总是返回'GET'或'POST'。

Request.has_data()

返回实例是否有非None数据。

Request.get_data()

返回实例的数据。

Request.add_header(key, val)

向请求添加另一个标头。除了HTTP处理程序之外，所有处理程序都会忽略标题，并将它们添加到发送到服务器的标题列表中。请注意，不能有多个具有相同名称的标题，并且以后的调用将覆盖以前的调用，以防万一键发生冲突。目前，这并不是HTTP功能的损失，因为所有在不止一次使用时具有含义的标题具有仅使用一个标题获得相同功能的（标题特定的）方式。

Request.add_unredirected_header(key, header)

添加不会添加到重定向请求的标头。

2.4版本中的新功能。

Request.has_header(header)

返回实例是否具有指定的头（同时检查常规和未重定向）。

2.4版本中的新功能。

Request.get_full_url()

返回构造函数中给出的URL。

Request.get_type()

返回URL的类型 - 也称为方案。

Request.get_host()

返回将建立连接的主机。

Request.get_selector()

返回选择器 - 发送到服务器的URL的一部分。

Request.get_header(header_name, default=None)

返回给定标题的值。如果标题不存在，则返回默认值。

Request.header_items()

返回请求标头的元组列表（header_name，header_value）。

Request.set_proxy(host, type)

通过连接到代理服务器来准备请求。该主机和类型将取代这些实例，并且该实例的选择将是在构造函数中给出的原始URL。

Request.get_origin_req_host()

按照RFC 2965的规定，返回原始事务的请求主机。请参阅Request构造函数的文档。

Request.is_unverifiable()

根据RFC 2965的规定，返回请求是否无法验证。请参阅Request构造函数的文档。

2. OpenerDirector对象

OpenerDirector 实例具有以下方法：

OpenerDirector.add_handler(handler)

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

• protocol_open- 表示处理程序知道如何打开协议 URL。

• http_error_type- 表示处理程序知道如何使用HTTP错误代码类型处理HTTP错误。

• protocol_error- 表示处理程序知道如何处理来自（非http）协议的错误。

• protocol_request- 表示处理程序知道如何预处理协议请求。

• protocol_response- 表示处理程序知道如何后处理协议响应。

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

打开给定的URL（可以是请求对象或字符串），可以传递给定的数据。引发的参数，返回值和异常与那些urlopen()（它只是open()在当前安装的全局中调用方法OpenerDirector）相同。可选的timeout参数指定阻止诸如连接尝试（如果未指定，将使用全局默认超时设置）等操作的超时（以秒为单位）。超时功能实际上仅适用于HTTP，HTTPS和FTP连接）。

在版本2.6中更改：添加了超时。

OpenerDirector.error(proto[, arg[, ...]])

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

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

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

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

• 每个使用类似方法的处理程序都会调用该方法来预处理请求。protocol_request

• 调用名为like的方法来处理请求。当处理程序返回非值（即响应）或引发异常（通常）时，此阶段结束。允许异常传播。protocol_openNoneURLError

实际上，上述算法首先被尝试用于名为的方法default_open()。如果所有这些方法都返回None，则对于名为like的方法重复该算法。如果所有这些方法都返回，则对于名为的方法重复该算法。protocol_openNoneunknown_open()

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

• 每个使用类似方法的处理程序都会调用该方法来后处理响应。protocol_response

3. BaseHandler对象

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

BaseHandler.add_parent(director)

添加导演作为父项。

BaseHandler.close()

删除任何父母。

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

注意

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

BaseHandler.parent

一个有效的OpenerDirector，可以用来打开使用不同的协议，或处理错误。

BaseHandler.default_open(req)

这个方法没有被定义BaseHandler，但是如果他们想要捕获所有的URL，子类应该定义它。

这个方法，如果实施，将由父母调用OpenerDirector。它应该返回一个类似于文件的对象，如open()of OpenerDirector或者返回值中所述None。它应该提高URLError，除非发生真正的例外事件（例如，MemoryError不应映射到URLError）。

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

BaseHandler.protocol_open(req)

（“协议”将被协议名称替换。）

这个方法没有被定义BaseHandler，但是如果他们想要使用给定的协议处理URL，子类应该定义它。

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

BaseHandler.unknown_open(req)

这个方法没有定义BaseHandler，但是子类应该定义它，如果他们想捕获所有没有特定注册处理器的URL来打开它。

这个方法如果被实现的话，将会被调用parent OpenerDirector。返回值应该与for相同default_open()。

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

这个方法没有在中定义BaseHandler，但是如果它们打算提供一个捕获所有其他未处理的HTTP错误的子类，它应该覆盖它。它会被OpenerDirector错误自动调用，通常不会在其他情况下调用。

req将是一个Request对象，fp将是一个带有HTTP错误体的文件类对象，代码将是错误的三位代码，msg将是代码的用户可见解释，而hdrs将是一个映射对象与错误的标题。

返回的值和异常应该与那些相同urlopen()。

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

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

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

提出的参数，返回值和异常应该与for相同http_error_default()。

BaseHandler.protocol_request(req)

（“协议”将被协议名称替换。）

这个方法没有在中定义BaseHandler，但是如果他们想要预处理给定协议的请求，子类就应该定义它。

该方法（如果已定义）将由父级调用OpenerDirector。请求将成为一个Request对象。返回值应该是一个Request对象。

BaseHandler.protocol_response(req, response)

（“协议”将被协议名称替换。）

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

该方法（如果已定义）将由父级调用OpenerDirector。请求将成为一个Request对象。响应将是一个实现与返回值相同的接口的对象urlopen()。返回值应该实现与返回值相同的接口urlopen()。

HTTPRedirectHandler对象

注意

某些HTTP重定向需要来自此模块的客户端代码的操作。如果是这样的话，HTTPError就提出来了。有关各种重定向代码的准确含义的详细信息，请参阅RFC 2616。

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

返回Request或None响应重定向。http_error_30*()当从服务器收到重定向时，这由方法的默认实现调用。如果应该发生重定向，则返回一个新的Request以允许http_error_30*()执行重定向到newurl。否则，HTTPError如果没有其他处理程序尝试处理此URL，则返回，或者None如果您不能，则返回另一个处理程序。

注意

此方法的默认实现并不严格遵循RFC 2616，该规范规定，对于POST请求的301和302响应不得在用户未经确认的情况下自动重定向。实际上，浏览器确实允许自动重定向这些响应，将POST更改为a GET，并且默认实现会重现此行为。

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

重定向到Location:或URI:网址。OpenerDirector当获得HTTP“永久移动”响应时，父级调用此方法。

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()，但呼吁“临时重定向”响应。

5. HTTPCookieProcessor对象

2.4版本中的新功能。

HTTPCookieProcessor 实例有一个属性：

HTTPCookieProcessor.cookiejar

在cookielib.CookieJar其中存储Cookie。

6. ProxyHandler对象

ProxyHandler.protocol_open(request)

（“协议”将被协议名称替换。）

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

7. HTTPPasswordMgr对象

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

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

uri可以是单个URI，也可以是一系列URI。realm，user和passwd必须是字符串。(user, passwd)当给定领域的认证和给定URI的任何给定的超级URI时，这导致用作认证令牌。

HTTPPasswordMgr.find_user_password(realm, authuri)

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

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

8. AbstractBasicAuthHandler对象

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

通过获取用户/密码对来处理认证请求，然后重新尝试请求。authreq应该是请求中包含有关域的信息的头的名称，host指定要认证的URL和路径，req应该是（失败的）Request对象，并且头应该是错误头。

主机是权威（例如"python.org"）或包含权威组件（例如"http://python.org/"）的URL 。在任一情况下，权限不能包含userinfo的组分（所以，"python.org"和"python.org:80"都很好，"joe:password@python.org"是不是）。

9. HTTPBasicAuthHandler对象

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

如果可用，请重新尝试带有认证信息的请求。

10. ProxyBasicAuthHandler对象

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

如果可用，请重新尝试带有认证信息的请求。

11. AbstractDigestAuthHandler对象

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

authreq应该是包含在请求中的关于域的信息的头部的名称，主机应该是要认证的主机，req应该是（失败的）Request对象，并且头部应该是错误头部。

12. HTTPDigestAuthHandler对象

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

如果可用，请重新尝试带有认证信息的请求。

13. ProxyDigestAuthHandler对象

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

如果可用，请重新尝试带有认证信息的请求。

14. HTTPHandler对象

HTTPHandler.http_open(req)

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

15. HTTPSHandler对象

HTTPSHandler.https_open(req)

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

16. FileHandler对象

FileHandler.file_open(req)

如果没有主机名或主机名是本地打开文件'localhost'。将协议更改为ftp其他方式，然后重试使用parent。

17. FTPHandler对象

FTPHandler.ftp_open(req)

打开req指示的FTP文件。登录始终使用空的用户名和密码完成。

18. CacheFTPHandler对象

CacheFTPHandler对象是FTPHandler具有以下附加方法的对象：

CacheFTPHandler.setTimeout(t)

将连接超时设置为t秒。

CacheFTPHandler.setMaxConns(m)

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

19. UnknownHandler对象

UnknownHandler.unknown_open()

引发URLError异常。

20. HTTPErrorProcessor对象

2.4版本中的新功能。

HTTPErrorProcessor.http_response()

处理HTTP错误响应。

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

对于非200错误代码，这只是将作业传递给处理程序方法。最终，如果没有其他处理程序处理该错误，则会引发一次。protocol_error_codeOpenerDirector.error()urllib2.HTTPDefaultErrorHandlerHTTPError

HTTPErrorProcessor.https_response()

处理HTTPS错误响应。

行为与之相同http_response()。

21.例子

除了下面的例子，HOWTO使用urllib2获取互联网资源中给出了更多的例子。

这个例子获取python.org主页面并显示它的前100个字节：

在这里，我们正在向CGI的stdin发送数据流并读取它返回给我们的数据。请注意，此示例仅在Python安装支持SSL时起作用。

上例中使用的示例CGI的代码是：

使用基本HTTP认证：

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

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

添加HTTP标头：

对构造函数使用headers参数Request，或者：

OpenerDirector自动为每个用户添加一个User-Agent头Request。要改变这一点：

另外，请记住，传递给（或）时会添加一些标准标题（Content-Length，Content-Type和Host）。Requesturlopen()OpenerDirector.open()