python-openpublictransport 0.1.14__tar.gz → 0.1.15__tar.gz

{python_openpublictransport-0.1.14 → python_openpublictransport-0.1.15}/PKG-INFO

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

{python_openpublictransport-0.1.14 → python_openpublictransport-0.1.15}/pyproject.toml

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

{python_openpublictransport-0.1.14 → python_openpublictransport-0.1.15}/src/openpublictransport/models.py

@@ -38,6 +38,9 @@ class UnifiedDeparture:
     notices: Optional[list[str]] = None
     planned_platform: Optional[str] = None
     platform_changed: bool = False
+    # Human-readable form of `platform` when the provider offers one
+    # ("Gleis 3" next to the technical "3")
+    platform_name: Optional[str] = None
     line_color: Optional[str] = None
     line_text_color: Optional[str] = None
 
@@ -60,6 +63,8 @@ class UnifiedDeparture:
             result["agency"] = self.agency
         if self.notices:
             result["notices"] = self.notices
+        if self.platform_name and self.platform_name != self.platform:
+            result["platform_name"] = self.platform_name
         if self.platform_changed:
             result["planned_platform"] = self.planned_platform
             result["platform_changed"] = True

{python_openpublictransport-0.1.14 → python_openpublictransport-0.1.15}/src/openpublictransport/parsers.py

@@ -1,6 +1,7 @@
 """Common parsing utilities for all providers."""
 
 import logging
+import re
 from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Optional, Union
 from zoneinfo import ZoneInfo
@@ -9,6 +10,29 @@ from .models import UnifiedDeparture
 
 _LOGGER = logging.getLogger(__name__)
 
+# Human-readable platform labels APIs prefix onto the bare track identifier:
+# "Gleis 3", "Bstg. 12", "Steig B", "Platform 4", "Pl. 2", "Track 1".
+_PLATFORM_LABEL_RE = re.compile(
+    r"^(?:gleis|bstg\.?|bahnsteig|steig|platform|plattform|pl\.|track|quai|voie|spor|perron)\s*",
+    re.IGNORECASE,
+)
+
+
+def normalize_platform(value: Any) -> str:
+    """Reduce a platform value to its bare identifier, lowercased.
+
+    ``"Gleis 3"``, ``"gleis 3"`` and ``"3"`` all normalize to ``"3"``. Used to
+    compare a technical platform value against a human-readable one without
+    reporting a spurious platform change, and re-used by consumers that want to
+    match user input like ``platform: 3`` against whatever the provider returns.
+    """
+    if value is None:
+        return ""
+    text = str(value).strip()
+    if not text:
+        return ""
+    return _PLATFORM_LABEL_RE.sub("", text).strip().casefold()
+
 
 def _parse_dt(s: str) -> Optional[datetime]:
     """Parse an ISO datetime string, returning None on failure."""
@@ -18,6 +42,13 @@ def _parse_dt(s: str) -> Optional[datetime]:
         return None
 
 
+def _default_planned_platform_fn(stop: Dict[str, Any]) -> str:
+    """Legacy planned-platform lookup used when a provider supplies none."""
+    platform = stop.get("platform")
+    planned_name = platform.get("plannedName") if isinstance(platform, dict) else None
+    return stop.get("plannedPlatformName") or planned_name or ""
+
+
 def parse_departure_generic(
     stop: Dict[str, Any],
     tz: Union[ZoneInfo, Any],
@@ -25,6 +56,8 @@ def parse_departure_generic(
     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],
+    get_planned_platform_fn: Optional[Callable[[Dict[str, Any]], str]] = None,
+    get_platform_name_fn: Optional[Callable[[Dict[str, Any]], str]] = None,
 ) -> Optional[UnifiedDeparture]:
     """Generic parser for departure data — shared logic across all providers."""
     try:
@@ -75,6 +108,7 @@ def parse_departure_generic(
 
         transport_type = get_transport_type_fn(transportation)
         platform = get_platform_fn(stop)
+        platform_name = get_platform_name_fn(stop) if get_platform_name_fn else ""
 
         time_diff = estimated_local - now
         minutes_until = max(0, int(time_diff.total_seconds() / 60))
@@ -93,10 +127,13 @@ def parse_departure_generic(
                 if text and isinstance(text, str):
                     notices.append(text.strip())
 
-        planned_platform = stop.get("plannedPlatformName") or stop.get("platform", {}).get("plannedName")
-        actual_platform = platform
+        planned_fn = get_planned_platform_fn or _default_planned_platform_fn
+        planned_platform = planned_fn(stop)
+        # Compare normalized values: providers mix the technical identifier
+        # ("3") with the human-readable label ("Gleis 3") across the actual and
+        # planned fields, and those are the same platform, not a change.
         platform_changed = bool(
-            planned_platform and actual_platform and str(planned_platform).strip() != str(actual_platform).strip()
+            planned_platform and platform and normalize_platform(planned_platform) != normalize_platform(platform)
         )
 
         return UnifiedDeparture(
@@ -115,6 +152,7 @@ def parse_departure_generic(
             notices=notices if notices else None,
             planned_platform=str(planned_platform).strip() if planned_platform and platform_changed else None,
             platform_changed=platform_changed,
+            platform_name=str(platform_name).strip() or None,
         )
 
     except Exception as e:

{python_openpublictransport-0.1.14 → python_openpublictransport-0.1.15}/src/openpublictransport/providers/efa_base.py

@@ -4,7 +4,7 @@ import asyncio
 import logging
 from abc import abstractmethod
 from datetime import datetime
-from typing import Any, Callable, Dict, List, Optional, Union
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 from urllib.parse import quote
 from zoneinfo import ZoneInfo
 
@@ -39,6 +39,52 @@ def _transport_type_from_name(name: str) -> str:
     return "unknown"
 
 
+def _location_and_properties(stop: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """Return (location, location.properties) from an EFA stop event."""
+    location = stop.get("location")
+    if not isinstance(location, dict):
+        return {}, {}
+    properties = location.get("properties")
+    return location, properties if isinstance(properties, dict) else {}
+
+
+def _efa_platform(stop: Dict[str, Any]) -> str:
+    """Technical platform/track of an EFA stop event.
+
+    EFA's RapidJSON carries the track under ``location.properties.platform``.
+    Prefer that technical value ("3") over the human-readable ``platformName``
+    / ``disassembledName`` ("Gleis 3"): the readable form is only populated for
+    rail platforms, while bus and tram stops still have the technical
+    identifier (issue #56).
+
+    The last two fallbacks are the pre-RapidJSON shape, kept so older or
+    non-standard EFA deployments keep working.
+    """
+    location, properties = _location_and_properties(stop)
+    legacy = stop.get("platform")
+    legacy_name = legacy.get("name") if isinstance(legacy, dict) else None
+    return (
+        properties.get("platform")
+        or properties.get("platformName")
+        or location.get("disassembledName")
+        or legacy_name
+        or stop.get("platformName")
+        or ""
+    )
+
+
+def _efa_platform_name(stop: Dict[str, Any]) -> str:
+    """Human-readable platform label ("Gleis 3"), when EFA supplies one."""
+    location, properties = _location_and_properties(stop)
+    return properties.get("platformName") or location.get("disassembledName") or ""
+
+
+def _efa_planned_platform(stop: Dict[str, Any]) -> str:
+    """Scheduled platform, for detecting a real-time platform change."""
+    _, properties = _location_and_properties(stop)
+    return properties.get("plannedPlatform") or properties.get("plannedPlatformName") or ""
+
+
 class EFABaseProvider(BaseProvider):
     """Base class for all EFA-based providers (VRR, KVV, HVV, MVV, etc.)."""
 
@@ -53,8 +99,16 @@ class EFABaseProvider(BaseProvider):
         """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", "")
+        """Return function to extract the technical platform from a stop event."""
+        return _efa_platform
+
+    def get_platform_name_fn(self) -> Callable[[Dict[str, Any]], str]:
+        """Return function to extract the human-readable platform label."""
+        return _efa_platform_name
+
+    def get_planned_platform_fn(self) -> Callable[[Dict[str, Any]], str]:
+        """Return function to extract the scheduled platform."""
+        return _efa_planned_platform
 
     def get_realtime_fn(self) -> Callable[[Dict[str, Any], Optional[str], Optional[str]], bool]:
         """Return function to detect realtime data."""
@@ -163,6 +217,8 @@ class EFABaseProvider(BaseProvider):
             get_transport_type_fn=determine_transport_type,
             get_platform_fn=self.get_platform_fn(),
             get_realtime_fn=self.get_realtime_fn(),
+            get_planned_platform_fn=self.get_planned_platform_fn(),
+            get_platform_name_fn=self.get_platform_name_fn(),
         )
 
     async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:

{python_openpublictransport-0.1.14 → python_openpublictransport-0.1.15}/src/openpublictransport/providers/hvv.py

@@ -31,10 +31,8 @@ class HVVProvider(EFABaseProvider):
     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", "")
-        )
+    # location.properties.platform is now the EFABaseProvider default, so this
+    # provider no longer needs its own override.
 
     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

{python_openpublictransport-0.1.14 → python_openpublictransport-0.1.15}/src/openpublictransport/providers/kvv.py

@@ -31,8 +31,9 @@ class KVVProvider(EFABaseProvider):
     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", "")
+    # Platform comes from EFABaseProvider: location.properties.platform, with
+    # location.disassembledName ("Gleis 3") still a fallback and now exposed
+    # separately as platform_name.
 
     def get_realtime_fn(self) -> Callable[[Dict[str, Any], Optional[str], Optional[str]], bool]:
         return lambda s, est, plan: s.get("isRealtimeControlled", False)

{python_openpublictransport-0.1.14 → python_openpublictransport-0.1.15}/src/python_openpublictransport.egg-info/PKG-INFO

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

{python_openpublictransport-0.1.14 → python_openpublictransport-0.1.15}/src/python_openpublictransport.egg-info/SOURCES.txt

@@ -56,6 +56,7 @@ src/python_openpublictransport.egg-info/SOURCES.txt
 src/python_openpublictransport.egg-info/dependency_links.txt
 src/python_openpublictransport.egg-info/requires.txt
 src/python_openpublictransport.egg-info/top_level.txt
+tests/test_efa_platform.py
 tests/test_entur.py
 tests/test_hafas_base.py
 tests/test_hafas_mgate.py

python_openpublictransport-0.1.15/tests/test_efa_platform.py

@@ -0,0 +1,188 @@
+"""Tests for EFA platform/track extraction.
+
+EFA's RapidJSON keeps the track under ``location.properties.platform``, but the
+base provider used to read ``platform.name`` / ``platformName``, which that
+response shape never has — so every EFA provider without its own override
+reported an empty platform.
+See https://github.com/NerdySoftPaw/openpublictransport/issues/56.
+"""
+
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+from openpublictransport.parsers import normalize_platform
+from openpublictransport.providers.hvv import HVVProvider
+from openpublictransport.providers.kvv import KVVProvider
+from openpublictransport.providers.vrr import VRRProvider
+from openpublictransport.providers.vvs import VVSProvider
+
+TZ = ZoneInfo("Europe/Berlin")
+NOW = datetime(2026, 7, 18, 20, 8, tzinfo=TZ)
+
+
+# The exact stop event pasted into issue #56 (VVS Vaihingen, S1 to Plochingen).
+VVS_STOP_EVENT = {
+    "location": {
+        "id": "de:08111:6002:1:3",
+        "isGlobalId": True,
+        "name": "Vaihingen",
+        "disassembledName": "Gleis 3",
+        "type": "platform",
+        "pointType": "TRACK",
+        "properties": {
+            "stopId": "5006002",
+            "platform": "3",
+            "platformName": "Gleis 3",
+            "plannedPlatformName": "Gleis 3",
+        },
+    },
+    "departureTimePlanned": "2026-07-18T18:25:00Z",
+    "departureTimeEstimated": "2026-07-18T18:26:00Z",
+    "isRealtimeControlled": True,
+    "transportation": {
+        "name": "S-Bahn S1",
+        "number": "S1",
+        "description": "Herrenberg - Stuttgart - Plochingen - Kirchheim (T)",
+        "destination": {"name": "Plochingen"},
+        "product": {"class": 1, "name": "S-Bahn"},
+    },
+}
+
+
+def _bus_stop_event() -> dict:
+    """A bus departure: technical platform present, readable label empty."""
+    return {
+        "location": {
+            "id": "de:08111:6002:0:A",
+            "name": "Vaihingen",
+            "disassembledName": "",
+            "type": "platform",
+            "pointType": "BUS_POINT",
+            "properties": {"stopId": "5006002", "platform": "A"},
+        },
+        "departureTimePlanned": "2026-07-18T18:25:00Z",
+        "departureTimeEstimated": "2026-07-18T18:25:00Z",
+        "transportation": {
+            "number": "92",
+            "destination": {"name": "Rohr"},
+            "product": {"class": 5, "name": "Stadtbus"},
+        },
+    }
+
+
+def test_vvs_maps_technical_platform():
+    """The platform attribute is the technical value from properties.platform."""
+    departure = VVSProvider(None).parse_departure(VVS_STOP_EVENT, TZ, NOW)
+
+    assert departure is not None
+    assert departure.platform == "3"
+    assert departure.line == "S1"
+    assert departure.destination == "Plochingen"
+
+
+def test_vvs_exposes_readable_platform_name_separately():
+    """The human-readable label is kept, but not as `platform`."""
+    departure = VVSProvider(None).parse_departure(VVS_STOP_EVENT, TZ, NOW)
+
+    assert departure.platform_name == "Gleis 3"
+    assert departure.to_dict()["platform"] == "3"
+    assert departure.to_dict()["platform_name"] == "Gleis 3"
+
+
+def test_planned_platform_name_is_not_a_platform_change():
+    """"3" vs "Gleis 3" is the same platform, not a real-time change."""
+    departure = VVSProvider(None).parse_departure(VVS_STOP_EVENT, TZ, NOW)
+
+    assert departure.platform_changed is False
+    assert departure.planned_platform is None
+    assert "planned_platform" not in departure.to_dict()
+
+
+def test_real_platform_change_is_detected():
+    """A genuinely different scheduled track still reports a change."""
+    event = {
+        **VVS_STOP_EVENT,
+        "location": {
+            **VVS_STOP_EVENT["location"],
+            "properties": {
+                **VVS_STOP_EVENT["location"]["properties"],
+                "platform": "5",
+                "platformName": "Gleis 5",
+            },
+        },
+    }
+
+    departure = VVSProvider(None).parse_departure(event, TZ, NOW)
+
+    assert departure.platform == "5"
+    assert departure.platform_changed is True
+    assert departure.planned_platform == "Gleis 3"
+    assert departure.to_dict()["platform_changed"] is True
+
+
+def test_bus_stop_keeps_technical_platform_without_readable_label():
+    """Bus stops have no "Gleis N" label but do have the technical value."""
+    departure = VVSProvider(None).parse_departure(_bus_stop_event(), TZ, NOW)
+
+    assert departure.platform == "A"
+    assert departure.platform_name is None
+    assert "platform_name" not in departure.to_dict()
+
+
+def test_all_efa_providers_share_the_fix():
+    """The fix lives in EFABaseProvider, so it is not VVS-specific."""
+    for provider in (VVSProvider(None), VRRProvider(None), KVVProvider(None), HVVProvider(None)):
+        departure = provider.parse_departure(VVS_STOP_EVENT, TZ, NOW)
+        assert departure is not None, provider.provider_id
+        assert departure.platform == "3", provider.provider_id
+
+
+def test_legacy_platform_shape_still_works():
+    """Pre-RapidJSON responses that use platform.name keep working."""
+    event = {
+        "departureTimePlanned": "2026-07-18T18:25:00Z",
+        "departureTimeEstimated": "2026-07-18T18:25:00Z",
+        "platform": {"name": "2"},
+        "transportation": {
+            "number": "U79",
+            "destination": {"name": "Duisburg Hbf"},
+            "product": {"class": 2, "name": "U-Bahn"},
+        },
+    }
+
+    departure = VRRProvider(None).parse_departure(event, TZ, NOW)
+
+    assert departure.platform == "2"
+
+
+def test_missing_platform_is_empty_not_an_error():
+    event = {
+        "departureTimePlanned": "2026-07-18T18:25:00Z",
+        "departureTimeEstimated": "2026-07-18T18:25:00Z",
+        "location": {"properties": None},
+        "transportation": {
+            "number": "92",
+            "destination": {"name": "Rohr"},
+            "product": {"class": 5, "name": "Stadtbus"},
+        },
+    }
+
+    departure = VVSProvider(None).parse_departure(event, TZ, NOW)
+
+    assert departure.platform == ""
+    assert departure.platform_changed is False
+
+
+def test_normalize_platform():
+    assert normalize_platform("Gleis 3") == "3"
+    assert normalize_platform("gleis 3") == "3"
+    assert normalize_platform("3") == "3"
+    assert normalize_platform(" Bstg. 12 ") == "12"
+    assert normalize_platform("Steig B") == "b"
+    assert normalize_platform("Platform 4") == "4"
+    assert normalize_platform("Track 1") == "1"
+    assert normalize_platform(None) == ""
+    assert normalize_platform("") == ""
+    # A platform genuinely named "Gleis" keeps a usable value
+    assert normalize_platform("Gleis") == ""
+    assert normalize_platform(3) == "3"