Requests库的开发者接口 - 守护式等待

一、主要接口

1.1 requests.request(method, url, **kwargs)

构造并发送一个Request对象，返回一个Response对象。

method – 新建 Request 对象要使用的HTTP方法
url – 新建 Request 对象的URL
params – (可选) Request 对象的查询字符中要发送的字典或字节内容
data – (可选) Request 对象的 body 中要包括的字典、字节或类文件数据
json – (可选) Request 对象的 body 中要包括的 Json 数据
headers – (可选) Request 对象的字典格式的 HTTP 头
cookies – (可选) Request 对象的字典或 CookieJar 对象
files – (可选) 字典，'name': file-like-objects (或{'name': ('filename', fileobj)}) 用于上传含多个部分的（类）文件对象
auth – (可选) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
timeout (浮点或元组) – (可选) 等待服务器数据的超时限制，是一个浮点数，或是一个(connect timeout, read timeout) 元组
allow_redirects (bool) – (可选) Boolean. True 表示允许跟踪 POST/PUT/DELETE 方法的重定向
proxies – (可选) 字典，用于将协议映射为代理的URL
verify – (可选) 为 True 时将会验证 SSL 证书，也可以提供一个 CA_BUNDLE 路径
stream – (可选) 如果为 False，将会立即下载响应内容
cert – (可选) 为字符串时应是 SSL 客户端证书文件的路径(.pem格式)，如果是元组，就应该是一个(‘cert’, ‘key’) 二元值对
```
>>> import requests
>>> req = requests.request('GET', 'http://httpbin.org/get')
<Response [200]>
```

1.2 requests.head(url, **kwargs)

发送一个 HEAD 请求，返回一个 Response 对象

url – 新建 Request 对象的URL
**kwargs – 见 request 方法接收的可选参数

1.3 requests.get(url, **kwargs)

发送一个 GET 请求，返回一个 Response 对象

url – 新建 Request 对象的URL
**kwargs – 见 request 方法接收的可选参数

1.4 requests.post(url, data=None, **kwargs)

发送一个 PUT 请求，返回一个 Response 对象

url – 新建 Request 对象的URL
data – (可选) Request 对象的 body 中要包括的字典、字节或类文件数据
**kwargs – 见 request 方法接收的可选参数

1.5 requests.put(url, data=None, **kwargs)

发送一个 PUT 请求，返回一个 Response 对象

url – 新建 Request 对象的URL
data – (可选) Request 对象的 body 中要包括的字典、字节或类文件数据
**kwargs – 见 request 方法接收的可选参数

1.6 requests.patch(url, data=None, **kwargs)

发送一个 PUT 请求，返回一个 Response 对象

url – 新建 Request 对象的URL
data – (可选) Request 对象的 body 中要包括的字典、字节或类文件数据
**kwargs – 见 request 方法接收的可选参数

1.7 requests.delete(url, **kwargs)

发送一个 PUT 请求，返回一个 Response 对象

url – 新建 Request 对象的URL
**kwargs – 见 request 方法接收的可选参数

二、异常

exception requests.RequestException     # 处理你的请求时出现了一个有歧义的异常
exception requests.ConnectionError   # 连接异常
exception requests.HTTPError(*args, **kwargs)   # HTTP 错误
exception requests.URLRequired  # 无效的请求 URL
exception requests.TooManyRedirects   # 重定向过多  
exception requests.exceptions.ConnectTimeout(*args, **kwargs)   # 连接到远程服务器时，请求超时
exception requests.exceptions.ReadTimeout(*args, **kwargs)   # 服务器在分配的时间内没有发送任何数据  
exception requests.exceptions.Timeout(*args, **kwargs)  #  请求超时限制

三、Request 对象

requests.Request(method=None, url=None, headers=None, files=None, data={}, params={}, auth=None, cookies=None, hooks=None)

由用户创建的 Request 对象，用来准备一个 PreparedRequest 对象，后者被发给服务器

method – 要使用的 HTTP 方法
url – 目标 URL
headers – 字典，要发送的 HTTP header
files – 字典，形式为{filename: fileobject}，表示要上传的多个部分
data – the body to attach the request. If a dictionary is provided, form-encoding will take place.
params – 字典，包含追加到 URL 后的 URL 参数
auth – Auth 句柄或 (user, pass) 元组
cookies – 附加到这个请求的字典或 CookieJar 对象的cookies
hooks – dictionary of callback hooks, for internal usage.

>>> import requests
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> req.prepare()
<PreparedRequest [GET]>

方法：

register_hook(event, hook)    # 注册一个事件钩子
deregister_hook(event, hook)  # 撤销一个已经注册的 hook，如果 hook 存在则返回 True，否则返回 False
prepare()  # 构造一个 PreparedRequest 对象用于传输，返回一个 PreparedRequest 对象

四、PreparedRequest 对象

4.1 class requests.PreparedRequest

>>> import requests
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> r = req.prepare()
<PreparedRequest [GET]>
 
>>> s = requests.Session()
>>> s.send(r)
<Response [200]>

属性与方法：

body = None  # 发送给服务器的请求 body
deregister_hook(event, hook)  # 撤销一个已经注册的 hook，如果 hook 存在则返回 True，否则返回 False
headers = None   # 由HTTP headers构成的字典　　
hooks = None  # dictionary of callback hooks, 仅供内部使用
method = None  # HTTP 方法
path_url  # 构造要使用的路径URL
prepare(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)   # 用给定的参数准备整个请求
prepare_auth(auth, url='')  # 准备给定的 HTTP 认证数据
prepare_body(data, files, json=None)  # 准备给定的 HTTP body 数据
prepare_cookies(cookies)  # 准备给定的 HTTP cookie 数据
prepare_headers(headers)  # prepare_headers(headers)
prepare_hooks(hooks)   # 准备给定的 hooks
prepare_method(method)  # 准备给定的 HTTP 方法
prepare_url(url, params)  # 准备给定的 HTTP URL
register_hook(event, hook)  # 适当地注册一个 hook
url = None  # 将请求发往的 HTTP URL

五、Response对象

5.1 requests.Response

属性与方法：

apparent_encoding  #  编码
content  # 以字节表示的响应内容
cookies = None  # 一个服务器发回的 cookie 的 CookieJar
elapsed = None  # 发出请求和接收到响应之间的时间间隔 (一个 timedelta)
encoding = None   # 访问r.text时要以何种编码方式解码
headers = None  # 大小写无关的响应头组成的字典，例如： headers['content-encoding'] 将会返回 'Content-Encoding' 响应头的值
history = None  # 请求历史的响应对象列表。 任何重定向响应都会到这里。 该列表从最早的请求到最近的请求排序
iter_content(chunk_size=1, decode_unicode=False)   # 遍历响应数据。 这避免了一次将内容读入内存以获得较大的响应。 块大小是它应该读入内存的字节数。 这不一定是解码时返回的每个条目的长度。 
iter_lines(chunk_size=512, decode_unicode=None)  # 在响应数据上迭代，一次一行。 这避免了一次将内容读入内存以获得较大的响应。  
json(**kwargs)   # 如果存在，返回JSON格式编码的响应内容
links  # 如果有，返回已解析的响应头链接  
raise_for_status()  # 如果发生HTTPError，则引发存储的HTTPError。
raw = None  # 响应的文件类对象表示(用于高级使用)。 要求请求中的' ' stream=True '。  
status_code = None  # 整数HTTP响应状态码。
text  # uncode格式的响应内容
url = None  # 响应的最终URL地址

六、Session 对象

6.1 requests.Session 　　

>>> import requests
>>> s = requests.Session()
>>> s.get('http://httpbin.org/get')
200

属性与方法：

auth = None  # 附加到 Request 对象上的默认认证元组或对象
cert = None  # SSL 证书的缺省值
close()   # 关闭所有的 adapters 和 session
delete(url, **kwargs)   # 发送一个 DELETE 请求，返回 Response 对象
get(url, **kwargs)  # 发送一个 GET 请求，返回 Response 对象
get_adapter(url)  # 返回给定URL的适当连接适配器
head(url, **kwargs)  # 发送一个 HEAD 请求，返回 Response 对象
headers = None  # 一个大小写不敏感的字典，包含了这个 Session 发出的所有 Request 对象都包含的 headers
hooks = None  # 事件处理 hook
max_redirects = None  # 最大重定向次数
mount(prefix, adapter)  # 将一个连接适配器注册到一个前缀上
options(url, **kwargs)   # 发送一个 OPTIONS 请求，返回 Response 对象
params = None  # 查询字符串数据字典，附加到每个请求。 字典值可以是表示多值查询参数的列表。 
patch(url, data=None, **kwargs)   # 发送一个 PATCH 请求，返回 Response 对象
proxies = None  # 字典，将协议映射为每个Request使用的代理URL地址（例如： {‘http’: ‘foo.bar:3128’}) 
put(url, data=None, **kwargs)   # 发送一个 PUT 请求，返回 Response 对象
resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None)  # 接受一个 Response，返回一个 Responses 的 generator
send(request, **kwargs)  # 发送一个给定的 PreparedRequest 对象
stream = None  # 流式响应内容
trust_env = None   # 是否信任环境
verify = None   # SSL 验证的默认值

6.1 auth = None

　　附加到 Request 对象上的默认认证元组或对象

6.2 cert = None

　　SSL 证书的缺省值

6.3 close()

　　关闭所有的 adapters 和 session

6.4 delete(url, **kwargs)

　　发送一个 DELETE 请求，返回 Response 对象

　　参数:

url – URL for the new Request object.
**kwargs – 可选 arguments that request takes

6.5 get(url, **kwargs)

　　发送一个 GET 请求，返回 Response 对象

　　参数:

url – URL for the new Request object.
**kwargs – 可选 arguments that request takes.

6.6 get_adapter(url)

　　返回给定URL的适当连接适配器

6.7 head(url, **kwargs)

　　发送一个 HEAD 请求，返回 Response 对象

　　参数:

url – 新 Request 对象的URL
**kwargs – 请求需要的可选参数

6.8 headers = None

　　一个大小写不敏感的字典，包含了这个 Session 发出的所有 Request 对象都包含的 headers

6.9 hooks = None

　　事件处理 hook

6.10 max_redirects = None

　　最大重定向次数

6.11 mount(prefix, adapter)

　　将一个连接适配器注册到一个前缀上

6.12 options(url, **kwargs)

　　发送一个 OPTIONS 请求，返回 Response 对象

　　参数:

url – URL for the new Request object.
**kwargs – 可选 arguments that request takes.

6.13 params = None

　　Dictionary of querystring data to attach to each Request. The dictionary values may be lists for representing multivalued query parameters.

6.14 patch(url, data=None, **kwargs)

　　发送一个 PATCH 请求，返回 Response 对象

　　参数:

url – URL for the new Request object.
data – (可选) Dictionary, bytes, or file-like object to send in the body of the Request.
**kwargs – 可选 arguments that request takes.

6.15 post(url, data=None, **kwargs)

　　发送一个 POST 请求，返回 Response 对象

　　参数:

url – URL for the new Request object.
data – (可选) Dictionary, bytes, or file-like object to send in the body of the Request.
**kwargs – 可选 arguments that request takes.

6.16 proxies = None

　　字典，将协议映射为每个Request使用的代理URL地址（例如： {‘http’: ‘foo.bar:3128’})

6.17 put(url, data=None, **kwargs)

　　发送一个 PUT 请求，返回 Response 对象

　　参数:

url – 新 Request 对象的 URL
data – (可选) Dictionary, bytes, or file-like object to send in the body of the Request.
**kwargs – 可选 arguments that request takes.

6.18 resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None)

　　接受一个 Response，返回一个 Responses 的 generator

6.19 send(request, **kwargs)

　　发送一个给定的 PreparedRequest 对象

6.20 stream = None

　　流式响应内容

6.21 trust_env = None

　　是否信任环境

6.22 verify = None

　　SSL 验证的默认值

七、HTTPAdapter

class requests.adapters.HTTPAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)

针对 urllib3 的内置 HTTP Adapter，通过实现传输适配器接口，为 session 和 HTTP、 HTTPS连接提供了一个通用的接口。该类的实例通常由内部包裹下的Session类创建。

参数：

pool_connections – 缓存的 urllib3 连接池个数
pool_maxsize – 连接池中保存的最大连接数
max_retries (int) – 每次连接的最大失败重试次数，只用于 DNS 查询失败，socket 连接或连接超时，默认情况下 Requests 不会重试失败的连接，如果你需要对请求重试的条件进行细粒度的控制，可以引入 urllib3 的 Retry 类
pool_block – 连接池是否应该为连接阻塞

>>> import requests
>>> s = requests.Session()
>>> a = requests.adapters.HTTPAdapter(max_retries=3)
>>> s.mount('http://', a)

方法：

7.1 add_headers(request, **kwargs)

　　添加需要的 header，用户代码中不应该调用该方法，该方法应该只在 HTTPAdapter 的子类中使用

　　参数：

request – 要添加 header 的 PreparedRequest 对象
kwargs – 同于调用 send() 时的关键字参数

7.2 build_response(req, resp)

　　从一个 urllib3 响应构建一个Response对象，用户代码中不该调用该方法，该方法应该只在 HTTPAdapter 的子类中使用

　　参数：

req – 用于产生响应的 PreparedRequest 对象
resp – urllib3 响应对象

7.3 cert_verify(conn, url, verify, cert)

　　验证一个 SSL 证书，用户代码中不该调用该方法，该方法应该只在 HTTPAdapter 的子类中使用

　　参数：

conn – 与证书相关的 urllib3 connection 对象
url – 被请求的 URL.
verify – 是否真的验证证书
cert – 要验证的 SSL 证书

7.4 close()

　　处理掉所有的内部状态

　　当前该方法仅仅关闭 PoolManager 进而断开池中的连接

7.5 get_connection(url, proxies=None)

　　对于给定的URL，返回一个 urllib3 连接。用户代码中不该调用该方法，该方法应该只在 HTTPAdapter 的子类中使用

　　参数：

　　url – 要连接的URL

　　proxies – (可选) 一个 Requests 风格的字典，内容是此次请求使用的代理

7.6 init_poolmanager(connections, maxsize, block=False, **pool_kwargs)

　　初始化一个 urllib3 PoolManager 实例

　　用户代码中不该调用该方法，该方法应该只在 HTTPAdapter 的子类中使用

　　参数：

connections – 要缓存的 urllib3 连接池的个数
maxsize – 连接池可容纳的最大连接数
block – 没有可用连接时就阻塞
pool_kwargs – 初始化 Pool Manager 的其他关键字参数

7.7 proxy_headers(proxy)

　　Returns a dictionary of the headers to add to any request sent through a proxy. This works with urllib3 magic to ensure that they are correctly sent to the proxy, rather than in a tunnelled request if CONNECT is being used.

　　用户代码中不该调用该方法，该方法应该只在 HTTPAdapter 的子类中使用

　　参数：

proxies – 该请求使用的代理URL
kwargs – 可选的关键字参数

7.8 proxy_manager_for(proxy, **proxy_kwargs)

　　返回给定代理的 urllib3 ProxyManager 对象，用户代码中不该调用该方法，该方法应该只在 HTTPAdapter 的子类中使用

　　参数：

proxy – 要返回 urllib3 ProxyManager 的代理
proxy_kwargs – 用来配置Proxy Manager 的额外的关键字参数

　　返回：

　　ProxyManager

7.9 request_url(request, proxies)

　　获取最后一个请求的url，如果消息是由HTTP代理发送的，则必须使用完整的URL，否则只需要使用URL的路径部分

　　用户代码中不该调用该方法，该方法应该只在 HTTPAdapter 的子类中使用

　　参数：

request – 要发送的 PreparedRequest 对象
proxies – A dictionary of schemes to proxy URLs.

7.10 send(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)

　　发送 PreparedRequest 对象，返回 Response 对象

　　参数：

request – 要发送的 PreparedRequest 对象
stream – (可选) 是否 stream 请求的内容
timeout (float 或 tuple) –(可选) How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
verify – (可选) 是否验证 SSL 证书
cert – (可选) 可信任的用户提供的 SSL 证书
proxies – (可选) The proxies dictionary to apply to the request.

八、认证

8.1 class requests.auth.AuthBase

　　所有认证的基类

8.2 class requests.auth.HTTPBasicAuth(username, password)

　　将 HTTP Basic Authentication 附加到给定的 Request 对象

8.3 class requests.auth.HTTPProxyAuth(username, password)

　　将 HTTP Proxy Authentication 附加到给定的 Request 对象

8.4 class requests.auth.HTTPDigestAuth(username, password)

　　将 HTTP Digest Authentication 附加到给定的 Request 对象

九、编码

9.1 requests.utils.get_encodings_from_content(content)

　　返回给定内容的编码格式

　　参数：

content – 要从中提取编码格式的 bytestring

9.2 requests.utils.get_encoding_from_headers(headers)

　　根据给定的 HTTP Header 字典返回编码格式

　　参数：

headers – 要从中提取编码格式的字典

9.3 requests.utils.get_unicode_from_response(r)

　　以 unicode 返回响应内容

　　参数：

r – 要从中提取编码格式的 Response 对象

　　尝试：

content-type 里的字符集
fall back and replace all unicode characters

十、状态码查询

requests.codes()

>>> requests.codes['temporary_redirect']
307
 
>>> requests.codes.teapot
418
 
>>> requests.codes['\o/']
200

发表于 2022-01-21 11:24 守护式等待阅读(162) 评论(0) 编辑收藏举报