python Interface Automation - Requests-3 Advanced Usage

Advanced Usage

This document covers some of the advanced features of Requests.

Session object

Session object allows you to cross the request to keep certain parameters. It will be the same across all requests sent to keep a Session instance cookie, used during  urllib3 the  connection pooling  function. So if you send multiple requests to the same host, TCP underlying connection will be reused, leading to significant performance improvements. (See  HTTP persistent Connection ).

Session object has a method all major Requests API's.

We come across a request to keep some of the cookie:

s = requests.Session()
s.get('http://httpbin.org/cookies/set/sessioncookie/123456789')
r = s.get("http://httpbin.org/cookies")
print(r.text)

{
  "cookies": {
    "sessioncookie": "123456789"
  }
}

会话也可用来为请求方法提供缺省数据。这是通过为会话对象的属性提供数据来实现的：

s = requests.Session()
s.auth = ('user', 'pass')
s.headers.update({'x-test': 'true'})

# both 'x-test' and 'x-test2' are sent
s.get('http://httpbin.org/headers', headers={'x-test2': 'true'})

You to pass any request method dictionary and will set the session data layers combined. The method of the cover layer parameters parameters of the session.

Remember, though, even if the use of the session, the method level parameters will not be maintained across requests. The following examples only and a request to send cookie, instead of a second:

s = requests.Session()

r = s.get('http://httpbin.org/cookies', cookies={'from-my': 'browser'})
print(r.text)
# '{"cookies": {"from-my": "browser"}}'

r = s.get('http://httpbin.org/cookies')
print(r.text)
# '{"cookies": {}}'

If you want to manually add a cookie for the session, on the use of  Cookie utility functions  to manipulate  Session.cookies.

Can also be used as text before and after the session manager:

with requests.Session() as s:
    s.get('http://httpbin.org/cookies/set/sessioncookie/123456789')

这样就能确保 with 区块退出后会话能被关闭，即使发生了异常也一样。

从字典参数中移除一个值：
有时你会想省略字典参数中一些会话层的键。要做到这一点，你只需简单地在方法层参数中将那个键的值设置为 None ，那个键就会被自动省略掉。

包含在一个会话中的所有数据你都可以直接使用。学习更多细节请阅读 会话 API 文档。

请求与响应对象

任何时候进行了类似 requests.get() 的调用，你都在做两件主要的事情。其一，你在构建一个 Request 对象， 该对象将被发送到某个服务器请求或查询一些资源。其二，一旦 requests 得到一个从服务器返回的响应就会产生一个 Response 对象。该响应对象包含服务器返回的所有信息，也包含你原来创建的 Request 对象。如下是一个简单的请求，从 Wikipedia 的服务器得到一些非常重要的信息：

 r = requests.get('http://en.wikipedia.org/wiki/Monty_Python')

如果想访问服务器返回给我们的响应头部信息，可以这样做：

print（ r.headers）



{'content-length': '56170', 'x-content-type-options': 'nosniff', 'x-cache':
'HIT from cp1006.eqiad.wmnet, MISS from cp1010.eqiad.wmnet', 'content-encoding':
'gzip', 'age': '3080', 'content-language':in'', 'vary': 'Accept-Encoding,Cookie',
'server': 'Apache', 'last-modified': 'Wed, 13 Jun 2012 01:33:50 GMT',
'connection': 'close', 'cache-control': 'private, s-maxage=0, max-age=0,
must-revalidate', 'date': 'Thu, 14 Jun 2012 12:59:39 GMT', 'content-type':
'text/html; charset=UTF-8', 'x-cache-lookup': 'HIT from cp1006.eqiad.wmnet:3128,
MISS from cp1010.eqiad.wmnet:80'}

然而，如果想得到发送到服务器的请求的头部，我们可以简单地访问该请求，然后是该请求的头部：

r = requests.get('http://en.wikipedia.org/wiki/Monty_Python')
print(r.request.headers)

{'User-Agent': 'python-requests/2.21.0', 'Accept-Encoding': 'gzip, deflate', 'Accept': '*/*', 'Connection': 'keep-alive'}

Request prepared (the Prepared Request) ¶

When you receive a call from the API or session  Response object, the request property is actually used  PreparedRequest. Sometimes before sending the request, you need to body or header (or whatever) to do some additional processing, below demonstrates a simple approach:

from requests import Request, Session

s = Session()
req = Request('GET', url,
    data=data,
    headers=header
)
prepped = req.prepare()

# do something with prepped.body
# do something with prepped.headers

resp = s.send(prepped,
    stream=stream,
    verify=verify,
    proxies=proxies,
    cert=cert,
    timeout=timeout
)

print(resp.status_code)

Because you do not have to  Request do anything special thing objects, you immediately prepare and modify the  PreparedRequest object and then send it together with other parameters  requests.* or  Session.*.

However, the above code Requests will lose  Session some of the advantages of an object, in particular  Session the level of the state, such as cookie will not be applied to your requests go up. To obtain a state with  PreparedRequest, please  Session.prepare_request() replace  Request.prepare() the call, as follows:

from requests import Request, Session

s = Session()
req = Request('GET',  url,
    data=data
    headers=headers
)

prepped = s.prepare_request(req)

# do something with prepped.body
# do something with prepped.headers

resp = s.send(prepped,
    stream=stream,
    verify=verify,
    proxies=proxies,
    cert=cert,
    timeout=timeout
)

print(resp.status_code)

SSL certificate validation

Requests can verify the SSL certificate for HTTPS requests, like web browsers. SSL authentication is enabled by default, if the certificate verification fails, Requests throws SSLError:

>>> requests.get('https://requestb.in')
requests.exceptions.SSLError: hostname 'requestb.in' doesn't match either of '*.herokuapp.com', 'herokuapp.com'

SSL is not set on the domain name, it failed. But Github set up SSL:

>>> requests.get('https://github.com', verify=True)
<Response [200]>

You can  verify pass CA_BUNDLE path to the file, or the file that contains the trusted CA certificate file folder path:

requests.get('https://github.com', verify='/path/to/certfile')

Or to hold it in the session:

s = requests.Session()
s.verify = '/path/to/certfile'

Notes 
c_rehash tool to verify if the path to the folder, the folder must be provided by OpenSSL process.

You can also  REQUESTS_CA_BUNDLE define the trusted CA list of environment variables.

If you  verify set to False, Requests can ignore verification of SSL certificates.

>>> requests.get('https://kennethreitz.org', verify=False)
<Response [200]>

By default,  verify it is set to True. Option  verify applies only to the host certificate.

# 对于私有证书，你也可以传递一个 CA_BUNDLE 文件的路径给 verify。你也可以设置 # REQUEST_CA_BUNDLE 环境变量。

客户端证书

你也可以指定一个本地证书用作客户端证书，可以是单个文件（包含密钥和证书）或一个包含两个文件路径的元组：

>>> requests.get('https://kennethreitz.org', cert=('/path/client.cert', '/path/client.key'))
<Response [200]>

或者保持在会话中：

s = requests.Session()
s.cert = '/path/client.cert'

如果你指定了一个错误路径或一个无效的证书:

>>> requests.get('https://kennethreitz.org', cert='/wrong_path/client.pem')
SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib

WARNING 
local certificate private key must be decrypted state. Currently, Requests do not support the use of encryption key.

CA certificate

Requests default it comes with a set of trusted root certificates, from the  Mozilla Trust Store . However, they will be updated each time Requests updates. This means that if you use a fixed version of Requests, your certificate may have been too old.

After Requests from version 2.4.0, if the system is installed with a  certifi  package, Requests will attempt to use the certificate inside it. So that users can update their trusted certificates without modifying the code.

For security reasons, we recommend that you regularly update certifi!

Response body content workflow

By default, when you make a network request, the response was immediate download experience. You can  stream override this behavior parameters, visit the download postponed until the response body  Response.content attributes:

tarball_url = 'https://github.com/kennethreitz/requests/tarball/master'
r = requests.get(tarball_url, stream=True)

At this time, only a response header is downloaded, the connection remains open, thus allowing us to obtain content based on the condition:

if int(r.headers['content-length']) < TOO_LONG:
  content = r.content
  ...

You can further use  Response.iter_content and a  Response.iter_lines method to control the flow of work, or to  Response.raw the bottom urllib3 the read undecoded response body. urllib3.HTTPResponse <urllib3.response.HTTPResponse 

If you put in the request  stream is set  True, Requests can not be released back to the connection pool connection, unless you consume all the data, or call  Response.close. This will bring low connection efficiency. If you find that you use  while still part of the read request body (or did not read the body ), then you should consider using with statement sends a request, it can guarantee the request will be closed: stream=True

with requests.get('http://httpbin.org/get', stream=True) as r:
    # 在此处理响应。

保持活动状态（持久连接）

好消息——归功于 urllib3，同一会话内的持久连接是完全自动处理的！同一会话内你发出的任何请求都会自动复用恰当的连接！

注意：只有所有的响应体数据被读取完毕连接才会被释放为连接池；所以确保将 stream 设置为 False 或读取 Response 对象的 content 属性。

流式上传

Requests支持流式上传，这允许你发送大的数据流或文件而无需先把它们读入内存。要使用流式上传，仅需为你的请求体提供一个类文件对象即可：

with open('massive-body') as f:
    requests.post('http://some.url/streamed', data=f)

警告
我们强烈建议你用二进制模式（binary mode）打开文件。这是因为 requests 可能会为你提供 header 中的 Content-Length，在这种情况下该值会被设为文件的字节数。如果你用文本模式打开文件，就可能碰到错误。

块编码请求

对于出去和进来的请求，Requests 也支持分块传输编码。要发送一个块编码的请求，仅需为你的请求体提供一个生成器（或任意没有具体长度的迭代器）：

def gen():
    yield 'hi'
    yield 'there'

requests.post('http://some.url/chunked', data=gen())

对于分块的编码请求，我们最好使用 Response.iter_content() 对其数据进行迭代。在理想情况下，你的 request 会设置 stream=True，这样你就可以通过调用 iter_content 并将分块大小参数设为 None，从而进行分块的迭代。如果你要设置分块的最大体积，你可以把分块大小参数设为任意整数。

POST 多个分块编码的文件

你可以在一个请求中发送多个文件。例如，假设你要上传多个图像文件到一个 HTML 表单，使用一个多文件 field 叫做 "images":

<input type="file" name="images" multiple="true" required="true"/>

要实现，只要把文件设到一个元组的列表中，其中元组结构为 (form_field_name, file_info):

>>> url = 'http://httpbin.org/post'
>>> multiple_files = [
        ('images', ('foo.png', open('foo.png', 'rb'), 'image/png')),
        ('images', ('bar.png', open('bar.png', 'rb'), 'image/png'))]
>>> r = requests.post(url, files=multiple_files)
>>> r.text
{
  ...
  'files': {'images': 'data:image/png;base64,iVBORw ....'}
  'Content-Type': 'multipart/form-data; boundary=3131623adb2043caaeb5538cc7aa0b3a',
  ...
}

警告

我们强烈建议你用二进制模式（binary mode）打开文件。这是因为 requests 可能会为你提供 header 中的 Content-Length，在这种情况下该值会被设为文件的字节数。如果你用文本模式打开文件，就可能碰到错误。

事件挂钩

Requests有一个钩子系统，你可以用来操控部分请求过程，或信号事件处理。

可用的钩子:

response:

从一个请求产生的响应

你可以通过传递一个 {hook_name: callback_function} 字典给 hooks 请求参数为每个请求分配一个钩子函数：

hooks=dict(response=print_url)

callback_function 会接受一个数据块作为它的第一个参数。

def print_url(r, *args, **kwargs):
    print(r.url)

若执行你的回调函数期间发生错误，系统会给出一个警告。

若回调函数返回一个值，默认以该值替换传进来的数据。若函数未返回任何东西，也没有什么其他的影响。

我们来在运行期间打印一些请求方法的参数：

>>> requests.get('http://httpbin.org', hooks=dict(response=print_url))
http://httpbin.org
<Response [200]>

自定义身份验证

Requests 允许你使用自己指定的身份验证机制。

任何传递给请求方法的 auth 参数的可调用对象，在请求发出之前都有机会修改请求。

自定义的身份验证机制是作为 requests.auth.AuthBase 的子类来实现的，也非常容易定义。Requests 在 requests.auth 中提供了两种常见的的身份验证方案： HTTPBasicAuth 和 HTTPDigestAuth 。

假设我们有一个web服务，仅在 X-Pizza 头被设置为一个密码值的情况下才会有响应。虽然这不太可能，但就以它为例好了。

from requests.auth import AuthBase

class PizzaAuth(AuthBase):
    """Attaches HTTP Pizza Authentication to the given Request object."""
    def __init__(self, username):
        # setup any auth-related data here
        self.username = username

    def __call__(self, r):
        # modify and return the request
        r.headers['X-Pizza'] = self.username
        return r

然后就可以使用我们的PizzaAuth来进行网络请求:

>>> requests.get('http://pizzabin.org/admin', auth=PizzaAuth('kenneth'))
<Response [200]>

流式请求

使用 Response.iter_lines() 你可以很方便地对流式 API （例如 Twitter 的流式 API ） 进行迭代。简单地设置 stream 为 True 便可以使用 iter_lines 对相应进行迭代：

import json
import requests

r = requests.get('http://httpbin.org/stream/20', stream=True)

for line in r.iter_lines():

    # filter out keep-alive new lines
    if line:
        decoded_line = line.decode('utf-8')
        print(json.loads(decoded_line))

当使用 decode_unicode=True 在 Response.iter_lines() 或 Response.iter_content() 中时，你需要提供一个回退编码方式，以防服务器没有提供默认回退编码，从而导致错误：

r = requests.get('http://httpbin.org/stream/20', stream=True)

if r.encoding is None:
    r.encoding = 'utf-8'

for line in r.iter_lines(decode_unicode=True):
    if line:
        print(json.loads(line))

警告

iter_lines 不保证重进入时的安全性。多次调用该方法 会导致部分收到的数据丢失。如果你要在多处调用它，就应该使用生成的迭代器对象:

lines = r.iter_lines()
# 保存第一行以供后面使用，或者直接跳过

first_line = next(lines)

for line in lines:
    print(line)

代理

如果需要使用代理，你可以通过为任意请求方法提供 proxies 参数来配置单个请求:

import requests

proxies = {
  "http": "http://10.10.1.10:3128",
  "https": "http://10.10.1.10:1080",
}

requests.get("http://example.org", proxies=proxies)

你也可以通过环境变量 HTTP_PROXY 和 HTTPS_PROXY 来配置代理。

$ export HTTP_PROXY="http://10.10.1.10:3128"
$ export HTTPS_PROXY="http://10.10.1.10:1080"

$ python
>>> import requests
>>> requests.get("http://example.org")

若你的代理需要使用HTTP Basic Auth，可以使用 http://user:password@host/ 语法：

proxies = {
    "http": "http://user:[email protected]:3128/",
}

要为某个特定的连接方式或者主机设置代理，使用 scheme://hostname 作为 key， 它会针对指定的主机和连接方式进行匹配。

proxies = {'http://10.20.1.128': 'http://10.10.1.10:5323'}

注意，代理 URL 必须包含连接方式。

SOCKS

2.10.0 新版功能.

除了基本的 HTTP 代理，Request 还支持 SOCKS 协议的代理。这是一个可选功能，若要使用， 你需要安装第三方库。

你可以用 pip 获取依赖: