python-openpublictransport 0.1.0__py3-none-any.whl

openpublictransport/__init__.py

@@ -0,0 +1,5 @@
+"""python-openpublictransport — public transport API library."""
+
+from .providers import get_all_provider_ids, get_provider, register_provider
+
+__all__ = ["get_provider", "get_all_provider_ids", "register_provider"]

openpublictransport/const.py

@@ -0,0 +1,75 @@
+"""Provider IDs, transport type mappings and API base URLs."""
+
+# Provider IDs
+PROVIDER_VRR = "vrr"
+PROVIDER_KVV = "kvv"
+PROVIDER_HVV = "hvv"
+PROVIDER_BVG = "bvg"
+PROVIDER_MVV = "mvv"
+PROVIDER_VVS = "vvs"
+PROVIDER_VGN = "vgn"
+PROVIDER_VAGFR = "vagfr"
+PROVIDER_RMV = "rmv"
+PROVIDER_TRAFIKLAB_SE = "trafiklab_se"
+PROVIDER_NTA_IE = "nta_ie"
+PROVIDER_VRN = "vrn"
+PROVIDER_VVO = "vvo"
+PROVIDER_DING = "ding"
+PROVIDER_AVV_AUGSBURG = "avv_augsburg"
+PROVIDER_RVV = "rvv"
+PROVIDER_BSVG = "bsvg"
+PROVIDER_NWL = "nwl"
+PROVIDER_NVBW = "nvbw"
+PROVIDER_BEG = "beg"
+PROVIDER_SBB = "sbb"
+PROVIDER_OEBB = "oebb"
+PROVIDER_TRANSITOUS = "transitous"
+PROVIDER_DB = "db"
+PROVIDER_VBN_OTP = "vbn_otp"
+PROVIDER_VBN_TRIAS = "vbn_trias"
+PROVIDER_OPT = "openpublictransport"
+PROVIDER_OTP_CUSTOM = "otp_custom"
+
+# API base URLs
+API_BASE_URL_VRR = "https://openservice-test.vrr.de/static03/XML_DM_REQUEST"
+API_BASE_URL_KVV = "https://projekte.kvv-efa.de/sl3-alone/XSLT_DM_REQUEST"
+API_BASE_URL_HVV = "https://hvv.efa.de/efa/XML_DM_REQUEST"
+API_BASE_URL_TRAFIKLAB = "https://realtime-api.trafiklab.se/v1"
+API_BASE_URL_NTA_GTFSR = "https://api.nationaltransport.ie/gtfsr"
+
+# Transport type mappings
+KVV_TRANSPORTATION_TYPES = {
+    1: "train",
+    4: "tram",
+    5: "bus",
+}
+
+HVV_TRANSPORTATION_TYPES = {
+    0: "train",
+    1: "train",
+    2: "subway",
+    3: "bus",
+    4: "tram",
+    5: "bus",
+    6: "ferry",
+    7: "on_demand",
+}
+
+TRAFIKLAB_TRANSPORTATION_TYPES = {
+    "BUS": "bus",
+    "TRAIN": "train",
+    "TRAM": "tram",
+    "METRO": "subway",
+    "FERRY": "ferry",
+}
+
+NTA_TRANSPORTATION_TYPES = {
+    0: "tram",
+    1: "subway",
+    2: "train",
+    3: "bus",
+    4: "ferry",
+    5: "tram",
+    6: "tram",
+    7: "train",
+}

openpublictransport/models.py

@@ -0,0 +1,95 @@
+"""Unified data models for all public transport providers."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional
+
+
+class UnifiedTransportType(str, Enum):
+    """Unified transportation types across all providers."""
+
+    BUS = "bus"
+    TRAM = "tram"
+    SUBWAY = "subway"
+    TRAIN = "train"
+    FERRY = "ferry"
+    TAXI = "taxi"
+    ON_DEMAND = "on_demand"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class UnifiedDeparture:
+    """Unified departure data structure."""
+
+    line: str
+    destination: str
+    departure_time: str  # HH:MM format
+    planned_time: str  # HH:MM format
+    delay: int  # minutes
+    platform: Optional[str]
+    transportation_type: str
+    is_realtime: bool
+    minutes_until_departure: int
+    departure_time_obj: datetime  # For internal sorting
+    description: Optional[str] = None
+    agency: Optional[str] = None
+    notices: Optional[list[str]] = None
+    planned_platform: Optional[str] = None
+    platform_changed: bool = False
+    line_color: Optional[str] = None
+    line_text_color: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        result = {
+            "line": self.line,
+            "destination": self.destination,
+            "departure_time": self.departure_time,
+            "planned_time": self.planned_time,
+            "delay": self.delay,
+            "platform": self.platform,
+            "transportation_type": self.transportation_type,
+            "is_realtime": self.is_realtime,
+            "minutes_until_departure": self.minutes_until_departure,
+        }
+        if self.description:
+            result["description"] = self.description
+        if self.agency:
+            result["agency"] = self.agency
+        if self.notices:
+            result["notices"] = self.notices
+        if self.platform_changed:
+            result["planned_platform"] = self.planned_platform
+            result["platform_changed"] = True
+        if self.line_color:
+            result["line_color"] = self.line_color
+        if self.line_text_color:
+            result["line_text_color"] = self.line_text_color
+        return result
+
+
+@dataclass
+class UnifiedStop:
+    """Unified stop data structure for stop search results."""
+
+    id: str
+    name: str
+    place: Optional[str] = None
+    area_type: Optional[str] = None
+    transport_modes: Optional[list[str]] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        result: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+        }
+        if self.place:
+            result["place"] = self.place
+        if self.area_type:
+            result["area_type"] = self.area_type
+        if self.transport_modes is not None:
+            result["transport_modes"] = self.transport_modes
+        return result

openpublictransport/parsers.py

@@ -0,0 +1,122 @@
+"""Common parsing utilities for all providers."""
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional, Union
+from zoneinfo import ZoneInfo
+
+from .models import UnifiedDeparture
+
+_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
+
+
+def parse_departure_generic(
+    stop: Dict[str, Any],
+    tz: Union[ZoneInfo, Any],
+    now: datetime,
+    get_transport_type_fn: Callable[[Dict[str, Any]], str],
+    get_platform_fn: Callable[[Dict[str, Any]], str],
+    get_realtime_fn: Callable[[Dict[str, Any], Optional[str], Optional[str]], bool],
+) -> Optional[UnifiedDeparture]:
+    """Generic parser for departure data — shared logic across all providers."""
+    try:
+        if not isinstance(stop, dict):
+            _LOGGER.debug("Invalid stop data: expected dict, got %s", type(stop))
+            return None
+
+        planned_time_str = stop.get("departureTimePlanned")
+        estimated_time_str = stop.get("departureTimeEstimated")
+
+        if not planned_time_str:
+            _LOGGER.debug("Missing departureTimePlanned in stop data")
+            return None
+
+        if not isinstance(planned_time_str, str):
+            _LOGGER.debug("Invalid departureTimePlanned: expected str, got %s", type(planned_time_str))
+            return None
+
+        planned_time = _parse_dt(planned_time_str)
+        estimated_time = _parse_dt(estimated_time_str) if estimated_time_str else planned_time
+
+        if not planned_time:
+            _LOGGER.debug("Failed to parse departureTimePlanned: %s", planned_time_str)
+            return None
+
+        try:
+            planned_local = planned_time.astimezone(tz)
+            estimated_local = estimated_time.astimezone(tz) if estimated_time else planned_local
+        except (ValueError, TypeError) as e:
+            _LOGGER.debug("Failed to convert timezone: %s", e)
+            return None
+
+        delay_minutes = int((estimated_local - planned_local).total_seconds() / 60)
+
+        transportation = stop.get("transportation", {})
+        if not isinstance(transportation, dict):
+            _LOGGER.debug("Invalid transportation data: expected dict, got %s", type(transportation))
+            transportation = {}
+
+        destination_obj = transportation.get("destination", {})
+        if not isinstance(destination_obj, dict):
+            destination_obj = {}
+        destination = destination_obj.get("name", "Unknown")
+
+        line_number = str(transportation.get("number", ""))
+        description = str(transportation.get("description", ""))
+        agency = stop.get("agency")
+
+        transport_type = get_transport_type_fn(transportation)
+        platform = get_platform_fn(stop)
+
+        time_diff = estimated_local - now
+        minutes_until = max(0, int(time_diff.total_seconds() / 60))
+
+        is_realtime = get_realtime_fn(stop, estimated_time_str, planned_time_str)
+
+        notices = []
+        for info in stop.get("infos", []):
+            if isinstance(info, dict):
+                text = info.get("subtitle") or info.get("title") or info.get("content", "")
+                if text and isinstance(text, str):
+                    notices.append(text.strip())
+        for hint in stop.get("hints", []):
+            if isinstance(hint, dict):
+                text = hint.get("content") or hint.get("text", "")
+                if text and isinstance(text, str):
+                    notices.append(text.strip())
+
+        planned_platform = stop.get("plannedPlatformName") or stop.get("platform", {}).get("plannedName")
+        actual_platform = platform
+        platform_changed = bool(
+            planned_platform and actual_platform and str(planned_platform).strip() != str(actual_platform).strip()
+        )
+
+        return UnifiedDeparture(
+            line=line_number,
+            destination=destination,
+            departure_time=estimated_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=estimated_local,
+            description=description if description else None,
+            agency=agency if agency else None,
+            notices=notices if notices else None,
+            planned_platform=str(planned_platform).strip() if planned_platform and platform_changed else None,
+            platform_changed=platform_changed,
+        )
+
+    except Exception as e:
+        _LOGGER.debug("Error parsing departure: %s", e)
+        return None

openpublictransport/providers/__init__.py

@@ -0,0 +1,127 @@
+"""Provider registry and factory."""
+
+import aiohttp
+from typing import Dict, Optional, Type
+
+from ..const import (
+    PROVIDER_AVV_AUGSBURG,
+    PROVIDER_BEG,
+    PROVIDER_BSVG,
+    PROVIDER_BVG,
+    PROVIDER_DB,
+    PROVIDER_DING,
+    PROVIDER_HVV,
+    PROVIDER_KVV,
+    PROVIDER_MVV,
+    PROVIDER_NTA_IE,
+    PROVIDER_NVBW,
+    PROVIDER_NWL,
+    PROVIDER_OEBB,
+    PROVIDER_OPT,
+    PROVIDER_OTP_CUSTOM,
+    PROVIDER_RMV,
+    PROVIDER_RVV,
+    PROVIDER_SBB,
+    PROVIDER_TRAFIKLAB_SE,
+    PROVIDER_TRANSITOUS,
+    PROVIDER_VAGFR,
+    PROVIDER_VBN_OTP,
+    PROVIDER_VBN_TRIAS,
+    PROVIDER_VGN,
+    PROVIDER_VRN,
+    PROVIDER_VRR,
+    PROVIDER_VVO,
+    PROVIDER_VVS,
+)
+from .avv import AVVProvider
+from .base import BaseProvider
+from .beg import BEGProvider
+from .bsvg import BSVGProvider
+from .bvg import BVGProvider
+from .db import DBProvider
+from .ding import DINGProvider
+from .gtfsde import OPTProvider
+from .hvv import HVVProvider
+from .kvv import KVVProvider
+from .mvv import MVVProvider
+from .nta import NTAProvider
+from .nvbw import NVBWProvider
+from .nwl import NWLProvider
+from .oebb import OeBBProvider
+from .otp_custom import OTPCustomProvider
+from .rmv import RMVProvider
+from .rvv import RVVProvider
+from .sbb import SBBProvider
+from .trafiklab import TrafiklabProvider
+from .transitous import TransitousProvider
+from .vagfr import VAGFRProvider
+from .vbn import VBNOTPProvider, VBNTriasProvider
+from .vgn import VGNProvider
+from .vrn import VRNProvider
+from .vrr import VRRProvider
+from .vvo import VVOProvider
+from .vvs import VVSProvider
+
+_PROVIDER_REGISTRY: Dict[str, Type[BaseProvider]] = {}
+
+
+def register_provider(provider_id: str, provider_class: Type[BaseProvider]) -> None:
+    """Register a provider class."""
+    _PROVIDER_REGISTRY[provider_id] = provider_class
+
+
+def get_provider(
+    provider_id: Optional[str],
+    session: aiohttp.ClientSession,
+    api_key: Optional[str] = None,
+    api_key_secondary: Optional[str] = None,
+    custom_url: Optional[str] = None,
+) -> Optional[BaseProvider]:
+    """Get a provider instance by ID."""
+    if provider_id is None:
+        return None
+    provider_class = _PROVIDER_REGISTRY.get(provider_id)
+    if provider_class:
+        return provider_class(
+            session,
+            api_key=api_key,
+            api_key_secondary=api_key_secondary,
+            custom_url=custom_url,
+        )
+    return None
+
+
+def get_all_provider_ids() -> list[str]:
+    """Get all registered provider IDs."""
+    return list(_PROVIDER_REGISTRY.keys())
+
+
+# Register all providers
+register_provider(PROVIDER_VRR, VRRProvider)
+register_provider(PROVIDER_KVV, KVVProvider)
+register_provider(PROVIDER_HVV, HVVProvider)
+register_provider(PROVIDER_BVG, BVGProvider)
+register_provider(PROVIDER_MVV, MVVProvider)
+register_provider(PROVIDER_VVS, VVSProvider)
+register_provider(PROVIDER_VGN, VGNProvider)
+register_provider(PROVIDER_VAGFR, VAGFRProvider)
+register_provider(PROVIDER_RMV, RMVProvider)
+register_provider(PROVIDER_TRAFIKLAB_SE, TrafiklabProvider)
+register_provider(PROVIDER_NTA_IE, NTAProvider)
+register_provider(PROVIDER_VRN, VRNProvider)
+register_provider(PROVIDER_VVO, VVOProvider)
+register_provider(PROVIDER_DING, DINGProvider)
+register_provider(PROVIDER_AVV_AUGSBURG, AVVProvider)
+register_provider(PROVIDER_RVV, RVVProvider)
+register_provider(PROVIDER_BSVG, BSVGProvider)
+register_provider(PROVIDER_NWL, NWLProvider)
+register_provider(PROVIDER_NVBW, NVBWProvider)
+register_provider(PROVIDER_BEG, BEGProvider)
+register_provider(PROVIDER_SBB, SBBProvider)
+register_provider(PROVIDER_OEBB, OeBBProvider)
+register_provider(PROVIDER_TRANSITOUS, TransitousProvider)
+register_provider(PROVIDER_DB, DBProvider)
+register_provider(PROVIDER_VBN_OTP, VBNOTPProvider)
+register_provider(PROVIDER_VBN_TRIAS, VBNTriasProvider)
+register_provider(PROVIDER_OPT, OPTProvider)
+register_provider(PROVIDER_OTP_CUSTOM, OTPCustomProvider)

openpublictransport/providers/avv.py

@@ -0,0 +1,44 @@
+"""AVV (Augsburger Verkehrs- & Tarifverbund) provider implementation."""
+
+from typing import Any, Callable, Dict, Optional
+
+from ..const import PROVIDER_AVV_AUGSBURG
+from .efa_base import EFABaseProvider
+
+
+class AVVProvider(EFABaseProvider):
+    """AVV (Augsburg) provider."""
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_AVV_AUGSBURG
+
+    @property
+    def provider_name(self) -> str:
+        return "AVV (Augsburg)"
+
+    @property
+    def dm_base_url(self) -> str:
+        return "https://fahrtauskunft.avv-augsburg.de/efa/XML_DM_REQUEST"
+
+    @property
+    def sf_base_url(self) -> str:
+        return "https://fahrtauskunft.avv-augsburg.de/efa/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/base.py

@@ -0,0 +1,77 @@
+"""Base class for all public transport providers."""
+
+import aiohttp
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+from zoneinfo import ZoneInfo
+
+from ..models import UnifiedDeparture
+
+
+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
+
+    @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

openpublictransport/providers/beg.py

@@ -0,0 +1,46 @@
+"""BEG (Bayerische Eisenbahngesellschaft) provider implementation."""
+
+from typing import Any, Callable, Dict, Optional
+
+from ..const import PROVIDER_BEG
+from .efa_base import EFABaseProvider
+
+
+class BEGProvider(EFABaseProvider):
+    """BEG (Bayern) provider."""
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_BEG
+
+    @property
+    def provider_name(self) -> str:
+        return "BEG (Bayern)"
+
+    @property
+    def dm_base_url(self) -> str:
+        return "https://bahnland-bayern.de/efa/XML_DM_REQUEST"
+
+    @property
+    def sf_base_url(self) -> str:
+        return "https://bahnland-bayern.de/efa/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)
+            2: "subway",  # U-Bahn
+            3: "subway",  # U-Bahn variant
+            4: "tram",  # Tram/Streetcar
+            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/bsvg.py

@@ -0,0 +1,44 @@
+"""BSVG (Braunschweiger Verkehrs-GmbH) provider implementation."""
+
+from typing import Any, Callable, Dict, Optional
+
+from ..const import PROVIDER_BSVG
+from .efa_base import EFABaseProvider
+
+
+class BSVGProvider(EFABaseProvider):
+    """BSVG (Braunschweig) provider."""
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_BSVG
+
+    @property
+    def provider_name(self) -> str:
+        return "BSVG (Braunschweig)"
+
+    @property
+    def dm_base_url(self) -> str:
+        return "https://bsvg.efa.de/bsvagstd/XML_DM_REQUEST"
+
+    @property
+    def sf_base_url(self) -> str:
+        return "https://bsvg.efa.de/bsvagstd/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)
+            4: "tram",  # Tram/Streetcar
+            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/bvg.py

@@ -0,0 +1,32 @@
+"""BVG (Berliner Verkehrsbetriebe) provider implementation.
+
+Uses the v6.vbb.transport.rest API (FPTF format).
+No API key required.
+"""
+
+from ..const import PROVIDER_BVG
+from .fptf_base import FPTFBaseProvider
+
+
+class BVGProvider(FPTFBaseProvider):
+    """BVG (Berlin) provider using VBB REST API."""
+
+    API_BASE = "https://v6.vbb.transport.rest"
+
+    PRODUCT_MAPPING = {
+        "subway": "subway",
+        "suburban": "train",
+        "tram": "tram",
+        "bus": "bus",
+        "ferry": "ferry",
+        "express": "train",
+        "regional": "train",
+    }
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_BVG
+
+    @property
+    def provider_name(self) -> str:
+        return "BVG (Berlin)"