python 2.7 的urllib模块中文

可能有些地方翻译的不够，还请指正，转载请注明出处哈！

20.5. urllib — Open arbitrary resources by URL

This module provides a high-level interface for fetching data across the World Wide Web. In particular, the urlopen() function is similar to the built-in function open(), but accepts Universal Resource Locators (URLs) instead of filenames. Some restrictions apply — it can only open URLs for reading, and no seek operations are available.

这接口提供一个高级接口去www获取数据，特别的，urlopen功能类似内置open功能，除了前者是接受urls而不是filenames，有些对此有约束性的应用--它可以仅仅打开urls去读取，并且不提供查找操作符的功能。

20.5.1. 高级接口

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

Open a network object denoted by a URL for reading. If the URL does not have a scheme identifier, or if it has file: as its scheme identifier, this opens a local file (without universal newlines); otherwise it opens a socket to a server somewhere on the network. If the connection cannot be made the IOError exception is raised. If all went well, a file-like object is returned. This supports the following methods: read(), readline(), readlines(), fileno(), close(), info(), getcode() and geturl(). It also has proper support for the iterator protocol. One caveat: the read() method, if the size argument is omitted or negative, may not read until the end of the data stream; there is no good way to determine that the entire stream from a socket has been read in the general case.

Except for the info(), getcode() and geturl() methods, these methods have the same interface as for file objects — see section File Objects in this manual. (It is not a built-in file object, however, so it can’t be used at those few places where a true built-in file object is required.)

打开一个由url表示的网络对象进行读取，如果url没有指定一个编码标识符，或者如果它是文件：就像它的编码标识符，将打开一个本地文件（没有通用换行符）；（没指定）否则它在网络上打开一个socket到一个服务器的某处。如果IOException异常已经引发，连接将不成功。如果一切正常，一个文件对象将被返回。这支持以下方法：read，readline，fileno，close，info，getcode，geturl。

它也尽可能的支持iterator协议。一个告诫：read方法，如果size变量被省略或者负值，可能都不会读取，直到数据流的末端；这不是一个好的方式去决定一般情况下来自socket的整个流却已经被读取。除了info(), getcode() and geturl()以外，这些方法（指其余）有一样的接口作为文件对象--查看本手册的FileObjects部分 （它不是一个内置的文件对象，但是，它不能被用作需要的确需要内置文件对象的少数地方）

 

The info() method returns an instance of the class mimetools.Message containing meta-information associated with the URL. When the method is HTTP, these headers are those returned by the server at the head of the retrieved HTML page (including Content-Length and Content-Type). When the method is FTP, a Content-Length header will be present if (as is now usual) the server passed back a file length in response to the FTP retrieval request. A Content-Type header will be present if the MIME type can be guessed. When the method is local-file, returned headers will include a Date representing the file’s last-modified time, a Content-Length giving file size, and a Content-Type containing a guess at the file’s type. See also the description of the mimetools module.

Info方法返回一个mimetools.Message类的实例，这类包括连接url的元信息。当这方法是http下的，这些头部是从服务器返回来的获取的html页面头部信息（包括Content-Length and Content-Type）。当方法是ftp下的，如果（就像平时一样）服务器回传一个文件长度作为回复给FTP的获取请求，Content-Length 头部将会存在。如果MIME类型可以被确定，Content-Type头部将存在。当是在本地文件的情况下，返回的头部将包含一个描述最后一次定义这文件的时间，Content-Length负责给予大小信息，Content-Type负责确定的文件类型。参见mimetools模块

The geturl() method returns the real URL of the page. In some cases, the HTTP server redirects a client to another URL. The urlopen() function handles this transparently, but in some cases the caller needs to know which URL the client was redirected to. The geturl() method can be used to get at this redirected URL.

Geturl方法返回页面真实的url。有些情况下，http服务器重定向给客户端一个其他的url。Urlopen方法很明显地可以把弄它，但是有些情况下来访者需要知道客户端（）被重定向去哪个url了，在此情况下，Geturl方法可以被用来获取url。

The getcode() method returns the HTTP status code that was sent with the response, or None if the URL is no HTTP URL.

Getcode方法返回一个http状态码，如果不是HTTP url那么返回None

If the url uses the http: scheme identifier, the optional data argument may be given to specify a POST request (normally the request type is GET). The data argument must be in standard application/x-www-form-urlencoded format; see the urlencode() function below.

如果url使用http：标识符，选项data变量可能被用来定义POST请求（一般请求类型是GET）。Data变量必须符合application/x-www-form-urlencoded 格式；详见下面urlencode方法

The urlopen() function works transparently with proxies which do not require authentication. In a Unix or Windows environment, set the http_proxy, or ftp_proxy environment variables to a URL that identifies the proxy server before starting the Python interpreter. For example (the '%' is the command prompt):

Urlopen方法明显直接地跟不要求验证的proxies一块工作。在unix或者windows环境中，在开始启动python解释器之前，为url设置http_proxy或者ftp_proxy环境变量去辨别代理服务器。举个例子（%是命令行提示的内容）：

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

% export http_proxy

% python

...

The no_proxy environment variable can be used to specify hosts which shouldn’t be reached via proxy; if set, it should be a comma-separated list of hostname suffixes, optionally with :port appended, for example cern.ch,ncsa.uiuc.edu,some.host:8080.

No_proxy的环境变量可以被用来定义不该接触到via proxy代理的主机；如果设置了，它该变成一个有主机后缀的并以逗号分隔的列表，或者：port 尾部附加上去，例如：cern.ch,ncsa,uiuc.edu,som.host:8080

In a Windows environment, if no proxy environment variables are set, proxy settings are obtained from the registry’s Internet Settings section.

在windows环境下，如果设置了no_proxy环境变量，代理设置将在注册的因特网设置部分取得。

In a Mac OS X environment, urlopen() will retrieve proxy information from the OS X System Configuration Framework, which can be managed with Network System Preferences panel.

苹果·~~

Alternatively, the optional proxies argument may be used to explicitly specify proxies. It must be a dictionary mapping scheme names to proxy URLs, where an empty dictionary causes no proxies to be used, and None (the default value) causes environmental proxy settings to be used as discussed above. For example:

或者，proxies变量可能明确地被用来定义代理。它必须是一个字典映射的名字给代理urls，在此空的字典会导致没有代理来使用，并且None（也就是缺省值）会导致上述相关环境的（windows，unix等等）代理设置将被使用,例如：

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

Proxies which require authentication for use are not currently supported; this is considered an implementation limitation.

需要使用带验证的proxies在目前并不支持；这是实现上的限制

The context parameter may be set to a ssl.SSLContext instance to configure the SSL settings that are used if urlopen() makes a HTTPS connection.

Context属性可能被设置到一个ssl.SSLContext实例去配置在urlopen去连接https的情况下的ssl 的设定。

Changed in version 2.3: Added the proxies support.

Changed in version 2.6: Added getcode() to returned object and support for the no_proxy environment variable.

Changed in version 2.7.9: The context parameter was added.

Deprecated since version 2.6: The urlopen() function has been removed in Python 3 in favor of urllib2.urlopen().

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

Copy a network object denoted by a URL to a local file, if necessary. If the URL points to a local file, or a valid cached copy of the object exists, the object is not copied. Return a tuple (filename, headers) where filename is the local file name under which the object can be found, and headers is whatever the info() method of the object returned by urlopen() returned (for a remote object, possibly cached). Exceptions are the same as for urlopen().

如有需要，复制一个 通过url表示的网络对象 到本地文件。如果url指向本地文件，或者指向已存在的一个合法的对象缓存副本，那么对象将不被复制。文件名就是基于这个对象被找到的本地文件名，头部就是通过urlopen方法返回的（对远程的对象，尽可能地缓存），然后这对象info方法返回的一切数据，返回一个数组（文件名，头部）。异常跟urlopen方法抛出的一样。

The second argument, if present, specifies the file location to copy to (if absent, the location will be a tempfile with a generated name). The third argument, if present, is a hook function that will be called once on establishment of the network connection and once after each block read thereafter. The hook will be passed three arguments; a count of blocks transferred so far, a block size in bytes, and the total size of the file. The third argument may be -1 on older FTP servers which do not return a file size in response to a retrieval request.

第二个变量，如果写了，定义文件的位置（如果缺省，位置就是生成的临时文件的位置）。

第三个变量，如果写了，一旦访问一次网络连接和一旦每个块读了之后，这功能将被唤起。这货有三个变量：到今为止的大量已经转化的块，byte表示大小的块，文件的大小。这个变量（reporthook）在老ftp服务器可能是-1，它并不能在response中返回文件大小给 获取请求。

If the url uses the http: scheme identifier, the optional data argument may be given to specify a POST request (normally the request type is GET). The data argument must in standard application/x-www-form-urlencoded format; see the urlencode() function below.

如果url使用http：标识符，选项data变量可能被用来定义POST请求（一般请求类型是GET）。Data变量必须符合application/x-www-form-urlencoded 格式；详见下面urlencode方法

 

Changed in version 2.5: urlretrieve() will raise ContentTooShortError when it detects that the amount of data available was less than the expected amount (which is the size reported by a Content-Length header). This can occur, for example, when the download is interrupted.

2.5版本变化：当它检测到一大堆有效的data少于Content-Length header要求的大小时，urlretrieve() will raise ContentTooShortError。例如在下载被中断就会引发。

The Content-Length is treated as a lower bound: if there’s more data to read, urlretrieve() reads more data, but if less data is available, it raises the exception.

Content-Length 被看作在更低级的范围：如果有更多的数据要读，urlretrieve() 可以读取更多的数据，但是如果很少有效的数据，仍会引发异常。

You can still retrieve the downloaded data in this case, it is stored in the content attribute of the exception instance.

你可以在这种情况下获取下载的数据，它存在于异常实例的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.

如果没有Content-Length 头部，urlretrieve() 不会检查下载的数据大小，只是返回它而已。在此你仅仅需要猜想下载成功了就行。

 

 

The urlopen() and urlretrieve() functions can cause arbitrarily long delays while waiting for a network connection to be set up. This means that it is difficult to build an interactive Web client using these functions without using threads.

urlopen() and urlretrieve()这两个方法再等待网络连接的设置时候可以导致任意长度的延迟。这意味着如果没用线程，会很难去建立在使用前面方法的一个交互式的网页客户端。

· 

The data returned by urlopen() or urlretrieve() is the raw data returned by the server. This may be binary data (such as an image), plain text or (for example) HTML. The HTTP protocol provides type information in the reply header, which can be inspected by looking at the Content-Type header. If the returned data is HTML, you can use the module htmllib to parse it.

通过urlopen() or urlretrieve()返回服务器返回的原数据，这可能是二进制数据类如图像，纯文本或者HTML，HTTP协议再reply header提供类型信息，它可以通过查看Content-Type header进行检查，如果返回的data是HTML，你可以使用htmllib模块去解析它。

· 

The code handling the FTP protocol cannot differentiate between a file and a directory. This can lead to unexpected behavior when attempting to read a URL that points to a file that is not accessible. If the URL ends in a /, it is assumed to refer to a directory and will be handled accordingly. But if an attempt to read a file leads to a 550 error (meaning the URL cannot be found or is not accessible, often for permission reasons), then the path is treated as a directory in order to handle the case when a directory is specified by a URL but the trailing / has been left off. This can cause misleading results when you try to fetch a file whose read permissions make it inaccessible; the FTP code will try to read it, fail with a 550 error, and then perform a directory listing for the unreadable file. If fine-grained control is needed, consider using the ftplib module, subclassing FancyURLopener, or changing _urlopener to meet your needs

· 处理ftp协议的代码，并不能区别区别文件与目录。这将在尝试读取一个指向文件的url导致一个未知的行为：无法连接。如果url以“/”结尾，会被设想成查阅目录并且以此进行处理。但尝试读取一个文件却导致550错误(意味着url没找到或者无法连接，一般是权限的原因)，此时当url定义了目录，但没有使用/结尾，然后它就会被当作一个目录去处理这个事件。当你试着去取一个文件，文件的读取权限导致不可连接，这将导致引人误导的结果。ftp 代码将尝试读取它，显示550错误，并然后转换成一个列出不可读属性文件的目录。如果有更加细化的控制要求，考虑吧使用ftplib模块，子类FancyURLopener，或者changing_urlopener去迎合你的需要。

· 

This module does not support the use of proxies which require authentication. This may be implemented in the future.

这模块不支持使用带验证的代理，这可能在未来才实现这功能

· 

Although the urllib module contains (undocumented) routines to parse and unparse URL strings, the recommended interface for URL manipulation is in module urlparse.

尽管urllib模块包含（文档化的）程序去解析与反解析URL字符串，对url的操作，还是建议使用urlparse模块这一接口。

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