Pyinaturalist

[See all Issues & PRs for 0.17](https://github.com/pyinat/pyinaturalist/milestone/8?closed=1)

New Endpoints
* Added new **Observation** endpoint:
* `get_observation_popular_field_values()`
* Added new **Project** endpoint and helper functions:
* `update_project()`
* `add_project_users()`
* `delete_project_users()`

Modified Endpoints
* Updated `get_projects_by_id()` to allow string values (URL slugs) for `project_id`
* Updated `get_user_by_id()` to allow string values (usernames) for `user_id`
* Added support for setting timeout for individual API requests (with `timeout` parameter)
* Added support for setting cache timeout for individual API requests (with `expire_after` parameter)
* Added support for bypassing the cache for individual API requests (with `refresh` parameter)

Authentication
* Added support for JWT authentication, which will now be used by default
* To get an OAuth access token instead of a JWT, call `get_access_token(jwt=False)`
* Added caching to `get_access_token()`. JWTs will be stored in the API response cache and reused
until they expire.

Models
* Remove default values from output when model objects are printed with `rich`
* Add `ControlledTermCount` model for use with `/observations/popular_field_values`
* `Photo`: Add `ext` and `mimetype` properties
* `Taxon`: Use icon in place of `default_photo` if missing

Other Changes
* Dropped support for python 3.6
* Add an optional, abbreviated namespace `pyinat` as an alias for `pyinaturalist`
* Updated rate limiting with a SQLite-based backend. This adds persistence for rate limit tracking
across multiple threads, processes, and/or application restarts. See
[pyrate-limiter docs](https://github.com/vutran1710/PyrateLimiter#sqlite) for more details.
* Add a `clear_cache()` function for clearing cached API responses
* Misc improvements for response pretty-printing

[See all Issues & PRs for 0.16](https://github.com/pyinat/pyinaturalist/milestone/7?closed=1)

New Endpoints
* Added new **Taxon** endpoint: `get_taxa_map_layers()`
* Added new **Message** endpoints:
* `get_messages()`
* `get_message_by_id()`
* `get_unread_message_count()`

Observation Media
The following changes apply to `upload()`, `create_observation()`, and `update_observation()`:
* Added support for uploading observation photo & sound files from URLs
* Added support for attaching previously uploaded photos to an observation by photo ID

Other Changes
* Added support for python 3.10
* Removed `pyinaturalist.user_agent` global variable and API function keyword args, and recommend setting on session object instead
* Removed `pyinaturalist.DRY_RUN*` global variables, and recommend setting in environment variables instead
* Fixed `count_only=True`/`per_page=0` to not run full query
* Do not error on unrecognized `**kwargs`, for cases where the API may accept some additional undocumented parameters
* Allow overriding default location for API request cache

[See all Issues & PRs for 0.15](https://github.com/pyinat/pyinaturalist/milestone/6?closed=1)

New Endpoints
* Added new functions for v1 **Observation** endpoints:
* `create_observation()`
* `update_observation()`
* `delete_observation()`
* `upload()` (uploads both photos and sounds)
* These are now preferred over the older v0 endpoints
* Added new functions for v1 **Observation field value** endpoints:
* `set_observation_field()` (creates and updates observation field values)
* `delete_observation_field()`
* Added new function for **Observation taxon summary**: `get_observation_taxon_summary()`
* Added new functions for **Project observation** endpoints:
* `add_project_observation()`
* `delete_project_observation()`

Modified Endpoints
* Added a `dry_run` argument to all API request functions to dry-run an individual request
* Added a `reverse` argument to all paginated API request functions to reverse the sort order

Models
* Added new data models:
* ListedTaxon
* TaxonSummary
* UserCounts
* Added a preview version of `iNatClient`, a higher-level interface for API requests, which returns
model objects instead of JSON. See issues
[163](https://github.com/pyinat/pyinaturalist/issues/163) and
[217](https://github.com/pyinat/pyinaturalist/issues/217) for details.

Performance
* Added API request caching with [requests-cache](https://github.com/reclosedev/requests-cache)
* Updated rate-limiting not apply to cached requests
* Added custom `ClientSession` class to configure caching, rate-limiting, retries, and timeouts

Logging
* Improved logging output for dry-run mode: now shows formatted `PreparedRequest` details
instead of `request()` keyword args
* Added an `enable_logging()` function to optionally show prettier logs with `rich`
* Updated logging to redact all credentials from logged API requests

Other Changes
* Increased default timeout to 10 seconds to accommodate some longer-running queries
* Added `get_interval_ranges()` function to help with queries over a series of date/time intervals
* Fixed bug with `rule_details` param for `get_projects_by_id()`
* Added more tutorial/example notebooks

* Added new function for **Posts** endpoint: `get_posts()`
* Fixed broken `response_format` parameter in `v0.get_observations()`

[See all Issues & PRs for 0.14](https://github.com/pyinat/pyinaturalist/milestone/5?closed=1)

New Endpoints
* Added new function for **Observation sounds** endpoint: `upload_sounds()`
* Added new function for **Life list** endpoint: `get_observation_taxonomy()`

Modified Endpoints
* Added support for passing a `requests.Session` object to all API request functions
* Added a `photos` parameter `create_observation()` and `update_observation()` to upload photos
* Added a `sounds` parameter `create_observation()` and `update_observation()` to upload sounds
* Renamed `add_photo_to_observation()` to `upload_photos()`
* The alias `rest_api.add_photo_to_observation()` is still available for backwards-compatibility
* Updated `upload_photos()` to take accept either a single photo or a list of photos, and return a list of responses
* Updated `upload_sounds()` to take accept either a single sound or a list of sounds, and return a list of responses
* Added alias `observed_on` for `observed_on_string` in `create_observation()`
* Fixed conversion for datetime parameters in `create_observation()` and `update_observation()`
* Updated all requests to correctly convert `datetime` objects to strings
* Moved API functions into separate modules by API version and resource type.
* All can still be imported via `from pyinaturalist import *`
* Added aliases for backwards-compatibility, so imports from `pyinaturalist.rest_api` and `pyinaturalist.node_api` will still work

Deprecated Endpoints
* Deprecated `pyinaturalist.rest_api` module (moved to `pyinaturalist.v0` subpackage)
* Deprecated `pyinaturalist.node_api` module (moved to `pyinaturalist.v1` subpackage)
* Deprecated `get_geojson_observations()` (moved to join other observation conversion tools in `pyinaturalist-convert`)

Models
Added data models for all API response types, to support working with typed python objects instead of JSON.

Models:
* Comment
* ControlledTerm
* ControlledTermValue
* Annotation
* Identification
* LifeList
* LifeListTaxon
* Observation
* ObservationField
* ObservationFieldValue
* Photo
* Place
* Project
* ProjectObservation
* ProjectObservationField
* ProjectUser
* SearchResult
* Taxon
* ConservationStatus
* EstablishmentMeans
* TaxonCount
* TaxonCounts
* User

Model features:
* Type conversions
* Lazy initialization
* Basic formatters
* Table formatters

Other Changes
* Consolidated response formatting into a single `pprint()` function (instead of one per resource type)
* Refactored and reorganized the following internal utility modules (see API docs for details):
* `converters`
* `docs`
* `formatters`
* `request_params`
* Added a default response timeout of 5 seconds
* Added an example (`examples/sample_responses.py`) containing response JSON, model objects, and tables of every type to experiment with
* Added a tutorial notebook (`examples/Tutorial.ipynb`)
* Set up pyinaturalist-notebook to be [runnable with Binder](https://mybinder.org/v2/gh/pyinat/pyinaturalist/main?filepath=examples)

-----

[See all Issues & PRs for 0.13](https://github.com/pyinat/pyinaturalist/milestone/4?closed=1)

New Endpoints
* Added new function for **Search** endpoint: `search()` (combined search for places, projects, taxa, and users)
* Added new functions for **Identifications** endpoints: `get_identifications()` and `get_identifications_by_id()`
* Added new functions for **Users** endpoints: `get_user_by_id()` and `get_users_autocomplete()`

Modified Endpoints
* Added undocumented `ident_user_id` parameter to `get_observations()`
* Added `count_only=True` as an alias for `per_page=0` (to get only result counts).
* Added generic auto-pagination that can apply to any endpoint that supports pagination.
* Added `page='all'` as a shortcut for auto-pagination
* The above changes apply to all functions that support pagination:
* `node_api.get_identifications()`
* `node_api.get_observations()`
* `node_api.get_observation_species_counts()`
* `node_api.get_observation_observers()`
* `node_api.get_observation_identifiers()`
* `node_api.get_places_autocomplete()`
* `node_api.get_projects()`
* `node_api.get_taxa()`
* `rest_api.get_observations()`
* `rest_api.get_observation_fields()`
* Removed `node_api.get_all_observation_species_counts()`, since this was only added recently
* Updated `rest_api.get_observation_fields()` to return a dict with `'results'` for consistency with other endpoints

Deprecated Endpoints
The following methods are now deprecated. They are still functional, but will raise a
`DeprecationWarning`, and will be removed in a future release:
* `node_api.get_all_observations()`
* `rest_api.get_all_observation_fields()`

Other Changes
* Added response formatting functions to `pyinaturalist.formatters`
* All API functions and formatters can now be imported from the top-level package, e.g.
`from pyinaturalist import *`
* Removed `minify` option from `get_taxa_autocomplete`
* Published [pyinaturalist on conda-forge](https://anaconda.org/conda-forge/pyinaturalist)
* Added global rate-limiting to stay within the rates suggested in
[API Recommended Practices](https://www.inaturalist.org/pages/api+recommended+practices)
(per second, minute, and day)
* Moved `Dockerfile` and `docker-compose.yml` to a separate repo
([pyinaturalist-notebook](https://github.com/JWCook/pyinaturalist-notebook))
and published on Docker Hub
* Packaging is now handled with Poetry. For users, installation still works the same. For developers,
see [Contributing Guide](https://github.com/pyinat/pyinaturalist/blob/main/CONTRIBUTING.md) for details.

-----