pyinaturalist.api_requests¶

Summary¶

`delete`(url, **kwargs)	Wrapper around `requests.delete()` that supports dry-run mode and rate-limiting
`env_to_bool`(environment_variable)	Translate an environment variable to a boolean value, accounting for minor variations (case, None vs.
`get`(url, **kwargs)	Wrapper around `requests.get()` that supports dry-run mode and rate-limiting
`get_limiter`()	Get a rate limiter object, if pyrate-limiter is installed
`get_session`()	Get a Session object that will be reused across requests to take advantage of connection pooling.
`is_dry_run_enabled`(method)	A wrapper to determine if dry-run (aka test mode) has been enabled via either a constant or an environment variable.
`log_request`(args, *kwargs)	Log all relevant information about an HTTP request
`post`(url, **kwargs)	Wrapper around `requests.post()` that supports dry-run mode and rate-limiting
`put`(url, **kwargs)	Wrapper around `requests.put()` that supports dry-run mode and rate-limiting
`ratelimit`([bucket])	Add delays in between requests to stay within the rate limits.
`request`(method, url[, access_token, …])	Wrapper around `requests.request()` that supports dry-run mode and rate-limiting, and adds appropriate headers.

Details¶

Some common functions for HTTP requests used by all API modules

pyinaturalist.api_requests.delete(url, **kwargs)¶

Wrapper around requests.delete() that supports dry-run mode and rate-limiting

Return type: Response

pyinaturalist.api_requests.env_to_bool(environment_variable)¶

Translate an environment variable to a boolean value, accounting for minor variations (case, None vs. False, etc.)

Return type: bool

pyinaturalist.api_requests.get(url, **kwargs)¶

Wrapper around requests.get() that supports dry-run mode and rate-limiting

Return type: Response

pyinaturalist.api_requests.get_limiter()¶: Get a rate limiter object, if pyrate-limiter is installed

pyinaturalist.api_requests.get_session()¶

Get a Session object that will be reused across requests to take advantage of connection pooling. This is especially relevant for large paginated requests. If used in a multi-threaded context (for example, a ThreadPoolExecutor), a separate session is used for each thread.

Return type: Session

pyinaturalist.api_requests.is_dry_run_enabled(method)¶

A wrapper to determine if dry-run (aka test mode) has been enabled via either a constant or an environment variable. Dry-run mode may be enabled for either write requests, or all requests.

Return type: bool

pyinaturalist.api_requests.log_request(*args, **kwargs)¶: Log all relevant information about an HTTP request

pyinaturalist.api_requests.post(url, **kwargs)¶

Wrapper around requests.post() that supports dry-run mode and rate-limiting

Return type: Response

pyinaturalist.api_requests.put(url, **kwargs)¶

Wrapper around requests.put() that supports dry-run mode and rate-limiting

Return type: Response

pyinaturalist.api_requests.ratelimit(bucket='pyinaturalist/0.14.0')¶: Add delays in between requests to stay within the rate limits. If pyrate-limiter is not installed, this will quietly do nothing.

pyinaturalist.api_requests.request(method, url, access_token=None, user_agent=None, ids=None, headers=None, json=None, session=None, raise_for_status=True, timeout=5, **params)¶

Wrapper around requests.request() that supports dry-run mode and rate-limiting, and adds appropriate headers.

Parameters

method (str) – HTTP method
url (str) – Request URL
access_token (Optional[str]) – access_token: the access token, as returned by get_access_token()
user_agent (Optional[str]) – A custom user-agent string to provide to the iNaturalist API
ids (Union[int, Iterable[int], None]) – One or more integer IDs used as REST resource(s) to request
headers (Optional[Dict]) – Request headers
json (Optional[Dict]) – JSON request body
session (Optional[Session]) – Existing Session object to use instead of creating a new one
timeout (float) – Time (in seconds) to wait for a response from the server; if exceeded, a requests.exceptions.Timeout will be raised.
params (Dict[str, Any]) – All other keyword arguments are interpreted as request parameters

Return type

Response

Returns

API response