pyinaturalist.api_requests¶
Summary¶
|
Wrapper around |
|
Translate an environment variable to a boolean value, accounting for minor variations (case, None vs. |
|
Wrapper around |
|
Get a thread-local Session object with default settings. |
|
Translate request rate values into RequestRate objects |
|
A wrapper to determine if dry-run (aka test mode) has been enabled via either a constant or an environment variable. |
|
Wrapper around |
|
Translate |
|
Wrapper around |
|
Wrapper around |
Module Contents¶
Session class and related functions for preparing and sending API requests
- class pyinaturalist.api_requests.ClientSession(expire_after=None, per_second=1, per_minute=60, per_day=10000, burst=5, retries=5, backoff_factor=0.5, timeout=10, **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 thesession
argument for API request functions.- __init__(expire_after=None, per_second=1, per_minute=60, per_day=10000, burst=5, retries=5, backoff_factor=0.5, timeout=10, **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: Expirationper_second (
int
) – Max requests per secondper_minute (
int
) – Max requests per minuteper_minute – Max requests per day
burst (
int
) – Max number of consecutive requests allowed before applying per-second rate-limitingretries (
int
) – Maximum number of times to retry a failed requestbackoff_factor (
float
) – Factor for increasing delays between retriestimeout (
int
) – Maximum number of seconds to wait for a response from the serverkwargs – Additional keyword arguments for
CachedSession
and/orLimiterSession
- pyinaturalist.api_requests.delete(url, **kwargs)¶
Wrapper around
requests.delete()
with additional options specific to iNat API requests- Return type
- 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
- pyinaturalist.api_requests.get(url, **kwargs)¶
Wrapper around
requests.get()
with additional options specific to iNat API requests- Return type
- pyinaturalist.api_requests.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
- pyinaturalist.api_requests.get_request_rates(per_second, per_minute, burst)¶
Translate request rate values into RequestRate objects
- Return type
List
[RequestRate
]
- 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
- pyinaturalist.api_requests.post(url, **kwargs)¶
Wrapper around
requests.post()
with additional options specific to iNat API requests- Return type
- pyinaturalist.api_requests.prepare_request(method, url, access_token=None, files=None, headers=None, ids=None, json=None, params=None, user_agent=None, **kwargs)¶
Translate
pyinaturalist
-specific options into standard request arguments- Return type
- pyinaturalist.api_requests.put(url, **kwargs)¶
Wrapper around
requests.put()
with additional options specific to iNat API requests- Return type
- pyinaturalist.api_requests.request(method, url, access_token=None, dry_run=False, files=None, headers=None, ids=None, json=None, raise_for_status=True, session=None, user_agent=None, **params)¶
Wrapper around
requests.request()
with additional options specific to iNat API requests- Parameters
method (
str
) – HTTP methodurl (
str
) – Request URLaccess_token (
Optional
[str
]) – access_token: the access token, as returned byget_access_token()
dry_run (
bool
) – Just log the request instead of sending a real requestfiles (
Union
[BinaryIO
,str
,None
]) – File path or object to uploadids (
Union
[int
,Iterable
[int
],None
]) – One or more integer IDs used as REST resource(s) to requestsession (
Optional
[Session
]) – An existing Session object to use instead of creating a new onetimeout – Time (in seconds) to wait for a response from the server; if exceeded, a
requests.exceptions.Timeout
will be raised.user_agent (
Optional
[str
]) – A custom user-agent string to provide to the iNaturalist APIparams (
Dict
[str
,Any
]) – All other keyword arguments are interpreted as request parameters
- Return type
- Returns
API response