urllib

注意

该urllib模块已经被分成部分和在Python 3重命名为urllib.request，urllib.parse，和urllib.error。该2to3的转换你的源代码时，Python 3的另外请注意，该工具会自动适应进口urllib.request.urlopen()在Python 3功能相当于urllib2.urlopen()并且urllib.urlopen()已被删除。

该模块提供了一个高级接口，用于通过万维网获取数据。特别是，该urlopen()函数与内置函数类似open()，但接受通用资源定位符（URL）而不是文件名。有些限制适用 - 它只能打开URL进行阅读，并且没有可用的查找操作。

在版本2.7.9中进行了更改：对于HTTPS URI，urllib默认情况下执行所有必需的证书和主机名检查。

警告

对于早于2.7.9的Python版本，urllib不会尝试验证HTTPS URI的服务器证书。使用需要您自担风险！

1.高级界面

urllib.urlopen(url[, data[, proxies[, context]]])

打开一个由URL表示的网络对象以供阅读。如果URL没有方案标识符，或者它有方案标识符，则会file:打开一个本地文件（没有通用换行符）; 否则它会打开一个到网络上某个服务器的套接字。如果无法建立连接，IOError则引发异常。如果一切顺利，将返回一个类似文件的对象。这支持了以下方法：read()，readline()，readlines()，fileno()，close()，info()，getcode()和geturl()。它也对迭代器协议有适当的支持。一个警告：read()方法，如果size参数被省略或者是否定的，则可能直到数据流结束才读取; 在一般情况下，没有好方法可以确定来自套接字的整个流已被读取。

除info()，getcode()和geturl()方法，这些方法具有相同的界面，文件对象-见文件对象这份手册里。（但它不是内置的文件对象，所以它不能用于需要真正的内置文件对象的地方。）

该info()方法返回mimetools.Message包含与URL关联的元信息的类的一个实例。当方法是HTTP时，这些头部是服务器在检索到的HTML页面的头部（包括Content-Length和Content-Type）返回的头部。当方法是FTP时，如果服务器响应FTP检索请求传回一个文件长度（如现在一样），则会出现一个Content-Length头。如果可以猜出MIME类型，则会出现Content-Type标头。当方法是本地文件时，返回的头文件将包含表示文件上次修改时间的Date，给出文件大小的Content-Length和包含文件类型猜测的Content-Type。另请参阅mimetools模块的说明。

该geturl()方法返回页面的真实URL。在某些情况下，HTTP服务器会将客户端重定向到另一个URL。该urlopen()函数透明地处理这个问题，但在某些情况下，调用者需要知道客户端重定向到哪个URL。该geturl()方法可用于获取此重定向的URL。

该getcode()方法返回与响应一起发送的HTTP状态代码，或者None该URL不包含HTTP URL。

如果URL使用http:方案标识符，则可以给出可选的数据参数来指定POST请求（通常请求类型是GET）。的数据参数必须是在标准应用程序/ x-WWW窗体-urlencoded格式; 请参阅urlencode()下面的功能。

该urlopen()功能透明地与不需要认证的代理工作。在Unix或Windows环境中，在启动Python解释器之前，将环境变量http_proxy或ftp_proxy环境变量设置为标识代理服务器的URL。例如（这'%'是命令提示符）：

% http_proxy="http://www.someproxy.com:3128"
% export http_proxy
% python
...

该no_proxy环境变量可用于指定不应通过代理达到的主机; 如果设置，它应该是逗号分隔的主机名后缀列表，可选地:port附加后缀，例如cern.ch,ncsa.uiuc.edu,some.host:8080。

在Windows环境中，如果未设置代理环境变量，则代理设置将从注册表的“Internet设置”部分获取。

在Mac OS X环境中，urlopen()将从OS X系统配置框架中检索代理信息，可通过网络系统首选项面板进行管理。

或者，可选的代理参数可用于显式指定代理。它必须是字典映射方案名称以代理URL，其中空字典不会导致使用代理，并且None（默认值）会导致如上所述使用环境代理设置。例如：

# Use http://www.someproxy.com:3128 for HTTP proxying
proxies = {'http': 'http://www.someproxy.com:3128'}
filehandle = urllib.urlopen(some_url, proxies=proxies)
# Don't use any proxies
filehandle = urllib.urlopen(some_url, proxies={})
# Use proxies from environment - both versions are equivalent
filehandle = urllib.urlopen(some_url, proxies=None)
filehandle = urllib.urlopen(some_url)

目前不支持需要使用认证的代理; 这被视为实施限制。

该情境参数可以设置为一个ssl.SSLContext实例来配置如果使用SSL设置urlopen()使得HTTPS连接。

在版本2.3中更改：添加了代理支持。

在版本2.6中进行了更改：添加getcode()到返回的对象并支持no_proxy环境变量。

在版本2.7.9中更改：已添加上下文参数。所有必需的证书和主机名检查都是默认完成的。

自2.6版弃用：该urlopen()功能已在Python 3中被删除，以支持urllib2.urlopen()。

urllib.urlretrieve(url[, filename[, reporthook[, data]]])

如有必要，将由URL表示的网络对象复制到本地文件。如果URL指向本地文件，或者该对象的有效缓存副本存在，则不会复制该对象。返回一个元组(filename, headers)，其中filename是可以找到该对象的本地文件名，而headers是info()返回的对象的方法urlopen()（对于可能缓存的远程对象）。例外情况与之相同urlopen()。

第二个参数（如果存在）指定要复制到的文件位置（如果不存在，则该位置将是具有生成名称的临时文件）。第三个参数（如果存在的话）是一个钩子函数，在建立网络连接时会被调用一次，之后每个块被读取一次。该钩子将传递三个参数; 到目前为止传输的块的数量，以字节为单位的块大小以及文件的总大小。第三个参数可能-1在较旧的FTP服务器上，它们不响应检索请求而返回文件大小。

如果URL使用http:方案标识符，则可以给出可选的数据参数来指定POST请求（通常请求类型是GET）。的数据参数必须在标准应用程序/ x-WWW窗体-urlencoded格式; 请参阅urlencode()下面的功能。

在版本2.5中进行了更改：当它检测到可用数据量小于预期量（这是Content-Length报头报告的大小）时urlretrieve()将会增加。例如，当下载被中断时，会发生这种情况。ContentTooShortError

该内容长度被视为一个下界：如果有更多的数据读取，urlretrieve()读取更多的数据，但如果较少的数据是可用的，它引发异常。

在这种情况下，您仍可以检索下载的数据，并将其存储在content异常实例的属性中。

如果未提供Content-Length标头，urlretrieve()则无法检查已下载数据的大小，只是将其返回。在这种情况下，您只需假定下载成功。

urllib._urlopener

公共职能urlopen()并urlretrieve()创建FancyURLopener该类的一个实例并用它来执行他们所请求的操作。要覆盖此功能，程序员可以创建URLopeneror 的子类FancyURLopener，然后urllib._urlopener在调用所需的函数之前将该类的实例分配给该变量。例如，应用程序可能希望指定与定义不同的User-Agent标头URLopener。这可以用下面的代码来完成：

import urllib

class AppURLopener(urllib.FancyURLopener):
    version = "App/1.7"

urllib._urlopener = AppURLopener()

urllib.urlcleanup()

清除以前通过呼叫建立的缓存urlretrieve()。

2.实用功能

urllib.quote(string[, safe])

使用转义替换字符串中的特殊字符%xx。字母，数字和字符'_.-'从未被引用。默认情况下，此功能用于引用URL的路径部分。可选的安全参数指定不应引用的附加字符 - 其默认值为'/'。

Example: quote('/~connolly/') yields '/%7econnolly/'.

urllib.quote_plus(string[, safe])

就像quote()，但也用加号替换空格，这是在构建查询字符串进入URL时引用HTML表单值所需的。除非包含在保险箱中，否则原始字符串中的加号会被转义。它也没有安全的默认值'/'。

urllib.unquote(string)

用%xx它们的单字符替换换码。

Example: unquote('/%7Econnolly/') yields '/~connolly/'.

urllib.unquote_plus(string)

就像unquote()，但也用空格替换加号，以取消引用HTML表单值。

urllib.urlencode(query[, doseq])

将映射对象或两元素元组序列转换为“百分比编码”字符串，适合urlopen()作为可选数据参数传递给上面的元素。这对于将表单字段的字典传递给POST请求很有用。生成的字符串是一系列key=value由'&'字符分隔的对，其中键和值都使用quote_plus()上面的引号。当使用两元素元组作为查询参数时，每个元组的第一个元素是一个键，第二个元素是一个值。价值元素本身可以是一个序列，在这种情况下，如果可选参数doseq被评估为True，单独的key=value对被分隔'&'为密钥的值序列的每个元素生成。编码字符串中参数的顺序将与序列中参数元组的顺序相匹配。该urlparse模块提供的功能parse_qs()和parse_qsl()其用于解析查询字符串成Python数据结构。

urllib.pathname2url(path)

将路径的本地语法的路径名路径转换为URL的路径组件中使用的表单。这不会产生完整的网址。返回值将使用该quote()函数引用。

urllib.url2pathname(path)

将路径组件路径从百分比编码的URL 转换为路径的本地语法。这不接受完整的网址。此功能用于unquote()解码路径。

urllib.getproxies()

此帮助函数将代理服务器URL映射的方案字典返回。它以<scheme>_proxy大小写敏感的方式，首先为所有操作系统扫描环境变量，并在找不到它时，从Mac OS X系统配置Mac OS X和Windows系统注册表Windows查找代理信息。如果小写和大写环境变量都存在（并且不同意），则小写是首选。

注意

如果REQUEST_METHOD设置了环境变量（通常表示脚本正在CGI环境中运行），则环境变量HTTP_PROXY（大写_PROXY）将被忽略。这是因为该变量可以由客户端使用“Proxy：”HTTP标头注入。如果您需要在CGI环境中使用HTTP代理，请ProxyHandler明确使用，或确保变量名是小写（或至少_proxy后缀）。

注意

urllib还公开了某些实用功能，如splittype，splithost和其他解析URL到各种组件。但建议使用它urlparse来解析URL而不是直接使用这些函数。Python 3不从urllib.parse模块公开这些帮助函数。

3. URL开启器对象

class urllib.URLopener([proxies[, context[, **x509]]])

打开和阅读URL的基类。除非你需要使用比其他方案来支持开放的对象http:，ftp:或者file:，你可能想使用FancyURLopener。

默认情况下，URLopener该类将发送一个User-Agent标头urllib/VVV，其中VVV是urllib版本号。应用程序可以通过子类定义它们自己的User-Agent头，URLopener或者在子类定义FancyURLopener中将类属性version设置为合适的字符串值。

可选的代理参数应该是字典映射方案名称到代理URL，其中空字典将代理完全关闭。它的默认值是None，在这种情况下，如果存在的话，将使用环境代理设置，如urlopen()上面的定义中所讨论的。

该情境参数可以是一个ssl.SSLContext实例。如果给定，它定义开启者用于建立HTTPS连接的SSL设置。

在x509中收集的其他关键字参数可用于在使用该https:方案时验证客户端。支持关键字key_file和cert_file以提供SSL密钥和证书; 两者都需要支持客户端身份验证。

URLopenerIOError如果服务器返回错误代码，则对象将引发异常。

open(fullurl[, data])

使用适当的协议打开fullurl。此方法设置缓存和代理信息，然后使用其输入参数调用相应的open方法。如果该方案未被识别，open_unknown()则被调用。该数据参数的含义相同数据的说法urlopen()。

open_unknown(fullurl[, data])

可覆盖的界面打开未知的URL类型。

retrieve(url[, filename[, reporthook[, data]]])

检索url的内容并将其放在文件名中。返回值是由本地文件名和mimetools.Message包含响应头的对象（对于远程URL）或None（对于本地URL）组成的元组。调用者必须打开并读取文件名的内容。如果没有给出文件名并且URL指向本地文件，则返回输入文件名。如果URL非本地和文件名没有给出，则该文件的输出tempfile.mktemp()与输入URL的最后一个路径成分的后缀匹配的后缀。如果有报告给出，它必须是一个接受三个数字参数的函数。它将在每个数据块从网络中读取后调用。对于本地URL，reporthook被忽略。

如果URL使用http:方案标识符，则可以给出可选的数据参数来指定POST请求（通常请求类型是GET）。的数据参数必须在标准应用程序/ x-WWW窗体-urlencoded格式; 请参阅urlencode()下面的功能。

version

指定开启器对象的用户代理的变量。为了urllib告诉服务器它是一个特定的用户代理，在调用基础构造函数之前，在子类中将其设置为类变量或构造函数中。

class urllib.FancyURLopener(...)

FancyURLopener子类URLopener为下列HTTP响应代码提供默认处理：301,302,303,307和401.对于上面列出的30x响应代码，Location标头用于获取实际的URL。对于401响应代码（需要认证），执行基本的HTTP认证。对于30x响应代码，递归受限于maxtries属性的值，默认值为10。

对于所有其他响应代码，将http_error_default()调用该方法，您可以在子类中重写以适当地处理错误。

注意

根据RFC 2616的规定，301和302对POST请求的响应不得在没有用户确认的情况下自动重定向。实际上，浏览器确实允许自动重定向这些响应，将POST更改为GET，并urllib重现此行为。

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

注意

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

本FancyURLopener类提供了应该被重载，以提供适当的行为一个额外的方法：

prompt_user_passwd(host, realm)

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

实施提示在终端上提供这些信息; 应用程序应该重写此方法以在本地环境中使用适当的交互模型。

exception urllib.ContentTooShortError(msg[, content])

当urlretrieve()函数检测到下载的数据量小于预期量（由Content-Length标题给出）时，会引发此异常。该content属性存储下载的（并且假定被截断的）数据。

2.5版本中的新功能。

4. urllib限制

• 目前，仅支持以下协议：HTTP，（版本0.9和1.0），FTP和本地文件。

• 缓存功能urlretrieve()已被禁用，直到我找到时间来破解正确处理过期时间标题。

• 应该有一个函数来查询一个特定的URL是否在缓存中。

• 为了向后兼容，如果URL看起来指向本地文件，但文件无法打开，则使用FTP协议重新解释URL。这有时会导致混淆错误消息。

• 的urlopen()和urlretrieve()功能可能会导致任意长时间的延迟，而等待网络连接被建立。这意味着使用这些函数而不使用线程来构建交互式Web客户端是很困难的。

• 由urlopen()or 返回的urlretrieve()数据是服务器返回的原始数据。这可能是二进制数据（如图像），纯文本或（例如）HTML。HTTP协议在应答头中提供了类型信息，可以通过查看Content-Type头来检查。如果返回的数据是HTML，则可以使用该模块htmllib解析它。

• 处理FTP协议的代码不能区分文件和目录。当尝试读取指向无法访问的文件的URL时，这可能会导致意外的行为。如果URL以a结尾/，则假定引用一个目录并将相应地处理。但是，如果尝试读取文件导致550错误（意思是无法找到URL或者由于权限原因而无法访问该URL），那么该路径将被视为目录以处理指定目录时的情况由一个URL但尾随/已经被关闭了。当您尝试获取读取权限使其无法访问的文件时，这可能会导致误导性结果; FTP代码将尝试读取它，以550错误失败，然后执行不可读文件的目录列表。如果需要细粒度控制，请考虑使用ftplib模块，子类FancyURLopener或更改_urlopener以满足您的需求。

• 该模块不支持使用需要认证的代理。这可能会在未来实施。

• 虽然urllib模块包含解析和解析URL字符串的（未记录的）例程，但推荐的URL操作接口在模块中urlparse。

5.例子

以下是使用该GET方法检索包含参数的URL 的示例会话：

>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)
>>> print f.read()

以下示例使用该POST方法：

>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query", params)
>>> print f.read()

以下示例使用明确指定的HTTP代理覆盖环境设置：

>>> import urllib
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.FancyURLopener(proxies)
>>> f = opener.open("http://www.python.org")
>>> f.read()

以下示例完全不使用代理，覆盖环境设置：

>>> import urllib
>>> opener = urllib.FancyURLopener({})
>>> f = opener.open("http://www.python.org/")
>>> f.read()