pyinaturalist.api_requests module¶
Some common functions for HTTP requests used by all API modules
- pyinaturalist.api_requests.delete(url, **kwargs)[source]¶
Wrapper around
requests.delete()
that supports dry-run mode and rate-limiting- Return type
- Parameters
url (str) –
access_token (str) –
user_agent (str) –
ids (Union[int, List[int]]) –
params (Dict[str, Any]) –
headers (Dict) –
session (
requests.Session
) –
- pyinaturalist.api_requests.env_to_bool(environment_variable)[source]¶
Translate an environment variable to a boolean value, accounting for minor variations (case, None vs. False, etc.)
- Return type
bool
- Parameters
environment_variable (str) –
- pyinaturalist.api_requests.get(url, **kwargs)[source]¶
Wrapper around
requests.get()
that supports dry-run mode and rate-limiting- Return type
- Parameters
url (str) –
access_token (str) –
user_agent (str) –
ids (Union[int, List[int]]) –
params (Dict[str, Any]) –
headers (Dict) –
session (
requests.Session
) –
- pyinaturalist.api_requests.get_limiter()[source]¶
Get a rate limiter object, if pyrate-limiter is installed
- pyinaturalist.api_requests.get_session()[source]¶
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
- pyinaturalist.api_requests.is_dry_run_enabled(method)[source]¶
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
- Parameters
method (str) –
- pyinaturalist.api_requests.log_request(*args, **kwargs)[source]¶
Log all relevant information about an HTTP request
- pyinaturalist.api_requests.post(url, **kwargs)[source]¶
Wrapper around
requests.post()
that supports dry-run mode and rate-limiting- Return type
- Parameters
url (str) –
access_token (str) –
user_agent (str) –
ids (Union[int, List[int]]) –
params (Dict[str, Any]) –
headers (Dict) –
session (
requests.Session
) –
- pyinaturalist.api_requests.put(url, **kwargs)[source]¶
Wrapper around
requests.put()
that supports dry-run mode and rate-limiting- Return type
- Parameters
url (str) –
access_token (str) –
user_agent (str) –
ids (Union[int, List[int]]) –
params (Dict[str, Any]) –
headers (Dict) –
session (
requests.Session
) –
- pyinaturalist.api_requests.ratelimit(bucket='pyinaturalist/0.13.0')[source]¶
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, params=None, headers=None, session=None, **kwargs)[source]¶
Wrapper around
requests.request()
that supports dry-run mode and rate-limiting, and adds appropriate headers.- Parameters
method (
str
) – HTTP methodurl (
str
) – Request URLaccess_token (
Optional
[str
]) – access_token: the access token, as returned byget_access_token()
user_agent (
Optional
[str
]) – a user-agent string that will be passed to iNaturalistids (
Union
[int
,List
[int
],None
]) – One or more integer IDs used as REST resource(s) to requestparams (
Optional
[Dict
[str
,Any
]]) – Requests parametersheaders (
Optional
[Dict
]) – Request headerssession (
Optional
[Session
]) – Existing Session object to use instead of creating a new one
- Return type
- Returns
API response