requests 开发者接口
开发者接口
这部分文档包含了Requests所有的接口。对于Requests依赖的外部库部分，我们介绍 一些比较重要的并提供规范文档的链接。
主要接口
Requests所有的功能都可以通过以下7个方法访问。 它们全部都会返回 Response 对象的一个实例。
requests.request(method, url, **kwargs)
Constructs and sends a Request. Returns Response object.
参数:
method – method for the new Request object.
url – URL for the new Request object.
params – (optional) Dictionary or bytes to be sent in the query string for the Request.
data – (optional) Dictionary, bytes, or file-like object to send in the body of the Request.
headers – (optional) Dictionary of HTTP Headers to send with the Request.
cookies – (optional) Dict or CookieJar object to send with the Request.
files – (optional) Dictionary of ‘name’: file-like-objects (or {‘name’: (‘filename’, fileobj)}) for multipart encoding upload.
auth – (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
timeout – (optional) Float describing the timeout of the request.
allow_redirects – (optional) Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.
proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
verify – (optional) if True, the SSL cert will be verified. A CA_BUNDLE path can also be provided.
stream – (optional) if False, the response content will be immediately downloaded.
cert – (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.
Usage:
>>> import requests
>>> req = requests.request('GET', 'http://httpbin.org/get')
<Response [200]>
requests.head(url, **kwargs)
Sends a HEAD request. Returns Response object.
参数:
url – URL for the new Request object.
**kwargs – Optional arguments that request takes.
requests.get(url, **kwargs)
Sends a GET request. Returns Response object.
参数:
url – URL for the new Request object.
**kwargs – Optional arguments that request takes.
requests.post(url, data=None, **kwargs)
Sends a POST request. Returns Response object.
参数:
url – URL for the new Request object.
data – (optional) Dictionary, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.
requests.put(url, data=None, **kwargs)
Sends a PUT request. Returns Response object.
参数:
url – URL for the new Request object.
data – (optional) Dictionary, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.
requests.patch(url, data=None, **kwargs)
Sends a PATCH request. Returns Response object.
参数:
url – URL for the new Request object.
data – (optional) Dictionary, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.
requests.delete(url, **kwargs)
Sends a DELETE request. Returns Response object.
参数:
url – URL for the new Request object.
**kwargs – Optional arguments that request takes.
较低级别的类
class requests.Request(method=None, url=None, headers=None, files=None, data={}, params={}, auth=None, cookies=None, hooks=None)
A user-created Request object.
Used to prepare a PreparedRequest, which is sent to the server.
参数:
method – HTTP method to use.
url – URL to send.
headers – dictionary of headers to send.
files – dictionary of {filename: fileobject} files to multipart upload.
data – the body to attach the request. If a dictionary is provided, form-encoding will take place.
params – dictionary of URL parameters to append to the URL.
auth – Auth handler or (user, pass) tuple.
cookies – dictionary or CookieJar of cookies to attach to this request.
hooks – dictionary of callback hooks, for internal usage.
Usage:
>>> import requests
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> req.prepare()
<PreparedRequest [GET]>
deregister_hook(event, hook)
Deregister a previously registered hook. Returns True if the hook existed, False if not.
prepare()
Constructs a PreparedRequest for transmission and returns it.
register_hook(event, hook)
Properly register a hook.
class requests.Response
The Response object, which contains a server’s response to an HTTP request.
apparent_encoding
The apparent encoding, provided by the lovely Charade library (Thanks, Ian!).
content
Content of the response, in bytes.
cookies = None
A CookieJar of Cookies the server sent back.
elapsed = None
The amount of time elapsed between sending the request and the arrival of the response (as a timedelta)
encoding = None
Encoding to decode with when accessing r.text.
headers = None
Case-insensitive Dictionary of Response Headers.
For example, headers['content-encoding'] will return the value of a 'Content-Encoding' response header.
history = None
A list of Response objects from the history of the Request.
Any redirect responses will end up here. The list is sorted from the oldest to the most recent request.
iter_content(chunk_size=1, decode_unicode=False)
Iterates over the response data. This avoids reading the content at once into memory for large responses.
The chunk size is the number of bytes it should read into memory.
This is not necessarily the length of each item returned as decoding can take place.
iter_lines(chunk_size=512, decode_unicode=None)
Iterates over the response data, one line at a time. This avoids reading the content at once into memory for large responses.
json(**kwargs)
Returns the json-encoded content of a response, if any.
参数: **kwargs – Optional arguments that json.loads takes.
links
Returns the parsed header links of the response, if any.
raise_for_status()
Raises stored HTTPError, if one occurred.
raw = None
File-like object representation of response (for advanced usage). Requires that ``stream=True` on the request.
status_code = None
Integer Code of responded HTTP Status.
text
Content of the response, in unicode.
if Response.encoding is None and chardet module is available, encoding will be guessed.
url = None
Final URL location of Response.
请求会话
class requests.Session
A Requests session.
Provides cookie persistience, connection-pooling, and configuration.
Basic Usage:
>>> import requests
>>> s = requests.Session()
>>> s.get('http://httpbin.org/get')
200
auth = None
Default Authentication tuple or object to attach to Request.
cert = None
SSL certificate default.
close()
Closes all adapters and as such the session
delete(url, **kwargs)
Sends a DELETE request. Returns Response object.
参数:
url – URL for the new Request object.
**kwargs – Optional arguments that request takes.
get(url, **kwargs)
Sends a GET request. Returns Response object.
参数:
url – URL for the new Request object.
**kwargs – Optional arguments that request takes.
get_adapter(url)
Returns the appropriate connnection adapter for the given URL.
head(url, **kwargs)
Sends a HEAD request. Returns Response object.
参数:
url – URL for the new Request object.
**kwargs – Optional arguments that request takes.
headers = None
A case-insensitive dictionary of headers to be sent on each Request sent from this Session.
hooks = None
Event-handling hooks.
max_redirects = None
Maximum number of redirects to follow.
mount(prefix, adapter)
Registers a connection adapter to a prefix.
options(url, **kwargs)
Sends a OPTIONS request. Returns Response object.
参数:
url – URL for the new Request object.
**kwargs – Optional arguments that request takes.
params = None
Dictionary of querystring data to attach to each Request.
The dictionary values may be lists for representing multivalued query parameters.
patch(url, data=None, **kwargs)
Sends a PATCH request. Returns Response object.
参数:
url – URL for the new Request object.
data – (optional) Dictionary, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.
post(url, data=None, **kwargs)
Sends a POST request. Returns Response object.
参数:
url – URL for the new Request object.
data – (optional) Dictionary, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.
proxies = None
Dictionary mapping protocol to the URL of the proxy (e.g. {‘http’: ‘foo.bar:3128’}) to be used on each Request.
put(url, data=None, **kwargs)
Sends a PUT request. Returns Response object.
参数:
url – URL for the new Request object.
data – (optional) Dictionary, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.
resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None)
Receives a Response. Returns a generator of Responses.
send(request, **kwargs)
Send a given PreparedRequest.
stream = None
Stream response content default.
trust_env = None
Should we trust the environment?
verify = None
SSL Verification default.
跨请求保持一些cookies:
1 import requests
2
3 s = requests.Session()
4 s.get('http://httpbin.org/cookies/set/sessioncookie/123456789')
5 r = s.get("http://httpbin.org/cookies")
6
7 print(r.text)
8 #'{"cookies": {"sessioncookie": "123456789"}}'
会话也可用来为请求方法提供缺省数据。这是通过为会话对象的属性提供数据来实现的:
1 s = requests.Session()
2 s.auth = ('user', 'pass')
3 s.headers.update({'x-test': 'true'})
4
5 # both 'x-test' and 'x-test2' are sent
6 s.get('http://httpbin.org/headers', headers={'x-test2': 'true'})
Prepared Requests
1 from requests import Request, Session
2
3 s = Session()
4 req = Request('GET', url,
5 data=data,
6 headers=header)
7 prepped = req.prepare()
8
9 # do something with prepped.body
10 # do something with prepped.headers
11
12 resp = s.send(prepped,
13 stream=stream,
14 verify=verify,
15 proxies=proxies,
16 cert=cert,
17 timeout=timeout)
18
19 print(resp.status_code)
1 from requests import Request, Session
2
3 s = Session()
4 req = Request('GET', url,
5 data=data
6 headers=headers
7 )
8
9 prepped = s.prepare_request(req)
10
11 # do something with prepped.body
12 # do something with prepped.headers
13
14 resp = s.send(prepped,
15 stream=stream,
16 verify=verify,
17 proxies=proxies,
18 cert=cert,
19 timeout=timeout)
20 21
22 print(resp.status_code)
异常
exception requests.RequestException
There was an ambiguous exception that occurred while handling your request.
exception requests.ConnectionError
A Connection error occurred.
exception requests.HTTPError(*args, **kwargs)
An HTTP error occurred.
exception requests.URLRequired
A valid URL is required to make a request.
exception requests.TooManyRedirects
Too many redirects.
状态码查询
requests.codes()
Dictionary lookup object.
>>> requests.codes['temporary_redirect']
307
>>> requests.codes.teapot
418
>>> requests.codes['\o/']
200
Cookies
编码
类
class requests.PreparedRequest
The fully mutable PreparedRequest object, containing the exact bytes that will be sent to the server.
Generated from either a Request object or manually.
Usage:
>>> 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
request body to send to the server.
deregister_hook(event, hook)
Deregister a previously registered hook. Returns True if the hook existed, False if not.
headers = None
dictionary of HTTP headers.
hooks = None
dictionary of callback hooks, for internal usage.
method = None
HTTP verb to send to the server.
path_url
Build the path URL to use.
prepare_auth(auth)
Prepares the given HTTP auth data.
prepare_body(data, files)
Prepares the given HTTP body data.
prepare_cookies(cookies)
Prepares the given HTTP cookie data.
prepare_headers(headers)
Prepares the given HTTP headers.
prepare_hooks(hooks)
Prepares the given hooks.
prepare_method(method)
Prepares the given HTTP method.
prepare_url(url, params)
Prepares the given HTTP URL.
register_hook(event, hook)
Properly register a hook.
url = None
HTTP URL to send the request to.
浙公网安备 33010602011771号