pyinaturalist 0.19.0.dev0__tar.gz → 0.19.0.dev2__tar.gz

{pyinaturalist-0.19.0.dev0 → pyinaturalist-0.19.0.dev2}/CONTRIBUTORS.md

@@ -3,12 +3,14 @@ Thanks to the following individuals for providing pull requests, feedback, bug r
 questions, and other contributions that have helped to improve pyinaturalist:
 
 * [AE Hamrick](https://github.com/AEHamrick)
+* [abubelinha](https://github.com/abubelinha)
 * [Ben Armstrong](https://github.com/synrg)
 * [Dr. Tom August](https://github.com/AugustT)
 * [Eduardo Ramírez](https://github.com/eduramirezh)
 * [Felipe S Barros](https://github.com/FelipeSBarros)
-* [Ken-ichi Ueda](https://github.com/kueda/)
+* [Ken-ichi Ueda](https://github.com/kueda)
 * [Matt Muir](https://forum.inaturalist.org/u/muir)
+* [Nicolas Noé](https://github.com/niconoe)
 * [Patrick Leary](https://github.com/pleary)
 * [Peter Desmet](https://github.com/peterdesmet)
 * [pisum](https://forum.inaturalist.org/u/pisum)

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

@@ -6,7 +6,7 @@
 * Added new **User** endpoint: `get_current_user()`
 
 ### Modified Endpoints
-Add support for searching observations by observation fields, using a new `fields` param for the following functions:
+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()`
@@ -14,6 +14,12 @@ Add support for searching observations by observation fields, using a new `field
 * `get_observation_popular_field_values()`
 * `get_observation_species_counts()`
 
+### Models
+* 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 `Sound` model for `Observation.sounds`
+* Fix initialization of `ListedTaxon.place`
+
 ## 0.18.0 (2023-02-27)
 
 ### New Endpoints

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

@@ -1,12 +1,12 @@
 Metadata-Version: 2.1
 Name: pyinaturalist
-Version: 0.19.0.dev0
+Version: 0.19.0.dev2
 Summary: iNaturalist API client for python
 Home-page: https://github.com/pyinat/pyinaturalist
 License: MIT
 Keywords: inaturalist,biodiversity,conservation,citizen-science,community-science,api,api-client,data-model,requests
-Author: Nicolas Noé
-Author-email: nicolas@niconoe.eu
+Author: Jordan Cook
+Author-email: jordan.cook.git@proton.me
 Requires-Python: >=3.7,<4.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -24,13 +24,13 @@ Classifier: Typing :: Typed
 Provides-Extra: all
 Provides-Extra: docs
 Requires-Dist: attrs (>=21.2)
-Requires-Dist: furo (>=2022.9,<2023.0) ; extra == "docs"
+Requires-Dist: furo (>=2023.3,<2024.0) ; extra == "docs"
 Requires-Dist: ipython (>=7.25.0,<8.0.0) ; extra == "docs"
 Requires-Dist: keyring (>=22.3)
 Requires-Dist: linkify-it-py (>=1.0.1,<2.0.0) ; extra == "docs"
-Requires-Dist: myst-parser (>=0.19,<0.20) ; extra == "docs"
-Requires-Dist: nbsphinx (>=0.8,<0.9) ; extra == "docs"
-Requires-Dist: platformdirs (>=2.5)
+Requires-Dist: myst-parser (>=1.0,<2.0) ; extra == "docs"
+Requires-Dist: nbsphinx (>=0.9,<0.10) ; extra == "docs"
+Requires-Dist: platformdirs (>=2.6)
 Requires-Dist: python-dateutil (>=2.0)
 Requires-Dist: python-forge (>=18.6)
 Requires-Dist: requests (>=2.22)
@@ -43,7 +43,7 @@ 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: ujson (>=5.4.0,<6.0.0) ; extra == "all"
+Requires-Dist: ujson (>5.0) ; extra == "all"
 Project-URL: Documentation, https://pyinaturalist.readthedocs.io
 Project-URL: Repository, https://github.com/pyinat/pyinaturalist
 Description-Content-Type: text/markdown

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

@@ -12,10 +12,10 @@ from pyinaturalist.request_params import get_interval_ranges
 from pyinaturalist.session import ClientSession, clear_cache
 from pyinaturalist.v0 import *
 from pyinaturalist.v1 import *
-from pyinaturalist.v2 import *
 
 # For disambiguation
 from pyinaturalist.v0 import create_observation as create_observation_v0
 from pyinaturalist.v0 import get_observations as get_observations_v0
 from pyinaturalist.v0 import update_observation as update_observation_v0
 from pyinaturalist.v0 import delete_observation as delete_observation_v0
+from pyinaturalist.v2 import get_observations as get_observations_v2

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

@@ -196,6 +196,15 @@ SOURCES = ['places', 'projects', 'taxa', 'users']
 # Endpoint-specific options for multiple choice parameters
 V0_OBS_ORDER_BY_PROPERTIES = ['date_added', 'observed_on']
 V1_OBS_ORDER_BY_PROPERTIES = ['created_at', 'id', 'observed_on', 'species_guess', 'votes']
+V2_OBS_ORDER_BY_PROPERTIES = [
+    'created_at',
+    'id',
+    'observed_on',
+    'species_guess',
+    'updated_at',
+    'votes',
+    'random',
+]
 PROJECT_ORDER_BY_PROPERTIES = ['created', 'distance', 'featured', 'recent_posts', 'updated']
 
 # Multiple-choice request parameters, with keys mapped to their possible choices (non-endpoint-specific)

{pyinaturalist-0.19.0.dev0 → pyinaturalist-0.19.0.dev2}/pyinaturalist/docs/model_docs.py

@@ -14,7 +14,7 @@ from sphinx_autodoc_typehints import format_annotation
 from pyinaturalist.constants import DOCS_DIR
 from pyinaturalist.models import LazyProperty, get_lazy_properties
 
-IGNORE_PROPERTIES = ['row']
+IGNORE_PROPERTIES = ['_row', '_str_attrs']
 MODEL_DOC_DIR = join(DOCS_DIR, 'models')
 
 

{pyinaturalist-0.19.0.dev0 → pyinaturalist-0.19.0.dev2}/pyinaturalist/docs/templates.py

@@ -188,7 +188,7 @@ def _observation_v1(
     verifiable: Optional[bool] = None,
     not_id: Optional[MultiInt] = None,
     sound_license: Optional[MultiStr] = None,
-    fields: Optional[Union[List, Dict]] = None,
+    observation_fields: Optional[Union[List, Dict]] = None,
     ofv_datatype: Optional[MultiStr] = None,
     place_id: Optional[MultiInt] = None,
     project_id: Optional[MultiInt] = None,
@@ -260,7 +260,7 @@ def _observation_v1(
     project_id: Must be added to the project this ID or slug
     rank: Taxon must have this rank
     site_id: Must be affiliated with the iNaturalist network website with this ID
-    fields: Must have these observation fields (optionally with values)
+    observation_fields: Must have these observation fields (optionally with values)
     ofv_datatype: Must have an observation field value with this datatype
     sound_license: Must have at least one sound with this license
     without_taxon_id: Exclude observations of these taxa and their descendants
@@ -333,13 +333,24 @@ def _observation_v0(
     on: Filter by date string
     extra: Retrieve additional information.
         **'projects'** returns info about the projects the observations have been added to,
-        **'fields'** returns observation field values,
+        **'observation_fields'** returns observation field values,
         **'observation_photos'** returns information about the photos' relationship with the
         observation, like their order.
     response_format: A supported response format to return
     """
 
 
+# Observation params that are only in the v2 API
+def _observation_v2(
+    fields: Optional[Union[List[str], Dict[str, Any]]] = None,
+    except_fields: Optional[List[str]] = None,
+):
+    """Args:
+    fields: Data fields to return in the response
+    except_fields: Data fields to exclude from the response (and include all others)
+    """
+
+
 def _observation_histogram(
     date_field: str = 'observed',
     interval: str = 'month_of_year',
@@ -384,7 +395,7 @@ def _create_observation(
 ):
     """Args:
     species_guess: Equivalent to the 'What did you see?' field on the observation form.
-        iNat will try to choose a single taxon based on this, but it may fail if it's ambuguous
+        iNat will try to choose a single taxon based on this, but it may fail if it's ambiguous
     taxon_id: ID of the taxon to associate with this observation
     observed_on: Alias for ``observed_on_string``; accepts :py:class:`~datetime.datetime` objects.
     observed_on_string: Date/time of the observation. Time zone will default to the user's

{pyinaturalist-0.19.0.dev0 → pyinaturalist-0.19.0.dev2}/pyinaturalist/formatters.py

@@ -36,6 +36,7 @@ from pyinaturalist.models import (
     Project,
     ResponseOrObjects,
     SearchResult,
+    Sound,
     Taxon,
     TaxonCount,
     TaxonSummary,
@@ -130,6 +131,7 @@ UNIQUE_RESPONSE_ATTRS = {
     'score': SearchResult,
     'last_observation_id': ListedTaxon,
     'listed_taxon': TaxonSummary,
+    'native_sound_id': Sound,
     'count': TaxonCount,
     'rank': Taxon,
     'roles': User,

{pyinaturalist-0.19.0.dev0 → pyinaturalist-0.19.0.dev2}/pyinaturalist/models/__init__.py

@@ -70,7 +70,7 @@ def upper(value) -> Optional[str]:
 # Models imported in order of dependencies
 # --------------------------------------------------------
 
-from pyinaturalist.models.photo import IconPhoto, Photo
+from pyinaturalist.models.media import IconPhoto, Photo, Sound
 from pyinaturalist.models.place import Place
 from pyinaturalist.models.user import User, UserCount, UserCounts
 from pyinaturalist.models.checklist import Checklist, EstablishmentMeans, ListedTaxon

{pyinaturalist-0.19.0.dev0 → pyinaturalist-0.19.0.dev2}/pyinaturalist/models/checklist.py

@@ -126,7 +126,8 @@ class ListedTaxon(EstablishmentMeans):
 
     @place_id.setter
     def place_id(self, value: int):
-        self.place = Place(id=value)
+        self.place = self.place or Place()
+        self.place.id = value
 
     @property
     def updater_id(self) -> Optional[int]:
@@ -134,7 +135,8 @@ class ListedTaxon(EstablishmentMeans):
 
     @updater_id.setter
     def updater_id(self, value: int):
-        self.updater = User(id=value)
+        self.updater = self.updater or User()
+        self.updater.id = value
 
     @property
     def user_id(self) -> Optional[int]:
@@ -142,7 +144,8 @@ class ListedTaxon(EstablishmentMeans):
 
     @user_id.setter
     def user_id(self, value: int):
-        self.user = User(id=value)
+        self.user = self.user or User()
+        self.user.id = value
 
     @property
     def _row(self) -> TableRow:

pyinaturalist-0.19.0.dev0/pyinaturalist/models/photo.py → pyinaturalist-0.19.0.dev2/pyinaturalist/models/media.py

@@ -19,13 +19,7 @@ from pyinaturalist.models import BaseModel, define_model, field
 
 
 @define_model
-class Photo(BaseModel):
-    """:fa:`camera` An observation photo, based on the schema of photos from:
-
-    * `GET /observations <https://api.inaturalist.org/v1/docs/#!/Observations/get_observations>`_
-    * `GET /taxa <https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa>`
-    """
-
+class BaseMedia(BaseModel):
     attribution: str = field(default=None, doc='License attribution')
     license_code: str = field(
         default=None,
@@ -33,6 +27,30 @@ class Photo(BaseModel):
         options=ALL_LICENSES,
         doc='Creative Commons license code',
     )
+
+    @property
+    def ext(self) -> str:
+        """File extension from URL"""
+        return self.url.lower().split('.')[-1].split('?')[0]  # type: ignore
+
+    @property
+    def has_cc_license(self) -> bool:
+        """Determine if this photo has a Creative Commons license"""
+        return self.license_code in CC_LICENSES
+
+    @property
+    def _str_attrs(self) -> List[str]:
+        return ['id', 'license_code', 'url']
+
+
+@define_model
+class Photo(BaseMedia):
+    """:fa:`camera` An observation photo, based on the schema of photos from:
+
+    * `GET /observations <https://api.inaturalist.org/v1/docs/#!/Observations/get_observations>`_
+    * `GET /taxa <https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa>`
+    """
+
     observation_id: int = field(default=None, doc='Associated observation ID')
     original_dimensions: Tuple[int, int] = field(
         converter=format_dimensions, default=(0, 0), doc='Dimensions of original image'
@@ -65,21 +83,11 @@ class Photo(BaseModel):
             value = value['photo']
         return super(Photo, cls).from_json(value, **kwargs)
 
-    @property
-    def ext(self) -> str:
-        """File extension from URL"""
-        return self.url.lower().split('.')[-1].split('?')[0]
-
     @property
     def dimensions_str(self) -> str:
         """Dimensions as a string, formatted as ``{width}x{height}``"""
         return f'{self.original_dimensions[0]}x{self.original_dimensions[1]}'
 
-    @property
-    def has_cc_license(self) -> bool:
-        """Determine if this photo has a Creative Commons license"""
-        return self.license_code in CC_LICENSES
-
     @property
     def info_url(self) -> str:
         """Photo info URL on iNaturalist.org"""
@@ -147,10 +155,6 @@ class Photo(BaseModel):
             'URL': self.original_url,
         }
 
-    @property
-    def _str_attrs(self) -> List[str]:
-        return ['id', 'license_code', 'url']
-
 
 @define_model
 class IconPhoto(Photo):
@@ -179,3 +183,33 @@ class IconPhoto(Photo):
     @property
     def _str_attrs(self) -> List[str]:
         return ['iconic_taxon_name', 'url']
+
+
+@define_model
+class Sound(BaseMedia):
+    file_content_type: str = field(default=None)
+    file_url: str = field(default=None)
+    native_sound_id: str = field(default=None)
+    secret_token: str = field(default=None)
+    subtype: str = field(default=None)
+
+    # Unused attributes
+    # flags: List = field(factory=list)
+    # play_local: bool = field(default=None)
+
+    # Aliases
+    @property
+    def mimetype(self) -> str:
+        return self.file_content_type
+
+    @property
+    def url(self) -> str:
+        return self.file_url
+
+    @property
+    def _row(self) -> TableRow:
+        return {
+            'ID': self.id,
+            'License': self.license_code,
+            'URL': self.url,
+        }

{pyinaturalist-0.19.0.dev0 → pyinaturalist-0.19.0.dev2}/pyinaturalist/models/observation.py

@@ -1,5 +1,7 @@
 from datetime import datetime
-from typing import Any, Dict, List
+from itertools import chain
+from typing import Any, Dict, List, Tuple
+from warnings import warn
 
 from pyinaturalist.constants import (
     ALL_LICENSES,
@@ -22,6 +24,7 @@ from pyinaturalist.models import (
     ObservationFieldValue,
     Photo,
     ProjectObservation,
+    Sound,
     Taxon,
     User,
     coordinate_pair,
@@ -40,15 +43,20 @@ class Observation(BaseModel):
     :v1:`GET /observations <Observations/get_observations>`
     """
 
+    application: Dict = field(factory=dict, doc='Application that created the observation')
     created_at: datetime = datetime_now_field(doc='Date and time the observation was created')
     captive: bool = field(
         default=None, doc='Indicates if the organism is non-wild (captive or cultivated)'
     )
     community_taxon_id: int = field(default=None, doc='The current community identification taxon')
+    context_geoprivacy: str = field(default=None)
+    context_taxon_geoprivacy: str = field(default=None)
+    context_user_geoprivacy: str = field(default=None)
     description: str = field(default=None, doc='Observation description')
     faves: List[Dict] = field(
         factory=list, doc='Details on users who have favorited the observation'
     )
+    flags: List[Dict] = field(factory=list)
     geoprivacy: str = field(default=None, options=GEOPRIVACY_LEVELS, doc='Location privacy level')
     identifications_count: int = field(default=0, doc='Total number of identifications')
     identifications_most_agree: bool = field(
@@ -126,16 +134,19 @@ class Observation(BaseModel):
     site_id: int = field(
         default=None, doc='Site ID for iNaturalist network members, or ``1`` for inaturalist.org'
     )
-    sounds: List[Dict] = field(factory=list, doc='Observation sound files')
     species_guess: str = field(
         default=None, doc="Taxon name from observer's initial identification"
     )
     tags: List[str] = field(factory=list, doc='Arbitrary user tags added to the observation')
+    taxon_geoprivacy: str = field(default=None)
     updated_at: DateTime = datetime_field(doc='Date and time the observation was last updated')
     uri: str = field(default=None, doc='Link to observation details page')
     uuid: str = field(
         default=None, doc='Universally unique ID; generally preferred over ``id`` where possible'
     )
+    viewer_trusted_by_observer: bool = field(
+        default=None, doc='Observer trusts the authenticated user with access to hidden coordinates'
+    )
     votes: List[Dict] = field(factory=list, doc='Votes on data quality assessment metrics')
 
     # Lazy-loaded model objects
@@ -161,6 +172,9 @@ class Observation(BaseModel):
         type=List[ProjectObservation],
         doc='Details on any projects that the observation has been added to',
     )
+    sounds: property = LazyProperty(
+        Sound.from_json_list, type=List[Sound], doc='Observation sound files'
+    )
     taxon: property = LazyProperty(Taxon.from_json, type=Taxon, doc='Observation taxon')
     user: property = LazyProperty(User.from_json, type=User, doc='Observer')
 
@@ -170,15 +184,16 @@ class Observation(BaseModel):
     # created_at_details: Dict = field(factory=dict)
     # created_time_zone: str = field(default=None)
     # faves_count: int = field(default=None)
-    # flags: List = field(factory=list)
     # geojson: Dict = field(factory=dict)
     # id_please: bool = field(default=None)
     # map_scale: int = field(default=None)
     # non_owner_ids: List = field(factory=list)
+    # non_traditional_projects: property = LazyProperty(Project.from_json_list, type=List[Project])
     # observed_on_details: Dict = field(factory=dict)
     # observed_on_string: str = field(default=None)
     # observation_photos: List[Photo] = field(converter=Photo.from_dict_list, factory=list)
     # observed_time_zone: str = field(default=None)
+    # private_geojson: Dict = field(factory=dict)
     # spam: bool = field(default=None)
     # time_observed_at: DateTime = datetime_attr
     # time_zone_offset: str = field(default=None)
@@ -191,9 +206,11 @@ class Observation(BaseModel):
         observed_on = kwargs.pop('time_observed_at', None)
         if not isinstance(kwargs['observed_on'], datetime) and observed_on:
             kwargs['observed_on'] = observed_on
+
         # Set default URL based on observation ID
         if not kwargs.get('uri'):
             kwargs['uri'] = f'{INAT_BASE_URL}/observations/{kwargs.get("id", "")}'
+
         # Set identifications_count if missing
         if kwargs.get('identifications') and not kwargs.get('identifications_count'):
             kwargs['identifications_count'] = len(kwargs['identifications'])
@@ -201,12 +218,41 @@ class Observation(BaseModel):
 
     @classmethod
     def from_id(cls, id: int):
-        """Lookup and create a new Observation object from an ID"""
+        """**[Deprecated]** Lookup and create a new Observation object from an ID"""
         from pyinaturalist.v1 import get_observation
 
+        warn(
+            DeprecationWarning(
+                'This method is deprecated; please use iNatClient.observations() instead'
+            )
+        )
         json = get_observation(id)
         return cls.from_json(json)
 
+    @property
+    def cumulative_ids(self) -> Tuple[int, int]:
+        """Calculate the cumulative community ID score (agreements/total), as shown on the observation UI
+
+        Returns:
+            ``(agreements, total)``
+        """
+        idents_count = 0
+        idents_agree = 0
+        ident_taxon_ids = self.ident_taxon_ids
+
+        for ident in filter(lambda i: i.current, self.identifications):
+            user_taxon_ids = ident.taxon.ancestor_ids + [ident.taxon.id]
+            if self.community_taxon_id in user_taxon_ids:
+                # Count towards total & agree:
+                if ident.taxon.id in ident_taxon_ids:
+                    idents_count += 1
+                    idents_agree += 1
+            else:
+                # Maverick counts against:
+                idents_count += 1
+
+        return (idents_agree, idents_count)
+
     @property
     def default_photo(self) -> Photo:
         """Get the default observation photo if any; otherwise use taxon default photo or icon"""
@@ -217,6 +263,15 @@ class Observation(BaseModel):
         else:
             return IconPhoto.from_iconic_taxon('unknown')
 
+    @property
+    def ident_taxon_ids(self) -> List[int]:
+        """Get all taxon IDs (including ancestors) from identifications"""
+        ident_taxa = [
+            ident.taxon for ident in self.identifications if ident.taxon and ident.current
+        ]
+        ident_ids = chain.from_iterable([t.ancestor_ids + [t.id] for t in ident_taxa])
+        return list(set(ident_ids))
+
     @property
     def _row(self) -> TableRow:
         return {

{pyinaturalist-0.19.0.dev0 → pyinaturalist-0.19.0.dev2}/pyinaturalist/models/taxon.py

@@ -224,10 +224,9 @@ class Taxon(BaseModel):
         """Info URL on iNaturalist.org"""
         return f'{INAT_BASE_URL}/taxa/{self.id}'
 
-    # TODO: Experimental; not sure if I want to have API calls in model classes
     @classmethod
     def from_id(cls, id: int) -> 'Taxon':
-        """Lookup and create a new Taxon object by ID"""
+        """**[Deprecated]** Lookup and create a new Taxon object by ID"""
         from pyinaturalist.v1 import get_taxa_by_id
 
         warn(DeprecationWarning('This method is deprecated; please use iNatClient.taxa() instead'))

{pyinaturalist-0.19.0.dev0 → pyinaturalist-0.19.0.dev2}/pyinaturalist/request_params.py

@@ -177,7 +177,8 @@ def convert_observation_field_params(params: RequestParams) -> RequestParams:
 
 
 def convert_observation_field_filters(params: RequestParams) -> RequestParams:
-    fields = params.pop('fields', None)
+    """Convert observation field filters from simplified format to full request params"""
+    fields = params.pop('observation_fields', None)
     if not fields:
         return params
     # List of fields to filter on (any value)
@@ -357,7 +358,7 @@ def _validate_multiple_choice_param(
             return True
         if not isinstance(value, list):
             value = [value]
-        return all([v in choices for v in value])
+        return all(v in choices for v in value)
 
     def normalize(value):
         if not value: