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

Response

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

Response

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_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

Session

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

Response

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

Response

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(limiter=<pyrate_limiter.limiter.Limiter object>, 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 method

  • url (str) – Request URL

  • access_token (Optional[str]) – access_token: the access token, as returned by get_access_token()

  • user_agent (Optional[str]) – a user-agent string that will be passed to iNaturalist

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

  • params (Optional[Dict[str, Any]]) – Requests parameters

  • headers (Optional[Dict]) – Request headers

  • session (Optional[Session]) – Existing Session object to use instead of creating a new one

Return type

Response

Returns

API response