1"""
  2.. include:: ../README.md
  3
  4---
  5"""
  6from __future__ import annotations
  7
  8import logging
  9
 10from abc import ABCMeta
 11from dataclasses import dataclass
 12from datetime import datetime
 13from typing import Iterable
 14
 15from .data import ID, API, ThreadedAPI, ScheduledEvent, Position
 16from .exceptions import InitialConnectionError
 17
 18logger = logging.getLogger(__name__)
 19
 20__all__ = [
 21    "bus",
 22    "data",
 23    "exceptions",
 24    "mixins",
 25    "other",
 26    "plane",
 27    "protocols",
 28    "ship",
 29    "train",
 30    "units",
 31    "Vehicle",
 32    "Station",
 33    "ConnectingVehicle",
 34]
 35
 36
 37class Vehicle(metaclass=ABCMeta):
 38    """
 39    Base class for all vehicles
 40    """
 41
 42    _api: API
 43    """The :class:`API` that supplies the data for this vehicle."""
 44
 45    def __enter__(self):
 46        self.init()
 47        return self
 48
 49    def __exit__(self, exc_type, exc_val, exc_tb):
 50        self.shutdown()
 51
 52    def init(self) -> None:
 53        """Initialize the connection to the API.
 54
 55        Call the init method of the API that supplies the data for this vehicle.
 56
 57        Raises:
 58          InitialConnectionError: If the connection to the API could not be established.
 59        """
 60        if not hasattr(self, '_api'):
 61            return  # Abstract class without API implementation
 62
 63        try:
 64            self._api.init()
 65            if isinstance(self._api, ThreadedAPI):
 66                self._api.start()
 67                # noinspection PyProtectedMember
 68                if not self._api.ready.wait(timeout=max(self._api._interval * 1.5, 15)):
 69                    raise RuntimeError('API readiness period timed out!')
 70                return
 71        except RuntimeError as e:
 72            raise InitialConnectionError from e
 73
 74    def shutdown(self) -> None:
 75        """
 76        This method will be called when exiting the context manager.
 77
 78        :return: Nothing
 79        :rtype: None
 80        """
 81        if not hasattr(self, '_api'):
 82            return  # Abstract class without API implementation
 83
 84        if isinstance(self._api, ThreadedAPI):
 85            self._api.stop()
 86
 87    @property
 88    def now(self) -> datetime:
 89        """
 90        Get the current time as seen by the vehicle
 91
 92        :return: The current time
 93        :rtype: datetime.datetime
 94        """
 95        return datetime.now()
 96
 97    @property
 98    def id(self) -> ID:
 99        """
100        :return: The ID of the vehicle
101        :raises DataInvalidError: If the ID could not be fetched from the server
102        """
103        return 'undefined'
104
105
106@dataclass
107class ConnectingVehicle(object):
108    """
109    A connecting vehicle is a vehicle that is not part of the main trip but of a connecting service.
110    It may only have limited information available.
111    """
112    vehicle_type: str | None
113    """The abbreviated vehicle type"""
114    line_number: str | None
115    """The line number of the vehicle"""
116    departure: ScheduledEvent[datetime] | None
117    """The departure time of the vehicle"""
118    destination: str | None
119    """The destination of the vehicle"""
120
121
122@dataclass
123class Station(object):
124    """
125    A Station is a stop on the trip
126    """
127    # noinspection PyTypeHints
128    id: ID
129    """The ID of the station"""
130    name: str
131    """The name of the station"""
132    arrival: ScheduledEvent[datetime] | None
133    """The arrival time at this station"""
134    departure: ScheduledEvent[datetime] | None
135    """The departure time from this station"""
136    position: Position | None
137    """The geographic position of the station"""
138    distance: float | None
139    """The distance from the start to this station"""
140    _connections: Iterable[ConnectingVehicle]
141
142    def __str__(self) -> str:
143        return self.name
144
145    @property
146    def connections(self) -> list[ConnectingVehicle]:
147        """The connecting services departing from this station."""
148        if not isinstance(self._connections, list):
149            self._connections = list(self._connections)
150        return self._connections
151
152    def calculate_distance(self, other: Station | Position | int | float) -> float | None:
153        """
154        Calculate the distance in meters between this station and something else.
155
156        Accepts a :class:`Station`, :class:`Position` or a number for the distance calculation.
157
158        :param other: The other station or position to calculate the distance to
159        :type other: Station | Position | int | float
160        :return: The distance in meters
161        :rtype: Optional[float]
162        """
163        # If there is not enough information to calculate the distance, return None
164        if other is None:
165            return None
166
167        # Both distances since the start are known
168        if isinstance(other, (int, float)) and self.distance is not None:
169            return abs(self.distance - other)
170
171        # Both positions are known
172        if isinstance(other, Position) and self.position is not None:
173            return self.position.calculate_distance(other)
174
175        # Both are a station
176        if isinstance(other, Station):
177            if self.distance is not None and other.distance is not None:
178                return abs(self.distance - other.distance)
179            if self.position is not None and other.position is not None:
180                return self.position.calculate_distance(other.position)
181        # No distance could be determined
182        return None