python-openpublictransport 0.1.17__tar.gz → 0.2.0__tar.gz

{python_openpublictransport-0.1.17 → python_openpublictransport-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-openpublictransport
-Version: 0.1.17
+Version: 0.2.0
 Summary: Python library for public transport APIs (EFA, OTP2, TRIAS, FPTF, HAFAS, GTFS-RT)
 License: MIT
 Requires-Python: >=3.11

{python_openpublictransport-0.1.17 → python_openpublictransport-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-openpublictransport"
-version = "0.1.17"
+version = "0.2.0"
 description = "Python library for public transport APIs (EFA, OTP2, TRIAS, FPTF, HAFAS, GTFS-RT)"
 readme = "README.md"
 license = { text = "MIT" }

{python_openpublictransport-0.1.17 → python_openpublictransport-0.2.0}/src/openpublictransport/__init__.py

@@ -1,6 +1,13 @@
 """python-openpublictransport — public transport API library."""
 
-from .exceptions import AuthenticationError
+from .exceptions import (
+    ApiConnectionError,
+    ApiError,
+    ApiResponseError,
+    ApiTimeoutError,
+    AuthenticationError,
+    OpenPublicTransportError,
+)
 from .providers import get_all_provider_ids, get_provider, get_provider_class, register_provider
 
 __all__ = [
@@ -8,5 +15,10 @@ __all__ = [
     "get_provider_class",
     "get_all_provider_ids",
     "register_provider",
+    "OpenPublicTransportError",
+    "ApiError",
+    "ApiConnectionError",
+    "ApiTimeoutError",
+    "ApiResponseError",
     "AuthenticationError",
 ]

python_openpublictransport-0.2.0/src/openpublictransport/exceptions.py

@@ -0,0 +1,81 @@
+"""Exceptions for python-openpublictransport.
+
+Every failure raised by this library derives from :class:`OpenPublicTransportError`.
+Callers can therefore catch the whole family with a single ``except`` clause, or
+discriminate on the concrete type to tell a server-side outage apart from a
+network problem or an empty result.
+
+Empty results are *not* errors: ``search_stops()`` returns ``[]`` and
+``fetch_departures()`` returns ``None`` only when the provider genuinely had no
+data to give.
+"""
+
+from typing import Optional
+
+
+class OpenPublicTransportError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class ApiError(OpenPublicTransportError):
+    """Raised when a provider API answers with a non-200 HTTP status.
+
+    The HTTP status is available as :attr:`status` so callers can report it to
+    the user instead of silently treating the failure as "no results".
+    :attr:`body` holds a truncated copy of the error response, which is often
+    the only place a provider explains what it disliked.
+    """
+
+    def __init__(
+        self,
+        provider: str,
+        status: int,
+        message: Optional[str] = None,
+        body: Optional[str] = None,
+    ) -> None:
+        self.provider = provider
+        self.status = status
+        self.body = body
+        if message is None:
+            message = f"{provider}: API returned HTTP {status}"
+            if body:
+                message = f"{message} — {body}"
+        super().__init__(message)
+
+
+class ApiConnectionError(OpenPublicTransportError):
+    """Raised when the provider API cannot be reached (DNS, TCP or TLS failure)."""
+
+
+class ApiTimeoutError(ApiConnectionError):
+    """Raised when the provider API does not answer within the timeout."""
+
+
+class ApiResponseError(OpenPublicTransportError):
+    """Raised when a 200 response carries a payload that cannot be used.
+
+    Covers undecodable JSON/XML as well as a well-formed body whose shape does
+    not match what the provider protocol requires.
+    """
+
+
+class AuthenticationError(ApiError):
+    """Raised when API authentication fails (HTTP 401 or 403).
+
+    Signals that the configured API key is invalid or expired.
+    Callers should prompt the user to re-enter credentials rather than retrying.
+    """
+
+    def __init__(
+        self,
+        provider: str,
+        status: int = 401,
+        message: Optional[str] = None,
+        body: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            provider,
+            status,
+            message or f"{provider}: authentication failed (HTTP {status}) — check the API key",
+            body=body,
+        )

python_openpublictransport-0.2.0/src/openpublictransport/providers/base.py

@@ -0,0 +1,199 @@
+"""Base class for all public transport providers."""
+
+import asyncio
+import logging
+
+import aiohttp
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+from zoneinfo import ZoneInfo
+
+from ..exceptions import (
+    ApiConnectionError,
+    ApiError,
+    ApiResponseError,
+    ApiTimeoutError,
+    AuthenticationError,
+)
+from ..models import UnifiedDeparture
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class BaseProvider(ABC):
+    """Abstract base class for all public transport providers."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        api_key: Optional[str] = None,
+        api_key_secondary: Optional[str] = None,
+        custom_url: Optional[str] = None,
+    ):
+        self.session = session
+        self.api_key = api_key
+        self.api_key_secondary = api_key_secondary
+        self.custom_url = custom_url
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        retries: int = 1,
+        timeout: int = 10,
+        response_format: str = "json",
+        json_content_type: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Perform an HTTP request, returning the decoded payload or raising.
+
+        This is the single place where HTTP status codes are turned into
+        exceptions. Providers must not swallow the result: an empty list or
+        ``None`` returned by a provider means "no data", never "request failed".
+
+        Args:
+            method: ``"get"`` or ``"post"``.
+            url: Absolute request URL.
+            retries: Total number of attempts. Only 5xx responses, timeouts and
+                connection errors are retried, with ``2 ** attempt`` backoff.
+                4xx responses fail immediately — retrying a bad key or a wrong
+                endpoint only delays the error the user needs to see.
+            timeout: Total request timeout in seconds.
+            response_format: ``"json"``, ``"text"`` or ``"bytes"``.
+            json_content_type: Passed to ``response.json()``. The default
+                ``None`` disables aiohttp's strict content-type check, because
+                some EFA deployments send RapidJSON with an XML header (#79).
+            **kwargs: Forwarded to the aiohttp session method (``params``,
+                ``headers``, ``data``, ``json``, ...).
+
+        Returns:
+            The decoded payload, or ``None`` for an empty 204 response.
+
+        Raises:
+            AuthenticationError: HTTP 401 or 403. Never retried.
+            ApiError: Any other non-2xx status, carrying ``.status``.
+            ApiTimeoutError: The request timed out on every attempt.
+            ApiConnectionError: The provider could not be reached.
+            ApiResponseError: A 2xx response whose body could not be decoded.
+        """
+        request = getattr(self.session, method.lower())
+        name = self.provider_name
+        last_error: Optional[Exception] = None
+
+        for attempt in range(1, retries + 1):
+            try:
+                async with request(url, timeout=aiohttp.ClientTimeout(total=timeout), **kwargs) as response:
+                    status = response.status
+
+                    if status in (401, 403):
+                        raise AuthenticationError(name, status, body=await self._error_body(response))
+
+                    if status >= 500:
+                        last_error = ApiError(name, status, body=await self._error_body(response))
+                    elif status >= 400:
+                        raise ApiError(name, status, body=await self._error_body(response))
+                    elif status == 204:
+                        return None
+                    else:
+                        return await self._decode_response(response, response_format, json_content_type)
+
+            except asyncio.TimeoutError as exc:
+                last_error = ApiTimeoutError(f"{name}: request timed out after {timeout}s")
+                last_error.__cause__ = exc
+            except aiohttp.ClientError as exc:
+                last_error = ApiConnectionError(f"{name}: connection failed ({exc})")
+                last_error.__cause__ = exc
+
+            if attempt < retries:
+                _LOGGER.debug("%s: attempt %s/%s failed (%s), retrying", name, attempt, retries, last_error)
+                await asyncio.sleep(2**attempt)
+
+        raise last_error if last_error else ApiConnectionError(f"{name}: request failed")
+
+    @staticmethod
+    async def _error_body(response: Any, limit: int = 300) -> Optional[str]:
+        """Return a truncated error body, or None if it cannot be read.
+
+        Providers often explain a rejection only in the body (a SOAP fault, a
+        JSON ``errorText``), so it is worth carrying into the exception.
+        """
+        try:
+            text = (await response.text() or "").strip()
+        except Exception:  # noqa: BLE001 — diagnostics must never mask the real error
+            return None
+        if not text:
+            return None
+        return text[:limit] + ("…" if len(text) > limit else "")
+
+    async def _decode_response(
+        self,
+        response: Any,
+        response_format: str,
+        json_content_type: Optional[str],
+    ) -> Any:
+        """Decode a successful response, raising ApiResponseError on bad payloads."""
+        try:
+            if response_format == "json":
+                return await response.json(content_type=json_content_type)
+            if response_format == "text":
+                return await response.text()
+            if response_format == "bytes":
+                return await response.read()
+        except (ValueError, aiohttp.ClientError) as exc:
+            raise ApiResponseError(f"{self.provider_name}: could not decode response ({exc})") from exc
+
+        raise ValueError(f"Unknown response_format: {response_format}")
+
+    @property
+    @abstractmethod
+    def provider_id(self) -> str:
+        """Return the provider identifier (e.g., 'vrr', 'kvv')."""
+        pass
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """Return the human-readable provider name."""
+        pass
+
+    @property
+    def requires_api_key(self) -> bool:
+        """Return True if this provider requires an API key."""
+        return False
+
+    @abstractmethod
+    async def fetch_departures(
+        self,
+        station_id: Optional[str],
+        place_dm: str,
+        name_dm: str,
+        departures_limit: int,
+    ) -> Optional[Dict[str, Any]]:
+        """Fetch departure data from the provider's API."""
+        pass
+
+    @abstractmethod
+    def parse_departure(
+        self, stop: Dict[str, Any], tz: Union[ZoneInfo, Any], now: datetime
+    ) -> Optional[UnifiedDeparture]:
+        """Parse a single departure from the provider's API response."""
+        pass
+
+    @abstractmethod
+    async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
+        """Search for stops/stations."""
+        pass
+
+    def get_timezone(self) -> str:
+        """Return the timezone for this provider (e.g., 'Europe/Berlin')."""
+        return "Europe/Berlin"
+
+    def get_transport_type_mapping(self) -> Dict[Any, str]:
+        """Return the transportation type mapping for this provider."""
+        return {}
+
+    async def cleanup(self) -> None:
+        """Cleanup provider resources."""
+        pass

{python_openpublictransport-0.1.17 → python_openpublictransport-0.2.0}/src/openpublictransport/providers/efa_base.py

@@ -1,6 +1,5 @@
 """Base class for EFA (Electronic Fahrplan-Auskunft) providers."""
 
-import asyncio
 import logging
 from abc import abstractmethod
 from datetime import datetime
@@ -8,8 +7,7 @@ from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 from urllib.parse import quote
 from zoneinfo import ZoneInfo
 
-import aiohttp
-
+from ..exceptions import ApiResponseError
 from ..models import UnifiedDeparture
 from ..parsers import parse_departure_generic
 from .base import BaseProvider
@@ -148,47 +146,18 @@ class EFABaseProvider(BaseProvider):
 
         headers = {"User-Agent": f"Mozilla/5.0 (compatible; OpenPublicTransport {self.provider_id.upper()})"}
 
-        max_retries = 3
-        for attempt in range(1, max_retries + 1):
-            try:
-                async with self.session.get(url, headers=headers, timeout=aiohttp.ClientTimeout(total=10)) as response:
-                    if response.status == 200:
-                        try:
-                            # content_type=None: some deployments (VGN) send RapidJSON
-                            # payloads with a "text/xml;;charset=utf-8" header (issue #79).
-                            json_data = await response.json(content_type=None)
-                            if not isinstance(json_data, dict):
-                                _LOGGER.warning("%s API returned non-dict response: %s", name, type(json_data))
-                                return None
-
-                            if "stopEvents" not in json_data:
-                                _LOGGER.debug("%s API response missing 'stopEvents' field", name)
-                                return {"stopEvents": []}
-
-                            return json_data
-                        except (ValueError, aiohttp.ContentTypeError) as e:
-                            _LOGGER.warning("%s API returned invalid JSON: %s", name, e)
-                            return None
-                        except Exception as e:
-                            _LOGGER.warning("%s API JSON parsing failed: %s", name, e)
-                            return None
-                    elif response.status == 404:
-                        _LOGGER.warning("%s API endpoint not found (404)", name)
-                        return None
-                    elif response.status >= 500:
-                        _LOGGER.warning("%s API server error (status %s)", name, response.status)
-                    else:
-                        _LOGGER.warning("%s API returned status %s", name, response.status)
-
-            except asyncio.TimeoutError:
-                _LOGGER.warning("%s API timeout on attempt %s", name, attempt)
-            except Exception as e:
-                _LOGGER.warning("%s attempt %s failed: %s", name, attempt, e)
-
-            if attempt < max_retries:
-                await asyncio.sleep(2**attempt)
-
-        return None
+        # content_type=None: some deployments (VGN) send RapidJSON payloads with
+        # a "text/xml;;charset=utf-8" header (issue #79).
+        json_data = await self._request("get", url, headers=headers, retries=3, timeout=10)
+
+        if not isinstance(json_data, dict):
+            raise ApiResponseError(f"{name}: API returned {type(json_data).__name__} instead of an object")
+
+        if "stopEvents" not in json_data:
+            _LOGGER.debug("%s API response missing 'stopEvents' field", name)
+            return {"stopEvents": []}
+
+        return json_data
 
     def parse_departure(
         self, stop: Dict[str, Any], tz: Union[ZoneInfo, Any], now: datetime
@@ -249,47 +218,31 @@ class EFABaseProvider(BaseProvider):
         url = f"{self.sf_base_url}?{params}"
         name = self.provider_name
 
-        try:
-            async with self.session.get(url, timeout=aiohttp.ClientTimeout(total=10)) as response:
-                if response.status == 200:
-                    try:
-                        # content_type=None: some deployments (VGN) send RapidJSON
-                        # payloads with a "text/xml;;charset=utf-8" header (issue #79).
-                        data = await response.json(content_type=None)
-                    except (ValueError, aiohttp.ContentTypeError) as e:
-                        _LOGGER.error("Invalid JSON response from %s API: %s", name, e)
-                        return []
-
-                    if not isinstance(data, dict):
-                        _LOGGER.error("%s API returned non-dict response: %s", name, type(data))
-                        return []
-
-                    locations = data.get("locations", [])
-                    results = []
-
-                    for location in locations:
-                        if not isinstance(location, dict):
-                            continue
-
-                        disassembled_name = location.get("disassembledName", "")
-                        place = ""
-                        if "," in disassembled_name:
-                            parts = disassembled_name.rsplit(",", 1)
-                            place = parts[-1].strip() if len(parts) > 1 else ""
-
-                        results.append(
-                            {
-                                "id": location.get("id", ""),
-                                "name": location.get("name", ""),
-                                "place": place,
-                                "area_type": location.get("type", ""),
-                            }
-                        )
-
-                    return results
-                else:
-                    _LOGGER.error("%s API returned status %s", name, response.status)
-        except Exception as e:
-            _LOGGER.error("Error searching %s stops: %s", name, e, exc_info=True)
-
-        return []
+        # content_type=None: some deployments (VGN) send RapidJSON payloads with
+        # a "text/xml;;charset=utf-8" header (issue #79).
+        data = await self._request("get", url, timeout=10)
+
+        if not isinstance(data, dict):
+            raise ApiResponseError(f"{name}: API returned {type(data).__name__} instead of an object")
+
+        results = []
+        for location in data.get("locations", []):
+            if not isinstance(location, dict):
+                continue
+
+            disassembled_name = location.get("disassembledName", "")
+            place = ""
+            if "," in disassembled_name:
+                parts = disassembled_name.rsplit(",", 1)
+                place = parts[-1].strip() if len(parts) > 1 else ""
+
+            results.append(
+                {
+                    "id": location.get("id", ""),
+                    "name": location.get("name", ""),
+                    "place": place,
+                    "area_type": location.get("type", ""),
+                }
+            )
+
+        return results

{python_openpublictransport-0.1.17 → python_openpublictransport-0.2.0}/src/openpublictransport/providers/entur.py

@@ -16,8 +16,6 @@ from typing import Any, Dict, List, Optional, Union
 from urllib.parse import quote
 from zoneinfo import ZoneInfo
 
-import aiohttp
-
 from ..const import PROVIDER_ENTUR_NO
 from ..models import UnifiedDeparture
 from .base import BaseProvider
@@ -84,18 +82,7 @@ class EnturProvider(BaseProvider):
             f"{GEOCODER_URL}?text={quote(search_term, safe='')}"
             "&size=12&lang=en&layers=venue"
         )
-        try:
-            async with self.session.get(
-                url, headers=self._headers(), timeout=aiohttp.ClientTimeout(total=10)
-            ) as response:
-                if response.status != 200:
-                    _LOGGER.error("Entur geocoder returned status %s", response.status)
-                    return []
-                data = await response.json()
-        except Exception as e:  # noqa: BLE001
-            _LOGGER.error("Error searching Entur stops: %s", e)
-            return []
-
+        data = await self._request("get", url, headers=self._headers(), timeout=10)
         return self._stops_from_geocoder(data)
 
     @staticmethod
@@ -135,23 +122,13 @@ class EnturProvider(BaseProvider):
             "query": _DEPARTURES_QUERY,
             "variables": {"id": station_id, "n": departures_limit},
         }
-        try:
-            async with self.session.post(
-                JOURNEY_PLANNER_URL,
-                json=payload,
-                headers=self._headers(),
-                timeout=aiohttp.ClientTimeout(total=15),
-            ) as response:
-                if response.status != 200:
-                    _LOGGER.warning("Entur journey planner returned status %s", response.status)
-                    return None
-                data = await response.json()
-        except aiohttp.ClientError as e:
-            _LOGGER.warning("Entur journey planner request failed: %s", e)
-            return None
-        except Exception as e:  # noqa: BLE001
-            _LOGGER.warning("Entur journey planner error: %s", e)
-            return None
+        data = await self._request(
+            "post",
+            JOURNEY_PLANNER_URL,
+            json=payload,
+            headers=self._headers(),
+            timeout=15,
+        )
 
         stop_place = (data.get("data") or {}).get("stopPlace")
         if not stop_place:

{python_openpublictransport-0.1.17 → python_openpublictransport-0.2.0}/src/openpublictransport/providers/fptf_base.py

@@ -6,8 +6,7 @@ from typing import Any, Dict, List, Optional, Union
 from urllib.parse import quote
 from zoneinfo import ZoneInfo
 
-import aiohttp
-
+from ..exceptions import ApiResponseError
 from ..models import UnifiedDeparture
 from .base import BaseProvider
 
@@ -45,22 +44,13 @@ class FPTFBaseProvider(BaseProvider):
 
         url = f"{self.API_BASE}/stops/{station_id}/departures?results={departures_limit}&duration=120"
 
-        try:
-            async with self.session.get(url, timeout=aiohttp.ClientTimeout(total=15)) as response:
-                if response.status == 200:
-                    data = await response.json()
-                    if not isinstance(data, dict) or "departures" not in data:
-                        _LOGGER.warning("%s API unexpected response format", self.provider_name)
-                        return {"stopEvents": []}
-                    return {"stopEvents": data["departures"]}
-                else:
-                    _LOGGER.warning("%s API returned status %s", self.provider_name, response.status)
-        except aiohttp.ClientError as e:
-            _LOGGER.warning("%s API request failed: %s", self.provider_name, e)
-        except Exception as e:
-            _LOGGER.warning("%s API error: %s", self.provider_name, e)
+        data = await self._request("get", url, timeout=15)
 
-        return None
+        if not isinstance(data, dict) or "departures" not in data:
+            _LOGGER.debug("%s API response missing 'departures' field", self.provider_name)
+            return {"stopEvents": []}
+
+        return {"stopEvents": data["departures"]}
 
     def parse_departure(
         self, stop: Dict[str, Any], tz: Union[ZoneInfo, Any], now: datetime
@@ -133,37 +123,29 @@ class FPTFBaseProvider(BaseProvider):
     async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
         url = f"{self.API_BASE}/locations?query={quote(search_term, safe='')}&results=15"
 
-        try:
-            async with self.session.get(url, timeout=aiohttp.ClientTimeout(total=10)) as response:
-                if response.status == 200:
-                    data = await response.json()
-                    if not isinstance(data, list):
-                        return []
-
-                    results = []
-                    for location in data:
-                        if not isinstance(location, dict):
-                            continue
-                        if location.get("type") not in ("stop", "station"):
-                            continue
-
-                        name = location.get("name", "")
-                        place = ""
-                        if "(" in name and name.endswith(")"):
-                            place = name[name.rfind("(") + 1 : -1]
-
-                        results.append(
-                            {
-                                "id": location.get("id", ""),
-                                "name": name,
-                                "place": place,
-                                "area_type": "stop",
-                            }
-                        )
-                    return results
-                else:
-                    _LOGGER.error("%s API returned status %s", self.provider_name, response.status)
-        except Exception as e:
-            _LOGGER.error("Error searching %s stops: %s", self.provider_name, e)
-
-        return []
+        data = await self._request("get", url, timeout=10)
+
+        if not isinstance(data, list):
+            raise ApiResponseError(f"{self.provider_name}: API returned {type(data).__name__} instead of a list")
+
+        results = []
+        for location in data:
+            if not isinstance(location, dict):
+                continue
+            if location.get("type") not in ("stop", "station"):
+                continue
+
+            name = location.get("name", "")
+            place = ""
+            if "(" in name and name.endswith(")"):
+                place = name[name.rfind("(") + 1 : -1]
+
+            results.append(
+                {
+                    "id": location.get("id", ""),
+                    "name": name,
+                    "place": place,
+                    "area_type": "stop",
+                }
+            )
+        return results