pyinaturalist 0.19.0.dev2__tar.gz → 0.19.0.dev3__tar.gz

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/HISTORY.md

@@ -15,9 +15,17 @@ Add support for searching observations by observation fields, using a new `obser
 * `get_observation_species_counts()`
 
 ### Models
+* 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
 * 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`
 * Fix initialization of `ListedTaxon.place`
 
 ## 0.18.0 (2023-02-27)

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyinaturalist
-Version: 0.19.0.dev2
+Version: 0.19.0.dev3
 Summary: iNaturalist API client for python
 Home-page: https://github.com/pyinat/pyinaturalist
 License: MIT
@@ -24,25 +24,27 @@ Classifier: Typing :: Typed
 Provides-Extra: all
 Provides-Extra: docs
 Requires-Dist: attrs (>=21.2)
-Requires-Dist: furo (>=2023.3,<2024.0) ; extra == "docs"
-Requires-Dist: ipython (>=7.25.0,<8.0.0) ; extra == "docs"
+Requires-Dist: furo (>=2023.3,<2024.0) ; (python_version >= "3.8") and (extra == "docs")
+Requires-Dist: ipython (>=7.34,<8.0) ; (python_version >= "3.8") and (extra == "docs")
 Requires-Dist: keyring (>=22.3)
-Requires-Dist: linkify-it-py (>=1.0.1,<2.0.0) ; extra == "docs"
-Requires-Dist: myst-parser (>=1.0,<2.0) ; extra == "docs"
-Requires-Dist: nbsphinx (>=0.9,<0.10) ; extra == "docs"
+Requires-Dist: linkify-it-py (>=2.0,<3.0) ; (python_version >= "3.8") and (extra == "docs")
+Requires-Dist: markdown-it-py (==2.2) ; python_version == "3.7"
+Requires-Dist: markdown-it-py (>=2.2) ; python_version >= "3.8"
+Requires-Dist: myst-parser (>=1.0) ; (python_version >= "3.8") and (extra == "docs")
+Requires-Dist: nbsphinx (>=0.9,<0.10) ; (python_version >= "3.8") and (extra == "docs")
 Requires-Dist: platformdirs (>=2.6)
 Requires-Dist: python-dateutil (>=2.0)
 Requires-Dist: python-forge (>=18.6)
-Requires-Dist: requests (>=2.22)
-Requires-Dist: requests-cache (>=1.0)
+Requires-Dist: requests (>=2.25)
+Requires-Dist: requests-cache (>=1.1)
 Requires-Dist: requests-ratelimiter (>=0.3.2)
 Requires-Dist: rich (>=10.9)
-Requires-Dist: sphinx (>=5.2,<6.0) ; extra == "docs"
-Requires-Dist: sphinx-autodoc-typehints (>=1.17,<2.0) ; extra == "docs"
-Requires-Dist: sphinx-automodapi (>=0.14,<0.15) ; extra == "docs"
-Requires-Dist: sphinx-copybutton (>=0.5) ; extra == "docs"
-Requires-Dist: sphinx-design (>=0.2.0) ; extra == "docs"
-Requires-Dist: sphinxcontrib-apidoc (>=0.3,<0.4) ; extra == "docs"
+Requires-Dist: sphinx (>=6.2,<7.0) ; (python_version >= "3.8") and (extra == "docs")
+Requires-Dist: sphinx-autodoc-typehints (==1.20) ; (python_version >= "3.8") and (extra == "docs")
+Requires-Dist: sphinx-automodapi (>=0.15,<0.16) ; (python_version >= "3.8") and (extra == "docs")
+Requires-Dist: sphinx-copybutton (>=0.5) ; (python_version >= "3.8") and (extra == "docs")
+Requires-Dist: sphinx-design (>=0.4) ; (python_version >= "3.8") and (extra == "docs")
+Requires-Dist: sphinxcontrib-apidoc (>=0.3,<0.4) ; (python_version >= "3.8") and (extra == "docs")
 Requires-Dist: ujson (>5.0) ; extra == "all"
 Project-URL: Documentation, https://pyinaturalist.readthedocs.io
 Project-URL: Repository, https://github.com/pyinat/pyinaturalist
@@ -99,10 +101,10 @@ Many of the most relevant API endpoints are supported, including:
 * 💬 Messages
 * 👀 Observations (multiple formats)
 * 📷 Observation photos + sounds
-* 📊 Observation observers, identifiers, histograms, life lists, and species counts
+* 📊 Observation histograms, observers, identifiers, life lists, and species counts
 * 📍 Places
 * 👥 Projects
-* 🐦Species
+* 🐦 Species
 * 👤 Users
 
 ## Quickstart
@@ -205,7 +207,7 @@ new_observation_id = response[0]['id']
 We can then [update the observation](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.update_observation) information, photos, or sounds:
 ```python
 update_observation(
-    17932425,
+    new_observation_id,
     access_token=token,
     description='updated description !',
     photos='~/observations/wasp_nest.jpg',

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/README.md

@@ -49,10 +49,10 @@ Many of the most relevant API endpoints are supported, including:
 * 💬 Messages
 * 👀 Observations (multiple formats)
 * 📷 Observation photos + sounds
-* 📊 Observation observers, identifiers, histograms, life lists, and species counts
+* 📊 Observation histograms, observers, identifiers, life lists, and species counts
 * 📍 Places
 * 👥 Projects
-* 🐦Species
+* 🐦 Species
 * 👤 Users
 
 ## Quickstart
@@ -155,7 +155,7 @@ new_observation_id = response[0]['id']
 We can then [update the observation](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.observations.html#pyinaturalist.v1.observations.update_observation) information, photos, or sounds:
 ```python
 update_observation(
-    17932425,
+    new_observation_id,
     access_token=token,
     description='updated description !',
     photos='~/observations/wasp_nest.jpg',

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/docs/conf.py

@@ -14,7 +14,7 @@
 * Some CSS and JS adds collapsible drop-down container
 * On Readthedocs, CSS and JS is automatically added for a version dropdown
 """
-# flake8: noqa: E402
+# ruff: noqa: E402
 import sys
 from importlib.metadata import version as pkg_version
 from os import makedirs, symlink

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/docs/endpoints.md

@@ -1,79 +1,80 @@
 (endpoints)=
 # {fa}`table` Endpoint Summary
 
-Below is a list of iNaturalist API endpoints that have either been added or may be added in the
-future, along with their corresponding functions in pyinaturalist.
+Below is a list of iNaturalist API endpoints that have either been added or are likely be added in
+the future, along with their corresponding functions in pyinaturalist.
 
 ## v1 API
 For all available endpoints, see: <http://api.inaturalist.org/v1/docs/>
 
-| Method | Endpoint                           | Function
-| ------ | --------                           | --------
+| Method | Endpoint                           | Function                                                     |
+| ------ | ---------------------------------- | ------------------------------------------------------------ |
 | POST   | /annotations                       |
 | DELETE | /annotations/{id}                  |
 | POST   | /comments                          |
 | DELETE | /comments/{id}                     |
 | PUT    | /comments/{id}                     |
-| GET    | /controlled_terms                  | {py:func}`.get_controlled_terms`
-| GET    | /controlled_terms/for_taxon        | {py:func}`.get_controlled_terms`
-| GET    | /identifications                   | {py:func}`.get_identifications`
-| GET    | /identifications/{id}              | {py:func}`.get_identifications_by_id`
+| GET    | /controlled_terms                  | {py:func}`.get_controlled_terms`                             |
+| GET    | /controlled_terms/for_taxon        | {py:func}`.get_controlled_terms`                             |
+| GET    | /identifications                   | {py:func}`.get_identifications`                              |
+| GET    | /identifications/{id}              | {py:func}`.get_identifications_by_id`                        |
 | GET    | /identifications/species_counts    |
 | GET    | /identifications/identifiers       |
 | GET    | /identifications/observers         |
 | GET    | /identifications/similar_species   |
-| GET    | /messages                          | {py:func}`.get_messages`
-| GET    | /messages/{id}                     | {py:func}`.get_message_by_id`
-| GET    | /messages/unread                   | {py:func}`.get_unread_meassage_count`
-| DELETE | /observation_field_values/{id}     | {py:func}`.delete_observation_field`
-| PUT    | /observation_field_values/{id}     | {py:func}`.set_observation_field`
-| POST   | /observation_field_values          | {py:func}`.set_observation_field`
-| POST   | /observation_photos                | {py:func}`.upload`
-| POST   | /observation_sounds                | {py:func}`.upload`
-| DELETE | /observations/{id}                 | {py:func}`~pyinaturalist.v1.observations.delete_observation`
-| GET    | /observations/{id}                 | {py:func}`.get_observations_by_id`
-| PUT    | /observations/{id}                 | {py:func}`~pyinaturalist.v1.observations.update_observation`
-| GET    | /observations/{id}/taxon_summary   | {py:func}`.get_observation_taxon_summary`
-| GET    | /observations                      | {py:func}`~pyinaturalist.v1.observations.get_observations`
-| POST   | /observations                      | {py:func}`~pyinaturalist.v1.observations.create_observation`
-| GET    | /observations/histogram            | {py:func}`.get_observation_histogram`
-| GET    | /observations/identifiers          | {py:func}`.get_observation_identifiers`
-| GET    | /observations/observers            | {py:func}`.get_observation_observers`
-| GET    | /observations/popular_field_values | {py:func}`.get_observation_popular_field_values`
-| GET    | /observations/species_counts       | {py:func}`.get_observation_species_counts`
-| GET    | /observations/taxonomy             | {py:func}`.get_observation_taxonomy`
-| GET    | /places/{id}                       | {py:func}`.get_places_by_id`
-| GET    | /places/autocomplete               | {py:func}`.get_places_autocomplete`
-| GET    | /places/nearby                     | {py:func}`.get_places_nearby`
-| GET    | /posts                             | {py:func}`.get_posts`
-| GET    | /projects                          | {py:func}`.get_projects`
-| GET    | /projects/{id}                     | {py:func}`.get_projects_by_id`
-| PUT    | /projects/{id}                     | {py:func}`.update_project`
+| GET    | /messages                          | {py:func}`.get_messages`                                     |
+| GET    | /messages/{id}                     | {py:func}`.get_message_by_id`                                |
+| GET    | /messages/unread                   | {py:func}`.get_unread_meassage_count`                        |
+| DELETE | /observation_field_values/{id}     | {py:func}`.delete_observation_field`                         |
+| PUT    | /observation_field_values/{id}     | {py:func}`.set_observation_field`                            |
+| POST   | /observation_field_values          | {py:func}`.set_observation_field`                            |
+| POST   | /observation_photos                | {py:func}`.upload`                                           |
+| POST   | /observation_sounds                | {py:func}`.upload`                                           |
+| DELETE | /observations/{id}                 | {py:func}`~pyinaturalist.v1.observations.delete_observation` |
+| GET    | /observations/{id}                 | {py:func}`.get_observations_by_id`                           |
+| PUT    | /observations/{id}                 | {py:func}`~pyinaturalist.v1.observations.update_observation` |
+| GET    | /observations/{id}/taxon_summary   | {py:func}`.get_observation_taxon_summary`                    |
+| GET    | /observations                      | {py:func}`~pyinaturalist.v1.observations.get_observations`   |
+| POST   | /observations                      | {py:func}`~pyinaturalist.v1.observations.create_observation` |
+| GET    | /observations/histogram            | {py:func}`.get_observation_histogram`                        |
+| GET    | /observations/identifiers          | {py:func}`.get_observation_identifiers`                      |
+| GET    | /observations/observers            | {py:func}`.get_observation_observers`                        |
+| GET    | /observations/popular_field_values | {py:func}`.get_observation_popular_field_values`             |
+| GET    | /observations/species_counts       | {py:func}`.get_observation_species_counts`                   |
+| GET    | /observations/taxonomy             | {py:func}`.get_observation_taxonomy`                         |
+| GET    | /places/{id}                       | {py:func}`.get_places_by_id`                                 |
+| GET    | /places/autocomplete               | {py:func}`.get_places_autocomplete`                          |
+| GET    | /places/nearby                     | {py:func}`.get_places_nearby`                                |
+| GET    | /posts                             | {py:func}`.get_posts`                                        |
+| GET    | /projects                          | {py:func}`.get_projects`                                     |
+| GET    | /projects/{id}                     | {py:func}`.get_projects_by_id`                               |
+| PUT    | /projects/{id}                     | {py:func}`.update_project`                                   |
 | GET    | /projects/{id}/members             |
 | GET    | /projects/{id}/subscriptions       |
-| POST   | /projects/{id}/add                 | {py:func}`.add_project_observation`
-| DELETE | /projects/{id}/remove              | {py:func}`.delete_project_observation`
+| POST   | /projects/{id}/add                 | {py:func}`.add_project_observation`                          |
+| DELETE | /projects/{id}/remove              | {py:func}`.delete_project_observation`                       |
 | GET    | /projects/autocomplete             |
-| GET    | /search                            | {py:func}`.search`
-| GET    | /taxa                              | {py:func}`.get_taxa`
-| GET    | /taxa/{id}                         | {py:func}`.get_taxa_by_id`
-| GET    | /taxa/{id}/map_layers              | {py:func}`.get_taxa_map_layers`
-| GET    | /taxa/autocomplete                 | {py:func}`.get_taxa_autocomplete`
-| GET    | /users/{id}                        | {py:func}`.get_user_by_id`
+| GET    | /search                            | {py:func}`.search`                                           |
+| GET    | /taxa                              | {py:func}`.get_taxa`                                         |
+| GET    | /taxa/{id}                         | {py:func}`.get_taxa_by_id`                                   |
+| GET    | /taxa/{id}/map_layers              | {py:func}`.get_taxa_map_layers`                              |
+| GET    | /taxa/autocomplete                 | {py:func}`.get_taxa_autocomplete`                            |
+| GET    | /taxa/lifelist_metadata            | {py:func}`.get_lifelist_metadata`                            |
+| GET    | /users/{id}                        | {py:func}`.get_user_by_id`                                   |
 | GET    | /users/{id}/projects               |
-| GET    | /users/autocomplete                | {py:func}`.get_users_autocomplete`
-| GET    | /users/me                          | {py:func}`.get_current_user`
+| GET    | /users/autocomplete                | {py:func}`.get_users_autocomplete`                           |
+| GET    | /users/me                          | {py:func}`.get_current_user`                                 |
 
 ## v0 API
 For all available endpoints, see: <https://www.inaturalist.org/pages/api+reference>
 
-| Method | Endpoint                        | Function
-| ------ | --------                        | --------
-| GET    | /observations                   | {py:func}`~pyinaturalist.v0.observations.get_observations`
-| POST   | /observations                   | {py:func}`~pyinaturalist.v0.observations.create_observation`
-| PUT    | /observations/{id}              | {py:func}`~pyinaturalist.v0.observations.update_observation`
-| DELETE | /observations/{id}              | {py:func}`~pyinaturalist.v0.observations.delete_observation`
-| GET    | /observation_fields             | {py:func}`.get_observation_fields`
-| PUT    | /observation_field_values/{id}  | {py:func}`.put_observation_field_values`
-| POST   | /observation_photos             | {py:func}`.upload_photos`
-| POST   | /observation_sounds             | {py:func}`.upload_sounds`
+| Method | Endpoint                       | Function                                                     |
+| ------ | ------------------------------ | ------------------------------------------------------------ |
+| GET    | /observations                  | {py:func}`~pyinaturalist.v0.observations.get_observations`   |
+| POST   | /observations                  | {py:func}`~pyinaturalist.v0.observations.create_observation` |
+| PUT    | /observations/{id}             | {py:func}`~pyinaturalist.v0.observations.update_observation` |
+| DELETE | /observations/{id}             | {py:func}`~pyinaturalist.v0.observations.delete_observation` |
+| GET    | /observation_fields            | {py:func}`.get_observation_fields`                           |
+| PUT    | /observation_field_values/{id} | {py:func}`.put_observation_field_values`                     |
+| POST   | /observation_photos            | {py:func}`.upload_photos`                                    |
+| POST   | /observation_sounds            | {py:func}`.upload_sounds`                                    |

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/docs/user_guide.md

@@ -32,13 +32,14 @@ See {ref}`contributing` for details on setup for local development.
 :::{admonition} Python version compatibility
 :class: toggle, tip
 
-pyinaturalist currently requires **python 3.6+**. If you need to use an older version
+pyinaturalist currently requires **python 3.7+**. If you need to use an older version
 of python, here are the last compatible versions of pyinaturalist:
 
 * **python 2.7:** pyinaturalist 0.1
 * **python 3.4:** pyinaturalist 0.10
 * **python 3.5:** pyinaturalist 0.11
-* **python 3.6:** still supported, but expected to be dropped in a future release
+* **python 3.6:** pyinaturalist 0.16
+* **python 3.7:** still supported, but expected to be dropped in a future release
 :::
 
 ## Imports
@@ -58,7 +59,6 @@ and [search URLs](https://forum.inaturalist.org/t/how-to-use-inaturalists-search
 
 For example, if you wanted to search observations by user, these three requests are equivalent:
 
-
 ::::{tab-set}
 :::{tab-item} search URL
 ```
@@ -111,12 +111,11 @@ And here is what that same observation looks like in JSON:
 ### Previewing Responses
 These responses can contain large amounts of response attributes, making it somewhat cumbersome if you
 just want to quickly preview results (for example, in a Jupyter notebook). For that purpose, the
-{py:func}`~pyinaturalist.formatters.pprint` function is included to format response data as a
+{py:func}`~pyinaturalist.formatters.pprint` function is available to format response data as a
 condensed, color-highlighted table.
 
 **Examples:**
 
-
 ::::{tab-set}
 :::{tab-item} Observations
 ```
@@ -182,7 +181,6 @@ To get all pages of results and combine them into a single response, use `page='
 Note that this replaces the `get_all_*()` functions from pyinaturalist\<=0.12.
 
 (auth)=
-
 ## Authentication
 For any endpoints that create, update, or delete data, you will need to authenticate using an
 OAuth2 access token. This requires both your iNaturalist username and password, and separate
@@ -491,7 +489,6 @@ $Env:DRY_RUN_ENABLED="true"
 :::
 ::::
 
-
 ### Dry-run only write requests
 If you would like to send real `GET` requests but mock out any requests that modify data
 (`POST`, `PUT`, and `DELETE`), you can use the `DRY_RUN_WRITE_ONLY` variable instead:

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/examples/Tutorial_2_Taxa.ipynb

@@ -1,6 +1,7 @@
 {
  "cells": [
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "36ffdd0e",
    "metadata": {},
@@ -36,14 +37,16 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "3bd30a71",
    "metadata": {},
    "source": [
     "## Basic taxon search\n",
-    "Let's say you partially remember either a genus or family name that started with **'vespi'**-something.\n",
     "The [taxa endpoint](https://pyinaturalist.readthedocs.io/en/stable/modules/pyinaturalist.v1.taxa.html#pyinaturalist.v1.taxa.get_taxa)\n",
-    "can be used to search by name, rank, and several other criteria"
+    "can be used to search by name, rank, and several other criteria.\n",
+    "Let's say you partially remember either a genus or family name that started with **'vespi'**-something.\n",
+    "Use the `q` parameter to search by name:"
    ]
   },
   {
@@ -58,6 +61,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "9dca3b13",
    "metadata": {},
@@ -187,6 +191,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "4020d25d",
    "metadata": {},
@@ -238,13 +243,14 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "b9767ea3",
    "metadata": {},
    "source": [
     "## Searching by parent ID\n",
-    "Oh, that's right, it was **'Vespidae'**! Now let's find all of its subfamilies using its taxon ID\n",
-    "from the results above:"
+    "Oh, that's right, it was **'Vespidae'**! Now let's find all of its subfamilies.\n",
+    "We can run another search by parent ID, using the taxon ID from the results above:"
    ]
   },
   {

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/examples/sample_data.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# flake8: noqa: F401, F403
+# ruff: noqa: E402, F401, F402, F403, F405
 """Sample response data of every type to experiment with"""
 import sys
 
@@ -17,7 +17,7 @@ annotation = Annotation.from_json(j_annotation_1)
 comment = Comment.from_json(j_comment_1)
 controlled_term = ControlledTerm.from_json(j_controlled_term_1)
 identification = Identification.from_json(j_identification_1)
-life_list = LifeList.from_json(j_life_list)
+life_list = LifeList.from_json(j_life_list_1)
 observation = Observation.from_json(j_observation_1)
 observation_with_ofvs = Observation.from_json(j_observation_3_ofvs)
 observation_field = ObservationField.from_json(j_obs_field_1)

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/pyinat/__init__.py

@@ -1,4 +1,4 @@
-# flake8: noqa: F401, F403
+# ruff: noqa: F401, F403
 """Namespace alias that combines modules from pyinaturalist and pyinaturalist-convert (if installed).
 This allows abreviated imports like::
 

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/pyinaturalist/__init__.py

@@ -1,11 +1,11 @@
-# flake8: noqa: F401, F403
+# ruff: noqa: F401, F403
 # isort: skip_file
 __version__ = '0.19.0'
 
 from pyinaturalist.auth import get_access_token
 from pyinaturalist.client import iNatClient
 from pyinaturalist.constants import *
-from pyinaturalist.formatters import enable_logging, format_table, pprint
+from pyinaturalist.formatters import enable_logging, format_table, pprint, pprint_tree
 from pyinaturalist.models import *
 from pyinaturalist.paginator import Paginator, IDPaginator, WrapperPaginator
 from pyinaturalist.request_params import get_interval_ranges

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/pyinaturalist/client.py

@@ -10,7 +10,7 @@ from requests import Session
 from pyinaturalist.auth import get_access_token
 from pyinaturalist.constants import RequestParams
 from pyinaturalist.controllers import (
-    ControlledTermController,
+    AnnotationController,
     ObservationController,
     PlaceController,
     ProjectController,
@@ -93,7 +93,7 @@ class iNatClient:
             tokens as needed. Using a keyring instead is recommended, though.
         default_params: Default request parameters to pass to any applicable API requests
         dry_run: Just log all requests instead of sending real requests
-        loop: An event loop to use to run any executors used for async iteration
+        loop: An event loop to run any executors used for async iteration
         session: Session object to use instead of creating a new one
         kwargs: Keyword arguments for :py:class:`.ClientSession`
     """
@@ -117,9 +117,7 @@ class iNatClient:
         self._token_expires = None
 
         # Controllers
-        self.controlled_terms = ControlledTermController(
-            self
-        )  #: Interface for controlled term/annotation requests
+        self.annotations = AnnotationController(self)  #: Interface for annotation requests
         self.observations = ObservationController(self)  #: Interface for observation requests
         self.places = PlaceController(self)  #: Interface for project requests
         self.projects = ProjectController(self)  #: Interface for project requests

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/pyinaturalist/constants.py

@@ -11,6 +11,7 @@ API_V0 = 'https://www.inaturalist.org'
 API_V1 = 'https://api.inaturalist.org/v1'
 API_V2 = 'https://api.inaturalist.org/v2'
 EXPORT_URL = 'https://www.inaturalist.org/observations/export'
+GBIF_TAXON_BASE_URL = 'https://www.gbif.org/species'
 INAT_BASE_URL = API_V0
 INAT_REPO = 'https://raw.githubusercontent.com/inaturalist/inaturalist/main'
 ICONIC_TAXA_BASE_URL = f'{INAT_REPO}/app/assets/images/iconic_taxa'
@@ -103,6 +104,7 @@ ROOT_TAXON_ID = 48460
 
 # Taxonomic ranks that can be filtered on, and numeric values for comparison
 # Source: https://github.com/inaturalist/inaturalist/blob/main/app/models/taxon.rb
+UNRANKED = 90  # Used for comparing unranked taxa
 RANK_LEVELS = {
     'infrahybrid': 5,
     'form': 5,
@@ -138,18 +140,15 @@ RANK_LEVELS = {
     'subphylum': 57,
     'phylum': 60,
     'kingdom': 70,
-    'unranked': 90,  # Invented to make parent check work (this is null in the db)
+    'unranked': UNRANKED,
     'stateofmatter': 100,
 }
 RANKS = list(RANK_LEVELS.keys())[:-2]
 
-# Simplified subset of ranks that are useful for display
+# The main 7 taxonomic ranks, used for condensed display
 COMMON_RANKS = [
-    'form',
-    'variety',
     'species',
     'genus',
-    'tribe',
     'family',
     'order',
     'class',

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/pyinaturalist/controllers/__init__.py

@@ -1,7 +1,8 @@
 """Controller classes for :py:class:`.iNatClient`"""
-# flake8: noqa: F401
+# ruff: noqa: F401
+# isort: skip_file
 from pyinaturalist.controllers.base_controller import BaseController
-from pyinaturalist.controllers.controlled_term_controller import ControlledTermController
+from pyinaturalist.controllers.annotation_controller import AnnotationController
 from pyinaturalist.controllers.observation_controller import ObservationController
 from pyinaturalist.controllers.place_controller import PlaceController
 from pyinaturalist.controllers.project_controller import ProjectController

pyinaturalist-0.19.0.dev2/pyinaturalist/controllers/controlled_term_controller.py → pyinaturalist-0.19.0.dev3/pyinaturalist/controllers/annotation_controller.py

@@ -1,12 +1,14 @@
 from typing import Dict, List
 
+from pyinaturalist.constants import API_V2, IntOrStr
 from pyinaturalist.controllers import BaseController
-from pyinaturalist.docs import document_controller_params
+from pyinaturalist.docs import document_common_args, document_controller_params
 from pyinaturalist.models import Annotation, ControlledTerm
+from pyinaturalist.session import delete, post
 from pyinaturalist.v1 import get_controlled_terms, get_controlled_terms_for_taxon
 
 
-class ControlledTermController(BaseController):
+class AnnotationController(BaseController):
     """:fa:`tag` Controller for ControlledTerm and Annotation requests"""
 
     def __init__(self, *args, **kwargs):
@@ -46,3 +48,51 @@ class ControlledTermController(BaseController):
                 annotation.controlled_attribute = term
                 annotation.controlled_value = term.get_value_by_id(annotation.controlled_value.id)
         return annotations
+
+    # TODO: Allow passing labels instead of IDs
+    @document_common_args
+    def create(
+        self,
+        controlled_attribute_id: int,
+        controlled_value_id: int,
+        resource_id: IntOrStr,
+        resource_type: str = 'Observation',
+        **params,
+    ) -> Annotation:
+        """Create a new annotation on an observation.
+
+        Args:
+            controlled_attribute_id: Annotation attribute ID
+            controlled_value_id: Annotation value ID
+            resource_id: Observation ID or UUID
+            resource_type: Resource type, if something other than an observation
+
+        Example:
+
+            Add a 'Plant phenology: Flowering' annotation to an observation:
+
+            >>> annotation = client.annotations.create(12, 13, 164609837)
+
+        Returns:
+            The newly created Annotation object
+        """
+        response = post(
+            f'{API_V2}/annotations',
+            controlled_attribute_id=controlled_attribute_id,
+            controlled_value_id=controlled_value_id,
+            resource_id=resource_id,
+            resource_type=resource_type,
+            **params,
+        )
+        return Annotation.from_json(response.json()['results'][0])
+
+    def delete(self, uuid: str, **params):
+        """Delete an annotation
+
+        Args:
+            uuid: Annotation UUID
+
+        Returns:
+            Nothing; success means the item has been deleted
+        """
+        delete(f'{API_V2}/annotations/{uuid}', **params)

{pyinaturalist-0.19.0.dev2 → pyinaturalist-0.19.0.dev3}/pyinaturalist/controllers/observation_controller.py

@@ -25,6 +25,7 @@ from pyinaturalist.request_params import validate_multiple_choice_param
 from pyinaturalist.v1 import (
     create_observation,
     delete_observation,
+    get_life_list_metadata,
     get_observation_histogram,
     get_observation_identifiers,
     get_observation_observers,
@@ -75,7 +76,7 @@ class ObservationController(BaseController):
             _get_observations,
             Observation,
             cls=ObservationPaginator,
-            annotation_callback=self.client.controlled_terms.lookup,
+            annotation_callback=self.client.annotations.lookup,
             **params,
         )
 
@@ -89,9 +90,27 @@ class ObservationController(BaseController):
         response = self.client.request(get_observation_identifiers, **params)
         return UserCounts.from_json(response)
 
-    @document_controller_params(get_observation_taxonomy, add_common_args=False)
-    def life_list(self, user_id: IntOrStr, **params) -> LifeList:
+    @document_controller_params(get_observation_taxonomy)
+    def life_list(
+        self, user_id: Optional[IntOrStr] = None, locale: Optional[str] = None, **params
+    ) -> LifeList:
+        """Get taxa from a user's dynamic life list
+
+        Args:
+            user_id: iNaturalist user ID or username
+            locale: Locale preference for taxon common names
+        """
         response = self.client.request(get_observation_taxonomy, user_id=user_id, **params)
+
+        # Add additional metadata to a life list response; requires a user ID
+        if user_id:
+            metadata = self.client.request(
+                get_life_list_metadata, user_id=user_id, locale=locale, **params
+            )
+            meta_by_id = {item['id']: item for item in metadata['results']}
+            for taxon in response['results']:
+                taxon.update(meta_by_id.get(taxon['id'], {}))
+
         return LifeList.from_json(response)
 
     @document_controller_params(get_observation_observers)