python-openpublictransport 0.1.0__py3-none-any.whl

openpublictransport/providers/db.py

@@ -0,0 +1,39 @@
+"""Deutsche Bahn provider implementation.
+
+Uses the v6.db.transport.rest API (FPTF format).
+No API key required.
+
+NOTE: This API is a community-maintained proxy (by derhuerst).
+It is free and open but not officially supported by Deutsche Bahn.
+Availability is not guaranteed — the API may experience occasional downtime.
+"""
+
+from ..const import PROVIDER_DB
+from .fptf_base import FPTFBaseProvider
+
+
+class DBProvider(FPTFBaseProvider):
+    """Deutsche Bahn provider using v6.db.transport.rest API."""
+
+    API_BASE = "https://v6.db.transport.rest"
+
+    PRODUCT_MAPPING = {
+        "nationalExpress": "train",  # ICE
+        "national": "train",  # IC/EC
+        "regionalExpress": "train",  # RE
+        "regional": "train",  # RB
+        "suburban": "train",  # S-Bahn
+        "subway": "subway",  # U-Bahn
+        "tram": "tram",
+        "bus": "bus",
+        "ferry": "ferry",
+        "taxi": "taxi",
+    }
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_DB
+
+    @property
+    def provider_name(self) -> str:
+        return "DB (Deutsche Bahn)"

openpublictransport/providers/ding.py

@@ -0,0 +1,44 @@
+"""DING (Donau-Iller-Nahverkehrsverbund) provider implementation."""
+
+from typing import Any, Callable, Dict, Optional
+
+from ..const import PROVIDER_DING
+from .efa_base import EFABaseProvider
+
+
+class DINGProvider(EFABaseProvider):
+    """DING (Ulm) provider."""
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_DING
+
+    @property
+    def provider_name(self) -> str:
+        return "DING (Ulm)"
+
+    @property
+    def dm_base_url(self) -> str:
+        return "https://www.ding.eu/ding3/XML_DM_REQUEST"
+
+    @property
+    def sf_base_url(self) -> str:
+        return "https://www.ding.eu/ding3/XML_STOPFINDER_REQUEST"
+
+    def get_timezone(self) -> str:
+        return "Europe/Berlin"
+
+    def get_transport_type_mapping(self) -> Dict[Any, str]:
+        return {
+            0: "train",  # High-speed trains (ICE, IC, EC)
+            1: "train",  # Regional trains (RE, RB, S-Bahn)
+            4: "tram",  # Straßenbahn
+            5: "bus",  # City bus
+            6: "bus",  # Regional bus
+            7: "bus",  # Express bus
+            8: "bus",  # Night bus
+            13: "train",  # Regionalzug (RE)
+        }
+
+    def get_realtime_fn(self) -> Callable[[Dict[str, Any], Optional[str], Optional[str]], bool]:
+        return lambda s, est, plan: est != plan if est and plan else False

openpublictransport/providers/efa_base.py

@@ -0,0 +1,209 @@
+"""Base class for EFA (Electronic Fahrplan-Auskunft) providers."""
+
+import asyncio
+import logging
+from abc import abstractmethod
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional, Union
+from urllib.parse import quote
+from zoneinfo import ZoneInfo
+
+import aiohttp
+
+from ..models import UnifiedDeparture
+from ..parsers import parse_departure_generic
+from .base import BaseProvider
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class EFABaseProvider(BaseProvider):
+    """Base class for all EFA-based providers (VRR, KVV, HVV, MVV, etc.)."""
+
+    @property
+    @abstractmethod
+    def dm_base_url(self) -> str:
+        """Return the base URL for departure monitor requests."""
+
+    @property
+    @abstractmethod
+    def sf_base_url(self) -> str:
+        """Return the base URL for stop finder requests."""
+
+    def get_platform_fn(self) -> Callable[[Dict[str, Any]], str]:
+        """Return function to extract platform from stop event."""
+        return lambda s: s.get("platform", {}).get("name") or s.get("platformName", "")
+
+    def get_realtime_fn(self) -> Callable[[Dict[str, Any], Optional[str], Optional[str]], bool]:
+        """Return function to detect realtime data."""
+        return lambda s, est, plan: "MONITORED" in s.get("realtimeStatus", [])
+
+    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 EFA API."""
+        if station_id:
+            params = (
+                f"outputFormat=RapidJSON&"
+                f"stateless=1&"
+                f"type_dm=any&"
+                f"name_dm={station_id}&"
+                f"mode=direct&"
+                f"useRealtime=1&"
+                f"limit={departures_limit}"
+            )
+        else:
+            params = (
+                f"outputFormat=RapidJSON&"
+                f"place_dm={place_dm}&"
+                f"type_dm=stop&"
+                f"name_dm={name_dm}&"
+                f"mode=direct&"
+                f"useRealtime=1&"
+                f"limit={departures_limit}"
+            )
+
+        url = f"{self.dm_base_url}?{params}"
+        name = self.provider_name
+
+        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:
+                            json_data = await response.json()
+                            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
+
+    def parse_departure(
+        self, stop: Dict[str, Any], tz: Union[ZoneInfo, Any], now: datetime
+    ) -> Optional[UnifiedDeparture]:
+        """Parse a single departure from EFA API response."""
+        type_mapping = self.get_transport_type_mapping()
+
+        def determine_transport_type(transportation: Dict[str, Any]) -> str:
+            product = transportation.get("product", {})
+            product_class = product.get("class", 0)
+            transport_type = type_mapping.get(product_class, "unknown")
+            if transport_type == "unknown":
+                _LOGGER.debug(
+                    "Unknown transport class %s for line %s",
+                    product_class,
+                    transportation.get("number", "unknown"),
+                )
+            return transport_type
+
+        return parse_departure_generic(
+            stop,
+            tz,
+            now,
+            get_transport_type_fn=determine_transport_type,
+            get_platform_fn=self.get_platform_fn(),
+            get_realtime_fn=self.get_realtime_fn(),
+        )
+
+    async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
+        """Search for stops using EFA Stopfinder API."""
+        if "," in search_term:
+            parts = search_term.split(",", 1)
+            stop_name = parts[0].strip()
+            place_name = parts[1].strip()
+            params = (
+                f"outputFormat=RapidJSON&"
+                f"locationServerActive=1&"
+                f"type_sf=any&"
+                f"name_sf={quote(stop_name, safe='')}&"
+                f"place_sf={quote(place_name, safe='')}&"
+                f"SpEncId=0"
+            )
+        else:
+            params = (
+                f"outputFormat=RapidJSON&"
+                f"locationServerActive=1&"
+                f"type_sf=stop&"
+                f"name_sf={quote(search_term, safe='')}&"
+                f"SpEncId=0"
+            )
+
+        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:
+                        data = await response.json()
+                    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 []

openpublictransport/providers/fptf_base.py

@@ -0,0 +1,169 @@
+"""Base provider for FPTF (Friendly Public Transport Format) APIs."""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+from urllib.parse import quote
+from zoneinfo import ZoneInfo
+
+import aiohttp
+
+from ..models import UnifiedDeparture
+from .base import BaseProvider
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _parse_dt(s: str) -> Optional[datetime]:
+    """Parse an ISO datetime string, returning None on failure."""
+    try:
+        return datetime.fromisoformat(s)
+    except (ValueError, TypeError):
+        return None
+
+
+class FPTFBaseProvider(BaseProvider):
+    """Base class for FPTF-based providers (transport.rest APIs)."""
+
+    API_BASE: str = ""
+    PRODUCT_MAPPING: Dict[str, str] = {}
+    DEFAULT_TRANSPORT_TYPE: str = "train"
+
+    def get_timezone(self) -> str:
+        return "Europe/Berlin"
+
+    async def fetch_departures(
+        self,
+        station_id: Optional[str],
+        place_dm: str,
+        name_dm: str,
+        departures_limit: int,
+    ) -> Optional[Dict[str, Any]]:
+        if not station_id:
+            _LOGGER.warning("%s provider requires a station_id", self.provider_name)
+            return None
+
+        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)
+
+        return None
+
+    def parse_departure(
+        self, stop: Dict[str, Any], tz: Union[ZoneInfo, Any], now: datetime
+    ) -> Optional[UnifiedDeparture]:
+        try:
+            when_str = stop.get("when") or stop.get("plannedWhen")
+            planned_str = stop.get("plannedWhen")
+            if not when_str or not planned_str:
+                return None
+
+            when = _parse_dt(when_str)
+            planned = _parse_dt(planned_str)
+            if not when or not planned:
+                return None
+
+            when_local = when.astimezone(tz)
+            planned_local = planned.astimezone(tz)
+
+            delay_seconds = stop.get("delay") or 0
+            delay_minutes = int(delay_seconds / 60)
+
+            line_info = stop.get("line", {})
+            line_name = line_info.get("name", "")
+            product = line_info.get("product", "")
+            transport_type = self.PRODUCT_MAPPING.get(product, self.DEFAULT_TRANSPORT_TYPE)
+
+            destination_info = stop.get("destination", {})
+            destination = destination_info.get("name", stop.get("direction", "Unknown"))
+
+            platform = stop.get("platform") or ""
+            planned_platform = stop.get("plannedPlatform") or ""
+            platform_changed = bool(platform and planned_platform and platform != planned_platform)
+
+            time_diff = when_local - now
+            minutes_until = max(0, int(time_diff.total_seconds() / 60))
+
+            is_realtime = stop.get("prognosisType") is not None
+
+            notices = []
+            for remark in stop.get("remarks", []):
+                if isinstance(remark, dict) and remark.get("type") == "warning":
+                    text = remark.get("text") or remark.get("summary", "")
+                    if text:
+                        notices.append(text)
+
+            operator = line_info.get("operator", {})
+            agency = operator.get("name") if isinstance(operator, dict) else None
+
+            return UnifiedDeparture(
+                line=line_name,
+                destination=destination,
+                departure_time=when_local.strftime("%H:%M"),
+                planned_time=planned_local.strftime("%H:%M"),
+                delay=delay_minutes,
+                platform=platform,
+                transportation_type=transport_type,
+                is_realtime=is_realtime,
+                minutes_until_departure=minutes_until,
+                departure_time_obj=when_local,
+                description=stop.get("direction"),
+                agency=agency,
+                notices=notices if notices else None,
+                planned_platform=planned_platform if platform_changed else None,
+                platform_changed=platform_changed,
+            )
+        except Exception as e:
+            _LOGGER.debug("Error parsing %s departure: %s", self.provider_name, e)
+            return None
+
+    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 []

openpublictransport/providers/gtfsde.py

@@ -0,0 +1,21 @@
+"""Community OTP2 provider — api.openpublictransport.net (GTFS.DE data, Germany-wide)."""
+
+from .otp import OTPProvider
+
+
+class OPTProvider(OTPProvider):
+    """Community server at api.openpublictransport.net."""
+
+    otp_base_url = "https://api.openpublictransport.net/otp/routers/default"
+
+    @property
+    def provider_id(self) -> str:
+        return "openpublictransport"
+
+    @property
+    def provider_name(self) -> str:
+        return "openpublictransport.net (Deutschlandweit)"
+
+    @property
+    def requires_api_key(self) -> bool:
+        return True

openpublictransport/providers/hvv.py

@@ -0,0 +1,40 @@
+"""HVV (Hamburger Verkehrsverbund) provider implementation."""
+
+from typing import Any, Callable, Dict, Optional
+
+from ..const import HVV_TRANSPORTATION_TYPES, PROVIDER_HVV
+from .efa_base import EFABaseProvider
+
+
+class HVVProvider(EFABaseProvider):
+    """HVV (Hamburger Verkehrsverbund) provider."""
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_HVV
+
+    @property
+    def provider_name(self) -> str:
+        return "HVV (Hamburg)"
+
+    @property
+    def dm_base_url(self) -> str:
+        return "https://hvv.efa.de/efa/XML_DM_REQUEST"
+
+    @property
+    def sf_base_url(self) -> str:
+        return "https://hvv.efa.de/efa/XML_STOPFINDER_REQUEST"
+
+    def get_timezone(self) -> str:
+        return "Europe/Berlin"
+
+    def get_transport_type_mapping(self) -> Dict[Any, str]:
+        return HVV_TRANSPORTATION_TYPES
+
+    def get_platform_fn(self) -> Callable[[Dict[str, Any]], str]:
+        return lambda s: (
+            s.get("location", {}).get("properties", {}).get("platform") or s.get("location", {}).get("platformName", "")
+        )
+
+    def get_realtime_fn(self) -> Callable[[Dict[str, Any], Optional[str], Optional[str]], bool]:
+        return lambda s, est, plan: est != plan if est and plan else False

openpublictransport/providers/kvv.py

@@ -0,0 +1,38 @@
+"""KVV (Karlsruher Verkehrsverbund) provider implementation."""
+
+from typing import Any, Callable, Dict, Optional
+
+from ..const import KVV_TRANSPORTATION_TYPES, PROVIDER_KVV
+from .efa_base import EFABaseProvider
+
+
+class KVVProvider(EFABaseProvider):
+    """KVV (Karlsruher Verkehrsverbund) provider."""
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_KVV
+
+    @property
+    def provider_name(self) -> str:
+        return "KVV (Karlsruhe)"
+
+    @property
+    def dm_base_url(self) -> str:
+        return "https://projekte.kvv-efa.de/sl3-alone/XSLT_DM_REQUEST"
+
+    @property
+    def sf_base_url(self) -> str:
+        return "https://projekte.kvv-efa.de/sl3-alone/XML_STOPFINDER_REQUEST"
+
+    def get_timezone(self) -> str:
+        return "Europe/Berlin"
+
+    def get_transport_type_mapping(self) -> Dict[Any, str]:
+        return KVV_TRANSPORTATION_TYPES
+
+    def get_platform_fn(self) -> Callable[[Dict[str, Any]], str]:
+        return lambda s: s.get("location", {}).get("disassembledName") or s.get("platformName", "")
+
+    def get_realtime_fn(self) -> Callable[[Dict[str, Any], Optional[str], Optional[str]], bool]:
+        return lambda s, est, plan: s.get("isRealtimeControlled", False)

openpublictransport/providers/mvv.py

@@ -0,0 +1,48 @@
+"""MVV (Münchner Verkehrs- und Tarifverbund) provider implementation."""
+
+from typing import Any, Callable, Dict, Optional
+
+from ..const import PROVIDER_MVV
+from .efa_base import EFABaseProvider
+
+
+class MVVProvider(EFABaseProvider):
+    """MVV (München) provider."""
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_MVV
+
+    @property
+    def provider_name(self) -> str:
+        return "MVV (München)"
+
+    @property
+    def dm_base_url(self) -> str:
+        return "https://efa.mvv-muenchen.de/ng/XML_DM_REQUEST"
+
+    @property
+    def sf_base_url(self) -> str:
+        return "https://efa.mvv-muenchen.de/ng/XML_STOPFINDER_REQUEST"
+
+    def get_timezone(self) -> str:
+        return "Europe/Berlin"
+
+    def get_transport_type_mapping(self) -> Dict[Any, str]:
+        return {
+            0: "train",  # Fernverkehr (ICE, IC, EC)
+            1: "train",  # S-Bahn
+            2: "subway",  # U-Bahn
+            3: "subway",  # U-Bahn variant
+            4: "tram",  # Tram
+            5: "bus",  # Stadtbus
+            6: "bus",  # Regionalbus
+            7: "bus",  # Schnellbus
+            8: "bus",  # Nachtbus
+            9: "ferry",  # Fähre
+            10: "taxi",  # Rufbus/Taxi
+            13: "train",  # Regionalzug (RE/RB)
+        }
+
+    def get_realtime_fn(self) -> Callable[[Dict[str, Any], Optional[str], Optional[str]], bool]:
+        return lambda s, est, plan: est != plan if est and plan else False