urllib.request.urlretrieve()用法 【翻译官方文档】

官方文档地址

前言

因为网上很多出错的文章，并且找博客很浪费时间，就准备自己阅读官方文档，并翻译出来（顺便提升一下自己的阅读能力）

因为个人能力有限，翻译不好的地方还请指出。

正文

urllib.request.urlretrieve() 是从Python 2的urllib模块中移植过来的，之后这个函数可能被弃用。

urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)

将 URL 中的网络资源拷贝到本地。如果 URL 指定的是一个本地文件并且没有提供filename，拷贝不会被执行。该函数会返回一个二元组(filename, headers)，filename指定一个本地文件，用来存储 URL 中的网络资源，headers是调用urlopen()后的返回对象再调用info()方法后的返回值（用于远程对象）。抛出的异常类型和urlopen()相同。

对于第二个参数来说，如果这个文件存在，会将 URL 中的网络资源拷贝到这个文件中（如果不存在，本地会按照提供的文件名生成一个临时文件）。第三个参数是一个回调函数（callable），如果提供了这个函数，那么函数在连接建立时被调用一次，之后每读取到一个块都会再被调用一次。这个回调函数被传递3个参数：到目前为止收到的块数、一个块占多少字节、整个网络资源有多少块。在一些老旧的FTP服务器中可能会给第三个参数中传递-1，这些服务器不响应返回文件大小的检索请求。

下面的例子是一个常见的使用场景：

import urllib.request
local_filename, headers = urllib.request.urlretrieve('http://python.org/')
html = open(local_filename)
html.close()

如果 url 使用http:标识符（scheme identifier），在POST请求中 data 参数可以指定（通常情况下使用的请求类型都是GET）。data 参数必须满足 application/x-www-form-urlencoded 的格式要求；详细内容的可以看urllib.parse.urlencode()。

当检测到接收到的数据大小小于期望大小（网络资源的总大小，header 的 Content-Length 字段指明了该信息）时urlretrieve() 抛出 ContentTooShortError 异常。例如，当下载被截断时，该异常会被抛出。

Content-Length 被当做一个下界：当数据量多于这个大小时，urlretrieve会读取这些多出的数据，但是当数据量小于这个大小时，程序会抛出异常。

如果抛出异常，可以通过 ContentTooShortError 检索已经下载的信息。
但是如果 header 中没有 Content-Length 字段，urlretrieve不能检索该信息。在这种情况下，我们假设文件已经下载完成，不会抛出异常。