feat(documentation): add documentation

README.md

@@ -59,7 +59,7 @@ Additional dependencies are described in the [pyproject.toml file](pyproject.tom
 
 ##  Contributing
 
-You are free to contribute to the repo. Please read [Contributing.md](CONTRIBUTING.md).
+You are free to contribute to the repo. Please read [Contributing.md](docs/CONTRIBUTING.md).
 
 ##  Additional questions
 

navitia_client/client/apis/api_base_client.py

@@ -11,6 +11,8 @@
 
 
 class ApiBaseClient:
+    """Common base client for API calls."""
+
     def __init__(self, auth_token: str, base_navitia_url: str) -> None:
         self.base_navitia_url = base_navitia_url
         self.session = Session()

navitia_client/client/apis/arrival_apis.py

@@ -6,23 +6,72 @@
 
 
 class ArrivalApiClient(ApiBaseClient):
+    """
+    A 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_departure_objects_from_response(
+    def _get_arrival_objects_from_response(
         response: Any,
     ) -> Sequence[Arrival]:
+        """
+        Converts raw response data into a list of Arrival objects.
+
+        Parameters
+        ----------
+        response : Any
+            The raw response data from the API containing arrivals' information.
+
+        Returns
+        -------
+        Sequence[Arrival]
+            A list of Arrival objects created from the raw response data.
+        """
+
         arrivals = []
         for arrival_data in response:
             arrivals.append(Arrival.from_payload(arrival_data))
 
         return arrivals
 
-    def _get_departures(
+    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]
+            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))
         raw_results = results.json()["arrivals"]
         pagination = Pagination.from_payload(results.json()["pagination"])
-        return self._get_departure_objects_from_response(raw_results), pagination
+        return self._get_arrival_objects_from_response(raw_results), pagination
 
     def list_arrivals_by_region_id_and_path(
         self,
@@ -36,6 +85,35 @@ def list_arrivals_by_region_id_and_path(
         disable_geojson: bool = False,
         direction_type: str = "all",
     ) -> 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.
+        from_datetime : datetime, optional
+            The starting datetime for fetching arrivals (default is current datetime).
+        duration : int, optional
+            The duration in seconds for which to fetch arrivals (default is 86400 seconds).
+        depth : int, optional
+            The depth of the search (default is 1).
+        forbidden_uris : Optional[Sequence[str]], optional
+            A list of URIs to exclude from the search (default is None).
+        data_freshness : str, optional
+            The freshness of the data to fetch, either "realtime" or "base_schedule" (default is "realtime").
+        disable_geojson : bool, optional
+            Whether to disable geoJSON in the response (default is False).
+        direction_type : str, optional
+            The direction type of the arrivals to fetch, e.g., "all", "forward", "backward" (default is "all").
+
+        Returns
+        -------
+        Tuple[Sequence[Arrival], Pagination]
+            A tuple containing a list of Arrival objects and a Pagination object for managing result pages.
+        """
         request_url = f"{self.base_navitia_url}/coverage/{region_id}/{resource_path}/terminus_schedules"
 
         filters = {
@@ -48,7 +126,7 @@ def list_arrivals_by_region_id_and_path(
             "direction_type": direction_type,
         }
 
-        return self._get_departures(request_url, filters)
+        return self._get_arrivals(request_url, filters)
 
     def list_arrivals_by_coordinates(
         self,
@@ -64,6 +142,39 @@ def list_arrivals_by_coordinates(
         disable_geojson: bool = False,
         direction_type: str = "all",
     ) -> 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.
+        from_datetime : datetime, optional
+            The starting datetime for fetching arrivals (default is current datetime).
+        duration : int, optional
+            The duration in seconds for which to fetch arrivals (default is 86400 seconds).
+        depth : int, optional
+            The depth of the search (default is 1).
+        forbidden_uris : Optional[Sequence[str]], optional
+            A list of URIs to exclude from the search (default is None).
+        data_freshness : str, optional
+            The freshness of the data to fetch, either "realtime" or "base_schedule" (default is "realtime").
+        disable_geojson : bool, optional
+            Whether to disable geoJSON in the response (default is False).
+        direction_type : str, optional
+            The direction type of the arrivals to fetch, e.g., "all", "forward", "backward" (default is "all").
+
+        Returns
+        -------
+        Tuple[Sequence[Arrival], Pagination]
+            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
         request_url = f"{self.base_navitia_url}/coverage/{region_lon};{region_lat}/coords/{lon};{lat}/terminus_schedules"
 
@@ -77,4 +188,4 @@ def list_arrivals_by_coordinates(
             "direction_type": direction_type,
         }
 
-        return self._get_departures(request_url, filters)
+        return self._get_arrivals(request_url, filters)

navitia_client/client/apis/contributors_apis.py

@@ -6,10 +6,40 @@
 
 
 class ContributorsApiClient(ApiBaseClient):
+    """
+    A client class to interact with the Navitia API for fetching contributors APIs.
+
+    See https://doc.navitia.io/#contributors
+
+    Methods
+    -------
+    _get_contributors_from_response(raw_contributors_response: Any) -> Sequence[Contributor]
+        A static method to transform raw API response data into a list of Contributor objects.
+
+    list_contributors(region_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Contributor], Pagination]
+        Retrieves a list of contributors for a specified region from the Navitia API.
+
+    get_contributor_on_dataset(region_id: str, dataset_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Contributor], Pagination]
+        Retrieves a list of contributors for a specified dataset in a region from the Navitia API.
+    """
+
     @staticmethod
     def _get_contributors_from_response(
         raw_contributors_response: Any,
     ) -> Sequence[Contributor]:
+        """
+        Converts raw response data into a list of Contributor objects.
+
+        Parameters
+        ----------
+        raw_contributors_response : Any
+            The raw response data from the API containing contributors' information.
+
+        Returns
+        -------
+        Sequence[Contributor]
+            A list of Contributor objects created from the raw response data.
+        """
         contributors = []
         for contributor_data in raw_contributors_response:
             contributors.append(Contributor.from_payload(contributor_data))
@@ -19,6 +49,23 @@ def _get_contributors_from_response(
     def list_contributors(
         self, region_id: str, start_page: int = 0, count: int = 25
     ) -> Tuple[Sequence[Contributor], Pagination]:
+        """
+        Retrieves a list of contributors for a specific region.
+
+        Parameters
+        ----------
+        region_id : str
+            The identifier of the region to fetch contributors from.
+        start_page : int, optional
+            The starting page for pagination (default is 0).
+        count : int, optional
+            The number of contributors to fetch per page (default is 25).
+
+        Returns
+        -------
+        Tuple[Sequence[Contributor], Pagination]
+            A tuple containing a list of Contributor objects and a Pagination object for managing result pages.
+        """
         results = self.get_navitia_api(
             f"{self.base_navitia_url}/coverage/{region_id}/contributors?start_page={start_page}&count={count}"
         )
@@ -31,6 +78,25 @@ def list_contributors(
     def get_contributor_on_dataset(
         self, region_id: str, dataset_id: str, start_page: int = 0, count: int = 25
     ) -> Tuple[Sequence[Contributor], Pagination]:
+        """
+        Retrieves 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.
+        start_page : int, optional
+            The starting page for pagination (default is 0).
+        count : int, optional
+            The number of contributors to fetch per page (default is 25).
+
+        Returns
+        -------
+        Tuple[Sequence[Contributor], Pagination]
+            A tuple containing a list of Contributor objects and a Pagination object for managing result pages.
+        """
         results = self.get_navitia_api(
             f"{self.base_navitia_url}/coverage/{region_id}/contributors/{dataset_id}?start_page={start_page}&count={count}"
         )

navitia_client/client/apis/coverage_apis.py

@@ -6,8 +6,41 @@
 
 
 class CoverageApiClient(ApiBaseClient):
+    """
+    A client class to interact with the Navitia API for fetching coverage area information.
+
+    See https://doc.navitia.io/#coverage
+
+    Methods
+    -------
+    _get_regions_from_response(raw_regions_response: Any) -> Sequence[Region]
+        A static method to transform raw API response data into a list of Region objects.
+
+    list_covered_areas(start_page: int = 0, count: int = 25) -> Tuple[Sequence[Region], Pagination]
+        Retrieves a list of covered areas from the Navitia API.
+
+    get_coverage_by_region_id(region_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Region], Pagination]
+        Retrieves information about a specific region by its ID.
+
+    get_coverage_by_region_coordinates_and_coordinates(lon: float, lat: float, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Region], Pagination]
+        Retrieves information about a region based on coordinates.
+    """
+
     @staticmethod
     def _get_regions_from_response(raw_regions_response: Any) -> Sequence[Region]:
+        """
+        Converts raw response data into a list of Region objects.
+
+        Parameters
+        ----------
+        raw_regions_response : Any
+            The raw response data from the API containing regions' information.
+
+        Returns
+        -------
+        Sequence[Region]
+            A list of Region objects created from the raw response data.
+        """
         regions = []
         for region_data in raw_regions_response:
             regions.append(Region.from_payload(region_data))
@@ -16,6 +49,21 @@ def _get_regions_from_response(raw_regions_response: Any) -> Sequence[Region]:
     def list_covered_areas(
         self, start_page: int = 0, count: int = 25
     ) -> Tuple[Sequence[Region], Pagination]:
+        """
+        Retrieves a list of covered areas from the Navitia API.
+
+        Parameters
+        ----------
+        start_page : int, optional
+            The starting page for pagination (default is 0).
+        count : int, optional
+            The number of regions to fetch per page (default is 25).
+
+        Returns
+        -------
+        Tuple[Sequence[Region], Pagination]
+            A tuple containing a list of Region objects and a Pagination object for managing result pages.
+        """
         results = self.get_navitia_api(
             f"{self.base_navitia_url}/coverage?start_page={start_page}&count={count}"
         )
@@ -24,9 +72,26 @@ def list_covered_areas(
         pagination = Pagination.from_payload(results.json()["pagination"])
         return regions, pagination
 
-    def get_region_by_id(
+    def get_coverage_by_region_id(
         self, region_id: str, start_page: int = 0, count: int = 25
     ) -> 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.
+        start_page : int, optional
+            The starting page for pagination (default is 0).
+        count : int, optional
+            The number of regions to fetch per page (default is 25).
+
+        Returns
+        -------
+        Tuple[Sequence[Region], Pagination]
+            A tuple containing a list of Region objects and a Pagination object for managing result pages.
+        """
         results = self.get_navitia_api(
             f"{self.base_navitia_url}/coverage/{region_id}?start_page={start_page}&count={count}"
         )
@@ -35,9 +100,28 @@ def get_region_by_id(
         pagination = Pagination.from_payload(results.json()["pagination"])
         return regions, pagination
 
-    def get_region_by_coordinates(
+    def get_coverage_by_region_coordinates_and_coordinates(
         self, lon: float, lat: float, start_page: int = 0, count: int = 25
     ) -> 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.
+        start_page : int, optional
+            The starting page for pagination (default is 0).
+        count : int, optional
+            The number of regions to fetch per page (default is 25).
+
+        Returns
+        -------
+        Tuple[Sequence[Region], Pagination]
+            A tuple containing a list of Region objects and a Pagination object for managing result pages.
+        """
         results = self.get_navitia_api(
             f"{self.base_navitia_url}/coverage/{lon};{lat}?start_page={start_page}&count={count}"
         )