python / 3.7.2rc1 / all / library-urllib.request.html

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

源代码: Lib/urllib/request.py


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:closeHeaders。

可选的* 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文档中指定的响应头。

对于由旧版URLopenerFancyURLopener类显式处理的 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,它们的参数fullurldataheadersmethod均取自请求对象。

在版本 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 证书。

如果 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 系统注册表中查找代理信息。如果小写和大写环境变量都存在(并且不同意),则首选小写。

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 请求的抽象。
  • url *应该是包含有效 URL 的字符串。

  • data 必须是指定要发送到服务器的其他数据的对象,如果不需要,则为None。当前,HTTP 请求是唯一使用 data 的请求。受支持的对象类型包括字节,类似文件的对象以及类似字节的对象的可迭代对象。如果没有提供Content-LengthTransfer-EncodingHeaders 字段,则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-AgentHeaders 值,该值由浏览器用来标识自己–一些 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-TypeHeaders。如果尚未提供此 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 系统配置框架检索代理信息。

要禁用自动检测到的代理,请传递一个空字典。

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_authenticatedMap 的数据库。可以由 BasicAuth 处理程序用来确定何时立即发送身份验证凭据,而不是先 await401响应。

3.5 版中的新Function。

    • class * urllib.request. AbstractBasicAuthHandler(* password_mgr = None *)
    • 这是一个混合类,可帮助对远程主机和代理进行 HTTP 身份验证。 * password_mgr (如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。如果 passwd_mgr *还提供is_authenticatedupdate_authenticated方法(请参见HTTPPasswordMgrWithPriorAuth Objects),则处理程序将使用is_authenticated结果用于给定的 URI 以确定是否随请求发送身份验证凭据。如果is_authenticated返回 URI 的True,则发送凭据。如果is_authenticatedFalse,则不发送凭据,然后,如果收到401响应,则使用身份验证凭据重新发送请求。如果身份验证成功,则会调用update_authenticated来为 URI 设置is_authenticated True,以便对 URI 或其任何超级 URI 的后续请求将自动包含身份验证凭据。

3.5 版的新Function:添加了is_authenticated支持。

    • class * urllib.request. HTTPBasicAuthHandler(* password_mgr = None *)
    • 使用远程主机处理身份验证。 * password_mgr *(如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。出现错误的身份验证方案时,HTTPBasicAuthHandler 将引发ValueError
    • class * urllib.request. ProxyBasicAuthHandler(* password_mgr = None *)
    • class * urllib.request. AbstractDigestAuthHandler(* password_mgr = None *)
    • 这是一个混合类,可帮助对远程主机和代理进行 HTTP 身份验证。 * password_mgr *(如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。
    • class * urllib.request. HTTPDigestAuthHandler(* password_mgr = None *)
    • 使用远程主机处理身份验证。 * password_mgr *(如果提供)应该与HTTPPasswordMgr兼容;有关必须支持的接口的信息,请参阅第HTTPPasswordMgr Objects节。当同时添加了摘要身份验证处理程序和基本身份验证处理程序时,始终首先try摘要身份验证。如果摘要式身份验证再次返回 40x 响应,则会将其发送到基本身份验证处理程序进行处理。当使用除 Digest 或 Basic 之外的身份验证方案时,此 Handler 方法将引发ValueError

在版本 3.3 中进行了更改:在不受支持的身份验证方案上提高ValueError

    • class * urllib.request. ProxyDigestAuthHandler(* password_mgr = None *)
  • 类别 urllib.request. HTTPHandler

    • 一个用于处理 HTTP URL 的类。
    • class * urllib.request. HTTPSHandler(* debuglevel = 0 context = None check_hostname = None *)

在 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.dataNone则返回'GET',否则返回'POST'。这仅对 HTTP 请求有意义。

在版本 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 错误。
  • <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>()方法。

返回的值和引发的异常与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调用。它应返回OpenerDirectorNoneopen()的返回值中所述的文件状对象。除非发生 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

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

如果为 HTTPRedirectHandler 提供的重定向 URL 不是 HTTP,HTTPS 或 FTP URL,则出于安全考虑而引发HTTPError异常。

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

Note

此方法的默认实现未严格遵循 RFC 2616,即 RFC 2616POST请求的响应不得未经用户确认而自动重定向。实际上,浏览器确实允许这些响应的自动重定向,将 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 *)

  • HTTPRedirectHandler. http_error_303(* req fp code msg hdrs *)

  • HTTPRedirectHandler. http_error_307(* req fp code msg hdrs *)

HTTPCookieProcessor Objects

HTTPCookieProcessor个实例具有一个属性:

ProxyHandler Objects

  • ProxyHandler.<protocol>_open(request)

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

HTTPPasswordMgr Objects

这些方法可用于HTTPPasswordMgrHTTPPasswordMgrWithDefaultRealm对象。

  • 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领域。

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 *被忽略。
  • HTTPPasswordMgr. find_user_password(* realm authuri *)

  • HTTPPasswordMgrWithPriorAuth. update_authenticated(* self uri is_authenticated = False *)

    • 为给定的* uri *或 URI 列表更新is_authenticated标志。
  • HTTPPasswordMgrWithPriorAuth. is_authenticated(* self authuri *)

    • 返回给定 URI 的is_authenticated标志的当前状态。

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

HTTPSHandler Objects

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

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

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 *)
    • 将 URL 表示的网络对象复制到本地文件。如果 URL 指向本地文件,则除非提供文件名,否则不会复制该对象。返回一个 Tuples(filename, headers),其中* filename 是可以在其中找到对象的本地文件名,而 headers *则是返回urlopen()返回的对象的info()方法(对于远程对象)。exception 与urlopen()相同。

第二个参数(如果存在)指定要复制到的文件位置(如果不存在,该位置将是具有生成名称的临时文件)。第三个参数(如果存在)是可调用的,它将在构建网络连接时被调用一次,此后每个块读取一次。可调用对象将被传递三个参数。到目前为止已传输的块数,块大小(以字节为单位)以及文件的总大小。第三个参数在旧的 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 ( )

  • 类别 urllib.request. URLopener(代理=无,*** x509 *)

    • 从版本 3.3 开始不推荐使用。

用于打开和读取 URL 的 Base Class。除非您需要使用http:ftp:file:以外的方案来支持打开对象,否则您可能要使用FancyURLopener

默认情况下,URLopener类发送urllib/VVV的* User-Agent Headers,其中 VVV urllib版本号。应用程序可以pass将URLopenerFancyURLopener子类化并将类属性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 使用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

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

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

Note

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

FancyURLopener类提供了另一种方法,应重载以提供适当的行为:

  • prompt_user_passwd(* host realm *)
    • 返回在指定安全领域中给定主机上对用户进行身份验证所需的信息。返回值应该是一个 Tuples(user, password),可以用于基本身份验证。

实现会在终端上提示 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模块内部使用。