Improvements suggested by kara (#234)

-removes `fetch_latest_observations` as it didn’t really serve a useful role
-removes`fetch_latest_observations_by_entity`
as it is basically the same as `fetch_observations_by_entity` but just
with a default of the latest date.
- renames`fetch_observations_by_entity` to `fetch_observations_by_entity_dcid`
- renames`get_observations_as_records` to `to_observation_records`. This name
more accurately reflects what the method does: it transforms nested
observation data and facet metadata into a list of flat, record-like
dictionaries suitable for analysis. This mirrors common data science
terminology.

Author: jm-rivera

datacommons_client/client.py

@@ -87,12 +87,11 @@ def _find_filter_facet_ids(
       return None
 
     if fetch_by == "entity":
-      observations = self.observation.fetch_observations_by_entity(
+      observations = self.observation.fetch_observations_by_entity_dcid(
           date=date,
           entity_dcids=entity_dcids,
           variable_dcids=variable_dcids,
-          select=["variable", "entity", "facet"],
-      )
+          select=["variable", "entity", "facet"])
     else:
       observations = self.observation.fetch_observations_by_entity_type(
           date=date,
@@ -176,11 +175,10 @@ def observations_dataframe(
           filter_facet_ids=facets,
       )
     else:
-      observations = self.observation.fetch_observations_by_entity(
+      observations = self.observation.fetch_observations_by_entity_dcid(
           date=date,
           entity_dcids=entity_dcids,
           variable_dcids=variable_dcids,
-          filter_facet_ids=facets,
-      )
+          filter_facet_ids=facets)
 
-    return pd.DataFrame(observations.get_observations_as_records())
+    return pd.DataFrame(observations.to_observation_records())

datacommons_client/endpoints/observation.py

@@ -63,72 +63,6 @@ def fetch(
     # Send the request
     return ObservationResponse.from_json(self.post(payload))
 
-  def fetch_latest_observations(
-      self,
-      variable_dcids: str | list[str],
-      entity_dcids: Optional[str | list[str]] = None,
-      entity_expression: Optional[str] = None,
-      *,
-      select: Optional[list[ObservationSelect | str]] = None,
-      filter_facet_domains: Optional[str | list[str]] = None,
-      filter_facet_ids: Optional[str | list[str]] = None,
-  ) -> ObservationResponse:
-    """
-        Fetches the latest observations for the given variable and entity.
-
-        Args:
-            variable_dcids (str | list[str]): One or more variable IDs for the data.
-            entity_dcids (Optional[str | list[str]]): One or more entity IDs to filter the data.
-            entity_expression (Optional[str]): A string expression to filter entities.
-            select (Optional[list[ObservationSelect | str]]): Fields to include in the response.
-                If not provided, defaults to ["date", "variable", "entity", "value"].
-            filter_facet_domains: Optional[str | list[str]: One or more domain names to filter the data.
-            filter_facet_ids: Optional[str | list[str]: One or more facet IDs to filter the data.
-
-        Returns:
-            ObservationResponse: The response object containing observations for the specified query.
-        """
-    return self.fetch(
-        variable_dcids=variable_dcids,
-        date=ObservationDate.LATEST,
-        entity_dcids=entity_dcids,
-        entity_expression=entity_expression,
-        filter_facet_domains=filter_facet_domains,
-        filter_facet_ids=filter_facet_ids,
-        select=[s for s in ObservationSelect] if not select else select,
-    )
-
-  def fetch_latest_observations_by_entity(
-      self,
-      variable_dcids: str | list[str],
-      entity_dcids: str | list[str],
-      *,
-      select: Optional[list[ObservationSelect | str]] = None,
-      filter_facet_domains: Optional[str | list[str]] = None,
-      filter_facet_ids: Optional[str | list[str]] = None,
-  ) -> ObservationResponse:
-    """Fetches the latest observations for the given variable and entities.
-
-        Args:
-            variable_dcids (str | list[str]): One or more variable IDs for the data.
-            entity_dcids (str | list[str]): One or more entity IDs to filter the data.
-            select (Optional[list[ObservationSelect | str]]): Fields to include in the response.
-                If not provided, defaults to ["date", "variable", "entity", "value"].
-            filter_facet_domains: Optional[str | list[str]: One or more domain names to filter the data.
-            filter_facet_ids: Optional[str | list[str]: One or more facet IDs to filter the data.
-
-        Returns:
-            ObservationResponse: The response object containing observations for the specified query.
-        """
-
-    return self.fetch_latest_observations(
-        variable_dcids=variable_dcids,
-        entity_dcids=entity_dcids,
-        select=[s for s in ObservationSelect] if not select else select,
-        filter_facet_domains=filter_facet_domains,
-        filter_facet_ids=filter_facet_ids,
-    )
-
   def fetch_observations_by_entity_type(
       self,
       date: ObservationDate | str,
@@ -185,7 +119,7 @@ def fetch_observations_by_entity_type(
         filter_facet_ids=filter_facet_ids,
     )
 
-  def fetch_observations_by_entity(
+  def fetch_observations_by_entity_dcid(
       self,
       date: ObservationDate | str,
       entity_dcids: str | list[str],
@@ -218,7 +152,7 @@ def fetch_observations_by_entity(
 
             ```python
             api = API()
-            ObservationEndpoint(api).fetch_observations_by_entity(
+            ObservationEndpoint(api).fetch_observations_by_entity_dcid(
                 date="all",
                 entity_dcids="country/NGA",
                 variable_dcids="sdg/SI_POV_DAY1"

datacommons_client/endpoints/response.py

@@ -105,11 +105,20 @@ def get_data_by_entity(self) -> Dict:
         variable: data.byEntity for variable, data in self.byVariable.items()
     }
 
-  def get_observations_as_records(self) -> List[Dict[str, Any]]:
-    """Converts the observation data into a list of records.
+  def to_observation_records(self) -> List[Dict[str, Any]]:
+    """Returns a flat list of observation records combining date, variable, entity,
+         observation, and facet metadata.
 
-        Returns:
-            List[Dict[str, Any]]: A flattened list of observation records.
+    This method transforms the nested `byVariable` and `facets` data in the ObservationResponse
+    into a flat list of dictionaries. Each dictionary (or "record") represents a single observation
+    for a variable and entity, enriched with its associated facet metadata (e.g., measurement method,
+    observation period, unit).
+
+    This format is suitable for exporting to a DataFrame or serializing to JSON for tabular or analytical use.
+
+    Returns:
+        List[Dict[str, Any]]: A list of observation records, where each record contains the variable,
+        entity, date, value, facetId, and any additional metadata provided by the facet.
         """
     return observations_as_records(data=self.get_data_by_entity(),
                                    facets=self.facets)

datacommons_client/tests/endpoints/test_observation_endpoint.py

@@ -42,68 +42,6 @@ def test_fetch():
                                         next_token=None)
 
 
-def test_fetch_latest_observation():
-  """Tests the fetch_latest_observation method."""
-  api_mock = MagicMock(spec=API)
-  endpoint = ObservationEndpoint(api=api_mock)
-
-  response = endpoint.fetch_latest_observations(
-      variable_dcids=["dc/Variable1", "dc/Variable2"],
-      select=["date", "variable", "entity", "value"],
-      entity_dcids="dc/EntityID")
-
-  # Check the response
-  assert isinstance(response, ObservationResponse)
-
-  # Check the post request
-  api_mock.post.assert_called_once_with(payload={
-      "date": ObservationDate.LATEST,
-      "variable": {
-          "dcids": ["dc/Variable1", "dc/Variable2"]
-      },
-      "entity": {
-          "dcids": ["dc/EntityID"]
-      },
-      "select": ["date", "variable", "entity", "value"],
-  },
-                                        endpoint="observation",
-                                        all_pages=True,
-                                        next_token=None)
-
-
-def test_fetch_latest_observations_by_entity():
-  """Tests the fetch_latest_observations_by_entity method."""
-  api_mock = MagicMock(spec=API)
-  endpoint = ObservationEndpoint(api=api_mock)
-
-  response = endpoint.fetch_latest_observations_by_entity(
-      variable_dcids="dc/VariableID",
-      entity_dcids=["dc/Entity1", "dc/Entity2"],
-      select=["date", "variable", "entity", "value"],
-      filter_facet_ids="facet1")
-
-  # Check the response
-  assert isinstance(response, ObservationResponse)
-
-  # Check the post request
-  api_mock.post.assert_called_once_with(payload={
-      "date": ObservationDate.LATEST,
-      "variable": {
-          "dcids": ["dc/VariableID"]
-      },
-      "entity": {
-          "dcids": ["dc/Entity1", "dc/Entity2"]
-      },
-      "select": ["date", "variable", "entity", "value"],
-      "filter": {
-          "facet_ids": ["facet1"]
-      }
-  },
-                                        endpoint="observation",
-                                        all_pages=True,
-                                        next_token=None)
-
-
 def test_fetch_observations_by_entity_type():
   """Tests the fetch_observations_by_entity_type method."""
   api_mock = MagicMock(spec=API)

datacommons_client/tests/endpoints/test_response.py

@@ -488,7 +488,7 @@ def test_get_observations_as_records():
   response = ObservationResponse(byVariable=mock_data, facets=mock_facets)
 
   # Call the method and get the result
-  result = response.get_observations_as_records()
+  result = response.to_observation_records()
 
   # Expected output
   expected = [

datacommons_client/tests/test_client.py

@@ -96,7 +96,7 @@ def test_observations_dataframe_raises_error_when_invalid_entity_type_usage(
 def test_observations_dataframe_calls_fetch_observations_by_entity_type(
     mock_client):
   """Tests that fetch_observations_by_entity_type is called with correct parameters."""
-  mock_client.observation.fetch_observations_by_entity_type.return_value.get_observations_as_records.return_value = (
+  mock_client.observation.fetch_observations_by_entity_type.return_value.to_observation_records.return_value = (
       [])
 
   df = mock_client.observations_dataframe(
@@ -122,14 +122,14 @@ def test_observations_dataframe_calls_fetch_observations_by_entity_type(
 def test_observations_dataframe_calls_fetch_observations_by_entity(mock_client):
   """Tests that fetch_observations_by_entity is called with correct parameters."""
 
-  mock_client.observation.fetch_observations_by_entity.return_value.get_observations_as_records.return_value = (
+  mock_client.observation.fetch_observations_by_entity_dcid.return_value.to_observation_records.return_value = (
       [])
 
   df = mock_client.observations_dataframe(variable_dcids="var1",
                                           date="latest",
                                           entity_dcids=["entity1", "entity2"])
 
-  mock_client.observation.fetch_observations_by_entity.assert_called_once_with(
+  mock_client.observation.fetch_observations_by_entity_dcid.assert_called_once_with(
       date="latest",
       entity_dcids=["entity1", "entity2"],
       variable_dcids="var1",
@@ -142,7 +142,7 @@ def test_observations_dataframe_calls_fetch_observations_by_entity(mock_client):
 def test_observations_dataframe_returns_dataframe_with_expected_columns(
     mock_client):
   """Tests that the method returns a DataFrame with expected columns."""
-  mock_client.observation.fetch_observations_by_entity.return_value.get_observations_as_records.return_value = [
+  mock_client.observation.fetch_observations_by_entity_dcid.return_value.to_observation_records.return_value = [
       {
           "date": "2024",
           "entity": "entity1",
@@ -198,7 +198,7 @@ def test_find_filter_facet_ids_returns_none_when_no_filters(mock_client):
 
 def test_find_filter_facet_ids_returns_facet_ids(mock_client):
   """Tests that _find_filter_facet_ids correctly returns facet IDs when filters are provided."""
-  mock_client.observation.fetch_observations_by_entity.return_value.find_matching_facet_id.side_effect = [
+  mock_client.observation.fetch_observations_by_entity_dcid.return_value.find_matching_facet_id.side_effect = [
       ["213"], ["3243"]
   ]
 
@@ -219,7 +219,7 @@ def test_observations_dataframe_filters_by_facet_ids(mock_client):
   """Tests that observations_dataframe includes facet filtering when property_filters are used."""
   mock_client._find_filter_facet_ids = MagicMock(
       return_value=["facet_1", "facet_2"])
-  mock_client.observation.fetch_observations_by_entity.return_value.get_observations_as_records.return_value = []
+  mock_client.observation.fetch_observations_by_entity_dcid.return_value.to_observation_records.return_value = []
 
   df = mock_client.observations_dataframe(
       variable_dcids="var1",
@@ -228,7 +228,7 @@ def test_observations_dataframe_filters_by_facet_ids(mock_client):
       property_filters={"measurementMethod": "Census"},
   )
 
-  mock_client.observation.fetch_observations_by_entity.assert_called_once_with(
+  mock_client.observation.fetch_observations_by_entity_dcid.assert_called_once_with(
       variable_dcids="var1",
       date="2024",
       entity_dcids=["entity1"],