python-openpublictransport 0.1.0__py3-none-any.whl

openpublictransport/providers/otp.py

@@ -0,0 +1,378 @@
+"""Generic OTP2 provider base — used by the community server and custom instances."""
+
+import asyncio
+import logging
+import math
+import time
+from typing import Any, Dict, List, Optional
+
+import aiohttp
+
+from .otp_base import OTPBaseProvider
+
+_LOGGER = logging.getLogger(__name__)
+
+_CITY_PREFIXES: Dict[str, str] = {
+    "düsseldorf": "D-",
+    "duesseldorf": "D-",
+    "köln": "K-",
+    "koeln": "K-",
+    "cologne": "K-",
+    "dortmund": "Do-",
+    "essen": "E-",
+    "duisburg": "DU-",
+    "wuppertal": "W-",
+    "bochum": "BO-",
+    "bielefeld": "BI-",
+    "münster": "MS-",
+    "muenster": "MS-",
+    "aachen": "AC-",
+    "krefeld": "KR-",
+    "mönchengladbach": "MG-",
+    "moenchengladbach": "MG-",
+    "oberhausen": "OB-",
+    "hagen": "HA-",
+    "hamm": "HAM-",
+    "gelsenkirchen": "GE-",
+    "mülheim": "MH-",
+    "muelheim": "MH-",
+    "leverkusen": "LEV-",
+    "bonn": "BN-",
+}
+
+_GRAPHQL_STOP_SEARCH = (
+    '{ stops(name: "%s") { gtfsId name lat lon parentStation { gtfsId name } routes { agency { name } } } }'
+)
+
+
+def _smart_title(s: str) -> str:
+    return " ".join(w[0].upper() + w[1:] if w else w for w in s.split())
+
+
+def _primary_agency(stops: List[Dict[str, Any]]) -> str:
+    counts: Dict[str, int] = {}
+    for s in stops:
+        for route in s.get("routes") or []:
+            name = (route.get("agency") or {}).get("name", "")
+            if name:
+                counts[name] = counts.get(name, 0) + 1
+    return max(counts, key=lambda k: counts[k]) if counts else ""
+
+
+_GRAPHQL_NEAREST = """{
+  nearest(lat: %f, lon: %f, maxDistance: %d, filterByPlaceTypes: [STOP]) {
+    edges {
+      node {
+        place {
+          ... on Stop {
+            gtfsId
+            name
+            lat
+            lon
+            parentStation { gtfsId name }
+            routes { agency { name } }
+          }
+        }
+        distance
+      }
+    }
+  }
+}"""
+
+
+def _detect_city_prefix(search_term: str) -> Optional[str]:
+    words = search_term.strip().replace(",", " ").split()
+    for i, word in enumerate(words):
+        prefix = _CITY_PREFIXES.get(word.lower())
+        if prefix:
+            remaining = " ".join(w for j, w in enumerate(words) if j != i).strip()
+            if remaining:
+                return prefix + remaining
+    return None
+
+
+_MAX_PLATFORM_DISTANCE_M = 500
+
+
+def _haversine_m(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    r = 6_371_000
+    phi1, phi2 = math.radians(lat1), math.radians(lat2)
+    dphi = math.radians(lat2 - lat1)
+    dlambda = math.radians(lon2 - lon1)
+    a = math.sin(dphi / 2) ** 2 + math.cos(phi1) * math.cos(phi2) * math.sin(dlambda / 2) ** 2
+    return r * 2 * math.asin(math.sqrt(a))
+
+
+def _cluster_by_proximity(stops: List[Dict[str, Any]]) -> List[List[Dict[str, Any]]]:
+    n = len(stops)
+    parent = list(range(n))
+
+    def find(i: int) -> int:
+        while parent[i] != i:
+            parent[i] = parent[parent[i]]
+            i = parent[i]
+        return i
+
+    for i in range(n):
+        for j in range(i + 1, n):
+            si, sj = stops[i], stops[j]
+            if si.get("lat") and si.get("lon") and sj.get("lat") and sj.get("lon"):
+                if _haversine_m(si["lat"], si["lon"], sj["lat"], sj["lon"]) <= _MAX_PLATFORM_DISTANCE_M:
+                    parent[find(i)] = find(j)
+
+    groups: Dict[int, List[Dict[str, Any]]] = {}
+    for i, stop in enumerate(stops):
+        groups.setdefault(find(i), []).append(stop)
+    return list(groups.values())
+
+
+_GRAPHQL_STOPTIMES = """{
+  stop(id: "%s") {
+    name
+    alerts {
+      alertHeaderText
+      alertDescriptionText
+    }
+    stoptimesWithoutPatterns(numberOfDepartures: %d, startTime: %d) {
+      serviceDay
+      scheduledDeparture
+      realtimeDeparture
+      departureDelay
+      realtime
+      headsign
+      trip {
+        alerts {
+          alertHeaderText
+          alertDescriptionText
+        }
+        route {
+          shortName
+          mode
+          color
+          textColor
+          agency {
+            name
+          }
+          alerts {
+            alertHeaderText
+            alertDescriptionText
+          }
+        }
+      }
+    }
+  }
+}"""
+
+
+class OTPProvider(OTPBaseProvider):
+    """Generic OTP2 provider — subclass and set otp_base_url, provider_id, provider_name."""
+
+    otp_base_url: str = ""
+
+    @property
+    def _effective_base_url(self) -> str:
+        return (self.custom_url or "").rstrip("/") or self.otp_base_url
+
+    def _auth_headers(self) -> Dict[str, str]:
+        headers = {"Accept": "application/json", "Content-Type": "application/json"}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        return headers
+
+    async def _graphql(self, query: str) -> Optional[Dict[str, Any]]:
+        url = f"{self._effective_base_url}/index/graphql"
+        try:
+            async with self.session.post(
+                url,
+                json={"query": query},
+                headers=self._auth_headers(),
+                timeout=aiohttp.ClientTimeout(total=15),
+            ) as resp:
+                if resp.status == 200:
+                    return await resp.json()
+                _LOGGER.warning("%s GraphQL → HTTP %s", self.provider_name, resp.status)
+        except Exception as exc:
+            _LOGGER.warning("%s GraphQL request failed: %s", self.provider_name, exc)
+        return None
+
+    def _raw_stops_from_body(self, body: Optional[Dict]) -> List[Dict[str, Any]]:
+        return [
+            s for s in (((body or {}).get("data") or {}).get("stops") or []) if isinstance(s, dict) and "gtfsId" in s
+        ]
+
+    def _group_by_name(self, raw_stops: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        by_parent: Dict[str, List[Dict[str, Any]]] = {}
+        no_parent: List[Dict[str, Any]] = []
+
+        for s in raw_stops:
+            parent = s.get("parentStation")
+            if parent and parent.get("gtfsId"):
+                by_parent.setdefault(parent["gtfsId"], []).append(s)
+            else:
+                no_parent.append(s)
+
+        result = []
+
+        for stops in by_parent.values():
+            compound_id = "|".join(s["gtfsId"] for s in stops)
+            name = (stops[0].get("parentStation") or {}).get("name") or stops[0]["name"]
+            agency = _primary_agency(stops)
+            result.append({"id": compound_id, "name": name, "place": name, "agency": agency, "area_type": "stop"})
+
+        by_name: Dict[str, List[Dict[str, Any]]] = {}
+        for s in no_parent:
+            by_name.setdefault(s["name"], []).append(s)
+        for name, stops in by_name.items():
+            for cluster in _cluster_by_proximity(stops):
+                compound_id = "|".join(s["gtfsId"] for s in cluster)
+                agency = _primary_agency(cluster)
+                result.append({"id": compound_id, "name": name, "place": name, "agency": agency, "area_type": "stop"})
+
+        return result
+
+    async def _search_one(self, term: str) -> List[Dict[str, Any]]:
+        q = _GRAPHQL_STOP_SEARCH % term.replace('"', '\\"')
+        return self._raw_stops_from_body(await self._graphql(q))
+
+    async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
+        """Search stops via OTP2 GraphQL with city-prefix fallback for VRR/NRW."""
+        ss_term = search_term.replace("ß", "ss") if "ß" in search_term else None
+        smart_term = _smart_title(search_term)
+        smart_term = smart_term if smart_term != search_term else None
+
+        for term in filter(None, [search_term, ss_term, smart_term]):
+            raw = await self._search_one(term)
+            if raw:
+                return self._group_by_name(raw)[:20]
+
+        detected = _detect_city_prefix(search_term)
+        if detected:
+            raw = await self._search_one(detected)
+            if raw:
+                return self._group_by_name(raw)[:20]
+            detected_ss = detected.replace("ß", "ss") if "ß" in detected else None
+            if detected_ss:
+                raw = await self._search_one(detected_ss)
+                if raw:
+                    return self._group_by_name(raw)[:20]
+
+        prefixed = [p + search_term for p in _CITY_PREFIXES.values()]
+        if ss_term:
+            prefixed += [p + ss_term for p in _CITY_PREFIXES.values()]
+        seen_terms: set = set()
+        unique = [t for t in prefixed if not (t in seen_terms or seen_terms.add(t))]  # type: ignore[func-returns-value]
+
+        bodies = await asyncio.gather(*[self._graphql(_GRAPHQL_STOP_SEARCH % t.replace('"', '\\"')) for t in unique])
+        all_raw: List[Dict[str, Any]] = []
+        seen_ids: set = set()
+        for body in bodies:
+            for stop in self._raw_stops_from_body(body):
+                if stop["gtfsId"] not in seen_ids:
+                    seen_ids.add(stop["gtfsId"])
+                    all_raw.append(stop)
+        if all_raw:
+            return self._group_by_name(all_raw)[:20]
+
+        coords = await self._geocode(search_term)
+        if coords is None:
+            _LOGGER.warning("%s: could not geocode '%s'", self.provider_name, search_term)
+            return []
+        lat, lon = coords
+        q = _GRAPHQL_NEAREST % (lat, lon, self.stop_search_radius)
+        body = await self._graphql(q)
+        edges = (((body or {}).get("data") or {}).get("nearest") or {}).get("edges") or []
+        raw = [
+            edge["node"]["place"]
+            for edge in edges
+            if isinstance((edge.get("node") or {}).get("place"), dict) and "gtfsId" in edge["node"]["place"]
+        ]
+        if raw:
+            return self._group_by_name(raw)[:20]
+        return []
+
+    @staticmethod
+    def _alert_texts(alerts: Optional[List[Dict[str, Any]]]) -> List[str]:
+        seen: set = set()
+        result = []
+        for a in alerts or []:
+            text = (a.get("alertHeaderText") or a.get("alertDescriptionText") or "").strip()
+            if text and text not in seen:
+                seen.add(text)
+                result.append(text)
+        return result
+
+    def _stoptimes_to_events(self, stoptimes: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        mode_mapping = self.get_mode_mapping()
+        events = []
+        for st in stoptimes:
+            trip = st.get("trip") or {}
+            route = trip.get("route") or {}
+            trip_notices = self._alert_texts(trip.get("alerts"))
+            route_notices = [t for t in self._alert_texts(route.get("alerts")) if t not in trip_notices]
+            notices = trip_notices + route_notices
+            raw_color = route.get("color") or ""
+            raw_text = route.get("textColor") or ""
+            events.append(
+                {
+                    "routeName": route.get("shortName", ""),
+                    "transportType": mode_mapping.get(route.get("mode", ""), "unknown"),
+                    "agency": (route.get("agency") or {}).get("name", ""),
+                    "notices": notices or None,
+                    "serviceDay": st.get("serviceDay", 0),
+                    "scheduledDeparture": st.get("scheduledDeparture", 0),
+                    "realtimeDeparture": st.get("realtimeDeparture", 0),
+                    "departureDelay": st.get("departureDelay", 0),
+                    "realtime": st.get("realtime", False),
+                    "headsign": st.get("headsign", ""),
+                    "lineColor": f"#{raw_color}" if raw_color and not raw_color.startswith("#") else raw_color or None,
+                    "lineTextColor": f"#{raw_text}" if raw_text and not raw_text.startswith("#") else raw_text or None,
+                }
+            )
+        return events
+
+    async def _fetch_one_stop(self, gtfs_id: str, limit: int, start_epoch: int) -> List[Dict[str, Any]]:
+        q = _GRAPHQL_STOPTIMES % (gtfs_id.replace('"', '\\"'), limit, start_epoch)
+        body = await self._graphql(q)
+        if body is None:
+            return []
+        stop_data = ((body.get("data") or {}).get("stop")) or {}
+        stoptimes = stop_data.get("stoptimesWithoutPatterns") or []
+        events = self._stoptimes_to_events(stoptimes)
+        stop_notices = self._alert_texts(stop_data.get("alerts"))
+        if stop_notices:
+            for ev in events:
+                existing = ev.get("notices") or []
+                ev["notices"] = stop_notices + [n for n in existing if n not in stop_notices]
+        return events
+
+    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:
+            return None
+
+        gtfs_ids = station_id.split("|")
+        start_epoch = int(time.time())
+
+        if len(gtfs_ids) == 1:
+            events = await self._fetch_one_stop(gtfs_ids[0], departures_limit, start_epoch)
+        else:
+            results = await asyncio.gather(
+                *[self._fetch_one_stop(gid, departures_limit, start_epoch) for gid in gtfs_ids]
+            )
+            seen_keys: set = set()
+            merged = []
+            for batch in results:
+                for ev in batch:
+                    key = (ev["serviceDay"], ev["realtimeDeparture"], ev["routeName"], ev["headsign"])
+                    if key not in seen_keys:
+                        seen_keys.add(key)
+                        merged.append(ev)
+            merged.sort(key=lambda x: x["serviceDay"] + x["realtimeDeparture"])
+            events = merged[:departures_limit]
+
+        return {"stopEvents": events}

openpublictransport/providers/otp_base.py

@@ -0,0 +1,268 @@
+"""Base provider for OpenTripPlanner (OTP) REST API."""
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple, Union
+from urllib.parse import quote
+from zoneinfo import ZoneInfo
+
+import aiohttp
+
+from ..models import UnifiedDeparture
+from .base import BaseProvider
+
+_LOGGER = logging.getLogger(__name__)
+
+_NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
+_NOMINATIM_UA = "openpublictransport/1.0 (github.com/NerdySoftPaw/openpublictransport)"
+
+
+def _nominatim_candidates(term: str) -> List[str]:
+    """Return progressively simpler Nominatim queries for a search term."""
+    candidates: List[str] = [term]
+
+    if "," in term:
+        parts = [p.strip() for p in term.split(",", 1)]
+        swapped = " ".join(reversed(parts))
+        if swapped not in candidates:
+            candidates.append(swapped)
+
+    words = term.replace(",", " ").split()
+    if len(words) > 2:
+        for i in range(len(words)):
+            shorter = " ".join(w for j, w in enumerate(words) if j != i)
+            if shorter not in candidates:
+                candidates.append(shorter)
+
+    return candidates
+
+
+OTP_MODE_MAP: Dict[str, str] = {
+    "BUS": "bus",
+    "COACH": "bus",
+    "RAIL": "train",
+    "TRAM": "tram",
+    "SUBWAY": "subway",
+    "FERRY": "ferry",
+    "GONDOLA": "tram",
+    "FUNICULAR": "train",
+    "CABLE_CAR": "tram",
+}
+
+
+class OTPBaseProvider(BaseProvider):
+    """Base class for OpenTripPlanner REST API providers."""
+
+    otp_base_url: str = ""
+    stop_search_radius: int = 500
+
+    def get_timezone(self) -> str:
+        return "Europe/Berlin"
+
+    def get_mode_mapping(self) -> Dict[str, str]:
+        return OTP_MODE_MAP
+
+    def _auth_headers(self) -> Dict[str, str]:
+        """Request headers — override in subclasses to add API key auth."""
+        return {"Accept": "application/json"}
+
+    def _index_url(self, path: str) -> str:
+        return f"{self.otp_base_url}/index/{path}"
+
+    async def _get(
+        self,
+        url: str,
+        params: Optional[Dict] = None,
+    ) -> Optional[Any]:
+        try:
+            async with self.session.get(
+                url,
+                params=params or {},
+                headers=self._auth_headers(),
+                timeout=aiohttp.ClientTimeout(total=15),
+            ) as resp:
+                if resp.status == 200:
+                    return await resp.json()
+                if resp.status == 204:
+                    return None
+                _LOGGER.warning("%s OTP %s → HTTP %s", self.provider_name, url, resp.status)
+        except aiohttp.ClientError as exc:
+            _LOGGER.warning("%s OTP request failed: %s", self.provider_name, exc)
+        except Exception as exc:
+            _LOGGER.warning("%s OTP error: %s", self.provider_name, exc)
+        return None
+
+    async def _geocode(self, search_term: str) -> Optional[Tuple[float, float]]:
+        """Resolve a stop name to (lat, lon) via Nominatim / OpenStreetMap."""
+        for i, candidate in enumerate(_nominatim_candidates(search_term)):
+            if i > 0:
+                await asyncio.sleep(0.3)
+            try:
+                async with self.session.get(
+                    _NOMINATIM_URL,
+                    params={"q": candidate, "format": "json", "limit": 1, "countrycodes": "de"},
+                    headers={"User-Agent": _NOMINATIM_UA, "Accept": "application/json"},
+                    timeout=aiohttp.ClientTimeout(total=10),
+                ) as resp:
+                    if resp.status == 200:
+                        results = await resp.json(content_type=None)
+                        if results:
+                            if i > 0:
+                                _LOGGER.debug(
+                                    "%s: Nominatim hit on simplified query '%s'", self.provider_name, candidate
+                                )
+                            return float(results[0]["lat"]), float(results[0]["lon"])
+            except Exception as exc:
+                _LOGGER.debug("%s: Nominatim geocode error: %s", self.provider_name, exc)
+        _LOGGER.warning("%s: Nominatim found nothing for '%s'", self.provider_name, search_term)
+        return None
+
+    async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
+        """Search stops by geocoding the term, then finding nearby OTP stops."""
+        coords = await self._geocode(search_term)
+        if coords is None:
+            _LOGGER.warning(
+                "%s: could not geocode '%s' — check your search term",
+                self.provider_name,
+                search_term,
+            )
+            return []
+
+        lat, lon = coords
+        data = await self._get(
+            self._index_url("stops"),
+            {"lat": lat, "lon": lon, "radius": self.stop_search_radius},
+        )
+        if not data:
+            return []
+
+        return [
+            {
+                "id": s["id"],
+                "name": s.get("name", ""),
+                "place": s.get("name", ""),
+                "area_type": "stop",
+            }
+            for s in sorted(data, key=lambda x: x.get("dist", 0))
+            if isinstance(s, dict) and "id" in s
+        ]
+
+    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:
+            return None
+
+        encoded_id = quote(station_id, safe="")
+        mode_mapping = self.get_mode_mapping()
+
+        routes_data, alerts_data, stoptimes = await asyncio.gather(
+            self._get(self._index_url(f"stops/{encoded_id}/routes")),
+            self._get(self._index_url(f"stops/{encoded_id}/alerts")),
+            self._get(
+                self._index_url(f"stops/{encoded_id}/stoptimes"),
+                {
+                    "timeRange": 7200,
+                    "numberOfDepartures": max(departures_limit, 5),
+                    "omitNonPickups": "true",
+                },
+            ),
+        )
+
+        route_map: Dict[str, Dict[str, str]] = {}
+        if routes_data:
+            for r in routes_data:
+                if isinstance(r, dict) and "id" in r and r["id"] not in route_map:
+                    agency = r.get("agencyName") or (r["agency"]["name"] if isinstance(r.get("agency"), dict) else None)
+                    route_map[r["id"]] = {
+                        "shortName": r.get("shortName") or r.get("longName", ""),
+                        "mode": mode_mapping.get(r.get("mode", ""), "unknown"),
+                        "agency": agency or "",
+                    }
+
+        stop_notices: List[str] = []
+        if alerts_data:
+            seen: set = set()
+            for alert in alerts_data:
+                if not isinstance(alert, dict):
+                    continue
+                text = alert.get("alertHeaderText") or alert.get("alertDescriptionText") or ""
+                if text and text not in seen:
+                    stop_notices.append(text)
+                    seen.add(text)
+        if stoptimes is None:
+            return None
+
+        stop_events = []
+        for group in stoptimes:
+            if not isinstance(group, dict):
+                continue
+            pattern = group.get("pattern", {})
+            route_id = pattern.get("routeId", "")
+            route_info = route_map.get(route_id, {})
+
+            for t in group.get("times", []):
+                if not isinstance(t, dict):
+                    continue
+                stop_events.append(
+                    {
+                        "routeName": route_info.get("shortName") or pattern.get("desc", ""),
+                        "transportType": route_info.get("mode", "unknown"),
+                        "agency": route_info.get("agency", ""),
+                        "notices": stop_notices or None,
+                        "serviceDay": t.get("serviceDay", 0),
+                        "scheduledDeparture": t.get("scheduledDeparture", 0),
+                        "realtimeDeparture": t.get("realtimeDeparture", 0),
+                        "departureDelay": t.get("departureDelay", 0),
+                        "realtime": t.get("realtime", False),
+                        "headsign": t.get("headsign", ""),
+                    }
+                )
+
+        stop_events.sort(key=lambda x: x["serviceDay"] + x["realtimeDeparture"])
+        return {"stopEvents": stop_events[:departures_limit]}
+
+    def parse_departure(
+        self,
+        stop: Dict[str, Any],
+        tz: Union[ZoneInfo, Any],
+        now: datetime,
+    ) -> Optional[UnifiedDeparture]:
+        try:
+            service_day: int = stop["serviceDay"]
+            planned = datetime.fromtimestamp(service_day + stop["scheduledDeparture"], tz=timezone.utc).astimezone(tz)
+            actual = datetime.fromtimestamp(service_day + stop["realtimeDeparture"], tz=timezone.utc).astimezone(tz)
+
+            delay_min = max(0, int(stop.get("departureDelay", 0) / 60))
+            minutes_until = max(0, int((actual - now).total_seconds() / 60))
+
+            agency = stop.get("agency") or None
+            notices = stop.get("notices") or None
+
+            return UnifiedDeparture(
+                line=stop.get("routeName", ""),
+                destination=stop.get("headsign", "Unknown"),
+                departure_time=actual.strftime("%H:%M"),
+                planned_time=planned.strftime("%H:%M"),
+                delay=delay_min,
+                platform="",
+                transportation_type=stop.get("transportType", "unknown"),
+                is_realtime=stop.get("realtime", False),
+                minutes_until_departure=minutes_until,
+                departure_time_obj=actual,
+                description=None,
+                agency=agency,
+                notices=notices,
+                planned_platform=None,
+                platform_changed=False,
+                line_color=stop.get("lineColor") or None,
+                line_text_color=stop.get("lineTextColor") or None,
+            )
+        except Exception as exc:
+            _LOGGER.debug("%s OTP parse_departure error: %s", self.provider_name, exc)
+            return None

openpublictransport/providers/otp_custom.py

@@ -0,0 +1,22 @@
+"""Generic OTP2 provider for user-hosted instances.
+
+Users supply their own OTP2 base URL (e.g. http://192.168.1.10:8080/otp/routers/default)
+and an optional X-API-Key.  Stop search and departure logic are identical to the
+community server — this is a thin subclass that sets no default URL.
+"""
+
+from .otp import OTPProvider
+
+
+class OTPCustomProvider(OTPProvider):
+    """User-provided OTP2 instance with configurable URL and optional API key."""
+
+    otp_base_url = ""  # always overridden by self.custom_url set via constructor
+
+    @property
+    def provider_id(self) -> str:
+        return "otp_custom"
+
+    @property
+    def provider_name(self) -> str:
+        return "Custom OTP Server"