Add full API request params w/ type annotations and docstrings for No…

…de API observation endpoints

pyinaturalist/constants.py

@@ -113,5 +113,7 @@
 # Additional options for multiple-choice search filters, used for validation
 COMMUNITY_ID_STATUSES = ["most_agree", "most_disagree", "some_agree"]
 GEOPRIVACY_LEVELS = ["obscured", "obscured_private", "open", "private"]
+ORDER_DIRECTIONS = ["asc", "desc"]
+ORDER_BY_PROPERTIES = ["created_at", "id", "observed_on", "species_guess", "votes"]
 SEARCH_PROPERTIES = ["names", "tags", "description", "place"]
 QUALITY_GRADES = ["casual", "needs_id", "research"]

pyinaturalist/docstrings.py

@@ -20,7 +20,7 @@ def _format_param_choices():
 
 MULTIPLE_CHOICE_PARAM_DOCS = "**Multiple-Choice Parameters:**\n" + _format_param_choices()
 
-GET_OBSERVATIONS = """
+OBSERVATION_PARAMS = """
 Args:
     acc: Whether or not positional accuracy / coordinate uncertainty has been specified
     captive: Captive or cultivated observations
@@ -113,3 +113,20 @@ def _format_param_choices():
     preferred_place_id: Place preference for regional taxon common names
     ttl: Set the ``Cache-Control`` HTTP header with this value as ``max-age``, in seconds
 """
+
+PAGINATION_PARAMS = """
+    page: Pagination page number
+    per_page: Number of results to return in a page. The maximum value is generally 200,
+        unless otherwise noted
+    order: Sort order
+    order_by: Field to sort on 
+"""
+
+ONLY_ID = """
+    only_id: Return only the record IDs
+"""
+
+# Parameter combinations for individual functions
+GET_OBSERVATIONS = OBSERVATION_PARAMS + PAGINATION_PARAMS + ONLY_ID
+GET_ALL_OBSERVATIONS = OBSERVATION_PARAMS + ONLY_ID
+GET_OBSERVATION_SPECIES_COUNTS = OBSERVATION_PARAMS