Session#

Summary#

clear_cache()

Clear all cached API responses

delete(url[, session])

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[, session])

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.

get_refresh_params(endpoint)

In some cases, we need to be sure we have the most recent version of a resource, for example when updating projects.

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[, session])

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

put(url[, session])

Wrapper around requests.put() 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, bucket_class=<class 'pyrate_limiter.sqlite_bucket.SQLiteBucket'>, backoff_factor=0.5, max_retries=5, timeout=10, user_agent=None, **kwargs)#

Bases: requests_cache.session.CacheMixin, requests_ratelimiter.requests_ratelimiter.LimiterMixin, requests.sessions.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, bucket_class=<class 'pyrate_limiter.sqlite_bucket.SQLiteBucket'>, backoff_factor=0.5, max_retries=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

  • bucket_class (Type[AbstractBucket]) – Rate-limiting backend to use. Defaults to a persistent SQLite database.

  • backoff_factor (float) – Factor for increasing delays between retries

  • max_retries (int) – Maximum number of times to retry a failed request

  • 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

prepare_inat_request(method, url, access_token=None, files=None, headers=None, ids=None, json=None, params=None, allow_str_ids=False, **kwargs)#

Translate pyinaturalist-specific options into standard request arguments

Return type

PreparedRequest

request(method, url, headers=None, json=None, access_token=None, allow_redirects=False, allow_str_ids=False, dry_run=False, expire_after=None, files=None, ids=None, raise_for_status=True, refresh=False, stream=False, timeout=None, verify=True, **params)#

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

Parameters

  • method (str) – HTTP method

  • url (str) – Request URL

  • headers (Optional[Dict]) – Request headers

  • json (Optional[Dict]) – JSON request body

  • 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

  • expire_after (Union[None, int, float, str, datetime, timedelta]) – How long to keep cached API requests

  • files (Union[BinaryIO, str, None]) – File object, path, or URL to upload

  • ids (Union[int, Iterable[int], None]) – One or more integer IDs used as REST resource(s) to request

  • refresh (bool) – Skip reading from the cache and always fetch a fresh response

  • timeout (Optional[int]) – 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 will be used as request parameters

Return type

Response

Returns

API response

send(request, expire_after=None, refresh=False, retries=None, timeout=None, **kwargs)#

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

Parameters

  • request (PreparedRequest) – Prepared request to send

  • expire_after (Union[None, int, float, str, datetime, timedelta]) – How long to keep cached API requests

  • refresh (bool) – Skip reading from the cache and always fetch a fresh response

  • timeout (Optional[int]) – Maximum number of seconds to wait for a response from the server

Note: requests.Session.send() accepts separate timeout values for connect and read timeouts. The timeout argument will be used as the read timeout.

Return type

Response

pyinaturalist.session.clear_cache()#

Clear all cached API responses

pyinaturalist.session.delete(url, session=None, **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, session=None, **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

ClientSession

pyinaturalist.session.get_refresh_params(endpoint)#

In some cases, we need to be sure we have the most recent version of a resource, for example when updating projects. Normally we would handle this with cache headers, but the CDN cache does not respect these if the cached response is less than ~2 minutes old.

The iNat webapp handles this by adding an extra v request parameter, which results in a different cache key. This function does the same by tracking a separate rate limit per value, and finding the lowest value that is certain to result in a fresh response.

Return type

Dict

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, session=None, **kwargs)#

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

Return type

Response

pyinaturalist.session.put(url, session=None, **kwargs)#

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

Return type

Response