On this page
urllib.request —用于打开 URL 的可扩展库
urllib.request模块定义了有助于在复杂环境中打开 URL(主要是 HTTP)的Function和类-基本身份验证和摘要身份验证,重定向,Cookie 等。
See also
推荐使用Requests package作为更高级别的 HTTPClient 端界面。
urllib.request模块定义以下Function:
urllib.request.
urlopen
(* url , data = None *,[* timeout *,] **, cafile = None , capath = None , cadefault = False , context = None *)- 打开 URL * url *,它可以是字符串或Request对象。
- data *必须是指定要发送到服务器的其他数据的对象;如果不需要此类数据,则为
None
。有关详情,请参见Request。
urllib.request 模块使用 HTTP/1.1,并在其 HTTP 请求中包含Connection:close
Headers。
可选的* timeout *参数以秒为单位指定用于阻止诸如连接try之类的操作的超时(如果未指定,将使用全局默认超时设置)。这实际上仅适用于 HTTP,HTTPS 和 FTP 连接。
如果指定了* context *,则它必须是描述各种 SSL 选项的ssl.SSLContext实例。有关更多详细信息,请参见HTTPSConnection。
可选的* cafile 和 capath *参数为 HTTPS 请求指定一组受信任的 CA 证书。 * cafile 应该指向包含一堆 CA 证书的单个文件,而 capath *应该指向哈希证书文件的目录。可以在ssl.SSLContext.load_verify_locations()中找到更多信息。
- cadefault *参数将被忽略。
此函数始终返回可以用作context manager的对象,并具有诸如
geturl()
—返回所获取资源的 URL,通常用于确定是否遵循了重定向info()
—以email.message_from_string()实例的形式返回页面的元信息,例如 Headers(请参见HTTPHeaders 快速参考)getcode()
–返回响应的 HTTP 状态代码。
对于 HTTP 和 HTTPS URL,此函数返回一个经过稍微修改的http.client.HTTPResponse对象。除了上面的三个新方法外,msg 属性包含与reason属性(服务器返回的原因短语)相同的信息,而不是HTTPResponse文档中指定的响应头。
对于由旧版URLopener和FancyURLopener类显式处理的 FTP,文件和数据 URL 和请求,此函数返回urllib.response.addinfourl
对象。
引发URLError协议错误。
请注意,如果没有处理程序处理请求,则可能返回None
(尽管默认安装的全局OpenerDirector使用UnknownHandler来确保永远不会发生此错误)。
另外,如果检测到代理设置(例如,设置了*_proxy
环境变量,如 http_proxy
),则默认安装ProxyHandler并确保pass代理处理请求。
Python 2.6 和更早版本的旧版urllib.urlopen
函数已停产; urllib.request.urlopen()对应于旧urllib2.urlopen
。可以pass使用ProxyHandler对象来获得代理处理,该处理是pass将字典参数传递给urllib.urlopen
来完成的。
默认的打开器会引发一个auditing event urllib.Request
,它们的参数fullurl
,data
,headers
,method
均取自请求对象。
在版本 3.2 中更改:添加了* cafile 和 capath *。
在版本 3.2 中进行了更改:现在尽可能支持 HTTPS 虚拟主机(即ssl.HAS_SNI为 true)。
3.2 版中的新Function:* 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
(开瓶器)- 安装OpenerDirector实例作为默认的全局启动器。仅当您希望 urlopen 使用该打开程序时,才需要安装打开程序。否则,只需调用OpenerDirector.open()而不是urlopen()即可。该代码不会检查OpenerDirector是否为实,任何具有适当接口的类都将起作用。
urllib.request.
build_opener
([* handler , ... *])- 返回一个OpenerDirector实例,该实例按给定的 Sequences 链接处理程序。 * 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 *)- 将路径组件* path 从百分比编码的 URL 转换为路径的本地语法。这不接受完整的 URL。此函数使用unquote()解码 path *。
urllib.request.
getproxies
( )- 此辅助函数将方案字典返回到代理服务器 URLMap。它以不区分大小写的方式在环境中首先扫描所有 os 的名称为
<scheme>_proxy
的变量,如果找不到该变量,则从 Mac OS X 的 Mac OSX 系统配置和 Windows 的 Windows 系统注册表中查找代理信息。如果小写和大写环境变量都存在(并且不同意),则首选小写。
- 此辅助函数将方案字典返回到代理服务器 URLMap。它以不区分大小写的方式在环境中首先扫描所有 os 的名称为
Note
如果设置了环境变量REQUEST_METHOD
(通常表示您的脚本在 CGI 环境中运行),则将忽略环境变量HTTP_PROXY
(大写_PROXY
)。这是因为 Client 端可以使用“ Proxy:” HTTPHeaders 注入该变量。如果需要在 CGI 环境中使用 HTTP 代理,则可以显式使用ProxyHandler
,或确保变量名称为小写(或至少为_proxy
后缀)。
提供了以下类:
-
- class *
urllib.request.
Request
(* url , data = None , headers ={} , origin_req_host = None , unverifiable = False , method = None *)
- 此类是 URL 请求的抽象。
- class *
url *应该是包含有效 URL 的字符串。
data 必须是指定要发送到服务器的其他数据的对象,如果不需要,则为
None
。当前,HTTP 请求是唯一使用 data 的请求。受支持的对象类型包括字节,类似文件的对象以及类似字节的对象的可迭代对象。如果没有提供Content-Length
或Transfer-Encoding
Headers 字段,则HTTPHandler将根据 data *的类型设置这些 Headers。Content-Length
将用于发送字节对象,而 RFC 7230中指定的Transfer-Encoding: chunked
将用于发送文件和其他可迭代对象。
对于 HTTP POST 请求方法,* data 应该是标准 application/x-www-form-urlencoded 格式的缓冲区。 urllib.parse.urlencode()函数采用 2Tuples 的 Map 或序列,并以这种格式返回 ASCII 字符串。在用作 data *参数之前,应将其编码为字节。
- headers *应该是一个字典,并且将被视为就好像每个键和值都作为参数调用add_header()一样。这通常用于“欺骗”
User-Agent
Headers 值,该值由浏览器用来标识自己–一些 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
Headers。如果尚未提供此 Headers,并且 data *不为 None,则默认添加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 文档中的图像,并且用户没有选择批准图像的自动获取,则应为 true。method 应该是指示将使用的 HTTP 请求方法的字符串(例如
'HEAD'
)。如果提供,则其值存储在method属性中,并由get_method()使用。如果 data *为None
或'POST'
,则默认值为'GET'
。子类可以pass在类本身中设置method属性来指示不同的默认方法。
Note
如果数据对象不能多次传递其内容(例如一个文件或只能产生一次内容的可迭代对象),并且该请求被重试以进行 HTTP 重定向或身份验证,则该请求将无法按预期工作。 * data *会在 Headers 之后立即发送到 HTTP 服务器。库中不支持 100 个连续期望。
在版本 3.3 中更改:Request.method参数已添加到 Request 类。
在版本 3.4 中更改:默认Request.method可能在类级别上指示。
3.6 版中的更改:如果未提供Content-Length
并且* data *既不是None
也不是字节对象,则不要引发错误。退而使用分块传输编码。
类别
urllib.request.
OpenerDirector
- OpenerDirector类pass链接在一起的BaseHandler打开 URL。它 Management 处理程序的链接以及从错误中恢复。
类别
urllib.request.
BaseHandler
- 这是所有注册处理程序的 Base Class,并且仅处理简单的注册机制。
类别
urllib.request.
HTTPDefaultErrorHandler
- 定义 HTTP 错误响应的默认处理程序的类;所有回复都变成HTTPError个 exception。
类别
urllib.request.
HTTPRedirectHandler
- 处理重定向的类。
类别
urllib.request.
HTTPCookieProcessor
(* cookiejar = None *)- 处理 HTTP Cookies 的类。
类别
urllib.request.
ProxyHandler
(代理=无)- 使请求pass代理。如果给出* proxies *,则它必须是将协议名称 Map 到代理 URL 的字典。默认设置是从环境变量
<protocol>_proxy
读取代理列表。如果未设置代理环境变量,则在 Windows 环境中,从注册表的“ Internet 设置”部分获取代理设置,在 Mac OS X 环境中,从 OS X 系统配置框架检索代理信息。
- 使请求pass代理。如果给出* proxies *,则它必须是将协议名称 Map 到代理 URL 的字典。默认设置是从环境变量
要禁用自动检测到的代理,请传递一个空字典。
no_proxy
环境变量可用于指定不应pass代理访问的主机;如果设置的话,它应该是主机名后缀的逗号分隔列表,可以选择附加:port
,例如cern.ch,ncsa.uiuc.edu,some.host:8080
。
Note
Note
如果设置了变量REQUEST_METHOD
,则HTTP_PROXY
将被忽略;请参阅getproxies()上的文档。
类别
urllib.request.
HTTPPasswordMgr
- 保留
(realm, uri) -> (user, password)
个 Map 的数据库。
- 保留
类别
urllib.request.
HTTPPasswordMgrWithDefaultRealm
- 保留
(realm, uri) -> (user, password)
个 Map 的数据库。None
的领域被认为是万能的领域,如果没有其他领域适合,则进行搜索。
- 保留
类别
urllib.request.
HTTPPasswordMgrWithPriorAuth
- HTTPPasswordMgrWithDefaultRealm的变体也具有
uri -> is_authenticated
Map 的数据库。可以由 BasicAuth 处理程序用来确定何时立即发送身份验证凭据,而不是先 await401
响应。
- HTTPPasswordMgrWithDefaultRealm的变体也具有
3.5 版中的新Function。
-
- class *
urllib.request.
AbstractBasicAuthHandler
(* password_mgr = None *)
- 这是一个混合类,可帮助对远程主机和代理进行 HTTP 身份验证。 * password_mgr (如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。如果 passwd_mgr *还提供
is_authenticated
和update_authenticated
方法(请参见HTTPPasswordMgrWithPriorAuth Objects),则处理程序将使用is_authenticated
结果用于给定的 URI 以确定是否随请求发送身份验证凭据。如果is_authenticated
返回 URI 的True
,则发送凭据。如果is_authenticated
是False
,则不发送凭据,然后,如果收到401
响应,则使用身份验证凭据重新发送请求。如果身份验证成功,则会调用update_authenticated
来为 URI 设置is_authenticated
True
,以便对 URI 或其任何超级 URI 的后续请求将自动包含身份验证凭据。
- class *
3.5 版的新Function:添加了is_authenticated
支持。
-
- class *
urllib.request.
HTTPBasicAuthHandler
(* password_mgr = None *)
- 使用远程主机处理身份验证。 * password_mgr *(如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。出现错误的身份验证方案时,HTTPBasicAuthHandler 将引发ValueError。
- class *
-
- class *
urllib.request.
ProxyBasicAuthHandler
(* password_mgr = None *)
- 使用代理处理身份验证。 * password_mgr *(如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。
- class *
-
- class *
urllib.request.
AbstractDigestAuthHandler
(* password_mgr = None *)
- 这是一个混合类,可帮助对远程主机和代理进行 HTTP 身份验证。 * password_mgr *(如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。
- class *
-
- class *
urllib.request.
HTTPDigestAuthHandler
(* password_mgr = None *)
- 使用远程主机处理身份验证。 * password_mgr *(如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。当同时添加了摘要身份验证处理程序和基本身份验证处理程序时,始终首先try摘要身份验证。如果摘要式身份验证再次返回 40x 响应,则会将其发送到基本身份验证处理程序进行处理。当使用除 Digest 或 Basic 之外的身份验证方案时,此 Handler 方法将引发ValueError。
- class *
在版本 3.3 中进行了更改:在不受支持的身份验证方案上提高ValueError。
-
- class *
urllib.request.
ProxyDigestAuthHandler
(* password_mgr = None *)
- 使用代理处理身份验证。 * password_mgr *(如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。
- 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相同的含义。
- class *
在 3.2 版中进行了更改:添加了* context 和 check_hostname *。
类别
urllib.request.
FileHandler
- 打开本地文件。
类别
urllib.request.
DataHandler
- 打开数据 URL。
3.4 版的新Function。
类别
urllib.request.
FTPHandler
- 打开 FTP URL。
类别
urllib.request.
CacheFTPHandler
- 开放的 FTP URL,保留开放的 FTP 连接的缓存,以最大程度地减少延迟。
类别
urllib.request.
UnknownHandler
- 一个处理所有未知 URL 的通用类。
类别
urllib.request.
HTTPErrorProcessor
- 处理 HTTP 错误响应。
Request Objects
以下方法描述了Request的公共接口,因此所有方法都可以在子类中覆盖。它还定义了几个公共属性,Client 端可以使用这些属性来检查已解析的请求。
Request.
full_url
- 原始 URL 传递给构造函数。
在版本 3.4 中更改。
Request.full_url 是具有设置器,获取器和删除器的属性。获取full_url将返回带有片段的原始请求 URL(如果存在)。
Request.
type
- URI 方案。
Request.
host
- URI 授权,通常是主机,但也可以包含由冒号分隔的端口。
Request.
origin_req_host
- 请求的原始主机,不带端口。
Request.
selector
- URI 路径。如果Request使用代理,则 selectors 将是传递给代理的完整 URL。
Request.
data
- 请求的实体,如果未指定,则为
None
。
- 请求的实体,如果未指定,则为
在版本 3.4 中进行了更改:更改值Request.data现在会删除“ Content-Length”Headers(如果先前已设置或计算)。
Request.
unverifiable
- 布尔值,指示该请求是否不可验证,如 RFC 2965所定义。
Request.
method
- 要使用的 HTTP 请求方法。默认情况下,其值为None,这意味着get_method()将对要使用的方法进行常规计算。可以pass在Request子类的类级别设置默认值或pass* method *参数将值传递给Request构造函数来提供默认值,从而设置其值(从而覆盖get_method()中的默认计算)。
版本 3.3 中的新Function。
在版本 3.4 中更改:现在可以在子类中设置默认值;以前只能pass构造函数参数进行设置。
Request.
get_method
( )- 返回指示 HTTP 请求方法的字符串。如果Request.method不是
None
,则返回其值;否则,如果Request.data是None
则返回'GET'
,否则返回'POST'
。这仅对 HTTP 请求有意义。
- 返回指示 HTTP 请求方法的字符串。如果Request.method不是
在版本 3.3 中更改:get_method 现在查看值Request.method。
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。
Request.
has_header
(* header *)- 返回实例是否具有命名头(检查常规和未重定向)。
Request.
remove_header
(* header *)- 从请求实例中删除命名 Headers(从常规 Headers 和未重定向 Headers 中都删除)。
3.4 版的新Function。
Request.
get_full_url
( )- 返回构造函数中给定的 URL。
在版本 3.4 中更改。
Returns Request.full_url
Request.
set_proxy
(* host , type *)- pass连接到代理服务器来准备请求。 * host 和 type *将替换实例的实例,而实例的 selectors 将是构造函数中提供的原始 URL。
Request.
get_header
(* header_name , default = None *)- 返回给定 Headers 的值。如果标题不存在,则返回默认值。
Request.
header_items
( )- 返回请求 Headers 的 Tuples 列表(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。
OpenerDirector Objects
OpenerDirector个实例具有以下方法:
OpenerDirector.
add_handler
(* handler *)-
- handler 应该是BaseHandler的实例。搜索以下方法,并将其添加到可能的链中(请注意,HTTP 错误是一种特殊情况)。请注意,在下文中,应将 protocol 替换为要处理的实际协议,例如
http_response()
将是 HTTP 协议响应处理程序。还应将 type *替换为实际的 HTTP 代码,例如http_error_404()
将处理 HTTP 404 错误。
- handler 应该是BaseHandler的实例。搜索以下方法,并将其添加到可能的链中(请注意,HTTP 错误是一种特殊情况)。请注意,在下文中,应将 protocol 替换为要处理的实际协议,例如
-
<protocol>_open()
—表示处理程序知道如何打开协议 URL。
有关更多信息,请参见BaseHandler.<protocol>_open()。
http_error_<type>()
—表示处理程序知道如何使用 HTTP 错误代码* type *处理 HTTP 错误。
有关更多信息,请参见BaseHandler.http_error_<nnn>()。
<protocol>_error()
—表示处理程序知道如何处理(非http
)协议中的错误。<protocol>_request()
—表示处理程序知道如何预处理协议请求。
有关更多信息,请参见BaseHandler.<protocol>_request()。
<protocol>_response()
—表示处理程序知道如何对协议响应进行后处理。
有关更多信息,请参见BaseHandler.<protocol>_response()。
OpenerDirector.
open
(* url , data = None * [,* timeout *])- 打开给定的* url (可以是请求对象或字符串),可以选择传递给定的 data 。引发的参数,返回值和异常与urlopen()相同(后者仅在当前安装的全局OpenerDirector上调用open()方法)。可选的 timeout *参数以秒为单位指定用于阻止诸如连接try之类的操作的超时(如果未指定,将使用全局默认超时设置)。超时Function实际上仅适用于 HTTP,HTTPS 和 FTP 连接)。
OpenerDirector.
error
(* proto ,* args *)- 处理给定协议的错误。这将使用给定的参数(特定于协议)调用给定协议的已注册错误处理程序。 HTTP 协议是一种特殊情况,它使用 HTTP 响应代码来确定特定的错误处理程序。请参阅处理程序类的
http_error_<type>()
方法。
- 处理给定协议的错误。这将使用给定的参数(特定于协议)调用给定协议的已注册错误处理程序。 HTTP 协议是一种特殊情况,它使用 HTTP 响应代码来确定特定的错误处理程序。请参阅处理程序类的
返回的值和引发的异常与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()
的方法的处理程序都会调用该方法以对响应进行后处理。
BaseHandler Objects
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()的返回值相同的接口。
HTTPRedirectHandler Objects
Note
HTTPRedirectHandler.
redirect_request
(* req , fp , code , msg , hdrs , newurl *)
Note
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()相同,但要求“临时重定向”响应。
HTTPCookieProcessor Objects
HTTPCookieProcessor个实例具有一个属性:
ProxyHandler Objects
ProxyHandler.<protocol>_open(request)
- 对于每个* protocol ,ProxyHandler都有一个方法
<protocol>_open()
,该方法在构造函数中提供的 proxies *词典中有一个代理。该方法将pass调用request.set_proxy()
来修改要pass代理的请求,并调用链中的下一个处理程序以实际执行协议。
- 对于每个* protocol ,ProxyHandler都有一个方法
HTTPPasswordMgr Objects
这些方法可用于HTTPPasswordMgr和HTTPPasswordMgrWithDefaultRealm对象。
HTTPPasswordMgr.
add_password
(* realm , uri , user , passwd *)-
- uri *可以是单个 URI 或 URI 序列。 * realm , user 和 passwd 必须是字符串。当给出对 realm *的身份验证以及任何给定 URI 的超级 URI 时,这将使
(user, passwd)
用作身份验证令牌。
- uri *可以是单个 URI 或 URI 序列。 * realm , user 和 passwd 必须是字符串。当给出对 realm *的身份验证以及任何给定 URI 的超级 URI 时,这将使
-
HTTPPasswordMgr.
find_user_password
(* realm , authuri *)- 获取给定领域和 URI(如果有)的用户/密码。如果没有匹配的用户/密码,此方法将返回
(None, None)
。
- 获取给定领域和 URI(如果有)的用户/密码。如果没有匹配的用户/密码,此方法将返回
对于HTTPPasswordMgrWithDefaultRealm个对象,如果给定的* realm *没有匹配的用户名/密码,将搜索None
领域。
HTTPPasswordMgrWithPriorAuth Objects
此密码 Management 器扩展了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 *被忽略。
- realm , uri , user , passwd *与HTTPPasswordMgr.add_password()相同。 * is_authenticated 为给定的 URI 或 URI 列表设置
-
HTTPPasswordMgr.
find_user_password
(* realm , authuri *)HTTPPasswordMgrWithPriorAuth.
update_authenticated
(* self , uri , is_authenticated = False *)- 为给定的* uri *或 URI 列表更新
is_authenticated
标志。
- 为给定的* uri *或 URI 列表更新
HTTPPasswordMgrWithPriorAuth.
is_authenticated
(* self , authuri *)- 返回给定 URI 的
is_authenticated
标志的当前状态。
- 返回给定 URI 的
AbstractBasicAuthHandler Objects
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"
则可以)。
HTTPBasicAuthHandler Objects
HTTPBasicAuthHandler.
http_error_401
(* req , fp , code , msg , hdrs *)- 重试带有身份验证信息的请求(如果有)。
ProxyBasicAuthHandler Objects
ProxyBasicAuthHandler.
http_error_407
(* req , fp , code , msg , hdrs *)- 重试带有身份验证信息的请求(如果有)。
AbstractDigestAuthHandler Objects
AbstractDigestAuthHandler.
http_error_auth_reqed
(* authreq , host , req , headers *)-
- authreq 应该是请求中包含有关领域信息的 Headers 名称, host 应该是要向其进行身份验证的主机, req 应该是(失败的)Request对象,而 headers *应该是错误标题。
-
HTTPDigestAuthHandler Objects
HTTPDigestAuthHandler.
http_error_401
(* req , fp , code , msg , hdrs *)- 重试带有身份验证信息的请求(如果有)。
ProxyDigestAuthHandler Objects
ProxyDigestAuthHandler.
http_error_407
(* req , fp , code , msg , hdrs *)- 重试带有身份验证信息的请求(如果有)。
HTTPHandler Objects
HTTPHandler.
http_open
(* req *)- 发送 HTTP 请求,该请求可以是 GET 或 POST,具体取决于
req.has_data()
。
- 发送 HTTP 请求,该请求可以是 GET 或 POST,具体取决于
HTTPSHandler Objects
HTTPSHandler.
https_open
(* req *)- 发送 HTTPS 请求,该请求可以是 GET 或 POST,具体取决于
req.has_data()
。
- 发送 HTTPS 请求,该请求可以是 GET 或 POST,具体取决于
FileHandler Objects
FileHandler.
file_open
(* req *)- 如果没有主机名,或者主机名是
'localhost'
,请在本地打开文件。
- 如果没有主机名,或者主机名是
在版本 3.2 中更改:此方法仅适用于 localhost 名。给定远程主机名时,将引发URLError。
DataHandler Objects
DataHandler.
data_open
(* req *)- 读取数据 URL。这种 URL 包含在 URL 本身中编码的内容。数据 URL 语法在 RFC 2397中指定。此实现忽略 base64 编码的数据 URL 中的空格,因此该 URL 可以包装在它来自的任何源文件中。但是,即使某些浏览器不介意在 base64 编码的数据 URL 末尾缺少填充,在这种情况下,此实现也会引发ValueError。
FTPHandler Objects
FTPHandler.
ftp_open
(* req *)- 打开* req *指示的 FTP 文件。登录始终使用空的用户名和密码完成。
CacheFTPHandler Objects
CacheFTPHandler个对象是FTPHandler个对象,具有以下其他方法:
CacheFTPHandler.
setTimeout
(* t *)- 将连接超时设置为* t *秒。
CacheFTPHandler.
setMaxConns
(* m *)- 将最大缓存连接数设置为* m *。
UnknownHandler Objects
UnknownHandler.
unknown_open
( )- 引发URLError异常。
HTTPErrorProcessor Objects
HTTPErrorProcessor.
http_response
(* request , response *)- 处理 HTTP 错误响应。
对于 200 个错误代码,将立即返回响应对象。
对于非 200 错误代码,这只是passOpenerDirector.error()将作业传递给http_error_<type>()
处理程序方法。finally,如果没有其他处理程序处理该错误,则HTTPDefaultErrorHandler将引发HTTPError。
HTTPErrorProcessor.
https_response
(* request , response *)- 处理 HTTPS 错误响应。
行为与http_response()相同。
Examples
除以下示 exception,如何使用 urllib 程序包获取 Internet 资源中还提供了更多示例。
本示例获取 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 *编码,因此我们将使用相同的编码来解码 bytes 对象。
>>> 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 的标准 Importing,并读取返回给我们的数据。请注意,此示例仅在 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()默认提供许 multiprocessing 程序,包括ProxyHandler。默认情况下,ProxyHandler使用名为<scheme>_proxy
的环境变量,其中<scheme>
是涉及的 URL 方案。例如,读取 http_proxy
环境变量以获得 HTTP 代理的 URL。
本示例将默认的ProxyHandler替换为使用以编程方式提供的代理 URL 的 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')
添加 HTTPHeaders:
使用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 *Headers。要更改此设置:
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())时,会添加一些标准 Headers(* 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 输出的参数作为数据发送到 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')
...
Legacy interface
以下函数和类是从 Python 2 模块urllib
(与urllib2
相对)移植的。他们可能会在将来的某个时候被弃用。
urllib.request.
urlretrieve
(* url , filename = None , reporthook = None , data = None *)
第二个参数(如果存在)指定要复制到的文件位置(如果不存在,该位置将是具有生成名称的临时文件)。第三个参数(如果存在)是可调用的,它将在构建网络连接时被调用一次,此后每个块读取一次。可调用对象将被传递三个参数。到目前为止已传输的块数,块大小(以字节为单位)以及文件的总大小。第三个参数在旧的 FTP 服务器上可能是-1
,这些 FTP 服务器不会响应检索请求而返回文件大小。
以下示例说明了最常见的使用情况:
>>> 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()Function。
当urlretrieve()检测到可用数据量小于预期量(即* Content-Length *Headers 报告的大小)时,它将引发ContentTooShortError
。例如,当下载break时,可能会发生这种情况。
- Content-Length *被视为下限:如果要读取的数据更多,则 urlretrieve 读取更多的数据,但是如果可用的数据较少,则会引发异常。
在这种情况下,您仍然可以检索下载的数据,该数据存储在异常实例的content
属性中。
如果未提供* Content-Length *Headers,则 urlretrieve 无法检查已下载数据的大小,而仅返回它。在这种情况下,您只需要假设下载成功即可。
urllib.request.
urlcleanup
( )- 清理以前调用urlretrieve()可能留下的临时文件。
类别
urllib.request.
URLopener
(代理=无,*** x509 *)- 从版本 3.3 开始不推荐使用。
用于打开和读取 URL 的 Base Class。除非您需要使用http:
,ftp:
或file:
以外的方案来支持打开对象,否则您可能要使用FancyURLopener。
默认情况下,URLopener类发送urllib/VVV
的* User-Agent Headers,其中 VVV 是urllib版本号。应用程序可以pass将URLopener或FancyURLopener子类化并将类属性version设置为子类定义中的适当字符串值来定义自己的 User-Agent *Headers。
可选的* proxies *参数应该是字典 Map 方案名称到代理 URL,其中空的字典会完全关闭代理。它的默认值为None
,在这种情况下,将使用环境代理设置(如果存在),如上面的urlopen()的定义中所述。
使用https:
方案时,在* x509 中收集的其他关键字参数可用于 Client 端的身份验证。支持关键字 key_file 和 cert_file *来提供 SSL 密钥和证书。两者都需要支持 Client 端身份验证。
如果服务器返回错误代码,则URLopener个对象将引发OSError异常。
open
(* fullurl , data = None *)- 使用适当的协议打开* fullurl *。该方法设置缓存和代理信息,然后使用其 Importing 参数调用相应的 open 方法。如果无法识别该方案,则调用open_unknown()。 * data 参数的含义与urlopen()的 data *参数相同。
此方法始终使用quote()引用* fullurl *。
open_unknown
(* fullurl , data = None *)- 可覆盖的接口,用于打开未知的 URL 类型。
retrieve
(* url , filename = None , reporthook = None , data = None *)- 检索* url 的内容并将其放在 filename 中。返回值是一个由本地文件名和包含响应 Headers(对于远程 URL)或
None
(对于本地 URL)的email.message.Message对象组成的 Tuples。然后,调用者必须打开并阅读 filename 的内容。如果未提供 filename 并且 URL 指向本地文件,则返回 Importing 文件名。如果 URL 是 nonlocal 的,并且未提供 filename ,则文件名是tempfile.mktemp()的输出,其后缀与 ImportingURL 的最后一个路径部分的后缀相匹配。如果给出了 reporthook *,它必须是一个接受三个数字参数的函数:块号,最大块数被读取以及下载的总大小(如果未知,则为-1)。在开始时以及从网络读取每个数据块之后,它将被调用一次。 * reporthook *对于本地 URL 被忽略。
- 检索* url 的内容并将其放在 filename 中。返回值是一个由本地文件名和包含响应 Headers(对于远程 URL)或
如果* url 使用http:
方案标识符,则可以提供可选的 data *参数以指定POST
请求(通常,请求类型为GET
)。 * data 参数必须采用标准 application/x-www-form-urlencoded *格式;参见urllib.parse.urlencode()Function。
version
- 指定打开器对象的用户代理的变量。若要使urllib告知服务器它是特定的用户代理,请在调用基本构造函数之前,在子类中将其设置为类变量或在构造函数中进行设置。
类别
urllib.request.
FancyURLopener
(* ... *)- 从版本 3.3 开始不推荐使用。
FancyURLopener子类URLopener为以下 HTTP 响应代码提供默认处理:301、302、303、307 和 401.对于上面列出的 30x 响应代码,* Location Headers 用于获取实际的 URL。对于 401 响应代码(需要身份验证),将执行基本的 HTTP 身份验证。对于 30 倍的响应代码,递归以 maxtries *属性的值为界,默认值为 10.
对于所有其他响应代码,将调用方法http_error_default()
,您可以在子类中覆盖该方法以适当地处理错误。
Note
构造函数的参数与URLopener的参数相同。
Note
执行基本身份验证时,FancyURLopener实例将调用其prompt_user_passwd()方法。默认实现是在控制终端上向用户询问所需的信息。如果需要,子类可以重写此方法以支持更适当的行为。
FancyURLopener类提供了另一种方法,应重载以提供适当的行为:
prompt_user_passwd
(* host , realm *)- 返回在指定安全领域中给定主机上对用户进行身份验证所需的信息。返回值应该是一个 Tuples
(user, password)
,可以用于基本身份验证。
- 返回在指定安全领域中给定主机上对用户进行身份验证所需的信息。返回值应该是一个 Tuples
实现会在终端上提示 Importing 此信息。应用程序应重写此方法,以在本地环境中使用适当的交互模型。
urllib.request Restrictions
Note
- 当前,仅支持以下协议:HTTP(0.9 和 1.0 版本),FTP,本地文件和数据 URL。
在版本 3.4 中进行了更改:添加了对数据 URL 的支持。
urlretrieve()的缓存Function已被禁用,直到有人找到时间来正确处理到期时间 Headers 为止。
应该有一个查询缓存中是否有特定 URL 的Function。
为了向后兼容,如果 URL 似乎指向本地文件,但无法打开该文件,则使用 FTP 协议重新解释 URL。有时这可能会导致混淆的错误消息。
urlopen()和urlretrieve()函数在 await 构建网络连接时可能会导致任意长的延迟。这意味着不使用线程就很难使用这些Function构建交互式 WebClient 端。
urlopen()或urlretrieve()返回的数据是服务器返回的原始数据。这可以是二进制数据(例如图像),纯文本或(例如)HTML。 HTTP 协议在回复 Headers 中提供类型信息,可以pass查看* Content-Type *Headers 来检查类型信息。如果返回的数据是 HTML,则可以使用模块html.parser对其进行解析。
处理 FTP 协议的代码无法区分文件和目录。try读取指向不可访问文件的 URL 时,这可能导致意外行为。如果 URL 以
/
结尾,则假定引用目录,并将对其进行相应处理。但是,如果try读取文件导致 550 错误(意味着通常出于权限原因而导致找不到 URL 或无法访问该 URL),则该路径将被视为目录,以便处理指定目录时的情况pass URL,但尾部的/
已被保留。当您try获取其读取权限使其无法访问的文件时,这可能会导致误导结果。 FTP 代码将try读取它,并以 550 错误失败,然后对不可读文件执行目录列表。如果需要细粒度的控制,请考虑使用ftplib模块,子类FancyURLopener或更改* _urlopener *以满足您的需求。
urllib.response — urllib 使用的响应类
urllib.response模块定义了函数和类,这些函数和类定义了一个最小的文件(如read()
和readline()
),例如 interface。典型的响应对象是 addinfourl 实例,该实例定义info()
方法并返回 Headers,而geturl()
方法则返回 url。该模块定义的Function由urllib.request模块内部使用。