Session¶

Summary¶

`delete`(url, **kwargs)	Wrapper around `requests.delete()` with additional options specific to iNat API requests
`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()` with additional options specific to iNat API requests
`get_local_session`(**kwargs)	Get a thread-local Session object with default settings.
`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.
`post`(url, **kwargs)	Wrapper around `requests.post()` with additional options specific to iNat API requests
`prepare_request`(session, method, url[, ...])	Translate `pyinaturalist`-specific options into standard request arguments
`put`(url, **kwargs)	Wrapper around `requests.put()` with additional options specific to iNat API requests
`request`(method, url[, access_token, ...])	Wrapper around `requests.request()` with additional options specific to iNat API requests

Module Contents¶

Session class and related functions for preparing and sending API requests

class pyinaturalist.session.ClientSession(expire_after=None, cache_file='/home/docs/.cache/pyinaturalist/api_requests.db', per_second=1, per_minute=60, per_day=10000, burst=5, retries=5, backoff_factor=0.5, timeout=10, user_agent=None, **kwargs)¶

Bases: requests_cache.session.CacheMixin, requests_ratelimiter.requests_ratelimiter.LimiterMixin, requests.Session

Custom session class used for sending API requests. Combines the following features and settings:

Caching
Rate-limiting (skipped for cached requests)
Retries
Timeouts

This is the default and recommended session class to use for API requests, but can be safely replaced with any Session-compatible class via the session argument for API request functions.

__init__(expire_after=None, cache_file='/home/docs/.cache/pyinaturalist/api_requests.db', per_second=1, per_minute=60, per_day=10000, burst=5, retries=5, backoff_factor=0.5, timeout=10, user_agent=None, **kwargs)¶

Get a Session object, optionally with custom settings for caching and rate-limiting.

Parameters

expire_after (Union[None, int, float, str, datetime, timedelta]) – How long to keep cached API requests; for advanced options, see requests-cache: Expiration
cache_file (Union[BinaryIO, str]) – Cache file path to use; defaults to the system default cache directory
per_second (int) – Max requests per second
per_minute (int) – Max requests per minute
per_day (float) – Max requests per day
burst (int) – Max number of consecutive requests allowed before applying per-second rate-limiting
retries (int) – Maximum number of times to retry a failed request
backoff_factor (float) – Factor for increasing delays between retries
timeout (int) – Maximum number of seconds to wait for a response from the server
user_agent (Optional[str]) – Additional User-Agent info to pass to API requests
kwargs – Additional keyword arguments for CachedSession and/or LimiterSession

send(request, **kwargs)¶

Send a request with caching, rate-limiting, and retries

Return type: Response

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

Wrapper around requests.delete() with additional options specific to iNat API requests

Return type: Response

pyinaturalist.session.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.session.get(url, **kwargs)¶

Wrapper around requests.get() with additional options specific to iNat API requests

Return type: Response

pyinaturalist.session.get_local_session(**kwargs)¶

Get a thread-local Session object with default settings. This will be reused across requests to take advantage of connection pooling and (optionally) caching. If used in a multi-threaded context (for example, a ThreadPoolExecutor), this will create and store a separate session object for each thread.

Parameters: kwargs – Keyword arguments for ClientSession()
Return type: Session

pyinaturalist.session.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.session.post(url, **kwargs)¶

Wrapper around requests.post() with additional options specific to iNat API requests

Return type: Response

pyinaturalist.session.prepare_request(session, method, url, access_token=None, files=None, headers=None, ids=None, json=None, params=None, **kwargs)¶

Translate pyinaturalist-specific options into standard request arguments

Return type: PreparedRequest

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

Wrapper around requests.put() with additional options specific to iNat API requests

Return type: Response

pyinaturalist.session.request(method, url, access_token=None, dry_run=False, files=None, headers=None, ids=None, json=None, raise_for_status=True, session=None, **params)¶

Wrapper around requests.request() with additional options specific to iNat API requests

Parameters

method (str) – HTTP method
url (str) – Request URL
access_token (Optional[str]) – access_token: the access token, as returned by get_access_token()
dry_run (bool) – Just log the request instead of sending a real request
files (Union[BinaryIO, str, None]) – File object, path, or URL to upload
headers (Optional[Dict]) – Request headers
ids (Union[int, Iterable[int], None]) – One or more integer IDs used as REST resource(s) to request
json (Optional[Dict]) – JSON request body
session (Optional[Session]) – An existing Session object to use instead of creating a new one
timeout – 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