python-navitia-client 1.3.0__tar.gz → 2.0.2__tar.gz

{python_navitia_client-1.3.0 → python_navitia_client-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-navitia-client
-Version: 1.3.0
+Version: 2.0.2
 Summary: Python library to use with Navitia APIs
 Author-email: Jonathan Perron <jonathan@perron.bzh>
 License: MIT License
@@ -25,7 +25,12 @@ Dynamic: license-file
 
 This repository provides a unofficial Python wrapper to use [navitia.io APIs](https://doc.navitia.io).
 
-##  Pre-requisites
+> **⚠️ Version 2.0.0 Breaking Changes**
+>
+> Version 2.0.0 introduces breaking changes with the adoption of Request objects for all API methods.
+> If you're upgrading from v1.x, please see the [CHANGELOG](CHANGELOG.md) for the migration guide.
+
+##  Pre-requisites
 
 To use this library, you will need an access token from [navitia.io](https://navitia.io/tarifs/).
 
@@ -69,30 +74,89 @@ 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:
+Create an instance of the NavitiaClient class with your authentication token:
+
+```python
+from navitia_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 properties in the `NavitiaClient` class. You can find the mapping [here](docs/api_support/).
+
+#### Simple APIs (Coverage, Datasets, Contributors)
+
+For simple APIs like coverage, datasets, and contributors, you can call methods directly:
 
 ```python
-from navitia_client.client import NavitiaClient
-client = NavitiaClient(auth=<YOUR_TOKEN_HERE>)
+# Get coverage information
+regions = client.coverage.list_coverage_regions()
+
+# Get datasets for a region
+datasets, pagination = client.datasets.list_datasets(region_id="fr-idf")
 ```
 
-A base URL for Navitia IO is hardcoded and provided to NavitiaClient by default. It can be updated using the base_navitia_url parameter.
+#### APIs with Request Objects (Journeys, Places, Schedules, etc.)
 
-###  Access APIs data
+Most APIs now use Request objects for better type safety and maintainability:
 
-URLs are mapped as property in the class `NavitiaClient`. You can find the mapping [here](docs/api_support/).
+```python
+from navitia_client.entities.request.journey import JourneyRequest
+from datetime import datetime
+
+# Create a journey request
+request = JourneyRequest(
+    from_="stop_area:RAT:SA:GDLYO",
+    to_="stop_area:RAT:SA:CHDEG",
+    datetime_=datetime(2024, 6, 1, 8, 0),
+    count=5
+)
+
+# Get journeys
+journeys = client.journeys.list_journeys(request=request)
+```
 
-For example, if you want to have the list of datasets in a given region, use:
+Other examples:
 
 ```python
-datasets, pagination = client.datasets.list_datasets(region_id=<REGION_ID>)
+from navitia_client.entities.request.places_nearby import PlacesNearbyRequest
+
+# Places nearby with custom parameters
+request = PlacesNearbyRequest(
+    distance=1000,
+    type=["stop_area", "stop_point"],
+    count=20
+)
+places, pagination = client.places_nearby.list_objects_by_region_id_and_path(
+    region_id="fr-idf",
+    resource_path="lines/line:RAT:M1",
+    request=request
+)
 ```
 
 ### 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`.
+Several APIs are paginated, particularly the public transportation APIs. You can navigate through results using the `start_page` and `count` parameters in Request objects:
+
+```python
+from navitia_client.entities.request.journey import JourneyRequest
+
+# Request with pagination
+request = JourneyRequest(
+    from_="stop_area:RAT:SA:GDLYO",
+    to_="stop_area:RAT:SA:CHDEG",
+    start_page=0,  # First page
+    count=10       # 10 results per page
+)
+
+journeys = client.journeys.list_journeys(request=request)
+```
 
-An object `Pagination` will be provided by the impacted methods to help you navigating.
+A `Pagination` object is provided by paginated methods to help you navigate through results.
 
 ### Tips
 

{python_navitia_client-1.3.0 → python_navitia_client-2.0.2}/README.md

@@ -6,7 +6,12 @@
 
 This repository provides a unofficial Python wrapper to use [navitia.io APIs](https://doc.navitia.io).
 
-##  Pre-requisites
+> **⚠️ Version 2.0.0 Breaking Changes**
+>
+> Version 2.0.0 introduces breaking changes with the adoption of Request objects for all API methods.
+> If you're upgrading from v1.x, please see the [CHANGELOG](CHANGELOG.md) for the migration guide.
+
+##  Pre-requisites
 
 To use this library, you will need an access token from [navitia.io](https://navitia.io/tarifs/).
 
@@ -50,30 +55,89 @@ 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:
+Create an instance of the NavitiaClient class with your authentication token:
+
+```python
+from navitia_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 properties in the `NavitiaClient` class. You can find the mapping [here](docs/api_support/).
+
+#### Simple APIs (Coverage, Datasets, Contributors)
+
+For simple APIs like coverage, datasets, and contributors, you can call methods directly:
 
 ```python
-from navitia_client.client import NavitiaClient
-client = NavitiaClient(auth=<YOUR_TOKEN_HERE>)
+# Get coverage information
+regions = client.coverage.list_coverage_regions()
+
+# Get datasets for a region
+datasets, pagination = client.datasets.list_datasets(region_id="fr-idf")
 ```
 
-A base URL for Navitia IO is hardcoded and provided to NavitiaClient by default. It can be updated using the base_navitia_url parameter.
+#### APIs with Request Objects (Journeys, Places, Schedules, etc.)
 
-###  Access APIs data
+Most APIs now use Request objects for better type safety and maintainability:
 
-URLs are mapped as property in the class `NavitiaClient`. You can find the mapping [here](docs/api_support/).
+```python
+from navitia_client.entities.request.journey import JourneyRequest
+from datetime import datetime
+
+# Create a journey request
+request = JourneyRequest(
+    from_="stop_area:RAT:SA:GDLYO",
+    to_="stop_area:RAT:SA:CHDEG",
+    datetime_=datetime(2024, 6, 1, 8, 0),
+    count=5
+)
+
+# Get journeys
+journeys = client.journeys.list_journeys(request=request)
+```
 
-For example, if you want to have the list of datasets in a given region, use:
+Other examples:
 
 ```python
-datasets, pagination = client.datasets.list_datasets(region_id=<REGION_ID>)
+from navitia_client.entities.request.places_nearby import PlacesNearbyRequest
+
+# Places nearby with custom parameters
+request = PlacesNearbyRequest(
+    distance=1000,
+    type=["stop_area", "stop_point"],
+    count=20
+)
+places, pagination = client.places_nearby.list_objects_by_region_id_and_path(
+    region_id="fr-idf",
+    resource_path="lines/line:RAT:M1",
+    request=request
+)
 ```
 
 ### 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`.
+Several APIs are paginated, particularly the public transportation APIs. You can navigate through results using the `start_page` and `count` parameters in Request objects:
+
+```python
+from navitia_client.entities.request.journey import JourneyRequest
+
+# Request with pagination
+request = JourneyRequest(
+    from_="stop_area:RAT:SA:GDLYO",
+    to_="stop_area:RAT:SA:CHDEG",
+    start_page=0,  # First page
+    count=10       # 10 results per page
+)
+
+journeys = client.journeys.list_journeys(request=request)
+```
 
-An object `Pagination` will be provided by the impacted methods to help you navigating.
+A `Pagination` object is provided by paginated methods to help you navigate through results.
 
 ### Tips
 

python_navitia_client-2.0.2/navitia_client/__init__.py

@@ -0,0 +1,3 @@
+# ruff: noqa: F401
+
+from .client import NavitiaClient

python_navitia_client-2.0.2/navitia_client/client/__init__.py

@@ -0,0 +1,3 @@
+# ruff: noqa: F401
+
+from .navitia_client import NavitiaClient

python_navitia_client-2.0.2/navitia_client/client/apis/arrival_apis.py

@@ -0,0 +1,95 @@
+from typing import Any, Sequence, Tuple
+from navitia_client.client.apis.api_base_client import ApiBaseClient
+from navitia_client.entities.request.arrival import ArrivalRequest
+from navitia_client.entities.response import Pagination
+from navitia_client.entities.response.arrival import Arrival
+
+
+class ArrivalApiClient(ApiBaseClient):
+    """Client class to interact with the Navitia API for fetching arrival information.
+
+    See https://doc.navitia.io/#arrivals
+    """
+
+    @staticmethod
+    def _get_arrival_objects_from_response(
+        response: Any,
+    ) -> Sequence[Arrival]:
+        """Convert raw response data into a list of Arrival objects.
+
+        Args:
+            response: The raw response data from the API containing arrivals' information.
+
+        Returns:
+            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]:
+        """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))
+        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,
+        request: ArrivalRequest,
+    ) -> Tuple[Sequence[Arrival], Pagination]:
+        """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:
+            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}/arrivals"
+        )
+
+        return self._get_arrivals(request_url, request.to_filters())
+
+    def list_arrivals_by_coordinates(
+        self,
+        region_lon: float,
+        region_lat: float,
+        lon: float,
+        lat: float,
+        request: ArrivalRequest,
+    ) -> 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
+        request_url = f"{self.base_navitia_url}/coverage/{region_lon};{region_lat}/coords/{lon};{lat}/arrivals"
+
+        return self._get_arrivals(request_url, request.to_filters())

python_navitia_client-2.0.2/navitia_client/client/apis/contributors_apis.py

@@ -0,0 +1,76 @@
+from typing import Any, Sequence, Tuple
+
+from navitia_client.client.apis.api_base_client import ApiBaseClient
+from navitia_client.entities.request.contributor import ContributorRequest
+from navitia_client.entities.response.contributor import Contributor
+from navitia_client.entities.response import Pagination
+
+
+class ContributorsApiClient(ApiBaseClient):
+    """Client class to interact with the Navitia API for fetching contributors.
+
+    See https://doc.navitia.io/#contributors
+    """
+
+    @staticmethod
+    def _get_contributors_from_response(
+        raw_contributors_response: Any,
+    ) -> Sequence[Contributor]:
+        """Convert raw response data into a list of Contributor objects.
+
+        Args:
+            raw_contributors_response: The raw response data from the API containing contributors' information.
+
+        Returns:
+            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, request: ContributorRequest
+    ) -> Tuple[Sequence[Contributor], Pagination]:
+        """Retrieve a list of contributors for a specific region.
+
+        Args:
+            region_id: The identifier of the region to fetch contributors from.
+            request: The request object containing query parameters.
+
+        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"
+        results = self.get_navitia_api(
+            url + self._generate_filter_query(request.to_filters())
+        )
+        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, request: ContributorRequest
+    ) -> Tuple[Sequence[Contributor], Pagination]:
+        """Retrieve a list of contributors for a specific dataset in a region.
+
+        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:
+            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}"
+        results = self.get_navitia_api(
+            url + self._generate_filter_query(request.to_filters())
+        )
+        raw_results = results.json()["contributors"]
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return ContributorsApiClient._get_contributors_from_response(
+            raw_results
+        ), pagination

python_navitia_client-2.0.2/navitia_client/client/apis/coverage_apis.py

@@ -0,0 +1,91 @@
+from typing import Any, Sequence, Tuple
+
+from navitia_client.client.apis.api_base_client import ApiBaseClient
+from navitia_client.entities.request.coverage import CoverageRequest
+from navitia_client.entities.response.administrative_region import Region
+from navitia_client.entities.response import Pagination
+
+
+class CoverageApiClient(ApiBaseClient):
+    """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]:
+        """Convert raw response data into a list of Region objects.
+
+        Args:
+            raw_regions_response: The raw response data from the API containing regions' information.
+
+        Returns:
+            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, request: CoverageRequest
+    ) -> Tuple[Sequence[Region], Pagination]:
+        """Retrieve a list of covered areas from the Navitia API.
+
+        Args:
+            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"
+        results = self.get_navitia_api(
+            url + self._generate_filter_query(request.to_filters())
+        )
+        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, request: CoverageRequest
+    ) -> 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}"
+        results = self.get_navitia_api(
+            url + self._generate_filter_query(request.to_filters())
+        )
+        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, request: CoverageRequest
+    ) -> 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}"
+        results = self.get_navitia_api(
+            url + self._generate_filter_query(request.to_filters())
+        )
+        result_regions = results.json()["regions"]
+        regions = CoverageApiClient._get_regions_from_response(result_regions)
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return regions, pagination

python_navitia_client-2.0.2/navitia_client/client/apis/datasets_apis.py

@@ -0,0 +1,74 @@
+from typing import Any, Sequence, Tuple
+
+from navitia_client.client.apis.api_base_client import ApiBaseClient
+from navitia_client.entities.request.dataset import DatasetRequest
+from navitia_client.entities.response.dataset import Dataset
+from navitia_client.entities.response import Pagination
+
+
+class DatasetsApiClient(ApiBaseClient):
+    """Client class to interact with the Navitia API for fetching dataset information.
+
+    See https://doc.navitia.io/#datasets
+    """
+
+    @staticmethod
+    def _get_datasets_from_response(raw_datasets_response: Any) -> Sequence[Dataset]:
+        """Convert raw response data into a list of Dataset objects.
+
+        Args:
+            raw_datasets_response: The raw response data from the API containing datasets' information.
+
+        Returns:
+            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, request: DatasetRequest
+    ) -> Tuple[Sequence[Dataset], Pagination]:
+        """Retrieve a list of datasets for a specified region from the Navitia API.
+
+        Args:
+            region_id: The identifier of the region to fetch datasets from.
+            request: The request object containing query parameters.
+
+        Returns:
+            A tuple containing a list of Dataset objects and a Pagination object for managing result pages.
+        """
+        url = f"{self.base_navitia_url}/coverage/{region_id}/datasets"
+        results = self.get_navitia_api(
+            url + self._generate_filter_query(request.to_filters())
+        )
+        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, request: DatasetRequest
+    ) -> Tuple[Sequence[Dataset], Pagination]:
+        """Retrieve information about a specific dataset by its ID within a region.
+
+        Args:
+            region_id: The identifier of the region to fetch the dataset from.
+            dataset_id: The identifier of the dataset to fetch.
+            request: The request object containing query parameters.
+
+        Returns:
+            A tuple containing a list of Dataset objects and a Pagination object for managing result pages.
+        """
+        url = f"{self.base_navitia_url}/coverage/{region_id}/datasets/{dataset_id}"
+        results = self.get_navitia_api(
+            url + self._generate_filter_query(request.to_filters())
+        )
+        raw_results = results.json()["datasets"]
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return DatasetsApiClient._get_datasets_from_response(raw_results), pagination

python_navitia_client-2.0.2/navitia_client/client/apis/departure_apis.py

@@ -0,0 +1,93 @@
+from typing import Any, Sequence, Tuple
+from navitia_client.client.apis.api_base_client import ApiBaseClient
+from navitia_client.entities.request.departure import DepartureRequest
+from navitia_client.entities.response import Pagination
+from navitia_client.entities.response.departure import Departure
+
+
+class DepartureApiClient(ApiBaseClient):
+    """Client for interacting with the Navitia API to retrieve departure schedules.
+
+    See https://doc.navitia.io/#departures
+    """
+
+    @staticmethod
+    def _get_departure_objects_from_response(
+        response: Any,
+    ) -> Sequence[Departure]:
+        """Convert raw response data into a list of Departure objects.
+
+        Args:
+            response: The raw response data from the API containing departures' information.
+
+        Returns:
+            A list of Departure objects created from the raw response data.
+        """
+        departures = []
+        for departure_data in response:
+            departures.append(Departure.from_payload(departure_data))
+
+        return departures
+
+    def _get_departures(
+        self, url: str, filters: dict
+    ) -> Tuple[Sequence[Departure], Pagination]:
+        """Fetch departures from the Navitia API based on the provided URL and filters.
+
+        Args:
+            url: The URL to fetch departures from.
+            filters: A dictionary of filters to apply to the query.
+
+        Returns:
+            A tuple containing a list of Departure objects and a Pagination object for managing result pages.
+        """
+        results = self.get_navitia_api(url + self._generate_filter_query(filters))
+        raw_results = results.json()["departures"]
+        pagination = Pagination.from_payload(results.json()["pagination"])
+        return self._get_departure_objects_from_response(raw_results), pagination
+
+    def list_departures_by_region_id_and_path(
+        self,
+        region_id: str,
+        resource_path: str,
+        request: DepartureRequest,
+    ) -> Tuple[Sequence[Departure], Pagination]:
+        """Retrieve a list of departures for a specified region and resource path.
+
+        Args:
+            region_id: The identifier of the region to fetch departures from.
+            resource_path: The resource path to fetch departures for.
+            request: The request object containing query parameters.
+
+        Returns:
+            A tuple containing a list of Departure objects and a Pagination object for managing result pages.
+        """
+        request_url = (
+            f"{self.base_navitia_url}/coverage/{region_id}/{resource_path}/departures"
+        )
+
+        return self._get_departures(request_url, request.to_filters())
+
+    def list_departures_by_coordinates(
+        self,
+        region_lon: float,
+        region_lat: float,
+        lon: float,
+        lat: float,
+        request: DepartureRequest,
+    ) -> Tuple[Sequence[Departure], Pagination]:
+        """Retrieve a list of departures for a specified region and coordinates.
+
+        Args:
+            region_lon: The longitude of the region.
+            region_lat: The latitude of the region.
+            lon: The longitude of the specific location.
+            lat: The latitude of the specific location.
+            request: The request object containing query parameters.
+
+        Returns:
+            A tuple containing a list of Departure objects and a Pagination object for managing result pages.
+        """
+        request_url = f"{self.base_navitia_url}/coverage/{region_lon};{region_lat}/coords/{lon};{lat}/departures"
+
+        return self._get_departures(request_url, request.to_filters())