diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index e23f4c70..00000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,28 +0,0 @@ -Summary. - -## Expected Result - -What you expected. - -## Actual Result - -What happened instead. - -## Reproduction Steps - -```python -import requests - -``` - -## System Information - - $ python -m requests.help - -``` - -``` - -This command is only available on Requests v2.16.4 and greater. Otherwise, -please provide some basic information about your system (Python version, -operating system, &c). \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..a625774a --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "restructuredtext.confPath": "${workspaceFolder}\\docs" +} \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index e214b868..668902a5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,7 +7,6 @@ Requests: 让 HTTP 服务人类 ============================ 发行版本 v\ |version|. (:ref:`安装说明 `) - .. image:: https://img.shields.io/pypi/l/requests.svg :target: https://pypi.python.org/pypi/requests @@ -24,13 +23,11 @@ Requests: 让 HTTP 服务人类 .. image:: https://img.shields.io/badge/Say%20Thanks!-🦉-1EAEDB.svg :target: https://saythanks.io/to/kennethreitz -Requests 唯一的一个\ **非转基因**\的 Python HTTP 库，人类可以安全享用。 -**警告**：非专业使用其他 HTTP 库会导致危险的副作用，包括：安全缺陷症、冗余代码症、重新发明轮子\ -症、啃文档症、抑郁、头疼、甚至死亡。 +**Requests** 一个优雅、简单的 Python HTTP 库，为人类所建。 -看吧，这就是 Requests 的威力： -:: +------------------- +**看吧，Requests的力量**:: >>> r = requests.get('https://api.github.com/user', auth=('user', 'pass')) >>> r.status_code @@ -40,50 +37,29 @@ Requests 唯一的一个\ **非转基因**\的 Python HTTP 库，人类可以安 >>> r.encoding 'utf-8' >>> r.text - u'{"type":"User"...' + '{"type":"User"...' >>> r.json() - {u'private_gists': 419, u'total_private_repos': 77, ...} + {'private_gists': 419, 'total_private_repos': 77, ...} 参见 `未使用 Requests 的相似代码 `_. -Requests 允许你发送\ **纯天然，植物饲养**\的 HTTP/1.1 请求，无需手工劳动。你不需要手动为 -URL 添加查询字串，也不需要对 POST 数据进行表单编码。Keep-alive 和 HTTP 连接池的功能是 -100% 自动化的，一切动力都来自于根植在 Requests 内部的 `urllib3 `_。 - -用户见证 ------------- - -Twitter、Spotify、Microsoft、Amazon、Lyft、BuzzFeed、Reddit、NSA、女王殿下的政府、\ -Amazon、Google、Twilio、Mozilla、Heroku、PayPal、NPR、Obama for America、\ -Transifex、Native Instruments、Washington Post、Twitter、SoundCloud、Kippt、Readability、\ -以及若干不愿公开身份的联邦政府机构都在内部使用。 - -**Armin Ronacher** - Requests 是一个完美的例子，它证明了通过恰到好处的抽象，API 可以写得多么优美。 - -**Matt DeBoard** - 我要想个办法，把 @kennethreitz 写的 Python requests 模块做成纹身。一字不漏。 - -**Daniel Greenfeld** - 感谢 @kennethreitz 的 Requests 库，刚刚用 10 行代码炸掉了 1200 行意大利面代码。\ - 今天真是爽呆了！ - -**Kenny Meyers** - Python HTTP: 疑惑与否，都去用 Requests 吧。简单优美，而且符合 Python 风格。 +**Requests** 允许你极其简单地发送 HTTP/1.1 请求。 +你不需要手动为URL 添加查询字符串（quering string），也不需要对 POST 数据进行form-encode。 +Keep-alive 和 HTTP 连接池的功能是100% 自动化的，感谢 `urllib3 `_。 功能特性 --------------- -Requests 完全满足今日 web 的需求。 +Requests 准备好面对现在的互联网。 - Keep-Alive & 连接池 -- 国际化域名和 URL -- 带持久 Cookie 的会话 -- 浏览器式的 SSL 认证 -- 自动内容解码 +- 国际域名和 URLs +- 持久的带 Cookie 的Session +- 浏览器式 SSL 认证 +- 自动化内容解码 - 基本/摘要式的身份认证 -- 优雅的 key/value Cookie +- 优雅的 key/value Cookies - 自动解压 - Unicode 响应体 - HTTP(S) 代理支持 @@ -92,39 +68,43 @@ Requests 完全满足今日 web 的需求。 - 连接超时 - 分块请求 - 支持 ``.netrc`` + +Requests 官方支持 Python 2.7和3.5以上版本，而且能在 PyPy 下良好运行。 -Requests 支持 Python 2.6—2.7以及3.3—3.7，而且能在 PyPy 下完美运行。 用户指南 ---------- -这部分文档是以文字为主，从 Requests 的背景讲起，然后对 Requests 的重点功能做了逐一的介绍。 +这部分文档是以文字为主，从 Requests 的背景信息讲起，然后对 Requests 的重点功能做了逐一的介绍。 .. toctree:: :maxdepth: 2 - user/intro user/install user/quickstart user/advanced user/authentication 社区指南 ----------- +------- 这部分文档也是文字为主，详细介绍了 Requests 的生态和社区。 .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - community/faq community/recommended + community/faq community/out-there community/support community/vulnerabilities - community/updates community/release-process + .. toctree:: + :maxdepth: 1 + + community/updates + API 文档/指南 ---------------- @@ -135,17 +115,16 @@ API 文档/指南 api -贡献指南 +贡献者指南 --------- -如果你要为项目做出贡献，请参考这部分文档。 +如果你要为项目做贡献，这部分文档就是为你准备的。 .. toctree:: :maxdepth: 3 dev/contributing - dev/philosophy - dev/todo + dev/authors 没有别的指南了，你现在要靠自己了。 diff --git a/docs/user/install.rst b/docs/user/install.rst index 47cf811d..a2dc43aa 100644 --- a/docs/user/install.rst +++ b/docs/user/install.rst @@ -1,41 +1,36 @@ .. _install: 安装 Requests -============== +============= -这部分文档包含了 Requests 的安装过程，使用任何软件的第一步就是正确地安装它。 +这部分文档包含了 Requests 的安装过程。 +使用任何软件的第一步是正确地安装它。 -pip install requests ---------------------- +$ python -m pip install requests +-------------------------------- -要安装 Requests，只要在你的终端中运行这个简单命令即可： - -:: - $ pip install requests - -如果你没有安装 pip （啧啧），这个 `Python installation guide `_ -可以带你完成这一流程。 +要安装 Requests，只要在你的终端中运行这个简单命令即可:: +$ python -m pip install requests 获得源码 ------------- +------- Requests 一直在 Github 上积极地开发，你可以一直从\ -`这里 `_\获取到代码。 +`这里 `_\获取到代码。 -你可以克隆公共版本库： -:: +你可以克隆公共版本库:: - git clone git://github.com/kennethreitz/requests.git +$ git clone git://github.com/psf/requests.git 也可以下载 `tarball `_:: - $ curl -OL https://github.com/requests/requests/tarball/master + $ curl -OL https://github.com/psf/requests/tarball/master # Windows 用户也可选择 zip 包 获得代码之后，你就可以轻松的将它嵌入到你的 python 包里，或者安装到你的 site-packages:: $ cd requests - $ pip install . + $ python -m pip install . diff --git a/docs/user/intro.rst b/docs/user/intro.rst deleted file mode 100644 index 67abf373..00000000 --- a/docs/user/intro.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _introduction: - -简介 -============ - -开发哲学 ----------- - -Requests 是以 :pep:`20` 的箴言为中心开发的 - - -#. Beautiful is better than ugly.(美丽优于丑陋) -#. Explicit is better than implicit.(直白优于含蓄) -#. Simple is better than complex.(简单优于复杂) -#. Complex is better than complicated.(复杂优于繁琐) -#. Readability counts.(可读性很重要) - -对于 Requests 所有的贡献都应牢记这些重要的准则。 - -.. _`apache2`: - -Apache2 协议 -------------- - -现在你找到的许多开源项目都是以 `GPL 协议`_\发布的。虽然 GPL 有它自己的一席之地， -但在开始你的下一个开源项目时，GPL 应该不再是你的默认选择。 - -项目发行于 GPL 协议之后，就不能用于任何本身没开源的商业产品中。 - -MIT、BSD、ISC、Apache2 许可都是优秀的替代品，它们允许你的开源软件自由应用在私有闭源软件中。 - -Requests 的发布许可为 `Apache2 License`_. - -.. _`GPL 协议`: http://www.opensource.org/licenses/gpl-license.php -.. _`Apache2 License`: http://opensource.org/licenses/Apache-2.0 - - -Requests 协议 ----------------- - - .. include:: ../../LICENSE diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index be0f82f6..adf8b40c 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -1,79 +1,76 @@ .. _quickstart: 快速上手 -========== +======= .. module:: requests.models -迫不及待了吗？本页内容为如何入门 Requests 提供了很好的指引。其假设你已经安装了 Requests。\ -如果还没有，去\ :ref:`安装 `\ 一节看看吧。 +迫不及待了吗？本页内容为如何入门 Requests 提供了很好的指引。 首先，确认一下： -* Requests :ref:`已安装 ` -* Requests :ref:`是最新的 ` +* Requests 是:ref:`已安装 ` +* Requests 是:ref:`最新的 ` + 让我们从一些简单的示例开始吧。 + 发送请求 ---------- 使用 Requests 发送网络请求非常简单。 -一开始要导入 Requests 模块： - -:: +一开始要导入 Requests 模块：:: >>> import requests -然后，尝试获取某个网页。本例子中，我们来获取 Github 的公共时间线： +现在，尝试获取某个网页。本例子中，我们来获取 Github 的公共时间线： :: >>> r = requests.get('https://api.github.com/events') -现在，我们有一个名为 ``r`` 的 :class:`Response ` -对象。我们可以从这个对象中获取所有我们想要的信息。 +现在，我们有对象 :class:`Response `叫做 ``r`` 。我们可以从这个对象中获取所有我们想要的信息。 Requests 简便的 API 意味着所有 HTTP 请求类型都是显而易见的。例如，你可以这样发送一个 HTTP POST 请求： - :: >>> r = requests.post('http://httpbin.org/post', data = {'key':'value'}) 漂亮，对吧？那么其他 HTTP 请求类型：PUT，DELETE，HEAD 以及 OPTIONS 又是如何的呢？都是一样的简单： - :: - >>> r = requests.put('http://httpbin.org/put', data = {'key':'value'}) - >>> r = requests.delete('http://httpbin.org/delete') - >>> r = requests.head('http://httpbin.org/get') - >>> r = requests.options('http://httpbin.org/get') + >>> r = requests.put('https://httpbin.org/put', data = {'key':'value'}) + >>> r = requests.delete('https://httpbin.org/delete') + >>> r = requests.head('https://httpbin.org/get') + >>> r = requests.options('https://httpbin.org/get') 都很不错吧，但这也仅是 Requests 的冰山一角呢。 -传递 URL 参数 + +在 URLs 传参 ------------------- -你也许经常想为 URL 的查询字符串(query string)传递某种数据。如果你是手工构建 URL，那么数据会以键/值\ -对的形式置于 URL 中，跟在一个问号的后面。例如， ``httpbin.org/get?key=val``\。 +你经常想在 URL 的查询字符串(query string)传递某种数据。如果你是手工构建 URL，那么数据会在URL中以键/值\ +对的形式给出，跟在一个问号的后面。例如， ``httpbin.org/get?key=val``\。 Requests 允许你使用 ``params`` 关键字参数，以一个字符串字典来提供这些参数。举例来说，如果你想传递 ``key1=value1`` 和 ``key2=value2`` 到 ``httpbin.org/get`` ，那么你可以使用如下代码： :: >>> payload = {'key1': 'value1', 'key2': 'value2'} - >>> r = requests.get("http://httpbin.org/get", params=payload) + >>> r = requests.get('https://httpbin.org/get', params=payload) 通过打印输出该 URL，你能看到 URL 已被正确编码： :: >>> print(r.url) - http://httpbin.org/get?key2=value2&key1=value1 + https://httpbin.org/get?key2=value2&key1=value1 -注意字典里值为 ``None`` 的键都不会被添加到 URL 的查询字符串里。 +注意字典里值为 ``None`` 的键将不会被添加到 URL 的查询字符串里。 你还可以将一个列表作为值传入： @@ -81,12 +78,12 @@ Requests 允许你使用 ``params`` 关键字参数，以一个字符串字典 >>> payload = {'key1': 'value1', 'key2': ['value2', 'value3']} - >>> r = requests.get('http://httpbin.org/get', params=payload) + >>> r = requests.get('https://httpbin.org/get', params=payload) >>> print(r.url) - http://httpbin.org/get?key1=value1&key2=value2&key2=value3 + https://httpbin.org/get?key1=value1&key2=value2&key2=value3 响应内容 --------------- +-------- 我们能读取服务器响应的内容。再次以 GitHub 时间线为例： @@ -95,11 +92,11 @@ Requests 允许你使用 ``params`` 关键字参数，以一个字符串字典 >>> import requests >>> r = requests.get('https://api.github.com/events') >>> r.text - u'[{"repository":{"open_issues":0,"url":"https://github.com/... + '[{"repository":{"open_issues":0,"url":"https://github.com/... Requests 会自动解码来自服务器的内容。大多数 unicode 字符集都能被无缝地解码。 -请求发出后，Requests 会基于 HTTP 头部对响应的编码作出有根据的推测。当你访问 ``r.text`` +当你请求发出后，Requests 会基于 HTTP 头部对响应的编码作出有根据的推测。当你访问 ``r.text`` 之时，Requests 会使用其推测的文本编码。你可以找出 Requests 使用了什么编码，并且能够使用 ``r.encoding`` 属性来改变它： @@ -109,18 +106,17 @@ Requests 会自动解码来自服务器的内容。大多数 unicode 字符集 'utf-8' >>> r.encoding = 'ISO-8859-1' -如果你改变了编码，每当你访问 ``r.text`` ，Request 都将会使用 ``r.encoding`` -的新值。你可能希望在使用特殊逻辑计算出文本的编码的情况下来修改编码。比如 HTTP 和 XML -自身可以指定编码。这样的话，你应该使用 ``r.content`` 来找到编码，然后设置 ``r.encoding`` -为相应的编码。这样就能使用正确的编码解析 ``r.text`` 了。 +如果你改变了编码 ，Request 都将会使用 ``r.encoding`` +的新值，每当你访问 ``r.text``。你可能希望在使用特殊逻辑计算出文本的编码的情况下来修改编码。 +比如 HTTP 和 XML在 body 块可以指定编码。这样的话，你应该使用 ``r.content`` 来找到编码，然后设置 ``r.encoding``为相应的编码。 +这样就能使用 ``r.text`` 正确解析编码。 在你需要的情况下，Requests 也可以使用定制的编码。如果你创建了自己的编码，并使用 ``codecs`` 模块进行注册，你就可以轻松地使用这个解码器名称作为 ``r.encoding`` 的值， -然后由 Requests 来为你处理编码。 - +Requests 将为你处理编码。 二进制响应内容 -------------------- +------------- 你也能以字节的方式访问请求响应体，对于非文本请求： @@ -131,7 +127,7 @@ Requests 会自动解码来自服务器的内容。大多数 unicode 字符集 Requests 会自动为你解码 ``gzip`` 和 ``deflate`` 传输编码的响应数据。 -例如，以请求返回的二进制数据创建一张图片，你可以使用如下代码： +例如，从请求返回的二进制数据打开（原文用得是creat）一张图片，你可以使用如下代码： :: @@ -142,7 +138,7 @@ Requests 会自动为你解码 ``gzip`` 和 ``deflate`` 传输编码的响应数 JSON 响应内容 ---------------- +------------- Requests 中也有一个内置的 JSON 解码器，助你处理 JSON 数据： @@ -152,10 +148,12 @@ Requests 中也有一个内置的 JSON 解码器，助你处理 JSON 数据： >>> r = requests.get('https://api.github.com/events') >>> r.json() - [{u'repository': {u'open_issues': 0, u'url': 'https://github.com/... + [{'repository': {'open_issues': 0, 'url': 'https://github.com/... -如果 JSON 解码失败， ``r.json()`` 就会抛出一个异常。例如，响应内容是 401 (Unauthorized)，\ -尝试访问 ``r.json()`` 将会抛出 ``ValueError: No JSON object could be decoded`` 异常。 +如果 JSON 解码失败， ``r.json()`` 就会抛出一个异常。 +例如，如果响应是 204 （无内容），或者如果响应包含无效 JSON，尝试``r.json()`` 将会抛出 ``simplejson.JSONDecodeError`` 异常。 +如果simplejson已经安装了， +在 Python 2中抛出``ValueError: No JSON object could be decoded`` 或在 Python 3中抛出``json.JSONDecodeError`` . 需要注意的是，成功调用 ``r.json()`` 并\**不**\ 意味着响应的成功。有的服务器会在失败的响应中\ 包含一个 JSON 对象（比如 HTTP 500 的错误细节）。这种 JSON 会被解码返回。要检查请求是否\ @@ -163,50 +161,62 @@ Requests 中也有一个内置的 JSON 解码器，助你处理 JSON 数据： 原始响应内容 ----------------- +----------- -在罕见的情况下，你可能想获取来自服务器的原始套接字响应，那么你可以访问 ``r.raw``\。 +在罕见的情况下，你可能想获取来自服务器的原始 socket 响应，那么你可以访问 ``r.raw``\。 如果你确实想这么干，那请你确保在初始请求中设置了 ``stream=True``\。具体你可以这么做： :: >>> r = requests.get('https://api.github.com/events', stream=True) + >>> r.raw - + >>> r.raw.read(10) '\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03' -但一般情况下，你应该以下面的模式将文本流保存到文件： +但一般情况下，你应该以下面的模式将数据流保存到文件： :: with open(filename, 'wb') as fd: - for chunk in r.iter_content(chunk_size): + for chunk in r.iter_content(chunk_size=128): fd.write(chunk) -使用 ``Response.iter_content`` 将会处理大量你直接使用 ``Response.raw`` 不得不处理的。 -当流下载时，上面是优先推荐的获取内容方式。 Note that ``chunk_size`` can be freely adjusted to a number that -may better fit your use cases. +使用 ``Response.iter_content`` 将会处理 +当你直接使用 ``Response.raw`` 大量不得不处理的内容。 +当流下载时，上面是优先推荐的获取内容方式。 +提示： ``chunk_size`` 可以被自行调整 +为一个更适合你使用情况的数字。 + +.. 提示:: + + 一个重要的提示关于使用 ``Response.iter_content`` VS ``Response.raw``. + ``Response.iter_content`` 将自动解码 ``gzip`` and ``deflate`` + transfer-encodings. ``Response.raw`` 是原始的字节流——它没有转换response的内容. 如果你真的需要得到返回的字节, 用 ``Response.raw``. + 定制请求头 ------------- -如果你想为请求添加 HTTP 头部，只要简单地传递一个 ``dict`` 给 ``headers`` 参数就可以了。 +如果你想为request添加 HTTP headers，只要简单地传递一个 ``dict`` 给 ``headers`` 参数。 -例如，在前一个示例中我们没有指定 content-type:: +例如，在前一个示例中我们没有指定 user-agent:: >>> url = 'https://api.github.com/some/endpoint' >>> headers = {'user-agent': 'my-app/0.0.1'} >>> r = requests.get(url, headers=headers) -注意: 定制 header 的优先级低于某些特定的信息源，例如： +注意: 定制 header 的优先级低于某些特定的信息源。例如： -* 如果在 ``.netrc`` 中设置了用户认证信息，使用 `headers=` 设置的授权就不会生效。而如果设置了 - ``auth=`` 参数，\``.netrc`` 的设置就无效了。 -* 如果被重定向到别的主机，授权 header 就会被删除。 +* 如果在 ``.netrc`` 中设置了用户认证信息，使用 `headers=` 设置的授权就不会生效。 +* 而如果设置了 + ``auth=`` 参数，``.netrc`` 的设置就无效了。 + Requests 将会在 `~/.netrc`, `~/_netrc`搜索netrc文件, 或者在 `NETRC` 环境变量的路径。 +* 如果被重定向到别的主机，授权 header 将会被删除。 * 代理授权 header 会被 URL 中提供的代理身份覆盖掉。 -* 在我们能判断内容长度的情况下，header 的 Content-Length 会被改写。 +* 在我们能决定内容长度的情况下，header 的 Content-Length 会被改写。 更进一步讲，Requests 不会基于定制 header 的具体情况改变自己的行为。只不过在最后的请求中，所有的 header 信息都会被传递进去。 @@ -217,14 +227,14 @@ header 也是允许的，但不建议这样做。 更加复杂的 POST 请求 ---------------------- -通常，你想要发送一些编码为表单形式的数据——非常像一个 HTML 表单。要实现这个，只需简单地传递\ +通常，你想要发送一些 form-encoded 的数据——非常像一个 HTML 表单。要实现这个，只需简单地传递 一个字典给 `data` 参数。你的数据字典在发出请求时会自动编码为表单形式： :: >>> payload = {'key1': 'value1', 'key2': 'value2'} - >>> r = requests.post("http://httpbin.org/post", data=payload) + >>> r = requests.post("https://httpbin.org/post", data=payload) >>> print(r.text) { ... @@ -235,14 +245,18 @@ header 也是允许的，但不建议这样做。 ... } -你还可以为 ``data`` 参数传入一个元组列表。在表单中多个元素使用同一 key 的时候，这种方式尤其有效： +``data`` 参数也可以为每个key传入多个值（values）。 +这可以通过 ``data`` 参数传入一个多元组的列表或一个多个列表的字典来实现。 +在表单中多个元素使用同一 key 的时候，这种方式尤其有效： :: - >>> payload = (('key1', 'value1'), ('key1', 'value2')) - >>> r = requests.post('http://httpbin.org/post', data=payload) - >>> print(r.text) - { +>>> payload_tuples = [('key1', 'value1'), ('key1', 'value2')] +>>> r1 = requests.post('https://httpbin.org/post', data=payload_tuples) +>>> payload_dict = {'key1': ['value1', 'value2']} +>>> r2 = requests.post('https://httpbin.org/post', data=payload_dict) +>>> print(r1.text) +{ ... "form": { "key1": [ @@ -252,11 +266,16 @@ header 也是允许的，但不建议这样做。 }, ... } + >>> r1.text == r2.text + True + +很多时候你想要发送非form-encoded（编码为表单形式）的数据。 +如果你传递一个 ``string`` 而不是一个 ``dict``， +那么数据会被直接posted。 + -很多时候你想要发送的数据并非编码为表单形式的。如果你传递一个 ``string`` 而不是一个 ``dict``\，\ -那么数据会被直接发布出去。 -例如，Github API v3 接受编码为 JSON 的 POST/PATCH 数据： +例如，GitHub API v3 接受编码为 JSON 的 POST/PATCH 数据： :: @@ -267,8 +286,7 @@ header 也是允许的，但不建议这样做。 >>> r = requests.post(url, data=json.dumps(payload)) -此处除了可以自行对 ``dict`` 进行编码，你还可以使用 ``json`` 参数直接传递，然后它就会被自动\ -编码。这是 2.4.2 版的新加功能： +除了可以自行对 ``dict`` 进行编码，你还可以直接使用 ``json`` 参数传递（于 2.4.2 版新增），然后它就会被自动编码： :: @@ -277,15 +295,19 @@ header 也是允许的，但不建议这样做。 >>> r = requests.post(url, json=payload) +提示：如果 ``data`` or ``files`` 被传参，the ``json`` 参数会被忽略。 + + +在请求中使用``json`` 参数将把请求头中的``Content-Type``变为 ``application/json``. POST一个多部分编码(Multipart-Encoded)的文件 ---------------------------------------------- +----------------------------------------- Requests 使得上传多部分编码文件变得很简单： :: - >>> url = 'http://httpbin.org/post' + >>> url = 'https://httpbin.org/post' >>> files = {'file': open('report.xls', 'rb')} >>> r = requests.post(url, files=files) @@ -298,11 +320,11 @@ Requests 使得上传多部分编码文件变得很简单： ... } -你可以显式地设置文件名，文件类型和请求头： +你可以明确地设置文件名，文件类型和请求头： :: - >>> url = 'http://httpbin.org/post' + >>> url = 'https://httpbin.org/post' >>> files = {'file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel', {'Expires': '0'})} >>> r = requests.post(url, files=files) @@ -315,11 +337,11 @@ Requests 使得上传多部分编码文件变得很简单： ... } -如果你想，你也可以发送作为文件来接收的字符串： +如果你想，你也可以发送作为文件被接收的字符串： :: - >>> url = 'http://httpbin.org/post' + >>> url = 'https://httpbin.org/post' >>> files = {'file': ('report.csv', 'some,data,to,send\nanother,row,to,send\n')} >>> r = requests.post(url, files=files) @@ -332,29 +354,27 @@ Requests 使得上传多部分编码文件变得很简单： ... } -如果你发送一个非常大的文件作为 ``multipart/form-data`` 请求，你可能希望将请求做成数据流。\ +如果你 post 一个非常大的文件作为 ``multipart/form-data`` 请求，你可能希望将请求做成数据流。 默认下 ``requests`` 不支持, 但有个第三方包 ``requests-toolbelt`` 是支持的。你可以阅读 -`toolbelt 文档 `_ 来了解使用方法。 +`toolbelt 文档 `_ 来了解使用方法的更多细节。 在一个请求中发送多文件参考 :ref:`高级用法 ` 一节。 -.. admonition:: 警告 - - 我们强烈建议你用二进制模式(`binary mode`_)打开文件。这是因为 Requests 可能会试图为你提供 +.. 警告::我们强烈建议你用二进制模式(`binary mode`_)打开文件。 + 这是因为 Requests 可能会试图为你提供 ``Content-Length`` header，在它这样做的时候，这个值会被设为文件的字节数（*bytes*）。\ - 如果用文本模式(text mode)打开文件，就可能会发生错误。 + 如果用文本模式(*text mode*)打开文件，就可能会发生错误。 + -.. _binary mode: https://docs.python.org/2/tutorial/inputoutput.html#reading-and-writing-files 响应状态码 -------------- 我们可以检测响应状态码： - :: - >>> r = requests.get('http://httpbin.org/get') + >>> r = requests.get('https://httpbin.org/get') >>> r.status_code 200 @@ -371,7 +391,7 @@ Requests 使得上传多部分编码文件变得很简单： :: - >>> bad_r = requests.get('http://httpbin.org/status/404') + >>> bad_r = requests.get('https://httpbin.org/status/404') >>> bad_r.status_code 404 @@ -395,7 +415,7 @@ Requests 使得上传多部分编码文件变得很简单： 响应头 ---------- -我们可以查看以一个 Python 字典形式展示的服务器响应头： +我们可以查看以一个 Python 字典形式查看的服务器响应头： :: @@ -410,11 +430,11 @@ Requests 使得上传多部分编码文件变得很简单： 'content-type': 'application/json' } -但是这个字典比较特殊：它是仅为 HTTP 头部而生的。根据 -`RFC 2616 `_\， +但是这个字典比较特殊：它是仅为 HTTP headers 而生的。根据 +`RFC 7230 `_\， HTTP 头部是大小写不敏感的。 -因此，我们可以使用任意大写形式来访问这些响应头字段： +因此，我们可以使用任意大写形式来访问这些响应头： :: @@ -436,10 +456,10 @@ HTTP 头部是大小写不敏感的。 接收者可以合并多个相同名称的 header 栏位，把它们合为一个 "field-name: field-value" 配对，将每个后续的栏位值依次追加到合并的栏位值中，用逗号隔开即可，这样做不会改变信息的语义。 -Cookie ---------- +Cookies +------- -如果某个响应中包含一些 cookie，你可以快速访问它们： +如果某个响应中包含一些 cookies，你可以快速访问它们： :: @@ -453,7 +473,7 @@ Cookie :: - >>> url = 'http://httpbin.org/cookies' + >>> url = 'https://httpbin.org/cookies' >>> cookies = dict(cookies_are='working') >>> r = requests.get(url, cookies=cookies) @@ -468,27 +488,31 @@ Cookie 的返回对象为 :class:`~requests.cookies.RequestsCookieJar`\，它的 >>> jar = requests.cookies.RequestsCookieJar() >>> jar.set('tasty_cookie', 'yum', domain='httpbin.org', path='/cookies') >>> jar.set('gross_cookie', 'blech', domain='httpbin.org', path='/elsewhere') - >>> url = 'http://httpbin.org/cookies' + >>> url = 'https://httpbin.org/cookies' >>> r = requests.get(url, cookies=jar) >>> r.text '{"cookies": {"tasty_cookie": "yum"}}' + 重定向与请求历史 -------------------- +--------------- + 默认情况下，除了 HEAD, Requests 会自动处理所有重定向。 -可以使用响应对象的 ``history`` 方法来追踪重定向。 + +我们可以使用响应对象的 ``history`` 方法来追踪重定向。 :attr:`Response.history ` 是一个 :class:`Response ` 对象的列表，为了完成请求而创建了这些对象。\ 这个对象列表按照从最老到最近的请求进行排序。 + 例如，Github 将所有的 HTTP 请求重定向到 HTTPS： :: - >>> r = requests.get('http://github.com') + >>> r = requests.get('http://github.com/') >>> r.url 'https://github.com/' @@ -502,20 +526,20 @@ Cookie 的返回对象为 :class:`~requests.cookies.RequestsCookieJar`\，它的 如果你使用的是GET、OPTIONS、POST、PUT、PATCH 或者 DELETE，那么你可以通过 ``allow_redirects`` 参数禁用重定向处理： - :: - >>> r = requests.get('http://github.com', allow_redirects=False) + >>> r = requests.get('http://github.com/', allow_redirects=False) + >>> r.status_code 301 >>> r.history [] 如果你使用了 HEAD，你也可以启用重定向： - :: - >>> r = requests.head('http://github.com', allow_redirects=True) + >>> r = requests.head('http://github.com/', allow_redirects=True) + >>> r.url 'https://github.com/' >>> r.history @@ -523,14 +547,11 @@ Cookie 的返回对象为 :class:`~requests.cookies.RequestsCookieJar`\，它的 超时 --------- - +---- 你可以告诉 requests 在经过以 ``timeout`` 参数设定的秒数时间之后停止等待响应。\ 基本上所有的生产代码都应该使用这一参数。如果不使用，你的程序可能会永远失去响应： - :: - - >>> requests.get('http://github.com', timeout=0.001) + >>> requests.get('https://github.com/', timeout=0.001) Traceback (most recent call last): File "", line 1, in requests.exceptions.Timeout: HTTPConnectionPool(host='github.com', port=80): Request timed out. (timeout=0.001) @@ -561,3 +582,4 @@ Cookie 的返回对象为 :class:`~requests.cookies.RequestsCookieJar`\，它的 ----------------------- 准备好学习更多内容了吗？去 :ref:`高级用法 ` 一节看看吧。 +如果你在就业市场, consider taking `this programming quiz `_. 如果你通过这个平台找到工作，重大的捐赠将为这个项目提供。 \ No newline at end of file