python-navitia-client 1.1.0__tar.gz

python_navitia_client-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jonathan Perron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_navitia_client-1.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.1
+Name: python-navitia-client
+Version: 1.1.0
+Summary: Python library to use with Navitia APIs
+Author-email: Jonathan Perron <jonathan@perron.bzh>
+License: MIT License
+Project-URL: Source, https://github.com/jonperron/python-navitia-client
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+
+# navitia-client
+
+This repository provides a unofficial Python wrapper to use [navitia.io APIs](https://doc.navitia.io).
+
+##  Pre-requisites
+
+To use this library, you will need an access token from [navitia.io](https://navitia.io/tarifs/).
+
+##  API support
+
+The library supports the following [APIs](https://doc.navitia.io/#api-catalog):
+
+| API                                       | Supported ? | Comment                                      |
+| ----------------------------------------- | ----------- | -------------------------------------------- |
+| Coverage                                  | ✅           |                                              |
+| Datasets                                  | ✅           |                                              |
+| Contributors                              | ✅           |                                              |
+| Inverted geocoding                        | ✅           |                                              |
+| Public transportation Objects exploration | ✅           |                                              |
+| Autocomplete on Public Transport objects  | ✅           |                                              |
+| Autocomplete on geographical objects      | ✅           |                                              |
+| Places nearby                             | ✅           |                                              |
+| Journeys                                  | ✅           |                                              |
+| Isochrones                                | ✅           | Beta endpoint according to API response      |
+| Route Schedules                           | ✅           |                                              |
+| Stop Schedules                            | ✅           |                                              |
+| Terminus Schedules                        | ✅           |                                              |
+| Departures                                | ✅           |                                              |
+| Arrivals                                  | ✅           |                                              |
+| Line reports                              | ✅           | Beta endpoint according to API response      |
+| Traffic reports                           | ✅           | Beta endpoint according to API response      |
+| Equipment reports                         | ❌           | Beta service, not available to all providers |
+
+##  Installation
+
+The package is not yet available on pip.
+
+For development purpose, you can install it using
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+To use this library, you need an authentication token provided by Navitia.io.
+
+### Create client instance
+
+Once created, you will create an instance of the NavitiaClient class with the following:
+
+```python
+from navitia_client.client import NavitiaClient
+client = NavitiaClient(auth=<YOUR_TOKEN_HERE>)
+```
+
+A base URL for Navitia IO is hardcoded and provided to NavitiaClient by default. It can be updated using the base_navitia_url parameter.
+
+###  Access APIs data
+
+URLs are mapped as property in the class `NavitiaClient`. You can find the mapping [here](docs/api_support/).
+
+For example, if you want to have the list of datasets in a given region, use:
+
+```python
+datasets, pagination = client.datasets.list_datasets(region_id=<REGION_ID>)
+```
+
+### Pagination
+
+A couple of APIs are paginated, in particular the public transporations APIs.. In such case, you can navigate in the response using the parameters `start_page` and `count`.
+
+An object `Pagination` will be provided by the impacted methods to help you navigatig.
+
+### Tips
+
+Few tips on how to use the Navitia APIs are available [here](docs/few_tips.md)
+
+##  Dependencies
+
+* Python >= 3.10
+* requests>=2.31
+
+Additional dependencies are described in the [pyproject.toml file](pyproject.toml).
+
+##  Contributing
+
+You are free to contribute to the repo. Please read [Contributing.md](docs/CONTRIBUTING.md).
+
+##  Additional questions
+
+* Are you affiliated with Navitia ?
+No. This is an unofficial wrapper for the Navitia.io APIs.
+
+* Is this client asynchronous ?
+No, and it is not planned to. If you want to add async support, feel free to contribute.
+
+* Is this client production ready ?
+Yes and no. For my own purpose, it is, but I cannot guarantee that everything will behave well. If you spot a bug, please open an issue in the repo.

python_navitia_client-1.1.0/README.md

@@ -0,0 +1,99 @@
+# navitia-client
+
+This repository provides a unofficial Python wrapper to use [navitia.io APIs](https://doc.navitia.io).
+
+##  Pre-requisites
+
+To use this library, you will need an access token from [navitia.io](https://navitia.io/tarifs/).
+
+##  API support
+
+The library supports the following [APIs](https://doc.navitia.io/#api-catalog):
+
+| API                                       | Supported ? | Comment                                      |
+| ----------------------------------------- | ----------- | -------------------------------------------- |
+| Coverage                                  | ✅           |                                              |
+| Datasets                                  | ✅           |                                              |
+| Contributors                              | ✅           |                                              |
+| Inverted geocoding                        | ✅           |                                              |
+| Public transportation Objects exploration | ✅           |                                              |
+| Autocomplete on Public Transport objects  | ✅           |                                              |
+| Autocomplete on geographical objects      | ✅           |                                              |
+| Places nearby                             | ✅           |                                              |
+| Journeys                                  | ✅           |                                              |
+| Isochrones                                | ✅           | Beta endpoint according to API response      |
+| Route Schedules                           | ✅           |                                              |
+| Stop Schedules                            | ✅           |                                              |
+| Terminus Schedules                        | ✅           |                                              |
+| Departures                                | ✅           |                                              |
+| Arrivals                                  | ✅           |                                              |
+| Line reports                              | ✅           | Beta endpoint according to API response      |
+| Traffic reports                           | ✅           | Beta endpoint according to API response      |
+| Equipment reports                         | ❌           | Beta service, not available to all providers |
+
+##  Installation
+
+The package is not yet available on pip.
+
+For development purpose, you can install it using
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+To use this library, you need an authentication token provided by Navitia.io.
+
+### Create client instance
+
+Once created, you will create an instance of the NavitiaClient class with the following:
+
+```python
+from navitia_client.client import NavitiaClient
+client = NavitiaClient(auth=<YOUR_TOKEN_HERE>)
+```
+
+A base URL for Navitia IO is hardcoded and provided to NavitiaClient by default. It can be updated using the base_navitia_url parameter.
+
+###  Access APIs data
+
+URLs are mapped as property in the class `NavitiaClient`. You can find the mapping [here](docs/api_support/).
+
+For example, if you want to have the list of datasets in a given region, use:
+
+```python
+datasets, pagination = client.datasets.list_datasets(region_id=<REGION_ID>)
+```
+
+### Pagination
+
+A couple of APIs are paginated, in particular the public transporations APIs.. In such case, you can navigate in the response using the parameters `start_page` and `count`.
+
+An object `Pagination` will be provided by the impacted methods to help you navigatig.
+
+### Tips
+
+Few tips on how to use the Navitia APIs are available [here](docs/few_tips.md)
+
+##  Dependencies
+
+* Python >= 3.10
+* requests>=2.31
+
+Additional dependencies are described in the [pyproject.toml file](pyproject.toml).
+
+##  Contributing
+
+You are free to contribute to the repo. Please read [Contributing.md](docs/CONTRIBUTING.md).
+
+##  Additional questions
+
+* Are you affiliated with Navitia ?
+No. This is an unofficial wrapper for the Navitia.io APIs.
+
+* Is this client asynchronous ?
+No, and it is not planned to. If you want to add async support, feel free to contribute.
+
+* Is this client production ready ?
+Yes and no. For my own purpose, it is, but I cannot guarantee that everything will behave well. If you spot a bug, please open an issue in the repo.

python_navitia_client-1.1.0/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))

python_navitia_client-1.1.0/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)

python_navitia_client-1.1.0/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