Requests 模块中文文档（六）

原文链接 -> 传送门

The API Documentation / Guide（4）

目录

The API Documentation / Guide（4）

十、迁移到 1.x

十一、迁移到 2.x

---

十、迁移到 1.x

本节详细介绍 0.x 和 1.x 的主要区别，减少升级带来的一些不便。

API 变化

1. Response.json 现在是可调用的并且不再是响应体的属性。

import requests
r = requests.get('https://github.com/timeline.json')
r.json()   # This *call* raises an exception if JSON decoding fails

2. Session API 也发生了变化。Sessions 对象不再需要参数，另外 Session 关键字现在是大写的，但为了向后兼容，它仍然能被小写的 session 实例化。

s = requests.Session()    # formerly, session took parameters
s.auth = auth
s.headers.update(headers)
r = s.get('http://httpbin.org/headers')

3. 除了 'response' 之外，所有的请求钩子均已被移除。

4. 认证帮助已经被独立为单独的模块，参见 requests-oauthlib 和 requests-kerberos。

5. 流请求的参数从 prefetch 变为 stream，并且运行逻辑也发生了颠覆。除此之外， stream 现在需要读取原始响应数据。

# in 0.x, passing prefetch=False would accomplish the same thing
r = requests.get('https://github.com/timeline.json', stream=True)
for chunk in r.iter_content(8192):
    ...

6. requests 方法的 config 参数已经被移除。现在配置这些选项都在 Session，比如 keep-alive 和重定向的最大次数等。更多选项应当由配置日志来处理。

import requests
import logging

# Enabling debugging at http.client level (requests->urllib3->http.client)
# you will see the REQUEST, including HEADERS and DATA, and RESPONSE with HEADERS but without DATA.
# the only thing missing will be the response.body which is not logged.
try: # for Python 3
    from http.client import HTTPConnection
except ImportError:
    from httplib import HTTPConnection
HTTPConnection.debuglevel = 1

logging.basicConfig() # you need to initialize logging, otherwise you will not see anything from requests
logging.getLogger().setLevel(logging.DEBUG)
requests_log = logging.getLogger("requests.packages.urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True

requests.get('http://httpbin.org/headers')

许可

有一个关键的与 API 无关的区别是开放许可从 ISC 许可变更到 Apache 2.0 许可。Apache 2.0 许可确保了对于 Requests 的贡献也被涵盖在 Apache 2.0 许可内。

---

十一、迁移到 2.x

和 1.0 发布版相比，破坏兼容性的改动比较少。不过在这个发布版中，依然还有一些应该注意的问题。

更多关于变更的细节，包括 API，以及相关的 GitHub Issue 和部分 bug 修复，请参阅 Cory 的 blog 中相关主题。

API 变化

1. Requests 处理异常的行为有一些修改。RequestException 现在是 IOError 的子类，而不是 RuntimeError 的子类，新的归类更为合理。此外，无效的 URL 转义序列现在会引发 RequestException 的一个子类，而非一个 ValueError。

requests.get('http://%zz/')   # raises requests.exceptions.InvalidURL

最后， 错误分块导致的 httplib.IncompleteRead 异常现在变成了 ChunkedEncodingError。

2. 代理 API 略有改动，现在需要提供代理 URL 的协议。

proxies = {
  "http": "10.10.1.10:3128",    # use http://10.10.1.10:3128 instead
}

# In requests 1.x, this was legal, in requests 2.x,
#  this raises requests.exceptions.MissingSchema
requests.get("http://example.org", proxies=proxies)

行为变化

1. headers 字典（dict）中的键现在都是原生字符串，在所有版本的 Python 中都是如此。也就是说，Python 2 中是 bytestrings，Python 3 中是 unicode。如果键不是原声字符串（Python 2 中是 unicode，或 Python 3 中是 bytestrings），它们会被以 UTF-8 编码转成原生字符串。

2. headers 字典（dict）中的值应该都是字符串。在 1.0 版之前该项目就是要求这样做的，只不过最近（v2.11.0 之后）这条变成了强制条款。建议在可能的情况下，避免 header 的值使用 unicode 编码。