Client#
Summary#
Module Contents#
- class pyinaturalist.client.iNatClient(creds=None, default_params=None, dry_run=False, session=None, **kwargs)#
Bases:
object
WIP/Experimental
API client class that provides a higher-level interface that is easier to configure, and returns model objects instead of JSON. See Controller classes for request details.
Examples
Basic usage
Search for observations by taxon name:
>>> from pyinaturalist import iNatClient >>> client = iNatClient() >>> observations = client.observations.search(taxon_name='Danaus plexippus')
Get a single observation by ID:
>>> observation = client.observations(12345)
Authentication
Add credentials needed for authenticated requests: Note: Passing credentials via environment variables or keyring is preferred
>>> creds = { ... 'username': 'my_inaturalist_username', ... 'password': 'my_inaturalist_password', ... 'app_id': '33f27dc63bdf27f4ca6cd95dd9dcd5df', ... 'app_secret': 'bbce628be722bfe2abd5fc566ba83de4', ... } >>> client = iNatClient(creds=creds)
Default request parameters:
Add default
locale
andpreferred_place_id
request params to pass to any requests that use them:>>> default_params={'locale': 'en', 'preferred_place_id': 1} >>> client = iNatClient(default_params=default_params)
Caching, Rate-limiting, and Retries
See
ClientSession
and the User Guide for details on these settings.iNatClient
will accept any arguments forClientSession
, for example:>>> client = iNatClient(per_second=50, expire_after=3600, retries=3)
Or you can provide your own custom session object:
>>> session = MyCustomSession(encabulation_factor=47.2) >>> client = iNatClient(session=session)
Updating settings
All settings can also be modified after creating the client:
>>> client.session = ClientSession() >>> client.creds['username'] = 'my_inaturalist_username' >>> client.default_params['locale'] = 'es' >>> client.dry_run = True
- Parameters
creds (
Optional
[Dict
[str
,str
]]) – Optional arguments forget_access_token()
, used to get and refresh access tokens as needed. Using a keyring instead is recommended, though.default_params (
Optional
[Dict
[str
,Any
]]) – Default request parameters to pass to any applicable API requestsdry_run (
bool
) – Just log all requests instead of sending real requestssession (
Optional
[Session
]) – Session object to use instead of creating a new onekwargs – Keyword arguments for
ClientSession
- add_client_settings(request_function, kwargs=None, auth=False)#
Add any applicable client settings to request parameters before sending a request. Explicit keyword arguments will override any client settings.
- observations#
Interface for observation requests
- paginate(request_function, model, auth=False, cls=<class 'pyinaturalist.paginator.Paginator'>, **kwargs)#
Create a paginator for a request, with client settings applied
- places#
Interface for project requests
- projects#
Interface for project requests
- request(request_function, *args, auth=False, **kwargs)#
Send a request, with client settings applied.
- taxa#
Interface for taxon requests
- users#
Interface for user requests