From 568be52180a62fa00d3f5a0b8fbd47acf9ca9ba8 Mon Sep 17 00:00:00 2001
From: Jordan Cook <jordan.cook.git@proton.me>
Date: Fri, 17 Nov 2023 17:00:23 -0600
Subject: [PATCH] WIP: Add examples to ObservationController methods

---
 .../controllers/observation_controller.py     | 70 ++++++++++++++++---
 pyinaturalist/v1/observations.py              |  6 +-
 2 files changed, 63 insertions(+), 13 deletions(-)

diff --git a/pyinaturalist/controllers/observation_controller.py b/pyinaturalist/controllers/observation_controller.py
index e78e24d4..9f4f4dfd 100644
--- a/pyinaturalist/controllers/observation_controller.py
+++ b/pyinaturalist/controllers/observation_controller.py
@@ -10,7 +10,12 @@
 )
 from pyinaturalist.controllers import BaseController
 from pyinaturalist.converters import ensure_list
-from pyinaturalist.docs import document_controller_description, document_controller_params
+from pyinaturalist.docs import (
+    copy_doc_signature,
+    document_controller_description,
+    document_controller_params,
+)
+from pyinaturalist.docs import templates as docs
 from pyinaturalist.models import (
     ControlledTermCounts,
     LifeList,
@@ -33,7 +38,6 @@
     get_observation_species_counts,
     get_observation_taxon_summary,
     get_observation_taxonomy,
-    get_observations,
     get_observations_by_id,
     update_observation,
     upload,
@@ -46,7 +50,11 @@ class ObservationController(BaseController):
     """:fa:`binoculars` Controller for Observation requests"""
 
     def __call__(self, observation_id: int, **kwargs) -> Optional[Observation]:
-        """Get a single observation by ID"""
+        """Get a single observation by ID
+
+        Args:
+            observation_ids: A single observation ID
+        """
         return self.from_ids(observation_id, **kwargs).one()
 
     @document_controller_description(get_observations_by_id)
@@ -64,17 +72,57 @@ def from_ids(self, observation_ids: MultiInt, **params) -> Paginator[Observation
             **params,
         )
 
-    @document_controller_params(get_observations)
+    @copy_doc_signature(*docs._get_observations, docs._only_id)
     def search(self, **params) -> Paginator[Observation]:
-        # Use a simplified version of v1.get_observations() to avoid running coord conversions twice
-        def _get_observations(**params):
-            params = validate_multiple_choice_param(params, 'order_by', V1_OBS_ORDER_BY_PROPERTIES)
+        """Search observations
+
+        .. rubric:: Notes
+
+        * :fas:`lock-open` :ref:`Optional authentication <auth>` (For private/obscured coordinates)
+        * API reference: :v1:`GET /observations <Observations/get_observations>`
+
+        Examples:
+
+            Get observations of Monarch butterflies with photos + public location info,
+            on a specific date in the provice of Saskatchewan, CA (place ID 7953):
+
+            >>> obs = client.observations.search(
+            >>>     taxon_name='Danaus plexippus',
+            >>>     created_on='2020-08-27',
+            >>>     photos=True,
+            >>>     geo=True,
+            >>>     geoprivacy='open',
+            >>>     place_id=7953,
+            >>> )
+
+            Get basic info for observations in response:
+
+            >>> pprint(obs)
+            ID       Taxon ID Taxon                       Observed on   User      Location
+            ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+            57707611 48662    Danaus plexippus (Monarch)  Aug 26, 2020  ingridt3  Michener Dr, Regina, SK, CA
+            57754375 48662    Danaus plexippus (Monarch)  Aug 27, 2020  samroom   Railway Ave, Wilcox, SK, CA
+
+            Search for observations with a given observation field:
+
+            >>> obs = client.observations.search(observation_fields=['Species count'])
+
+            Or observation field value:
+
+            >>> response = client.observations.search(observation_fields={'Species count': 2})
+
+        """
+
+        def get_observations(**params):
             return self.client.session.get(f'{API_V1}/observations', **params).json()
 
-        return self.client.paginate(
-            _get_observations,
+        params = validate_multiple_choice_param(params, 'order_by', V1_OBS_ORDER_BY_PROPERTIES)
+        params = self.client.add_client_settings(get_observations, params)
+
+        return ObservationPaginator(
+            get_observations,
             Observation,
-            cls=ObservationPaginator,
+            loop=self.client.loop,
             annotation_callback=self.client.annotations.lookup,
             **params,
         )
@@ -184,7 +232,7 @@ def __init__(
 
     def next_page(self) -> List[Observation]:
         observations = super().next_page()
-        # Used cached controlled_terms lookup to fill in missing annotation details
+        # Use cached controlled_terms lookup to fill in missing annotation details
         for obs in observations:
             obs.annotations = self.annotation_callback(obs.annotations)
         return observations
diff --git a/pyinaturalist/v1/observations.py b/pyinaturalist/v1/observations.py
index d6322ba9..d6ba7f1c 100644
--- a/pyinaturalist/v1/observations.py
+++ b/pyinaturalist/v1/observations.py
@@ -61,8 +61,10 @@ def get_observations(**params) -> JsonResponse:
         Get basic info for observations in response:
 
         >>> pprint(response)
-        '[57754375] Species: Danaus plexippus (Monarch) observed by samroom on 2020-08-27 at Railway Ave, Wilcox, SK'
-        '[57707611] Species: Danaus plexippus (Monarch) observed by ingridt3 on 2020-08-26 at Michener Dr, Regina, SK'
+        ID       Taxon ID Taxon                       Observed on   User      Location
+        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        57707611 48662    Danaus plexippus (Monarch)  Aug 26, 2020  ingridt3  Michener Dr, Regina, SK, CA
+        57754375 48662    Danaus plexippus (Monarch)  Aug 27, 2020  samroom   Railway Ave, Wilcox, SK, CA
 
         Search for observations with a given observation field: