Python API 翻译-urllib模块

最近工作要用到网络方面的模块，本着熟悉API的目的，顺带翻译一下Python2.7自带的文档。看到cnginx论坛上已经有人在翻译部分帐章节了，感觉自己还很菜，也不想让大家恶心，所以就先不报名去翻译了^ ^  翻译的不对的地方请大家拍砖- -

 

 

21.5. urllib-Open arbitrary resources by URL

该模块提供了一个 high-level 接口来抓取万维网上的数据。 urlopen() 函数类似于内置函数 open(), 接收的不是文件名而是一个 URL 。它有一些限制，只能够打开并读取 URL, 并不提供查找操作。

 

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

以只读方式打开一个 URL 连接，如果 URL 没有 scheme identifier ，或者以 file: 作为 scheme identifier ，此方法打开一个本地文件；否则打开一个 socket 。如果连接失败则返回 IOError 异常。如果一切正常，返回一个类似文件的对象。

它支持如下方法： read(), readline(), readlines(), fileno(), close(), info(), getcode() 和 geturl() 。

它也支持 iterator 协议。顺带说明一下：如果在 read() 方法中忘记声明参数长度或者是负数，将无法读取直到数据流结束；没有好的方法来判断整个已经读取的 socket 。

除了 info() ， getcode() and geturl() 方法，这些方法有和读取文件对象类似的接口。

 

info() 方法返回 httplib.HTTPMessage 的一个实例，包含与 URL 有关的原信息。当使用 HTTP 方法时，这些头文件由提取的 HTML 页面返回（包含内容长度和内容类型），当使用 FTP 方法时， …

 

geturl() 方法返回页面真正的 URL （当 HTTP 服务器重定向网页时）

 

getcode() 方法返回 HTTP 状态代码或者 None （如果 URL 不是 HTTP URL ）

 

如果 URL 使用 http: scheme identifier ，数据参数被认为是个 POST 请求（通常请求的类型是 GET ）。数据必须是标准的 application/x-www-form-urlencoded 格式，请参见下文的 urlencode() 函数。

 

urlopen() 函数不需要授权的代理。在 Unix 或 Windows 环境，启动 Python 解释器之前，为 URL 设置 http_proxy or ftp_proxy 环境变量来表明代理服务器。

例如：（‘ % ’是命令行提示）

% http_proxy=” http://www.someproxy.com:3128”

% export http_proxy

% python

 

no_proxy 环境变量用来声明 hosts ，不应该通过代理被访问到 ; 如果设置了，应该是以逗号分隔的由 hostname 的后缀组成的列表， :port 是可选的，例如 : cern.ch, ncsa.uiuc.edu, some.host:8080.

 

在 windows 环境中，如果没有代理环境变量，代理设置从 internet 设置部分获取。

 

可选的代理参数可以用来明确指定的代理方式。必须是一个字典，将 scheme names 映射到代理 URLs, 空的字典说明没有使用代理， None 是默认值 , 使用 Internet 默认设置。例如：

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

 

需要授权的代理目前还不支持（ 2.7 ）

 

 

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

 

复制一个由 URL 指定的网络对象到本地文件。如果 URL 指向一个本地文件，或者一个对象缓存的拷贝，对象就不会被复制。它返回元组 (filename, headers), filename 是本地文件名， headers 是 info() 方法的返回值，异常信息和 urlopen() 一样。

 

第二个参数指定要拷贝的文件的目的地。第三个参数是个 hook 函数，在网络连接时建立被调用，并且在每次读取一个块时调用一次。 hook 函数传递三个参数，目前为止转移的块的数量，一个块的字节数，和文件总的大小。第三个参数可能是 -1 ，因为老的 FTP 服务器不返回文件大小。

 

如果 url 使用 http: scheme identifier, 可选的数据参数可以用来指定给一个 POST 请求（通常请求类型是 GET ）。数据参数必须是标准的 application/x-www-form-urlencoded 格式。

 

2.5 版本中改变： urlretrieve() 会抛出 ContetnTooShortError 当他检测到数据量大小小于期望的大小（由 Contetn-Length header 报告）。当下载中断时可能发生。

Content-Length 被认为是 lower-bound ：如果有更多的数据需要读取， urlretrieve 就读取更多数据；但如果没有数据可用，将会抛出异常。

 

在这种情况下依然可以提取已经下载的书籍，它存储在异常实例的 content 属性中。

 

If no Content-Length header was supplied, urlretrieve can not check the size of the data it has downloaded, and just returns it. In this case you just have to assume that the download was successful.

 

urllib._urlopener

 

公有函数 urlopen() 和 urlretrieve() 创建 FancyURLopener 类的实例并用来执行请求。为了重写这个功能，程序员们可以创建 URLopener 或者 FancyURLopenerd 的子类，然后在调用需要函数之前，指定类的实例到 urllib._urlopener 变量。例如，有个应用想要指定不同的 USER-AGENTheader 而不是 URLopener 定义的，可以用下面的代码实现：

 

import urllib

 

class AppURLopener(urllib.FancyURLopener):

  version=”App/1.7”

urllib._urlopener=AppURLopener()

 

urllib.urlcleanup ()

清除 urlretrieve() 缓存。

 

 

 

21.5.2 .Utility functions

 

 

urllib.quote(string[,safe])

使用 %xx 替换特殊的字符 . 字母，数字 和符号 ’_.-‘ 均不会被引用替换。默认的，这个函数用来引用 URL 的路径。可选的 safe 参数指定不应该被引用的额外的字符 - 默认值是 ’/’

例如： quote (‘/~connoly/’) 产生 ‘/%7econnolly/’

 

urllib.quote_plus(string[,safe])

像 quote() 一样 , 但是还会用 + 号替换空格，用来引用由转向一个 URL 字符串发来的请求。

 

urllib.unquote(string)

 

urllib.unquote_plus(string)

 

 

 

urllib.urlencode ( query [ , doseq ] )

将映射对象或元组到一个“ url-encoded ”字符串，适用于给 urlopen （）传递数据参数。当把字典或表单提交给 POST 请求时这个函数非常有用。结果字符串是一系列的 key=value 对，由‘ & ’分隔开 ,key 和 value 都是使用 quote_plus() 。如果参数 doseq 为真，序列中每一个元素会生成独立的 key=value 对。当二元组用来充当查询参数时，第一个元素是 key, 第二个是 value ，在 encoded 字符串中参数的顺序匹配元组的顺序。 urlparse 模块提供了 parse_qs() and parse_qsl() 函数用来将查询字符串拆分成 Python 的数据结构。