Pyinaturalist

⚠️ Deprecations & Removals
* Drop support for python 3.7

Models
* Add `User.annotated_observations_count` field
* Add `root_id` filter to `taxon.make_tree()` to explicitly set the root taxon instead of determining it automatically
* Fix `taxon.make_tree()` rank filtering to allow skipping any number of rank levels
* Fix `taxon.make_tree()` rank filtering to handle all available ranks filtered out
* Update `taxon.make_tree()` to return copies of original taxon objects instead of modifying them in-place
* Update `Taxon.flatten(hide_root=True)` to only hide the root taxon if it was automatically inserted by `make_tree()`
* Add shortcut properties to `Taxon` for ancestors of common ranks:
`Taxon.kingdom`, `phylum`, `class_` (note the `_`; 'class' is a reserved keyword), `order`, `family`, `genus`
* Update `Observation.taxon.ancestors` based on identification data, if available

Rate limits, timeouts, and error handling
* Increase default request timeout from 10 to 20 seconds
* Add `validate_token()` function to manually check if an access token is valid
* Support rate limits less than one request per second (example: `ClientSession(per_second=0.5)`)
* Add error handling for file uploads over 20MB (not accepted by API)
* Allow setting lockfile path used for multiprocess rate limiting (example: `ClientSession(lock_path='/tmp/pyinat.lock')`)

Bugfixes
* Fix `KeyError` when using `create_observation()` in dry-run mode

New Endpoints
* Added new **User** endpoint: `get_current_user()`
* Added new **Taxon** endpoint: `get_life_list_metadata()`

Modified Endpoints
Add support for searching observations by observation fields, using a new `observation_fields` param for the following functions:
* `get_observations()`
* `get_observation_histogram()`
* `get_observation_identifiers()`
* `get_observation_observers()`
* `get_observation_popular_field_values()`
* `get_observation_species_counts()`

Models
**Observation:**
* Add `Observation.ident_taxon_ids` dynamic property to get all identification taxon IDs (with ancestors)
* Add `Observation.cumulative_ids` dynamic property to calculate agreements/total community identifications
* Add `Application` model for `Observation.application` (for v2 API)
* Add `Fave` model for `Observation.faves`
* Add `Flag` model for `Observation.flags`
* Add `QualityMetric` model for `Observation.quality_metrics`
* Add `Sound` model for `Observation.sounds`
* Add `Vote` model for `Observation.votes`

**Project:**
* Add `Project.last_post_at` datetime attribute
* Add `Project.observation_requirements_updated_at` datetime attribute

**Taxon:**
* Add `make_tree()` function to build a tree from `Taxon` objects or a `LifeList`
* Add `pprint_tree()` function to print a taxon tree on the console
* Add `Taxon.flatten()` method to return a taxon and its descendants as a flat list
* Fix initialization of `ListedTaxon.place`

Other changes
* Added support for python 3.12

⚠️ Deprecations & Removals
* `get_observation()` is now deprecated, and will be removed in a future release
* Please use `get_observations()` or `get_observations_by_id()` instead
* Remove redundant `Annotation.controlled_attribute_id` and `controlled_value_id` attributes (These can still be used as init arguments)

New Endpoints
* Added new **Observation** endpoint:
* `get_observations_by_id()`
* Replaces `get_observation`
* Accepts multiple IDs
* Uses a different endpoint (`GET /observations/{id}` instead of `GET /observations?id={id}`)
* returns full term and value details for annotations

Modified Endpoints
* Add some undocumented request params to `get_taxa_by_id()`:
* `locale`
* `preferred_place_id`
* `all_names`

Models
* Add full mapping of conservation status codes for IUCN, NatureServe, Norma Oficial Mexicana, and other generic codes
* Translate `ConservationStatus.status_name` based on status code and authority for more consistent results
* Add `ConservationStatus.display_name` property
* Add `Observation.default_photo` property
* Use taxon icon as placeholder for `Observation.default_photo` if observation has no photos
* Update `Annotation` model to include controlled term and value details from updated `GET /observations/{id}` response format
* Add `Annotation.term` and `value` properties and init arguments for simpler initialization from term and value labels

Sessions
* Add `cache_control` option to `ClientSession` to disable using Cache-Control headers for cache
expiration (enabled by default)
* Add `urls_expire_after` option to `ClientSession` to update default cache expiration URL patterns

Bugfixes
* Fix error `413: Payload too large` when using `add_project_users()` or `delete_project_users()` with a project with a large number of rules
* Fix JWT caching
* Fix `ObservationFieldValue` conversions for `date` and `datetime` fields
* Fix printing `Annotation` objects with `rich`
* Fix printing `Observation` tables when taxon is missing

Other Changes
* Added support for python 3.11
* All API functions that accept taxonomic rank parameters (`rank`, `lrank`, `observation_hrank`,etc.) now accept all rank variations that iNaturalist accepts (`var`, `spp` `sub-species`, etc.)
* Optionally use `ultrajson` instead of stdlib `json`, if installed
* Add `loop` argument to iNatClient and Paginator classes to allow passing an async event loop to be used for async iteration
* Add `Paginator.async_all()` method (async, non-blocking version of `.all()`)

* Use a single data directory instead of separate 'cache' and 'user data' dirs
* Platform-dependent; on Linux, for example, this will be `~/.local/share/pyinaturalist`

* Add retries for requests that return invalid (truncated) JSON
* `max_retries` and `backoff_factor` arguments for `ClientSession` will apply to these retries (in
addition to other request errors)

* Handle nested 'photo' dictionaries when loading `Taxon.taxon_photos`
* Add model for `ListedTaxon.list`, and handle differences in format between `/taxa` and `/observations/{id}/taxon_summary`
* Minor fixes and improvements for creating and converting `Observation`, `Taxon`, and other model objects