3. 快速入门 —— Requests中文文档

本文介绍了如何使用Request库。首先，确保：

• Request库已安装
• Request库已更新到最新。

让我们从一些简单的例子开始。

提出请求¶

用Request库提出请求非常简单。
首先导入Request模块：

    >>> import requests    

现在，让我们尝试获取一个网页。对于本例，让我们获取GitHub的时间轴：

    >>> r = requests.get('https://api.github.com/events')    

现在，我们有一个名为r的Response对象。我们可以从该对象获取所需的所有信息。
Request库使用简单API意味着各种HTTP请求都是很明显。例如，下面代码展示如何发出HTTP POST请求：

    >>> r = requests.post('https://httpbin.org/post', data = {'key':'value'})    

不错，对吧？其他HTTP请求类型：PUT、DELETE、HEAD和OPTIONS呢？这些都很简单：

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

这一切都很容易，但这也只是Request库能做工作的开始。

在URL中传递参数¶

您通常希望在URL的查询字符串中发送某种类型的数据。如果您是手工构建URL，那么这些数据将在URL中的问号后作为键/值对来给出，例如httpbin.org/get?key=val。Request库允许您使用params关键字参数将这些参数作为字符串字典提供。例如，如果要将key1=value1和key2=value2传递给httpbin.org/get，您可以使用以下代码：

    >>> payload = {'key1': 'value1', 'key2': 'value2'}
    >>> r = requests.get('https://httpbin.org/get', params=payload)    

通过打印URL，可以看到URL已被正确编码：

    >>> print(r.url)
    https://httpbin.org/get?key2=value2&key1=value1    

请注意，任何值为None的字典键都不会添加到URL的查询字符串中。也可以将列表作为值传递：

    >>> payload = {'key1': 'value1', 'key2': ['value2', 'value3']}
    
    >>> r = requests.get('https://httpbin.org/get', params=payload)
    >>> print(r.url)
    https://httpbin.org/get?key1=value1&key2=value2&key2=value3    

响应内容¶

我们可以读取服务器响应的内容。再考虑一下GitHub时间轴：

    >>> import requests
    
    >>> r = requests.get('https://api.github.com/events')
    >>> r.text
    '[{"repository":{"open_issues":0,"url":"https://github.com/...    

请求将自动解码来自服务器的内容。大多数Unicode字符都是无缝解码的。
当您发出请求时，Request库会根据HTTP报头对响应内容的编码进行有根据的猜测。访问r.text时，将返回使用猜测编码的文本。您可以使用r.encoding属性找到并更改它：

    >>> r.encoding
    'utf-8'
    >>> r.encoding = 'ISO-8859-1'    

如果更改编码，则无论何时调用r.text，请求都将使用新值r.encoding。在得出内容的编码后可以随时进行该操作。例如，HTML和XML可以在其主体中指定编码。在这种情况下，应该使用r.content来查找编码，然后设置r.encoding。这将允许您将r.text与正确的编码一起使用。
Request库还将在您需要的情况下使用自定义编码。如果您已经创建了自己的编码并将其注册到codecs模块中，您只需将编解码器名称用作r.encoding的值，Request库将为您处理解码。

二进制响应内容¶

对于非文本请求，您还可以以字节形式访问响应正文：

    >>> r.content
    b'[{"repository":{"open_issues":0,"url":"https://github.com/...    

使用gzip和deflate等类型传输编码的文本将自动为您解码。
例如，要从请求返回的二进制数据创建映像，可以使用以下代码：

    >>> from PIL import Image
    >>> from io import BytesIO
    
    >>> i = Image.open(BytesIO(r.content))    

JSON响应内容¶

还有一个内置的JSON解码器，以防处理JSON数据：

    >>> import requests
    
    >>> r = requests.get('https://api.github.com/events')
    >>> r.json()
    [{'repository': {'open_issues': 0, 'url': 'https://github.com/...    

如果JSON解码失败，r.json()将引发异常。例如，如果响应代码204（没有内容），或者如果响应包含无效的JSON文本，则调用r.json()将引发ValueError: No JSON object could be decoded。
需要注意的是，调用r.json()的成功并不是表示响应的成功。有些服务器可能在失败的响应中返回一个JSON对象（例如HTTP
500的错误详细信息）。类似JSON内容将被解码并返回。若要检查请求是否成功，请使用r.raise_for_status()或r.status。

原始响应内容¶

如果您希望从服务器获取原始套接字响应，则可以访问r.raw。如果要这样做，请确保在初始请求中设置了stream=True。然后你就可以这么做：

    >>> r = requests.get('https://api.github.com/events', stream=True)
    
    >>> r.raw
    <urllib3.response.HTTPResponse object at 0x101194810>
    
    >>> 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=128):
            fd.write(chunk)    

相比直接使用Response.raw，使用Response.iter_content会增加很多处理。但在流式下载时，是获取内容的首选和推荐方法。注意，chunk_size可以自由调整为一个更适合的数字。
注意：
Response.iter_content与Response.raw的一个重要区别在于：Response.iter_content将自动解码gzip和deflate传输编码的内容，而Response.raw是原始字节流——它不转换响应内容。如果您确实需要访问返回的字节，请使用Response.raw。

自定义HTTP Headers¶

如果要向请求中添加HTTP头，只需向headers参数传入一个dict。
例如，在前面的示例中，我们没有指定用户代理：

    >>> url = 'https://api.github.com/some/endpoint'
    >>> headers = {'user-agent': 'my-app/0.0.1'}
    
    >>> r = requests.get(url, headers=headers)    

注意：自定义HTTP头的优先级低于更具体的信息源。例如：

• 如果在.netrc中指定了授权，则使用headers=设置的授权将被覆盖，而该授权又将被auth=参数覆盖。
• 如果您被重定向离开主机，授权头将被删除。
• 代理授权标头将被URL中提供的代理授权覆盖。
• 当我们可以确定内容的长度时，内容长度标头将被覆盖。
  此外，请求根本不会根据指定的自定义头来更改其行为。头只是简单地传递到最终请求中。
  注意：所有头值必须是string、bytestring或unicode。建议避免传递unicode值。

更复杂的POST请求¶

通常，您希望提交一些表单编码的数据，例如一个HTML表单。为此，只需向data传递一个字典参数。在发出请求时，数据字典将自动进行表单编码：

    >>> payload = {'key1': 'value1', 'key2': 'value2'}
    
    >>> r = requests.post("https://httpbin.org/post", data=payload)
    >>> print(r.text)
    {
      ...
      "form": {
        "key2": "value2",
        "key1": "value1"
      },
      ...
    }    

data参数对于每个键也可以有多个值。这可以通过使data成为元组列表或以列表作为值的字典来实现。当表单包含多个使用同一键的元素时，这一点尤其有用：

    >>> 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": [
          "value1",
          "value2"
        ]
      },
      ...
    }
    >>> r1.text == r2.text
    True    

有时您可能希望发送的数据不是表单编码。如果如果传入一个string而不是dict，则该数据将直接传递。
例如，github api v3接受JSON编码的POST/PATCH数据：

    >>> import json
    
    >>> url = 'https://api.github.com/some/endpoint'
    >>> payload = {'some': 'data'}
    
    >>> r = requests.post(url, data=json.dumps(payload))
    

您也可以使用json参数（在版本2.4.2中添加）直接传递，而不是自己对dict进行编码，它将自动编码：

    >>> url = 'https://api.github.com/some/endpoint'
    >>> payload = {'some': 'data'}
    
    >>> r = requests.post(url, json=payload)
    

注意，如果传递data或files，则忽略json参数。在请求中使用json参数会将头中的Content Type更改为application/json。

提交多种编码的文件¶

Requests使上传多种编码的文件变得简单：

    >>> url = 'https://httpbin.org/post'
    >>> files = {'file': open('report.xls', 'rb')}
    
    >>> r = requests.post(url, files=files)
    >>> r.text
    {
      ...
      "files": {
        "file": "<censored...binary...data>"
      },
      ...
    }
    

您可以显式设置文件名、内容类型和标题：

    >>> 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)
    >>> r.text
    {
      ...
      "files": {
        "file": "<censored...binary...data>"
      },
      ...
    }
    

如果需要，可以发送字符串作为文件接收：

    >>> url = 'https://httpbin.org/post'
    >>> files = {'file': ('report.csv', 'some,data,to,send\nanother,row,to,send\n')}
    
    >>> r = requests.post(url, files=files)
    >>> r.text
    {
      ...
      "files": {
        "file": "some,data,to,send\\nanother,row,to,send\\n"
      },
      ...
    }
    

如果您将一个非常大的文件作为multipart/form-data请求上传，则可能需要流式处理该请求。默认情况下，Requests不支持此功能，但是有一个单独的包requests-toolbelt。你应该阅读requests-toolbelt有关文档获取如何使用的详细信息。
要在一个请求中发送多个文件，请参阅高级部分。
警告

强烈建议您以binary mode打开文件。这是因为Requests会尝试为您提供Content Length标头，该值将被设置为文件中的字节数。如果以text mode打开文件，则可能发生错误。

响应状态代码¶

我们可以查看响应状态代码：

    >>> r = requests.get('https://httpbin.org/get')
    >>> r.status_code
    200
    

为了便于引用，Requests还附带一个内置状态代码查找对象：

    >>> r.status_code == requests.codes.ok
    True
    

如果我们发出了一个错误的请求（4XX客户端错误或5XX服务器错误响应），我们可以使用Response.raise_for_status()抛出异常：

    >>> bad_r = requests.get('https://httpbin.org/status/404')
    >>> bad_r.status_code
    404
    
    >>> bad_r.raise_for_status()
    Traceback (most recent call last):
      File "requests/models.py", line 832, in raise_for_status
        raise http_error
    requests.exceptions.HTTPError: 404 Client Error
    

但是，由于r的status代码是200，所以当我们调用raise_for_status()时，我们得到：

    >>> r.raise_for_status()
    None
    

一切都很好。

响应头¶

我们可以使用Python字典查看服务器的响应头：

    >>> r.headers
    {
        'content-encoding': 'gzip',
        'transfer-encoding': 'chunked',
        'connection': 'close',
        'server': 'nginx/1.0.4',
        'x-runtime': '148ms',
        'etag': '"e1ca502697e5c9317743dc078f67693f"',
        'content-type': 'application/json'
    }
    

不过，这本词典很特别：它是专为HTTP头编写的。根据收件人RFC 7230，HTTP头名称不区分大小写。
因此，我们可以使用任意大小写来访问标题：

    >>> r.headers['Content-Type']
    'application/json'
    
    >>> r.headers.get('content-type')
    'application/json'
    

其中有一个特殊之处，服务器可能多次发送包括不同值的同一个响应头，但按RFC7230要求，Requests库进行了合并，使其可以在字典中用同一个映射表示：

浏览器可以将多个具有相同字段名的头字段组合成一个字段值对，无需更改消息的语义，方法是将每个后续字段值按顺序附加到组合字段值后，用逗号分隔。

Cookies¶

如果响应包含一些cookie，则可以快速访问它们：

    >>> url = 'http://example.com/some/cookie/setting/url'
    >>> r = requests.get(url)
    
    >>> r.cookies['example_cookie_name']
    'example_cookie_value'
    

要将自己的cookies发送到服务器，可以使用cookies参数：

    >>> url = 'https://httpbin.org/cookies'
    >>> cookies = dict(cookies_are='working')
    
    >>> r = requests.get(url, cookies=cookies)
    >>> r.text
    '{"cookies": {"cookies_are": "working"}}'
    

Cookie以RequestsCookieJar类的形式返回，它的作用类似于dict，但也提供了一个更完整的接口，适合在多个域或路径使用。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 = 'https://httpbin.org/cookies'
    >>> r = requests.get(url, cookies=jar)
    >>> r.text
    '{"cookies": {"tasty_cookie": "yum"}}'
    

重定向和历史记录¶

默认情况下，Requests将对除HEAD之外的所有请求执行位置重定向。我们可以使用Response对象的history属性来跟踪重定向。
属性Response.history以列表形式包含为完成请求而创建的Response对象，并按从最旧到最新进行排序。
例如，GitHub将所有HTTP请求重定向到HTTPS:：

    >>> r = requests.get('http://github.com/')
    
    >>> r.url
    'https://github.com/'
    
    >>> r.status_code
    200
    
    >>> r.history
    [<Response [301]>]
    

如果使用GET、OPTIONS、POST、PUT、PATCH或DELETE，则可以使用allow_redirects参数：

    >>> 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.url
    'https://github.com/'
    
    >>> r.history
    [<Response [301]>]
    

超时¶

您可以使用timeout参数告诉请求在给定的秒数后停止等待响应。几乎所有的生产环境代码都应该在所有的请求中使用此参数。否则会导致程序无限期挂起：

    >>> requests.get('https://github.com/', timeout=0.001)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    requests.exceptions.Timeout: HTTPConnectionPool(host='github.com', port=80): Request timed out. (timeout=0.001)
    

注意
timeout不是整个响应下载的时间限制；相反，如果服务器在timeout秒内没有发出响应（更准确地说，如果在timeout秒的基础套接字上没有接收到字节），则会引发异常。如果没有显式指定超时，则请求不会超时。

错误和异常¶

如果出现网络问题（例如DNS故障、拒绝连接等），Requests将抛出一个ConnectionError异常。
如果HTTP请求返回不成功的状态代码，Response.raise_for_status()将抛出一个HTTPError异常。
如果请求超时，将抛出Timeout异常。
如果请求超过配置的最大重定向数，将抛出TooManyRedirects异常。。
所有Requests抛出的显式异常均继承于requests.exceptions.RequestException。