API Reference#
Mixin class that adds rate-limiting behavior to requests. |
|
Session that adds rate-limiting behavior to requests. |
|
Transport adapter that adds rate-limiting behavior to requests. |
- class requests_ratelimiter.requests_ratelimiter.LimiterMixin(per_second=0, per_minute=0, per_hour=0, per_day=0, per_month=0, burst=1, bucket_class=<class 'pyrate_limiter.bucket.MemoryQueueBucket'>, bucket_kwargs=None, limiter=None, max_delay=None, per_host=True, limit_statuses=(429, ), **kwargs)#
Mixin class that adds rate-limiting behavior to requests.
The following parameters also apply to
LimiterSession
andLimiterAdapter
.Note
The
per_*
params are aliases for the most common rate limit intervals; for more complex rate limits, you can provide aLimiter
object instead.- Parameters
per_second (
float
) – Max requests per secondper_minute (
float
) – Max requests per minuteper_hour (
float
) – Max requests per hourper_day (
float
) – Max requests per dayper_month (
float
) – Max requests per monthburst (
float
) – Max number of consecutive requests allowed before applying per-second rate-limitingbucket_class (
Type
[AbstractBucket
]) – Bucket backend class; may be one ofMemoryQueueBucket
(default),SQLiteBucket
, orRedisBucket
bucket_kwargs (
Optional
[Dict
]) – Bucket backend keyword argumentslimiter (
Optional
[Limiter
]) – An existing Limiter object to use instead of the above paramsmax_delay (
Union
[int
,float
,None
]) – The maximum allowed delay time (in seconds); anything over this will abort the requestper_host (
bool
) – Track request rate limits separately for each host
- class requests_ratelimiter.requests_ratelimiter.LimiterSession(per_second=0, per_minute=0, per_hour=0, per_day=0, per_month=0, burst=1, bucket_class=<class 'pyrate_limiter.bucket.MemoryQueueBucket'>, bucket_kwargs=None, limiter=None, max_delay=None, per_host=True, limit_statuses=(429, ), **kwargs)#
Bases:
requests_ratelimiter.requests_ratelimiter.LimiterMixin
,requests.sessions.Session
Session that adds rate-limiting behavior to requests.
- auth#
Default Authentication tuple or object to attach to
Request
.
- cert#
SSL client certificate default, if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.
- close()#
Closes all adapters and as such the session
- cookies#
A CookieJar containing all currently outstanding cookies set on this session. By default it is a
RequestsCookieJar
, but may be any othercookielib.CookieJar
compatible object.
- delete(url, **kwargs)#
Sends a DELETE request. Returns
Response
object.- Parameters
url – URL for the new
Request
object.**kwargs – Optional arguments that
request
takes.
- Return type
- get(url, **kwargs)#
Sends a GET request. Returns
Response
object.- Parameters
url – URL for the new
Request
object.**kwargs – Optional arguments that
request
takes.
- Return type
- get_adapter(url)#
Returns the appropriate connection adapter for the given URL.
- Return type
- get_redirect_target(resp)#
Receives a Response. Returns a redirect URI or
None
- head(url, **kwargs)#
Sends a HEAD request. Returns
Response
object.- Parameters
url – URL for the new
Request
object.**kwargs – Optional arguments that
request
takes.
- Return type
- headers#
A case-insensitive dictionary of headers to be sent on each
Request
sent from thisSession
.
- hooks#
Event-handling hooks.
- max_redirects#
Maximum number of redirects allowed. If the request exceeds this limit, a
TooManyRedirects
exception is raised. This defaults to requests.models.DEFAULT_REDIRECT_LIMIT, which is 30.
- merge_environment_settings(url, proxies, stream, verify, cert)#
Check the environment and merge it with some settings.
- Return type
- mount(prefix, adapter)#
Registers a connection adapter to a prefix.
Adapters are sorted in descending order by prefix length.
- options(url, **kwargs)#
Sends a OPTIONS request. Returns
Response
object.- Parameters
url – URL for the new
Request
object.**kwargs – Optional arguments that
request
takes.
- Return type
- params#
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.- Parameters
url – URL for the new
Request
object.data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the
Request
.**kwargs – Optional arguments that
request
takes.
- Return type
- post(url, data=None, json=None, **kwargs)#
Sends a POST request. Returns
Response
object.- Parameters
url – URL for the new
Request
object.data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the
Request
.json – (optional) json to send in the body of the
Request
.**kwargs – Optional arguments that
request
takes.
- Return type
- prepare_request(request)#
Constructs a
PreparedRequest
for transmission and returns it. ThePreparedRequest
has settings merged from theRequest
instance and those of theSession
.- Parameters
request –
Request
instance to prepare with this session’s settings.- Return type
- proxies#
Dictionary mapping protocol or protocol and host to the URL of the proxy (e.g. {‘http’: ‘foo.bar:3128’, ‘http://host.name’: ‘foo.bar:4012’}) to be used on each
Request
.
- put(url, data=None, **kwargs)#
Sends a PUT request. Returns
Response
object.- Parameters
url – URL for the new
Request
object.data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the
Request
.**kwargs – Optional arguments that
request
takes.
- Return type
- rebuild_auth(prepared_request, response)#
When being redirected we may want to strip authentication from the request to avoid leaking credentials. This method intelligently removes and reapplies authentication where possible to avoid credential loss.
- rebuild_method(prepared_request, response)#
When being redirected we may want to change the method of the request based on certain specs or browser behavior.
- rebuild_proxies(prepared_request, proxies)#
This method re-evaluates the proxy configuration by considering the environment variables. If we are redirected to a URL covered by NO_PROXY, we strip the proxy configuration. Otherwise, we set missing proxy keys for this URL (in case they were stripped by a previous redirect).
This method also replaces the Proxy-Authorization header where necessary.
- Return type
- request(method, url, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None)#
Constructs a
Request
, prepares it and sends it. ReturnsResponse
object.- Parameters
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, list of tuples, bytes, or file-like object to send in the body of the
Request
.json – (optional) json 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
'filename': file-like-objects
for multipart encoding upload.auth – (optional) Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.
timeout (float or tuple) – (optional) How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
allow_redirects (bool) – (optional) Set to True by default.
proxies – (optional) Dictionary mapping protocol or protocol and hostname to the URL of the proxy.
stream – (optional) whether to immediately download the response content. Defaults to
False
.verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to
True
. When set toFalse
, requests will accept any TLS certificate presented by the server, and will ignore hostname mismatches and/or expired certificates, which will make your application vulnerable to man-in-the-middle (MitM) attacks. Setting verify toFalse
may be useful during local development or testing.cert – (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.
- Return type
- resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None, yield_requests=False, **adapter_kwargs)#
Receives a Response. Returns a generator of Responses or Requests.
- should_strip_auth(old_url, new_url)#
Decide whether Authorization header should be removed when redirecting
- stream#
Stream response content default.
- trust_env#
Trust environment settings for proxy configuration, default authentication and similar.
- verify#
SSL Verification default. Defaults to True, requiring requests to verify the TLS certificate at the remote end. If verify is set to False, requests will accept any TLS certificate presented by the server, and will ignore hostname mismatches and/or expired certificates, which will make your application vulnerable to man-in-the-middle (MitM) attacks. Only set this to False for testing.
- class requests_ratelimiter.requests_ratelimiter.LimiterAdapter(per_second=0, per_minute=0, per_hour=0, per_day=0, per_month=0, burst=1, bucket_class=<class 'pyrate_limiter.bucket.MemoryQueueBucket'>, bucket_kwargs=None, limiter=None, max_delay=None, per_host=True, limit_statuses=(429, ), **kwargs)#
Bases:
requests_ratelimiter.requests_ratelimiter.LimiterMixin
,requests.adapters.HTTPAdapter
Transport adapter that adds rate-limiting behavior to requests.
- add_headers(request, **kwargs)#
Add any headers needed by the connection. As of v2.0 this does nothing by default, but is left for overriding by users that subclass the
HTTPAdapter
.This should not be called from user code, and is only exposed for use when subclassing the
HTTPAdapter
.- Parameters
request – The
PreparedRequest
to add headers to.kwargs – The keyword arguments from the call to send().
- build_response(req, resp)#
Builds a
Response
object from a urllib3 response. This should not be called from user code, and is only exposed for use when subclassing theHTTPAdapter
- Parameters
req – The
PreparedRequest
used to generate the response.resp – The urllib3 response object.
- Return type
- cert_verify(conn, url, verify, cert)#
Verify a SSL certificate. This method should not be called from user code, and is only exposed for use when subclassing the
HTTPAdapter
.- Parameters
conn – The urllib3 connection object associated with the cert.
url – The requested URL.
verify – Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use
cert – The SSL certificate to verify.
- close()#
Disposes of any internal state.
Currently, this closes the PoolManager and any active ProxyManager, which closes any pooled connections.
- get_connection(url, proxies=None)#
Returns a urllib3 connection for the given URL. This should not be called from user code, and is only exposed for use when subclassing the
HTTPAdapter
.- Parameters
url – The URL to connect to.
proxies – (optional) A Requests-style dictionary of proxies used on this request.
- Return type
urllib3.ConnectionPool
- init_poolmanager(connections, maxsize, block=False, **pool_kwargs)#
Initializes a urllib3 PoolManager.
This method should not be called from user code, and is only exposed for use when subclassing the
HTTPAdapter
.- Parameters
connections – The number of urllib3 connection pools to cache.
maxsize – The maximum number of connections to save in the pool.
block – Block when no free connections are available.
pool_kwargs – Extra keyword arguments used to initialize the Pool Manager.
- 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.
This should not be called from user code, and is only exposed for use when subclassing the
HTTPAdapter
.- Parameters
proxy – The url of the proxy being used for this request.
- Return type
- proxy_manager_for(proxy, **proxy_kwargs)#
Return urllib3 ProxyManager for the given proxy.
This method should not be called from user code, and is only exposed for use when subclassing the
HTTPAdapter
.- Parameters
proxy – The proxy to return a urllib3 ProxyManager for.
proxy_kwargs – Extra keyword arguments used to configure the Proxy Manager.
- Returns
ProxyManager
- Return type
- request_url(request, proxies)#
Obtain the url to use when making the final request.
If the message is being sent through a HTTP proxy, the full URL has to be used. Otherwise, we should only use the path portion of the URL.
This should not be called from user code, and is only exposed for use when subclassing the
HTTPAdapter
.- Parameters
request – The
PreparedRequest
being sent.proxies – A dictionary of schemes or schemes and hosts to proxy URLs.
- Return type