Session

Summary

Classes

ClientSession(cache_file, cache_control, ...)

Custom session class used for sending API requests.

FileLockSQLiteBucket(rates, conn, table, lock)

Bucket backed by a SQLite database and file lock.

MockResponse(request, **kwargs)

A mock response to return in dry-run mode.

RequestTimeout(method, read_timeout, ...)

Timeout class that adjusts timeouts for write operations

Functions

clear_cache()

Clear all cached API responses

delete(url, session, **kwargs)

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

format_request(request, dry_run, timeout)

Format HTTP request info

format_response(response)

Format HTTP response info, including whether it came from the cache

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

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

put(url, session, **kwargs)

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.client.session.ClientSession(cache_file, cache_control, expire_after, urls_expire_after, per_second, per_minute, ...)

Bases: CacheMixin, LimiterMixin, Session

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

  • Caching

  • Rate-limiting (skipped for cached requests)

  • Retries

  • Timeouts

__init__(cache_file, cache_control, expire_after, urls_expire_after, per_second, per_minute, ...)

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

Parameters:

  • cache_file (BinaryIO | Path | str) – Cache file path to use; defaults to the system default cache directory

  • cache_control (bool) – Use server-provided Cache-Control headers to set cache expiration when possible (instead of expire_after or urls_expire_after)

  • expire_after (Union[None, int, float, str, datetime, timedelta]) – How long to keep cached API requests; for advanced options, see requests-cache: Expiration

  • See (urls_expire_after Glob patterns for per-URL cache expiration;) – requests-cache: URL Patterns

  • per_second (float) – Max requests per second

  • per_minute (float) – 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

  • ratelimit_path (Path | str | None) – Path to SQLite database for rate-limiting; defaults to the system default cache directory

  • use_file_lock (bool) – Use a file lock for the rate limit database; needed for multiprocess usage.

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

  • timeout (float | None) – Maximum number of seconds to wait for a response from the server; Set to None to disable all timeouts

  • write_timeout (float | None) – Maximum number of seconds to wait for sending data (create/update); ignored if timeout=None

  • user_agent (str | None) – Additional User-Agent info to pass to API requests

  • kwargs – Additional keyword arguments for CachedSession and/or LimiterSession

close()

Close cache and rate limit backends to avoid unclosed SQLite connections.

get_refresh_params(endpoint) → dict

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

prepare_inat_request(method, url, access_token, data, files, headers, ...) → Request

Translate pyinaturalist-specific options into standard request arguments

Return type:

Request

request(method, url, headers, json, access_token, allow_redirects, ...) → Response

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

Parameters:

  • method (str) – HTTP method

  • url (str) – Request URL

  • headers (dict | None) – Request headers

  • json (dict | None) – JSON request body

  • access_token (str | None) – access_token: the access token, as returned by get_access_token()

  • dry_run (bool) – Just log the request instead of sending a real request

  • data (dict | None) – Form data to include in the request body (for multipart uploads)

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

  • files (BinaryIO | Path | str | None) – File object, path, or URL to upload

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

  • only_if_cached (bool) – Only return a response if it is cached

  • raise_for_status (bool) – Raise an exception if the response status is not 2xx

  • refresh (bool) – Revalidate with the server before using a cached response, and refresh if needed (e.g., a “soft refresh,” like F5 in a browser)

  • force_refresh (bool) – Always make a new request, and overwrite any previously cached response (e.g., a “hard refresh”, like Ctrl-F5 in a browser))

  • stream (bool) – Stream the response content

  • timeout (Union[float, _TYPE_DEFAULT, None, Timeout]) – Time (in seconds) to wait for a response from the server; if exceeded, a requests.exceptions.Timeout will be raised.

  • verify (bool) – Verify SSL certificates

  • params (dict[str, Any]) – All other keyword arguments will be interpreted as request parameters

Return type:

Response

Returns:

API response

send(request, dry_run, expire_after, refresh, force_refresh, retries, ...) → Response

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

Parameters:

  • request (Union[Request, PreparedRequest, CachedRequest]) – Prepared request to send

  • 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

  • refresh (bool) – Revalidate with the server before using a cached response, and refresh if needed

  • force_refresh (bool) – Always make a new request, and overwrite any previously cached response

  • timeout (Union[float, _TYPE_DEFAULT, None, Timeout]) – Maximum number of seconds to wait for a response from the server

Return type:

Response

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

class pyinaturalist.client.session.FileLockSQLiteBucket(rates, conn, table, lock)

Bases: SQLiteBucket

Bucket backed by a SQLite database and file lock.

Deprecated since version Use: ClientSession(use_file_lock=True) instead. This class is kept for backwards-compatibility.

class pyinaturalist.client.session.MockResponse(request, **kwargs)

Bases: CachedResponse

A mock response to return in dry-run mode. This behaves the same as a cached response, but with the following additions:

  • Adds default response values

  • Returns a defaultdict when calling json(), to accommodate checking for arbitrary keys

cookies

A CookieJar of Cookies the server sent back.

created_at
elapsed

The amount of time elapsed between sending the request and the arrival of the response (as a timedelta). This property specifically measures the time taken between sending the first byte of the request and finishing parsing the headers. It is therefore unaffected by consuming the response content or the value of the stream keyword argument.

encoding

Encoding to decode with when accessing r.text.

expires
headers

Case-insensitive Dictionary of Response Headers. For example, headers['content-encoding'] will return the value of a 'Content-Encoding' response header.

history

A list of Response objects from the history of the Request. Any redirect responses will end up here. The list is sorted from the oldest to the most recent request.

json(**kwargs)

Decodes the JSON response body (if any) as a Python object.

This may return a dictionary, list, etc. depending on what is in the response.

Parameters:

**kwargs – Optional arguments that json.loads takes.

Raises:

requests.exceptions.JSONDecodeError – If the response body does not contain valid json.

reason

Textual reason of responded HTTP Status, e.g. “Not Found” or “OK”.

request

The PreparedRequest object to which this is a response.

status_code

Integer Code of responded HTTP Status, e.g. 404 or 200.

url

Final URL location of Response.

class pyinaturalist.client.session.RequestTimeout(method, read_timeout, write_timeout)

Bases: Timeout

Timeout class that adjusts timeouts for write operations

pyinaturalist.client.session.clear_cache()

Clear all cached API responses

pyinaturalist.client.session.delete(url, session, **kwargs) → Response

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

Return type:

Response

pyinaturalist.client.session.format_request(request, dry_run, timeout) → str

Format HTTP request info

Return type:

str

pyinaturalist.client.session.format_response(response) → str

Format HTTP response info, including whether it came from the cache

Return type:

str

pyinaturalist.client.session.get(url, session, **kwargs) → Response

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

Return type:

Response

pyinaturalist.client.session.get_local_session(**kwargs) → ClientSession

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.client.session.is_dry_run_enabled(method) → bool

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.client.session.post(url, session, **kwargs) → Response

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

Return type:

Response

pyinaturalist.client.session.put(url, session, **kwargs) → Response

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

Return type:

Response