python-navitia-client 1.1.0__py3-none-any.whl

navitia_client/client/apis/api_base_client.py

@@ -0,0 +1,50 @@
+from typing import Any
+from requests import Response, Session  # type: ignore
+
+from navitia_client.client.exceptions import (
+    NavitiaAccessTokenMissingError,
+    NavitiaForbiddenAccessError,
+    NavitiaNotFoundError,
+    NavitiaUnknownObjectError,
+    NavitiaUnableToParseError,
+)
+
+
+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()
+        self.session.headers.update({"Authorization": auth_token})
+
+    @staticmethod
+    def _check_response_for_exception(response: Response) -> Response:
+        json_payload = response.json()
+        if "error" in json_payload:
+            error_message = json_payload["error"]["message"]
+            match json_payload["error"]["id"]:
+                case "unable_to_parse":
+                    raise NavitiaUnableToParseError(error_message)
+                case "unknown_object":
+                    raise NavitiaUnknownObjectError(error_message)
+                case "no_solution":
+                    raise NavitiaNotFoundError(error_message)
+
+        if "message" in json_payload:
+            error_message = json_payload["message"]
+            if "no token" in error_message:
+                raise NavitiaAccessTokenMissingError(error_message)
+            if " either read-protected or not readable" in error_message:
+                raise NavitiaForbiddenAccessError(error_message)
+
+        return response
+
+    @staticmethod
+    def _generate_filter_query(filters: dict[str, Any]) -> str:
+        """Generate query string regarding provided filters"""
+        filter_query = "&".join([f"{key}={value}" for key, value in filters.items()])
+        return "?" + filter_query if filter_query else ""
+
+    def get_navitia_api(self, endpoint: str) -> Response:
+        return self._check_response_for_exception(self.session.get(endpoint))

navitia_client/client/apis/arrival_apis.py

@@ -0,0 +1,191 @@
+from datetime import datetime
+from typing import Any, Optional, Sequence, Tuple
+from navitia_client.client.apis.api_base_client import ApiBaseClient
+from navitia_client.entities.pagination import Pagination
+from navitia_client.entities.arrival import Arrival
+
+
+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_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_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_arrival_objects_from_response(raw_results), pagination
+
+    def list_arrivals_by_region_id_and_path(
+        self,
+        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.
+
+        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 = {
+            "from_datetime": from_datetime,
+            "duration": duration,
+            "depth": depth,
+            "disable_geojson": disable_geojson,
+            "forbidden_uris[]": forbidden_uris,
+            "data_freshness": data_freshness,
+            "direction_type": direction_type,
+        }
+
+        return self._get_arrivals(request_url, filters)
+
+    def list_arrivals_by_coordinates(
+        self,
+        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.
+
+        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"
+
+        filters = {
+            "from_datetime": from_datetime,
+            "duration": duration,
+            "depth": depth,
+            "disable_geojson": disable_geojson,
+            "forbidden_uris[]": forbidden_uris,
+            "data_freshness": data_freshness,
+            "direction_type": direction_type,
+        }
+
+        return self._get_arrivals(request_url, filters)

navitia_client/client/apis/contributors_apis.py

@@ -0,0 +1,107 @@
+from typing import Any, Sequence, Tuple
+
+from navitia_client.client.apis.api_base_client import ApiBaseClient
+from navitia_client.entities.contributor import Contributor
+from navitia_client.entities.pagination import Pagination
+
+
+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))
+
+        return contributors
+
+    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}"
+        )
+        raw_results = results.json()["contributors"]
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return ContributorsApiClient._get_contributors_from_response(
+            raw_results
+        ), pagination
+
+    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}"
+        )
+        raw_results = results.json()["contributors"]
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return ContributorsApiClient._get_contributors_from_response(
+            raw_results
+        ), pagination

navitia_client/client/apis/coverage_apis.py

@@ -0,0 +1,131 @@
+from typing import Any, Sequence, Tuple
+
+from navitia_client.client.apis.api_base_client import ApiBaseClient
+from navitia_client.entities.administrative_region import Region
+from navitia_client.entities.pagination import Pagination
+
+
+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))
+        return regions
+
+    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}"
+        )
+        result_regions = results.json()["regions"]
+        regions = CoverageApiClient._get_regions_from_response(result_regions)
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return regions, pagination
+
+    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}"
+        )
+        result_regions = results.json()["regions"]
+        regions = CoverageApiClient._get_regions_from_response(result_regions)
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return regions, pagination
+
+    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}"
+        )
+        result_regions = results.json()["regions"]
+        regions = CoverageApiClient._get_regions_from_response(result_regions)
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return regions, pagination

navitia_client/client/apis/datasets_apis.py

@@ -0,0 +1,105 @@
+from typing import Any, Sequence, Tuple
+
+from navitia_client.client.apis.api_base_client import ApiBaseClient
+from navitia_client.entities.dataset import Dataset
+from navitia_client.entities.pagination import Pagination
+
+
+class DatasetsApiClient(ApiBaseClient):
+    """
+    A client class to interact with the Navitia API for fetching dataset information.
+
+    See https://doc.navitia.io/#datasets
+
+    Methods
+    -------
+    _get_datasets_from_response(raw_datasets_response: Any) -> Sequence[Dataset]
+        A static method to transform raw API response data into a list of Dataset objects.
+
+    list_datasets(region_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Dataset], Pagination]
+        Retrieves a list of datasets for a specified region from the Navitia API.
+
+    get_dataset_by_id(region_id: str, dataset_id: str, start_page: int = 0, count: int = 25) -> Tuple[Sequence[Dataset], Pagination]
+        Retrieves information about a specific dataset by its ID within a region.
+    """
+
+    @staticmethod
+    def _get_datasets_from_response(raw_datasets_response: Any) -> Sequence[Dataset]:
+        """
+        Converts raw response data into a list of Dataset objects.
+
+        Parameters
+        ----------
+        raw_datasets_response : Any
+            The raw response data from the API containing datasets' information.
+
+        Returns
+        -------
+        Sequence[Dataset]
+            A list of Dataset objects created from the raw response data.
+        """
+        datasets = []
+        for dataset in raw_datasets_response:
+            dataset_contributor = dataset.get("contributor")
+            if not dataset_contributor:
+                continue
+
+            datasets.append(Dataset.from_payload(dataset))
+
+        return datasets
+
+    def list_datasets(
+        self, region_id: str, start_page: int = 0, count: int = 25
+    ) -> Tuple[Sequence[Dataset], Pagination]:
+        """
+        Retrieves a list of datasets for a specified region from the Navitia API.
+
+        Parameters
+        ----------
+        region_id : str
+            The identifier of the region to fetch datasets from.
+        start_page : int, optional
+            The starting page for pagination (default is 0).
+        count : int, optional
+            The number of datasets to fetch per page (default is 25).
+
+        Returns
+        -------
+        Tuple[Sequence[Dataset], Pagination]
+            A tuple containing a list of Dataset objects and a Pagination object for managing result pages.
+        """
+        results = self.get_navitia_api(
+            f"{self.base_navitia_url}/coverage/{region_id}/datasets?start_page={start_page}&count={count}"
+        )
+        raw_results = results.json()["datasets"]
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return DatasetsApiClient._get_datasets_from_response(raw_results), pagination
+
+    def get_dataset_by_id(
+        self, region_id: str, dataset_id: str, start_page: int = 0, count: int = 25
+    ) -> Tuple[Sequence[Dataset], Pagination]:
+        """
+        Retrieves information about a specific dataset by its ID within a region.
+
+        Parameters
+        ----------
+        region_id : str
+            The identifier of the region to fetch the dataset from.
+        dataset_id : str
+            The identifier of the dataset to fetch.
+        start_page : int, optional
+            The starting page for pagination (default is 0).
+        count : int, optional
+            The number of datasets to fetch per page (default is 25).
+
+        Returns
+        -------
+        Tuple[Sequence[Dataset], Pagination]
+            A tuple containing a list of Dataset objects and a Pagination object for managing result pages.
+        """
+        results = self.get_navitia_api(
+            f"{self.base_navitia_url}/coverage/{region_id}/datasets/{dataset_id}?start_page={start_page}&count={count}"
+        )
+        raw_results = results.json()["datasets"]
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return DatasetsApiClient._get_datasets_from_response(raw_results), pagination