fix(api): use request objects in all api clients (#97)

Changelog
* Fix APIs missing usage of request objects
* Update documentation
* Fix tests

Author: jonperron

navitia_client/client/apis/arrival_apis.py

@@ -6,41 +6,21 @@
 
 
 class ArrivalApiClient(ApiBaseClient):
-    """
-    A client class to interact with the Navitia API for fetching arrival information.
+    """Client class to interact with the Navitia API for fetching arrival information.
 
     See https://doc.navitia.io/#arrivals
-
-    Methods
-    -------
-    _get_departure_objects_from_response(response: Any) -> Sequence[Arrival]
-        A static method to transform raw API response data into a list of Arrival objects.
-
-    _get_departures(url: str, filters: dict) -> Tuple[Sequence[Arrival], Pagination]
-        Internal method to fetch departures based on a given URL and filters.
-
-    list_arrivals_by_region_id_and_path(region_id: str, resource_path: str, from_datetime: datetime = datetime.now(), duration: int = 86400, depth: int = 1, forbidden_uris: Optional[Sequence[str]] = None, data_freshness: str = "realtime", disable_geojson: bool = False, direction_type: str = "all") -> Tuple[Sequence[Arrival], Pagination]
-        Retrieves a list of arrivals for a specific region and resource path.
-
-    list_arrivals_by_coordinates(region_lon: float, region_lat: float, lon: float, lat: float, from_datetime: datetime = datetime.now(), duration: int = 86400, depth: int = 1, forbidden_uris: Optional[Sequence[str]] = None, data_freshness: str = "realtime", disable_geojson: bool = False, direction_type: str = "all") -> Tuple[Sequence[Arrival], Pagination]
-        Retrieves a list of arrivals for specific coordinates.
     """
 
     @staticmethod
     def _get_arrival_objects_from_response(
         response: Any,
     ) -> Sequence[Arrival]:
-        """
-        Converts raw response data into a list of Arrival objects.
+        """Convert raw response data into a list of Arrival objects.
 
-        Parameters
-        ----------
-        response : Any
-            The raw response data from the API containing arrivals' information.
+        Args:
+            response: The raw response data from the API containing arrivals' information.
 
-        Returns
-        -------
-        Sequence[Arrival]
+        Returns:
             A list of Arrival objects created from the raw response data.
         """
 
@@ -53,19 +33,13 @@ def _get_arrival_objects_from_response(
     def _get_arrivals(
         self, url: str, filters: dict
     ) -> Tuple[Sequence[Arrival], Pagination]:
-        """
-        Internal method to fetch departures based on a given URL and filters.
-
-        Parameters
-        ----------
-        url : str
-            The URL for the API request.
-        filters : dict
-            The filters to apply to the API request.
-
-        Returns
-        -------
-        Tuple[Sequence[Arrival], Pagination]
+        """Fetch arrivals based on a given URL and filters.
+
+        Args:
+            url: The URL for the API request.
+            filters: The filters to apply to the API request.
+
+        Returns:
             A tuple containing a list of Arrival objects and a Pagination object for managing result pages.
         """
         results = self.get_navitia_api(url + self._generate_filter_query(filters))
@@ -79,20 +53,14 @@ def list_arrivals_by_region_id_and_path(
         resource_path: str,
         request: ArrivalRequest,
     ) -> Tuple[Sequence[Arrival], Pagination]:
-        """
-        Retrieves a list of arrivals for a specific region and resource path.
-
-        Parameters
-        ----------
-        region_id : str
-            The identifier of the region to fetch arrivals from.
-        resource_path : str
-            The resource path within the region to fetch arrivals for.
+        """Retrieve a list of arrivals for a specific region and resource path.
 
+        Args:
+            region_id: The identifier of the region to fetch arrivals from.
+            resource_path: The resource path within the region to fetch arrivals for.
+            request: The ArrivalRequest containing filters and parameters for the query.
 
-        Returns
-        -------
-        Tuple[Sequence[Arrival], Pagination]
+        Returns:
             A tuple containing a list of Arrival objects and a Pagination object for managing result pages.
         """
         request_url = (
@@ -109,23 +77,16 @@ def list_arrivals_by_coordinates(
         lat: float,
         request: ArrivalRequest,
     ) -> Tuple[Sequence[Arrival], Pagination]:
-        """
-        Retrieves a list of arrivals for specific coordinates.
-
-        Parameters
-        ----------
-        region_lon : float
-            The longitude of the region to fetch arrivals from.
-        region_lat : float
-            The latitude of the region to fetch arrivals from.
-        lon : float
-            The longitude of the specific location to fetch arrivals for.
-        lat : float
-            The latitude of the specific location to fetch arrivals for.
-
-        Returns
-        -------
-        Tuple[Sequence[Arrival], Pagination]
+        """Retrieve a list of arrivals for specific coordinates.
+
+        Args:
+            region_lon: The longitude of the region to fetch arrivals from.
+            region_lat: The latitude of the region to fetch arrivals from.
+            lon: The longitude of the specific location to fetch arrivals for.
+            lat: The latitude of the specific location to fetch arrivals for.
+            request: The ArrivalRequest containing filters and parameters for the query.
+
+        Returns:
             A tuple containing a list of Arrival objects and a Pagination object for managing result pages.
         """
         # List of objects near the resource, navitia guesses the region from coordinates

navitia_client/client/apis/contributors_apis.py

@@ -7,9 +7,7 @@
 
 
 class ContributorsApiClient(ApiBaseClient):
-    """
-    A client class to interact with the Navitia API for fetching contributors APIs.
-    Uses the ContributorRequest class to encapsulate query parameters.
+    """Client class to interact with the Navitia API for fetching contributors.
 
     See https://doc.navitia.io/#contributors
     """
@@ -18,17 +16,12 @@ class ContributorsApiClient(ApiBaseClient):
     def _get_contributors_from_response(
         raw_contributors_response: Any,
     ) -> Sequence[Contributor]:
-        """
-        Converts raw response data into a list of Contributor objects.
+        """Convert raw response data into a list of Contributor objects.
 
-        Parameters
-        ----------
-        raw_contributors_response : Any
-            The raw response data from the API containing contributors' information.
+        Args:
+            raw_contributors_response: The raw response data from the API containing contributors' information.
 
-        Returns
-        -------
-        Sequence[Contributor]
+        Returns:
             A list of Contributor objects created from the raw response data.
         """
         contributors = []
@@ -40,19 +33,13 @@ def _get_contributors_from_response(
     def list_contributors(
         self, region_id: str, request: ContributorRequest
     ) -> Tuple[Sequence[Contributor], Pagination]:
-        """
-        Retrieves a list of contributors for a specific region.
+        """Retrieve a list of contributors for a specific region.
 
-        Parameters
-        ----------
-        region_id : str
-            The identifier of the region to fetch contributors from.
-        request : ContributorRequest
-            The request object containing query parameters (count, start_page).
+        Args:
+            region_id: The identifier of the region to fetch contributors from.
+            request: The request object containing query parameters.
 
-        Returns
-        -------
-        Tuple[Sequence[Contributor], Pagination]
+        Returns:
             A tuple containing a list of Contributor objects and a Pagination object for managing result pages.
         """
         url = f"{self.base_navitia_url}/coverage/{region_id}/contributors"
@@ -68,21 +55,14 @@ def list_contributors(
     def get_contributor_on_dataset(
         self, region_id: str, dataset_id: str, request: ContributorRequest
     ) -> Tuple[Sequence[Contributor], Pagination]:
-        """
-        Retrieves a list of contributors for a specific dataset in a region.
+        """Retrieve a list of contributors for a specific dataset in a region.
 
-        Parameters
-        ----------
-        region_id : str
-            The identifier of the region to fetch contributors from.
-        dataset_id : str
-            The identifier of the dataset to fetch contributors for.
-        request : ContributorRequest
-            The request object containing query parameters (count, start_page).
+        Args:
+            region_id: The identifier of the region to fetch contributors from.
+            dataset_id: The identifier of the dataset to fetch contributors for.
+            request: The request object containing query parameters.
 
-        Returns
-        -------
-        Tuple[Sequence[Contributor], Pagination]
+        Returns:
             A tuple containing a list of Contributor objects and a Pagination object for managing result pages.
         """
         url = f"{self.base_navitia_url}/coverage/{region_id}/contributors/{dataset_id}"

navitia_client/client/apis/coverage_apis.py

@@ -7,26 +7,19 @@
 
 
 class CoverageApiClient(ApiBaseClient):
-    """
-    A client class to interact with the Navitia API for fetching coverage area information.
-    Uses the CoverageRequest class to encapsulate query parameters.
+    """Client class to interact with the Navitia API for fetching coverage area information.
 
     See https://doc.navitia.io/#coverage
     """
 
     @staticmethod
     def _get_regions_from_response(raw_regions_response: Any) -> Sequence[Region]:
-        """
-        Converts raw response data into a list of Region objects.
+        """Convert raw response data into a list of Region objects.
 
-        Parameters
-        ----------
-        raw_regions_response : Any
-            The raw response data from the API containing regions' information.
+        Args:
+            raw_regions_response: The raw response data from the API containing regions' information.
 
-        Returns
-        -------
-        Sequence[Region]
+        Returns:
             A list of Region objects created from the raw response data.
         """
         regions = []
@@ -37,17 +30,12 @@ def _get_regions_from_response(raw_regions_response: Any) -> Sequence[Region]:
     def list_covered_areas(
         self, request: CoverageRequest
     ) -> Tuple[Sequence[Region], Pagination]:
-        """
-        Retrieves a list of covered areas from the Navitia API.
+        """Retrieve a list of covered areas from the Navitia API.
 
-        Parameters
-        ----------
-        request : CoverageRequest
-            The request object containing query parameters (count, start_page).
+        Args:
+            request: The request object containing query parameters.
 
-        Returns
-        -------
-        Tuple[Sequence[Region], Pagination]
+        Returns:
             A tuple containing a list of Region objects and a Pagination object for managing result pages.
         """
         url = f"{self.base_navitia_url}/coverage"
@@ -62,19 +50,13 @@ def list_covered_areas(
     def get_coverage_by_region_id(
         self, region_id: str, request: CoverageRequest
     ) -> Tuple[Sequence[Region], Pagination]:
-        """
-        Retrieves information about a specific region by its ID.
-
-        Parameters
-        ----------
-        region_id : str
-            The identifier of the region to fetch information about.
-        request : CoverageRequest
-            The request object containing query parameters (count, start_page).
-
-        Returns
-        -------
-        Tuple[Sequence[Region], Pagination]
+        """Retrieve information about a specific region by its ID.
+
+        Args:
+            region_id: The identifier of the region to fetch information about.
+            request: The request object containing query parameters.
+
+        Returns:
             A tuple containing a list of Region objects and a Pagination object for managing result pages.
         """
         url = f"{self.base_navitia_url}/coverage/{region_id}"
@@ -89,21 +71,14 @@ def get_coverage_by_region_id(
     def get_coverage_by_region_coordinates_and_coordinates(
         self, lon: float, lat: float, request: CoverageRequest
     ) -> Tuple[Sequence[Region], Pagination]:
-        """
-        Retrieves information about a region based on coordinates.
-
-        Parameters
-        ----------
-        lon : float
-            The longitude of the location to fetch information about.
-        lat : float
-            The latitude of the location to fetch information about.
-        request : CoverageRequest
-            The request object containing query parameters (count, start_page).
-
-        Returns
-        -------
-        Tuple[Sequence[Region], Pagination]
+        """Retrieve information about a region based on coordinates.
+
+        Args:
+            lon: The longitude of the location to fetch information about.
+            lat: The latitude of the location to fetch information about.
+            request: The request object containing query parameters.
+
+        Returns:
             A tuple containing a list of Region objects and a Pagination object for managing result pages.
         """
         url = f"{self.base_navitia_url}/coverage/{lon};{lat}"