Add endpoint-specific Endpoint classes (#213)

Introduced several changes to the package:
- Introduces the specific Endpoint classes and tests
- Removes the Sparql endpoint
- Adds support for `next_token` and to fetch `all_pages` (as default)
- Improves docstrings and makes other smaller tweaks

Author: jm-rivera

datacommons_client/endpoints/base.py

@@ -9,10 +9,10 @@
 class API:
   """Represents a configured API interface to the Data Commons API.
 
-    This class handles environment setup, resolving the base URL, building headers,
-    or optionally using a fully qualified URL directly. It can be used standalone
-    to interact with the API or in combination with Endpoint classes.
-    """
+  This class handles environment setup, resolving the base URL, building headers,
+  or optionally using a fully qualified URL directly. It can be used standalone
+  to interact with the API or in combination with Endpoint classes.
+  """
 
   def __init__(
       self,
@@ -21,19 +21,19 @@ def __init__(
       url: Optional[str] = None,
   ):
     """
-        Initializes the API instance.
-
-        Args:
-            api_key: The API key for authentication. Defaults to None.
-            dc_instance: The Data Commons instance domain. Ignored if `url` is provided.
-                         Defaults to 'datacommons.org' if both `url` and `dc_instance` are None.
-            url: A fully qualified URL for the base API. This may be useful if more granular control
-                of the API is required (for local development, for example). If provided, dc_instance`
-                 should not be provided.
-
-        Raises:
-            ValueError: If both `dc_instance` and `url` are provided.
-        """
+    Initializes the API instance.
+
+    Args:
+        api_key: The API key for authentication. Defaults to None.
+        dc_instance: The Data Commons instance domain. Ignored if `url` is provided.
+                     Defaults to 'datacommons.org' if both `url` and `dc_instance` are None.
+        url: A fully qualified URL for the base API. This may be useful if more granular control
+            of the API is required (for local development, for example). If provided, dc_instance`
+             should not be provided.
+
+    Raises:
+        ValueError: If both `dc_instance` and `url` are provided.
+    """
     if dc_instance and url:
       raise ValueError("Cannot provide both `dc_instance` and `url`.")
 
@@ -52,81 +52,105 @@ def __init__(
   def __repr__(self) -> str:
     """Returns a readable representation of the API object.
 
-        Indicates the base URL and if it's authenticated.
+    Indicates the base URL and if it's authenticated.
 
-        Returns:
-            str: A string representation of the API object.
-        """
+    Returns:
+        str: A string representation of the API object.
+    """
     has_auth = " (Authenticated)" if "X-API-Key" in self.headers else ""
     return f"<API at {self.base_url}{has_auth}>"
 
-  def post(self,
-           payload: dict[str, Any],
-           endpoint: Optional[str] = None) -> Dict[str, Any]:
+  def post(
+      self,
+      payload: dict[str, Any],
+      endpoint: Optional[str] = None,
+      *,
+      all_pages: bool = True,
+      next_token: Optional[str] = None,
+  ) -> Dict[str, Any]:
     """Makes a POST request using the configured API environment.
 
-        If `endpoint` is provided, it will be appended to the base_url. Otherwise,
-        it will just POST to the base URL.
+    If `endpoint` is provided, it will be appended to the base_url. Otherwise,
+    it will just POST to the base URL.
 
-        Args:
-            payload: The JSON payload for the POST request.
-            endpoint: An optional endpoint path to append to the base URL.
+    Args:
+        payload: The JSON payload for the POST request.
+        endpoint: An optional endpoint path to append to the base URL.
+        all_pages: If True, fetch all pages of the response. If False, fetch only the first page.
+            Defaults to True. Set to False to only fetch the first page. In that case, a
+            `next_token` key in the response will indicate if more pages are available.
+            That token can be used to fetch the next page.
 
-        Returns:
-            A dictionary containing the merged response data.
+    Returns:
+        A dictionary containing the merged response data.
 
-        Raises:
-            ValueError: If the payload is not a valid dictionary.
-        """
+    Raises:
+        ValueError: If the payload is not a valid dictionary.
+    """
     if not isinstance(payload, dict):
       raise ValueError("Payload must be a dictionary.")
 
     url = (self.base_url if endpoint is None else f"{self.base_url}/{endpoint}")
-    return post_request(url=url, payload=payload, headers=self.headers)
+    return post_request(url=url,
+                        payload=payload,
+                        headers=self.headers,
+                        all_pages=all_pages,
+                        next_token=next_token)
 
 
 class Endpoint:
   """Represents a specific endpoint within the Data Commons API.
 
-    This class leverages an API instance to make requests. It does not
-    handle instance resolution or headers directly; that is delegated to the API instance.
+  This class leverages an API instance to make requests. It does not
+  handle instance resolution or headers directly; that is delegated to the API instance.
 
-    Attributes:
-        endpoint (str): The endpoint path (e.g., 'node').
-        api (API): The API instance providing configuration and the `post` method.
-    """
+  Attributes:
+      endpoint (str): The endpoint path (e.g., 'node').
+      api (API): The API instance providing configuration and the `post` method.
+  """
 
   def __init__(self, endpoint: str, api: API):
     """
-        Initializes the Endpoint instance.
+    Initializes the Endpoint instance.
 
-        Args:
-            endpoint: The endpoint path (e.g., 'node').
-            api: An API instance that provides the environment configuration.
-        """
+    Args:
+        endpoint: The endpoint path (e.g., 'node').
+        api: An API instance that provides the environment configuration.
+    """
     self.endpoint = endpoint
     self.api = api
 
   def __repr__(self) -> str:
     """Returns a readable representation of the Endpoint object.
 
-        Shows the endpoint and underlying API configuration.
+    Shows the endpoint and underlying API configuration.
 
-        Returns:
-            str: A string representation of the Endpoint object.
-        """
+    Returns:
+        str: A string representation of the Endpoint object.
+    """
     return f"<{self.endpoint.title()} Endpoint using {repr(self.api)}>"
 
-  def post(self, payload: dict[str, Any]) -> Dict[str, Any]:
+  def post(self,
+           payload: dict[str, Any],
+           all_pages: bool = True,
+           next_token: Optional[str] = None) -> Dict[str, Any]:
     """Makes a POST request to the specified endpoint using the API instance.
 
-        Args:
-            payload: The JSON payload for the POST request.
+    Args:
+        payload: The JSON payload for the POST request.
+        all_pages: If True, fetch all pages of the response. If False, fetch only the first page.
+            Defaults to True. Set to False to only fetch the first page. In that case, a
+            `next_token` key in the response will indicate if more pages are available.
+            That token can be used to fetch the next page.
+        next_token: Optionally, the token to fetch the next page of results. Defaults to None.
 
-        Returns:
-            A dictionary with the merged API response data.
+    Returns:
+        A dictionary with the merged API response data.
 
-        Raises:
-            ValueError: If the payload is not a valid dictionary.
-        """
-    return self.api.post(payload=payload, endpoint=self.endpoint)
+    Raises:
+        ValueError: If the payload is not a valid dictionary.
+    """
+    return self.api.post(payload=payload,
+                         endpoint=self.endpoint,
+                         all_pages=all_pages,
+                         next_token=next_token)

datacommons_client/endpoints/node.py

@@ -0,0 +1,182 @@
+from typing import Optional
+
+from datacommons_client.endpoints.base import API
+from datacommons_client.endpoints.base import Endpoint
+from datacommons_client.endpoints.payloads import NodeRequestPayload
+from datacommons_client.endpoints.payloads import \
+    normalize_properties_to_string
+from datacommons_client.endpoints.response import NodeResponse
+
+
+class NodeEndpoint(Endpoint):
+  """Initializes the NodeEndpoint with a given API configuration.
+
+    Args:
+        api (API): The API instance providing the environment configuration
+            (base URL, headers, authentication) to be used for requests.
+    """
+
+  def __init__(self, api: API):
+    """Initializes the NodeEndpoint with a given API configuration."""
+    super().__init__(endpoint="node", api=api)
+
+  def fetch(
+      self,
+      node_dcids: str | list[str],
+      expression: str | list[str],
+      *,
+      all_pages: bool = True,
+      next_token: Optional[str] = None,
+  ) -> NodeResponse:
+    """Fetches properties or arcs for given nodes and properties.
+
+        Args:
+            node_dcids (str | List[str]): The DCID(s) of the nodes to query.
+            expression (str | List[str]): The property or relation expression(s) to query.
+            all_pages: If True, fetch all pages of the response. If False, fetch only the first page.
+              Defaults to True. Set to False to only fetch the first page. In that case, a
+              `next_token` key in the response will indicate if more pages are available.
+              That token can be used to fetch the next page.
+            next_token: Optionally, the token to fetch the next page of results. Defaults to None.
+
+        Returns:
+            NodeResponse: The response object containing the queried data.
+
+        Example:
+            ```python
+            response = node_endpoint.fetch(
+                node_dcids=["geoId/06"],
+                expression="<-"
+            )
+            print(response.data)
+            ```
+        """
+
+    # Create the payload
+    payload = NodeRequestPayload(node_dcids=node_dcids,
+                                 expression=expression).to_dict
+
+    # Make the request and return the response.
+    return NodeResponse.from_json(
+        self.post(payload, all_pages=all_pages, next_token=next_token))
+
+  def fetch_property_labels(
+      self,
+      node_dcids: str | list[str],
+      out: bool = True,
+      *,
+      all_pages: bool = True,
+      next_token: Optional[str] = None,
+  ) -> NodeResponse:
+    """Fetches all property labels for the given nodes.
+
+        Args:
+            node_dcids (str | list[str]): The DCID(s) of the nodes to query.
+            out (bool): Whether to fetch outgoing properties (`->`). Defaults to True.
+            all_pages: If True, fetch all pages of the response. If False, fetch only the first page.
+              Defaults to True. Set to False to only fetch the first page. In that case, a
+              `next_token` key in the response will indicate if more pages are available.
+              That token can be used to fetch the next page.
+            next_token: Optionally, the token to fetch the next page of results. Defaults to None.
+
+        Returns:
+            NodeResponse: The response object containing the property labels.
+
+        Example:
+            ```python
+            response = node_endpoint.fetch_properties(node_dcids="geoId/06")
+            print(response.data)
+            ```
+        """
+    # Determine the direction of the properties.
+    expression = "->" if out else "<-"
+
+    # Make the request and return the response.
+    return self.fetch(node_dcids=node_dcids,
+                      expression=expression,
+                      all_pages=all_pages,
+                      next_token=next_token)
+
+  def fetch_property_values(
+      self,
+      node_dcids: str | list[str],
+      properties: str | list[str],
+      constraints: Optional[str] = None,
+      out: bool = True,
+      *,
+      all_pages: bool = True,
+      next_token: Optional[str] = None,
+  ) -> NodeResponse:
+    """Fetches the values of specific properties for given nodes.
+
+        Args:
+            node_dcids (str | List[str]): The DCID(s) of the nodes to query.
+            properties (str | List[str]): The property or relation expression(s) to query.
+            constraints (Optional[str]): Additional constraints for the query. Defaults to None.
+            out (bool): Whether to fetch outgoing properties. Defaults to True.
+            all_pages: If True, fetch all pages of the response. If False, fetch only the first page.
+              Defaults to True. Set to False to only fetch the first page. In that case, a
+              `next_token` key in the response will indicate if more pages are available.
+              That token can be used to fetch the next page.
+            next_token: Optionally, the token to fetch the next page of results. Defaults to None.
+
+
+        Returns:
+            NodeResponse: The response object containing the property values.
+
+        Example:
+            ```python
+            response = node_endpoint.fetch_property_values(
+                node_dcids=["geoId/06"],
+                properties="name",
+                out=True
+            )
+            print(response.data)
+            ```
+        """
+
+    # Normalize the input to a string (if it's a list), otherwise use the string as is.
+    properties = normalize_properties_to_string(properties)
+
+    # Construct the expression based on the direction and constraints.
+    direction = "->" if out else "<-"
+    expression = f"{direction}{properties}"
+    if constraints:
+      expression += f"{{{constraints}}}"
+
+    return self.fetch(node_dcids=node_dcids,
+                      expression=expression,
+                      all_pages=all_pages,
+                      next_token=next_token)
+
+  def fetch_all_classes(
+      self,
+      *,
+      all_pages: bool = True,
+      next_token: Optional[str] = None,
+  ) -> NodeResponse:
+    """Fetches all Classes available in the Data Commons knowledge graph.
+
+        Args:
+          all_pages: If True, fetch all pages of the response. If False, fetch only the first page.
+              Defaults to True. Set to False to only fetch the first page. In that case, a
+              `next_token` key in the response will indicate if more pages are available.
+              That token can be used to fetch the next page.
+          next_token: Optionally, the token to fetch the next page of results. Defaults to None.
+
+
+        Returns:
+            NodeResponse: The response object containing all statistical variables.
+
+        Example:
+            ```python
+            response = node_endpoint.fetch_all_classes()
+            print(response.data)
+            ```
+        """
+
+    return self.fetch_property_values(node_dcids="Class",
+                                      properties="typeOf",
+                                      out=False,
+                                      all_pages=all_pages,
+                                      next_token=next_token)