onboardapis.train

  1"""
  2Package for trains
  3
  4## Operator ID
  5
  6The operator ID for trains is different depending on the region.
  7
  8For Europe, the operator ID is the [VKM register code](https://www.era.europa.eu/domains/registers/vkm_en).
  9
 10---
 11
 12Contains the following countries:
 13
 14- ``onboardapis.train.at`` - Austria
 15- ``onboardapis.train.cz`` - Czechia
 16- ``onboardapis.train.de`` - Germany
 17- ``onboardapis.train.fr`` - France
 18- ``onboardapis.train.it`` - Italy
 19
 20---
 21"""
 22from __future__ import annotations
 23
 24import logging
 25
 26from abc import ABCMeta
 27from dataclasses import dataclass
 28from typing import cast
 29
 30from .. import Vehicle, Station, ConnectingVehicle
 31from ..data import ScheduledEvent
 32
 33# noinspection PyUnresolvedReferences
 34from typing import Iterable  # for associations while generating docs
 35# noinspection PyUnresolvedReferences
 36from ..data import ID, Position  # noqa: F401  # for associations while generating docs
 37# noinspection PyUnresolvedReferences
 38from datetime import datetime  # noqa: F401  # for associations while generating docs
 39
 40logger = logging.getLogger(__name__)
 41
 42
 43__all__ = [
 44    "at",
 45    "cz",
 46    "de",
 47    "fr",
 48    "it",
 49    "third_party",
 50    "TrainStation",
 51    "Train",
 52    "ConnectingTrain",
 53]
 54
 55
 56@dataclass
 57class TrainStation(Station):
 58    """
 59    An `onboardapis.Station` with the additional information of a platform
 60    """
 61    _connections: Iterable[ConnectingTrain]
 62
 63    platform: ScheduledEvent[str] | None
 64    """The platform where the train arrives."""
 65
 66    @property
 67    def connections(self) -> list[ConnectingTrain]:
 68        return cast(list[ConnectingTrain], super().connections)  # maybe force type instead of casting?
 69
 70
 71class Train(Vehicle, metaclass=ABCMeta):
 72    """
 73    Base class for all train implementations.
 74    """
 75
 76    def __repr__(self) -> str:
 77        return f"<{self.__class__.__name__}>"
 78
 79    @property
 80    def type(self) -> str:
 81        """
 82        :return: The abbreviated train type
 83        :raises DataInvalidError: If the train type could not be fetched from the server
 84        """
 85        return 'undefined'
 86
 87    @property
 88    def line_number(self) -> str:
 89        """
 90        :return: The line number
 91        :raises DataInvalidError: If the line number could not be fetched from the server
 92        """
 93        return 'undefined'
 94
 95
 96@dataclass
 97class ConnectingTrain(ConnectingVehicle):
 98    """
 99    A connecting train is a train that is not part of the main trip but of a connecting service
100
101    It may only have limited information available
102    """
103
104    platform: ScheduledEvent[str] | None
105    """
106    The platform where the train will depart from
107    """