pyrail-uk 0.1.0__tar.gz

pyrail_uk-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: pyrail-uk
+Version: 0.1.0
+Summary: Python SDK for dealing with the National Rail API
+Author-email: Christopher Khoo <khoojinnwei@gmail.com>
+License: MIT
+Project-URL: repository, https://github.com/thekhoo/pyrail-uk
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: ~=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: cachetools
+Provides-Extra: development
+Requires-Dist: pytest; extra == "development"
+Requires-Dist: pytest-sugar; extra == "development"
+Requires-Dist: pyrefly; extra == "development"
+Requires-Dist: ruff; extra == "development"
+Requires-Dist: black; extra == "development"
+Requires-Dist: isort; extra == "development"
+Provides-Extra: local
+Requires-Dist: boto3; extra == "local"
+Requires-Dist: boto3-stubs[ssm]; extra == "local"
+Requires-Dist: python-dotenv; extra == "local"
+Provides-Extra: deploy
+Requires-Dist: build; extra == "deploy"
+Requires-Dist: twine; extra == "deploy"
+
+# PyRail
+
+An easier way to deal with the National Rail API
+
+## Supported APIs
+
+- [Departure Board with Details](https://raildata.org.uk/dashboard/dataProduct/P-9a01dd96-7211-4912-bcbb-c1b5d2e35609/overview)
+- [Reference Data (Stations Only)](https://raildata.org.uk/dashboard/dataProduct/P-c73f0d2a-c233-497d-846b-8354e2cac326/overview)

pyrail_uk-0.1.0/README.md

@@ -0,0 +1,8 @@
+# PyRail
+
+An easier way to deal with the National Rail API
+
+## Supported APIs
+
+- [Departure Board with Details](https://raildata.org.uk/dashboard/dataProduct/P-9a01dd96-7211-4912-bcbb-c1b5d2e35609/overview)
+- [Reference Data (Stations Only)](https://raildata.org.uk/dashboard/dataProduct/P-c73f0d2a-c233-497d-846b-8354e2cac326/overview)

pyrail_uk-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "pyrail-uk"
+version = "0.1.0"
+description = "Python SDK for dealing with the National Rail API"
+readme = "README.md"
+authors = [
+  { name = "Christopher Khoo", email = "khoojinnwei@gmail.com" },
+]
+license = {text = "MIT"}
+dependencies = ["requests", "cachetools"]
+requires-python = "~=3.13"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+[project.urls]
+repository = "https://github.com/thekhoo/pyrail-uk"
+
+[project.optional-dependencies]
+development = [
+  # unit tests
+  'pytest',
+  'pytest-sugar',
+  # linters
+  'pyrefly',
+  'ruff',
+  'black',
+  'isort'
+]
+local=["boto3", "boto3-stubs[ssm]", "python-dotenv"]
+deploy=["build", "twine"]
+
+
+[tool.setuptools.packages.find]
+exclude = ["tests"]
+
+[tool.black]
+line-length = 120
+
+[tool.ruff]
+# Directories to scan
+include = ["pyrail_uk/**/*.py"]
+
+[tool.pyrefly]
+project-includes=["pyrail_uk/**/*.py"]
+
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"

pyrail_uk-0.1.0/pyrail_uk/NationalRail.py

@@ -0,0 +1,38 @@
+import typing as t
+
+from pyrail_uk.api.departures import NationalRailAPIRequestClient
+from pyrail_uk.api.referencedata import NationalRailReferenceDataRequestClient
+
+from .service.departures import simplify_departures
+from .service.stations import find_crs_by_station_name, find_station_by_crs
+
+
+class NationalRailClient:
+
+    def __init__(self, departure_board_token: str, reference_data_token: str):
+        self.dep_client = NationalRailAPIRequestClient(departure_board_token)
+        self.ref_data_client = NationalRailReferenceDataRequestClient(reference_data_token)
+
+    def get_trains(
+        self,
+        dep_crs: str,
+        arr_crs: t.Optional[str] = None,
+        timeoffset_mins: int = 0,
+        timewindow_mins: int = 120,
+        simplified: bool = False,
+    ):
+        res = self.dep_client.get_departures(dep_crs, arr_crs, timeoffset_mins, timewindow_mins)
+
+        # allow users the option to get the full response
+        if not simplified:
+            return res
+
+        return simplify_departures(departures_data=res)
+
+    def get_station_name_by_crs(self, crs: str) -> str:
+        stations = self.ref_data_client.get_stations()
+        return find_station_by_crs(stations, crs)
+
+    def get_crs_by_station_name(self, station_name: str) -> str:
+        stations = self.ref_data_client.get_stations()
+        return find_crs_by_station_name(stations, station_name)

pyrail_uk-0.1.0/pyrail_uk/api/client.py

@@ -0,0 +1,29 @@
+import logging
+import typing as t
+
+import requests as r
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+logger = logging.getLogger(__name__)
+
+
+class APIClient:
+
+    def __init__(self, token: str, headers: t.Optional[dict] = None, retry_strategy: t.Optional[Retry] = None):
+        self.token = token
+        self.session = r.Session()
+
+        if headers:
+            self.session.headers.update(headers)
+
+        if retry_strategy:
+            adapter = HTTPAdapter(max_retries=retry_strategy)
+            self.session.mount("https://", adapter)
+            self.session.mount("http://", adapter)
+
+    def get(self, url: str):
+        logger.debug(f"Making GET request to URL: {url}")
+        res = self.session.get(url=url)
+        res.raise_for_status()
+        return res.json()

pyrail_uk-0.1.0/pyrail_uk/api/departures.py

@@ -0,0 +1,28 @@
+import logging
+import typing as t
+
+from urllib3.util.retry import Retry
+
+from .client import APIClient
+from .types import DepBoardWithDetailsResponseTypeDef
+from .url import get_departure_board_url
+
+logger = logging.getLogger(__name__)
+
+
+class NationalRailAPIRequestClient(APIClient):
+
+    def __init__(self, token: str, retry_strategy: t.Optional[Retry] = None):
+        super().__init__(
+            token,
+            headers={"x-apikey": token, "Accept": "*/*", "User-Agent": "pyrail-sdk", "Origin": "localhost"},
+            retry_strategy=retry_strategy,
+        )
+
+    def get_departures(
+        self, dep_crs: str, arr_crs: t.Optional[str] = None, timeoffset_mins: int = 0, timewindow_mins: int = 120
+    ) -> DepBoardWithDetailsResponseTypeDef:
+        url = get_departure_board_url(
+            dep_crs, arr_crs=arr_crs, timeoffset_mins=timeoffset_mins, timewindow_mins=timewindow_mins
+        )
+        return self.get(url=url)

pyrail_uk-0.1.0/pyrail_uk/api/referencedata.py

@@ -0,0 +1,35 @@
+import logging
+import typing as t
+
+from cachetools import TTLCache
+from urllib3.util.retry import Retry
+
+from .client import APIClient
+from .types import StationCRSTypeDef, StationListResponseTypeDef
+from .url import get_station_list_url
+
+logger = logging.getLogger(__name__)
+
+
+class NationalRailReferenceDataRequestClient(APIClient):
+
+    def __init__(self, token: str, retry_strategy: t.Optional[Retry] = None, cache_ttl_seconds: int = 300):
+        super().__init__(
+            token,
+            headers={"x-apikey": token, "Accept": "*/*", "User-Agent": "pyrail-sdk", "Origin": "localhost"},
+            retry_strategy=retry_strategy,
+        )
+
+        self.cache = TTLCache(maxsize=1, ttl=float(cache_ttl_seconds))
+
+    def get_stations(self) -> list[StationCRSTypeDef]:
+        if "stations" in self.cache:
+            logger.debug("stations data found within the cache, not requesting!")
+            return self.cache["stations"]
+
+        url = get_station_list_url()
+        res: StationListResponseTypeDef = self.get(url)
+
+        stations = res.get("StationList", [])
+        self.cache["stations"] = stations
+        return stations

pyrail_uk-0.1.0/pyrail_uk/api/types.py

@@ -0,0 +1,92 @@
+from typing import NotRequired, TypedDict
+
+
+class DepartureResponseMetadataTypeDef(TypedDict):
+    Count: int
+
+
+class NRCCMessagesTypeDef(TypedDict):
+    Value: str
+
+
+class DestinationTypeDef(TypedDict):
+    crs: str
+    locationName: str
+    assocIsCancelled: bool
+
+
+class CallingPointTypeDef(TypedDict):
+    locationName: str
+    crs: str
+
+    st: str  # Scheduled time
+    et: str  # Estimated time
+
+    isCancelled: bool
+    length: int
+    detachFront: bool
+    delayReason: NotRequired[str]
+    affectedByDiversion: bool
+    rerouteDelay: int
+
+
+class SubsequentCallingPointsTypeDef(TypedDict):
+    callingPoint: list[CallingPointTypeDef]
+    serviceType: str
+    serviceChangeRequired: bool
+    assocIsCancelled: bool
+
+
+class TrainServiceTypeDef(TypedDict):
+    serviceID: str
+    cancelReason: NotRequired[str]
+    delayReason: NotRequired[str]
+    isReverseFormation: bool
+    detachFront: bool
+    length: int
+    serviceType: str
+    filterLocationCancelled: bool
+    isCancelled: bool
+    isCircularRoute: bool
+
+    operatorCode: str
+    operator: str
+
+    platform: NotRequired[str]
+    etd: str  # Estimated Time of Departure
+    std: str  # Scheduled Time of Departure
+    rsid: str
+
+    # i honestly have no idea what these 2 fields mean... they're always false
+    futureCancellation: bool
+    futureDelay: bool
+
+    currentDestinations: list[DestinationTypeDef]
+    origin: list[DestinationTypeDef]
+    destination: list[DestinationTypeDef]
+
+    subsequentCallingPoints: list[SubsequentCallingPointsTypeDef]
+
+
+class DepBoardWithDetailsResponseTypeDef(TypedDict):
+    Xmlns: DepartureResponseMetadataTypeDef
+    areServicesAvailable: bool
+    crs: str
+    filterLocationName: str
+    filterType: str
+    filtercrs: str
+    generatedAt: str
+    locationName: str
+    nrccMessages: list[NRCCMessagesTypeDef]
+    platformAvailable: bool
+    trainServices: list[TrainServiceTypeDef]
+
+
+class StationCRSTypeDef(TypedDict):
+    crs: str
+    Value: str
+
+
+class StationListResponseTypeDef(TypedDict):
+    version: str
+    StationList: list[StationCRSTypeDef]

pyrail_uk-0.1.0/pyrail_uk/api/url.py

@@ -0,0 +1,39 @@
+import typing as t
+
+DEPARTURE_URL = (
+    "https://api1.raildata.org.uk/1010-live-departure-board-dep1_2/LDBWS/api/20220120/GetDepBoardWithDetails"
+)
+
+STATION_LIST_URL = "https://api1.raildata.org.uk/1010-reference-data1_0/LDBSVWS/api/ref/20211101/GetStationList"
+
+# NOTE: This is an alternate URL that can be used for less verbose details
+# it also has carriage information but weirdly, only for Elizabeth Line trains...
+# DEPARTURE_URL = "https://api1.raildata.org.uk/1010-live-departure-board-dep1_2/LDBWS/api/20220120/GetDepartureBoard"
+
+
+def get_departure_board_url(
+    dep_crs: str,
+    arr_crs: t.Optional[str] = None,
+    timeoffset_mins: t.Optional[int] = None,
+    timewindow_mins: t.Optional[int] = None,
+):
+    url = f"{DEPARTURE_URL}/{dep_crs}"
+    query_params = []
+
+    if arr_crs:
+        query_params.append(f"filterCrs={arr_crs}")
+
+    if timeoffset_mins:
+        query_params.append(f"timeOffset={timeoffset_mins}")
+
+    if timewindow_mins:
+        query_params.append(f"timeWindow={timewindow_mins}")
+
+    if query_params:
+        url += "?" + "&".join(query_params)
+
+    return url
+
+
+def get_station_list_url(version: int = 1):
+    return f"{STATION_LIST_URL}/{version}"

pyrail_uk-0.1.0/pyrail_uk/core/exceptions.py

@@ -0,0 +1,10 @@
+class NoTrainsFoundException(Exception):
+    pass
+
+
+class CRSNotFoundException(Exception):
+    pass
+
+
+class StationNotFoundException(Exception):
+    pass

pyrail_uk-0.1.0/pyrail_uk/service/departures.py

@@ -0,0 +1,117 @@
+from typing import Optional
+
+import pyrail_uk.utils.array as array
+from pyrail_uk.api.types import DepBoardWithDetailsResponseTypeDef, TrainServiceTypeDef
+
+from .types import DepartureServiceResponse, TrainService, TrainStatus
+
+ON_TIME_ETD = "On time"
+DEFAULT_DELAY_REASON = "No reason provided"
+DEFAULT_CANCEL_REASON = "No reason provided"
+
+
+def get_train_status_and_reason(service_info: TrainServiceTypeDef) -> tuple[TrainStatus, Optional[str]]:
+    if service_info.get("isCancelled", False) or service_info.get("filterLocationCancelled", False):
+        status = TrainStatus.CANCELLED
+        reason = service_info.get("cancelReason", DEFAULT_CANCEL_REASON)
+        return status, reason
+
+    if "subsequentCallingPoints" not in service_info:
+        etd = service_info.get("etd")
+        if etd == ON_TIME_ETD:
+            return TrainStatus.DEPARTED, None
+        else:
+            return TrainStatus.DELAYED_DEPARTED, None
+
+    etd = service_info.get("etd")
+    if etd == ON_TIME_ETD:
+        return TrainStatus.ON_TIME, None
+
+    return TrainStatus.DELAYED, service_info.get("delayReason", DEFAULT_DELAY_REASON)
+
+
+def get_eta(service_info: TrainServiceTypeDef, target_crs: str) -> Optional[str]:
+    if "subsequentCallingPoints" not in service_info:
+        return None
+
+    calling_points = service_info["subsequentCallingPoints"][0]["callingPoint"]
+    target_point = array.findfirst(calling_points, lambda cp: cp["crs"] == target_crs)
+
+    if not target_point:
+        return None
+
+    return target_point.get("et")
+
+
+def get_atd(service_info: TrainServiceTypeDef, train_status: TrainStatus) -> Optional[str]:
+    """Gets the actual time of departure for the train service, if it has departed."""
+    if train_status not in [TrainStatus.DEPARTED, TrainStatus.DELAYED_DEPARTED]:
+        return None
+
+    if train_status == TrainStatus.DELAYED_DEPARTED:
+        etd = service_info.get("etd")
+        return service_info.get("std") if etd == ON_TIME_ETD else etd
+
+    if train_status == TrainStatus.DEPARTED:
+        return service_info.get("std")
+
+
+def simplify_service_info(service_info: TrainServiceTypeDef, target_crs: Optional[str]) -> TrainService:
+    origin = service_info["origin"][0]
+    destination = service_info["destination"][0]
+
+    operator_code = service_info["operatorCode"]
+    operator = service_info["operator"]
+
+    status, reason = get_train_status_and_reason(service_info)
+
+    atd = get_atd(service_info, status)
+    eta = get_eta(service_info, target_crs or destination["crs"])  # handle no user destination cases
+
+    return TrainService(
+        # this origin is where the train originated from
+        train_origin_crs=origin["crs"],
+        train_origin=origin["locationName"],
+        # this destination is the final destination of the train service
+        train_destination_crs=destination["crs"],
+        train_destination=destination["locationName"],
+        # general information
+        status=status,
+        status_reason=reason,
+        operator=operator,
+        operator_code=operator_code,
+        # time and location details,
+        platform=service_info.get("platform"),
+        std=service_info["std"],
+        etd=service_info["etd"],
+        atd=atd,
+        eta=eta,
+    )
+
+
+def simplify_departures(departures_data: DepBoardWithDetailsResponseTypeDef):
+    # this is for the user's journey and not the train journey
+    # i.e.  the user is departing from OXF to RDF
+    #       but the train is going from WXP to PAD
+    origin_crs = departures_data.get("crs")
+    origin_name = departures_data.get("locationName")
+    destination_crs = departures_data.get("filtercrs", None)
+    destination_name = departures_data.get("filterLocationName", None)
+
+    services_raw = departures_data.get("trainServices", {})
+    services = [simplify_service_info(service, destination_crs) for service in services_raw]
+    num_services = departures_data.get("Xmlns", {}).get("Count", len(services))
+
+    # all the messages are an array of {"Value": "..."}
+    nrcc_warning_messages_raw = departures_data.get("nrccMessages", [])
+    warning_messages = [msg["Value"] for msg in nrcc_warning_messages_raw]
+
+    return DepartureServiceResponse(
+        origin_crs=origin_crs,
+        origin=origin_name,
+        destination_crs=destination_crs,
+        destination=destination_name,
+        warning_messages=warning_messages,
+        services=services,
+        num_services=num_services,
+    )

pyrail_uk-0.1.0/pyrail_uk/service/stations.py

@@ -0,0 +1,21 @@
+import pyrail_uk.utils.array as array
+
+from ..api.types import StationCRSTypeDef
+from ..core.exceptions import CRSNotFoundException, StationNotFoundException
+
+
+def find_station_by_crs(stations: list[StationCRSTypeDef], crs: str) -> str:
+    station = array.findone(stations, lambda s: s["crs"] == crs.upper())
+    if not station:
+        raise CRSNotFoundException(f"{crs} is not a valid CRS")
+
+    return station.get("Value")
+
+
+def find_crs_by_station_name(stations: list[StationCRSTypeDef], station_name: str) -> str:
+    station = array.findone(stations, lambda s: s["Value"].lower() == station_name.lower())
+
+    if not station:
+        raise StationNotFoundException(f"{station_name} is not a valid station, please check your spelling!")
+
+    return station.get("crs")

pyrail_uk-0.1.0/pyrail_uk/service/types.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class TrainStatus(str, Enum):
+    ON_TIME = "ON_TIME"
+    DELAYED = "DELAYED"
+    CANCELLED = "CANCELLED"
+    DEPARTED = "DEPARTED"
+    DELAYED_DEPARTED = "DELAYED_DEPARTED"
+
+
+@dataclass
+class TrainService:
+    # information about the train journey
+    train_origin_crs: str
+    train_origin: str
+    train_destination_crs: str
+    train_destination: str
+
+    # train status
+    status: TrainStatus
+    status_reason: Optional[str]
+
+    # information about the train operator
+    operator_code: str
+    operator: str
+
+    # timing and platform information
+    # NOTE: std - scheduled time of departure
+    #       etd - estimated time of departure
+    #       atd - actual time of departure
+    #       eta - estimated time of arrival
+    platform: Optional[str]  # not present if train cancelled
+    std: str
+    etd: str
+    atd: Optional[str]  # not present if train not departed
+    eta: Optional[str]  # not present if train cancelled
+
+
+@dataclass
+class DepartureServiceResponse:
+    origin_crs: str
+    origin: str
+    destination_crs: str
+    destination: str
+    warning_messages: list[str]
+    # metadata about services
+    services: list[TrainService]
+    num_services: int
+
+
+@dataclass
+class Station:
+    crs: str
+    name: str

pyrail_uk-0.1.0/pyrail_uk/utils/array.py

@@ -0,0 +1,58 @@
+import typing as t
+
+
+class NotFoundException(Exception):
+    pass
+
+
+class MultipleFoundException(Exception):
+    pass
+
+
+T = t.TypeVar("T")
+
+
+def findfirst(arr: list[T], condition: t.Callable, strict: bool = False) -> t.Optional[T]:
+    """Find the first element in an array that satisfies the given condition.
+
+    Args:
+        arr (list): The list to search through.
+        condition (Callable[[Any], bool]): A function that takes an element and returns True if it satisfies the condition.
+        strict (bool): If true, raises an error if no element is found. Defaults to False.
+
+    Returns:
+        Optional[Any]: The first element that satisfies the condition, or None if no such element is found.
+    """
+    for item in arr:
+        if condition(item):
+            return item
+
+    if strict:
+        raise NotFoundException("No element found that satisfies the condition.")
+
+    return None
+
+
+def findone(arr: list[T], condition: t.Callable, strict: bool = False) -> t.Optional[T]:
+    """Find exactly one element in an array that satisfies the given condition.
+
+    Args:
+        arr (list): The list to search through.
+        condition (Callable[[Any], bool]): A function that takes an element and returns True if it satisfies the condition.
+        strict (bool): If true, raises an error if no element is found or if multiple elements are found. Defaults to False.
+
+    Returns:
+        Optional[Any]: The element that satisfies the condition, or None if no such element is found.
+    """
+    found_items = [item for item in arr if condition(item)]
+
+    if len(found_items) == 1:
+        return found_items[0]
+    elif len(found_items) == 0:
+        if strict:
+            raise NotFoundException("No element found that satisfies the condition.")
+        return None
+    else:
+        if strict:
+            raise MultipleFoundException("Multiple elements found that satisfy the condition.")
+        return None

pyrail_uk-0.1.0/pyrail_uk.egg-info/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: pyrail-uk
+Version: 0.1.0
+Summary: Python SDK for dealing with the National Rail API
+Author-email: Christopher Khoo <khoojinnwei@gmail.com>
+License: MIT
+Project-URL: repository, https://github.com/thekhoo/pyrail-uk
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: ~=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: cachetools
+Provides-Extra: development
+Requires-Dist: pytest; extra == "development"
+Requires-Dist: pytest-sugar; extra == "development"
+Requires-Dist: pyrefly; extra == "development"
+Requires-Dist: ruff; extra == "development"
+Requires-Dist: black; extra == "development"
+Requires-Dist: isort; extra == "development"
+Provides-Extra: local
+Requires-Dist: boto3; extra == "local"
+Requires-Dist: boto3-stubs[ssm]; extra == "local"
+Requires-Dist: python-dotenv; extra == "local"
+Provides-Extra: deploy
+Requires-Dist: build; extra == "deploy"
+Requires-Dist: twine; extra == "deploy"
+
+# PyRail
+
+An easier way to deal with the National Rail API
+
+## Supported APIs
+
+- [Departure Board with Details](https://raildata.org.uk/dashboard/dataProduct/P-9a01dd96-7211-4912-bcbb-c1b5d2e35609/overview)
+- [Reference Data (Stations Only)](https://raildata.org.uk/dashboard/dataProduct/P-c73f0d2a-c233-497d-846b-8354e2cac326/overview)

pyrail_uk-0.1.0/pyrail_uk.egg-info/SOURCES.txt

@@ -0,0 +1,31 @@
+README.md
+pyproject.toml
+pyrail_uk/NationalRail.py
+pyrail_uk/__init__.py
+pyrail_uk.egg-info/PKG-INFO
+pyrail_uk.egg-info/SOURCES.txt
+pyrail_uk.egg-info/dependency_links.txt
+pyrail_uk.egg-info/requires.txt
+pyrail_uk.egg-info/top_level.txt
+pyrail_uk/api/__init__.py
+pyrail_uk/api/client.py
+pyrail_uk/api/departures.py
+pyrail_uk/api/referencedata.py
+pyrail_uk/api/types.py
+pyrail_uk/api/url.py
+pyrail_uk/core/__init__.py
+pyrail_uk/core/exceptions.py
+pyrail_uk/service/__init__.py
+pyrail_uk/service/departures.py
+pyrail_uk/service/stations.py
+pyrail_uk/service/types.py
+pyrail_uk/utils/__init__.py
+pyrail_uk/utils/array.py
+tests/pyrail_uk/__init__.py
+tests/pyrail_uk/api/__init__.py
+tests/pyrail_uk/api/test_url.py
+tests/pyrail_uk/service/__init__.py
+tests/pyrail_uk/service/test_departures.py
+tests/pyrail_uk/service/test_departures_integration.py
+tests/pyrail_uk/service/test_stations.py
+tests/pyrail_uk/service/testutils.py

pyrail_uk-0.1.0/pyrail_uk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyrail_uk-0.1.0/pyrail_uk.egg-info/requires.txt

@@ -0,0 +1,19 @@
+requests
+cachetools
+
+[deploy]
+build
+twine
+
+[development]
+pytest
+pytest-sugar
+pyrefly
+ruff
+black
+isort
+
+[local]
+boto3
+boto3-stubs[ssm]
+python-dotenv

pyrail_uk-0.1.0/pyrail_uk.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+dist
+pyrail_uk
+tests

pyrail_uk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyrail_uk-0.1.0/tests/pyrail_uk/api/test_url.py

@@ -0,0 +1,16 @@
+import pyrail_uk.api.url as url
+
+
+class Test_Get_URL:
+
+    def test_should_return_url_with_dep_crs_only(self):
+        actual_url = url.get_departure_board_url("RDG")
+        assert actual_url.endswith("/RDG")
+
+    def test_should_return_url_with_dep_and_arr_crs(self):
+        actual_url = url.get_departure_board_url(dep_crs="RDG", arr_crs="OXF")
+        assert actual_url.endswith("/RDG?filterCrs=OXF")
+
+    def test_should_return_url_with_multiple_query_params(self):
+        actual_url = url.get_departure_board_url(dep_crs="RDG", arr_crs="OXF", timeoffset_mins=15)
+        assert actual_url.endswith("/RDG?filterCrs=OXF&timeOffset=15")

pyrail_uk-0.1.0/tests/pyrail_uk/service/test_departures.py

@@ -0,0 +1,148 @@
+import pytest
+
+import pyrail_uk.service.departures as departures
+from pyrail_uk.service.types import TrainStatus
+
+from .testutils import MockCallingPoint, MockTrainServiceData
+
+CALLING_POINTS = [
+    MockCallingPoint("OXF", "16:30"),
+    MockCallingPoint("DID", "17:00"),
+    MockCallingPoint("RDG", "17:30"),
+    MockCallingPoint("PAD", "18:00"),
+]
+
+
+class Test_Get_Train_Status_And_Reason:
+
+    class Test_When_Trains_Are_Cancelled:
+
+        def test_should_return_cancel_status_with_reason_when_available(self):
+            payload = (
+                MockTrainServiceData()
+                .set_cancelled()
+                .set_cancel_reason("Signal failure")
+                .set_subsequent_calling_points(CALLING_POINTS)
+                .build()
+            )
+            status, reason = departures.get_train_status_and_reason(payload)
+
+            assert status == TrainStatus.CANCELLED
+            assert reason == "Signal failure"
+
+        def test_should_return_cancel_status_with_default_reason_when_not_provided(self):
+            payload = MockTrainServiceData().set_cancelled().set_subsequent_calling_points(CALLING_POINTS).build()
+            status, reason = departures.get_train_status_and_reason(payload)
+
+            assert status == TrainStatus.CANCELLED
+            assert isinstance(reason, str)
+
+        # we need this test because the absence of subsequent calling points
+        # suggests that the train has already departed
+        def test_should_return_cancel_when_no_subsequent_calling_points_and_cancelled(self):
+            payload = (
+                MockTrainServiceData()
+                .set_cancelled()
+                .set_cancel_reason("Signal failure")
+                .clear_subsequent_calling_points()
+                .build()
+            )
+            status, reason = departures.get_train_status_and_reason(payload)
+
+            assert status == TrainStatus.CANCELLED
+            assert reason == "Signal failure"
+
+    class Test_When_ETD_Is_On_Time:
+
+        def test_should_return_on_time_status_with_no_reason(self):
+            payload = MockTrainServiceData().set_subsequent_calling_points(CALLING_POINTS).set_etd("On time").build()
+            status, reason = departures.get_train_status_and_reason(payload)
+
+            assert status == TrainStatus.ON_TIME
+            assert reason is None
+
+    class Test_When_ETD_Is_Not_On_Time:
+
+        @pytest.mark.parametrize("etd", ["18:31", "Delayed"])
+        def test_should_return_delayed_status_with_delay_reason_when_available(self, etd):
+            payload = (
+                MockTrainServiceData()
+                .set_subsequent_calling_points(CALLING_POINTS)
+                .set_etd(etd)
+                .set_delay_reason("trespassers on track")
+                .build()
+            )
+            status, reason = departures.get_train_status_and_reason(payload)
+
+            assert status == TrainStatus.DELAYED
+            assert reason == "trespassers on track"
+
+        def test_should_return_delayed_status_with_default_reason_when_not_provided(self):
+            payload = MockTrainServiceData().set_subsequent_calling_points(CALLING_POINTS).set_etd("Delayed").build()
+            status, reason = departures.get_train_status_and_reason(payload)
+
+            assert status == TrainStatus.DELAYED
+            assert reason == "No reason provided"
+
+    class Test_When_There_Are_No_Subsequent_Calling_Points:
+
+        def test_should_return_departed_status_with_no_reason_if_etd_on_time(self):
+            payload = MockTrainServiceData().clear_subsequent_calling_points().set_etd("On time").build()
+            status, reason = departures.get_train_status_and_reason(payload)
+
+            assert status == TrainStatus.DEPARTED
+            assert reason is None
+
+        def test_should_return_delayed_departed_status_with_no_reason_if_etd_not_on_time(self):
+            payload = MockTrainServiceData().clear_subsequent_calling_points().set_etd("18:31").build()
+            status, reason = departures.get_train_status_and_reason(payload)
+
+            assert status == TrainStatus.DELAYED_DEPARTED
+            assert reason is None
+
+
+class Test_Get_ETA:
+
+    def test_should_return_none_if_no_subsequent_calling_points(self):
+        payload = MockTrainServiceData().clear_subsequent_calling_points().build()
+        eta = departures.get_eta(payload, "RDG")
+
+        assert eta is None
+
+    def test_should_return_none_if_target_crs_not_found(self):
+        crs = "LHR"
+        payload = MockTrainServiceData().set_subsequent_calling_points(CALLING_POINTS).build()
+        eta = departures.get_eta(payload, crs)
+
+        assert eta is None
+
+    def test_should_return_et_for_target_crs(self):
+        crs = "RDG"
+        payload = MockTrainServiceData().set_subsequent_calling_points(CALLING_POINTS).build()
+        eta = departures.get_eta(payload, crs)
+
+        assert eta == "17:30"
+
+
+class Test_Get_ATD:
+
+    @pytest.mark.parametrize("train_status", [TrainStatus.ON_TIME, TrainStatus.DELAYED, TrainStatus.CANCELLED])
+    def test_should_return_none_if_train_not_departed(self, train_status):
+        payload = MockTrainServiceData().build()
+        atd = departures.get_atd(payload, train_status)
+        assert atd is None
+
+    def test_should_return_std_if_train_departed_on_time(self):
+        payload = MockTrainServiceData().set_etd("On time").set_std("17:20").build()
+        atd = departures.get_atd(payload, TrainStatus.DEPARTED)
+        assert atd == "17:20"
+
+    def test_should_return_etd_if_train_departed_delayed(self):
+        payload = MockTrainServiceData().set_etd("17:48").set_std("17:20").build()
+        atd = departures.get_atd(payload, TrainStatus.DELAYED_DEPARTED)
+        assert atd == "17:48"
+
+    def test_should_return_std_if_train_departed_delayed_but_etd_on_time(self):
+        payload = MockTrainServiceData().set_etd("On time").set_std("17:20").build()
+        atd = departures.get_atd(payload, TrainStatus.DELAYED_DEPARTED)
+        assert atd == "17:20"

pyrail_uk-0.1.0/tests/pyrail_uk/service/test_departures_integration.py

@@ -0,0 +1,115 @@
+import pyrail_uk.service.departures as departures
+from pyrail_uk.service.types import TrainStatus
+
+from .testutils import MockCallingPoint, MockDepartureData, MockTrainServiceData
+
+CALLING_POINTS = [
+    MockCallingPoint("OXF", "16:30"),
+    MockCallingPoint("DID", "17:00"),
+    MockCallingPoint("RDG", "17:30"),
+    MockCallingPoint("PAD", "18:00"),
+]
+
+CANCELLED_TRAIN_SERVICE = (
+    MockTrainServiceData()
+    .set_cancelled()
+    .set_cancel_reason("more trains than usual needing repairs")
+    .set_subsequent_calling_points(CALLING_POINTS)
+    .build()
+)
+
+ON_TIME_TRAIN_SERVICE = (
+    MockTrainServiceData().set_etd("On time").set_std("16:30").set_subsequent_calling_points(CALLING_POINTS).build()
+)
+
+DELAYED_TRAIN_SERVICE = (
+    MockTrainServiceData().set_etd("16:52").set_std("16:30").set_subsequent_calling_points(CALLING_POINTS).build()
+)
+
+DEPARTED_TRAIN_SERVICE = (
+    MockTrainServiceData().clear_subsequent_calling_points().set_std("17:22").set_etd("On time").build()
+)
+
+DELAYED_DEPARTED_TRAIN_SERVICE = (
+    MockTrainServiceData().clear_subsequent_calling_points().set_etd("17:32").set_std("17:22").build()
+)
+
+
+class Test_Simplify_Service_Info:
+
+    # test general properties
+    def test_returns_non_service_related_fields_correctly(self):
+        res = departures.simplify_service_info(ON_TIME_TRAIN_SERVICE, "RDG")
+
+        assert res.train_origin == "Oxford"
+        assert res.train_origin_crs == "OXF"
+        assert res.train_destination == "London Paddington"
+        assert res.train_destination_crs == "PAD"
+        assert res.operator == "Great Western Railway"
+        assert res.operator_code == "GW"
+        assert res.platform == "3"
+
+    def test_when_train_is_cancelled(self):
+        res = departures.simplify_service_info(CANCELLED_TRAIN_SERVICE, "RDG")
+        assert res.status == TrainStatus.CANCELLED
+        assert res.status_reason == "more trains than usual needing repairs"
+
+    def test_when_train_is_on_time(self):
+        res = departures.simplify_service_info(ON_TIME_TRAIN_SERVICE, "RDG")
+        assert res.status == TrainStatus.ON_TIME
+        assert res.status_reason is None
+        assert res.etd == "On time"
+        assert res.eta == "17:30"
+
+    def test_when_train_is_delayed(self):
+        res = departures.simplify_service_info(DELAYED_TRAIN_SERVICE, "RDG")
+        assert res.status == TrainStatus.DELAYED
+        assert res.status_reason == "No reason provided"
+
+    def test_when_train_has_departed(self):
+        res = departures.simplify_service_info(DEPARTED_TRAIN_SERVICE, "RDG")
+        assert res.status == TrainStatus.DEPARTED
+        assert res.status_reason is None
+        assert res.atd == "17:22"
+
+    def test_when_train_has_departed_late(self):
+        res = departures.simplify_service_info(DELAYED_DEPARTED_TRAIN_SERVICE, "RDG")
+        assert res.status == TrainStatus.DELAYED_DEPARTED
+        assert res.status_reason is None
+        assert res.atd == "17:32"
+
+
+DEPARTURE_INFO_TRAINS_AVAILABLE = (
+    MockDepartureData()
+    .set_service_available()
+    .set_train_services([ON_TIME_TRAIN_SERVICE, CANCELLED_TRAIN_SERVICE, DELAYED_DEPARTED_TRAIN_SERVICE])
+    .set_count(3)
+    .set_nrcc_messages(["Delayed due to storm eowyn"])
+    .build()
+)
+
+DEPARTURE_INFO_NO_TRAINS = (
+    MockDepartureData().set_service_available().set_count(0).set_nrcc_messages(["Delayed due to storm eowyn"]).build()
+)
+
+
+class Test_Simplify_Departures:
+
+    def test_when_no_trains_available(self):
+        res = departures.simplify_departures(DEPARTURE_INFO_NO_TRAINS)
+        assert res.origin_crs == "RDG"
+        assert res.origin == "Reading"
+        assert res.destination_crs == "OXF"
+        assert res.destination == "Oxford"
+        assert res.warning_messages == ["Delayed due to storm eowyn"]
+        assert res.services == []
+
+    def test_when_trains_are_available(self):
+        res = departures.simplify_departures(DEPARTURE_INFO_TRAINS_AVAILABLE)
+        assert res.origin_crs == "RDG"
+        assert res.origin == "Reading"
+        assert res.destination_crs == "OXF"
+        assert res.destination == "Oxford"
+        assert res.warning_messages == ["Delayed due to storm eowyn"]
+        assert res.num_services == 3
+        assert len(res.services) == 3  # don't actually check the event, just make sure number is correct

pyrail_uk-0.1.0/tests/pyrail_uk/service/test_stations.py

@@ -0,0 +1,31 @@
+import pytest
+
+import pyrail_uk.core.exceptions as ex
+import pyrail_uk.service.stations as st
+
+STATIONS = [
+    {"crs": "RDG", "Value": "Reading"},
+    {"crs": "OXF", "Value": "Oxford"},
+]
+
+
+class Test_Find_Station_By_CRS:
+
+    def test_should_raise_CRSNotFoundException_when_no_crs_found(self):
+        with pytest.raises(ex.CRSNotFoundException):
+            st.find_station_by_crs(STATIONS, "NAN")
+
+    @pytest.mark.parametrize("crs", ["rdg", "rDg", "RDG", "Rdg"])
+    def test_should_return_station_name_when_valid_crs_given(self, crs):
+        assert st.find_station_by_crs(STATIONS, crs) == "Reading"
+
+
+class Test_Find_CRS_By_Station_Name:
+
+    def test_should_raise_StationNotFoundException_when_no_station_name_found(self):
+        with pytest.raises(ex.StationNotFoundException):
+            st.find_crs_by_station_name(STATIONS, "NotAStation")
+
+    @pytest.mark.parametrize("station_name", ["Oxford", "OXFORD", "oxford", "OxFoRd"])
+    def test_should_return_crs_when_valid_station_name_given(self, station_name):
+        assert st.find_crs_by_station_name(STATIONS, station_name) == "OXF"

pyrail_uk-0.1.0/tests/pyrail_uk/service/testutils.py

@@ -0,0 +1,138 @@
+class MockCallingPoint:
+
+    def __init__(self, crs: str, et: str):
+        self.event = {
+            "crs": crs,
+            "et": et,
+        }
+
+    def set_crs(self, crs: str):
+        self.event["crs"] = crs
+        return self
+
+    def set_et(self, et: str):
+        self.event["et"] = et
+        return self
+
+    def build(self):
+        return self.event
+
+
+class MockTrainServiceData:
+    """
+    Not cancelled, delayed and has no subsequent calling points
+    by default.
+    """
+
+    def __init__(self):
+        self.event = {
+            "serviceID": "12345678",
+            "isReverseFormation": False,
+            "detachFront": False,
+            "length": 0,
+            "serviceType": "train",
+            "filterLocationCancelled": False,
+            "isCancelled": False,
+            "isCircularRoute": False,
+            # operator information
+            "operatorCode": "GW",
+            "operator": "Great Western Railway",
+            # platform
+            "platform": None,
+            "etd": "On time",
+            "std": "14:39",
+            "rsid": "GW1234",
+            # bogus
+            "futureCancellation": False,
+            "futureDelay": False,
+            # train information
+            "platform": "3",
+            "origin": [{"crs": "OXF", "locationName": "Oxford"}],
+            "destination": [{"crs": "PAD", "locationName": "London Paddington"}],
+            "currentDestinations": [{"crs": "RDG", "locationName": "Reading"}],
+        }
+
+    def build(self):
+        return self.event
+
+    def set_cancelled(self):
+        self.event["isCancelled"] = True
+        return self
+
+    def set_cancel_reason(self, reason: str):
+        self.event["cancelReason"] = reason
+        return self
+
+    def set_delay_reason(self, reason: str):
+        self.event["delayReason"] = reason
+        return self
+
+    def set_etd(self, etd: str):
+        self.event["etd"] = etd
+        return self
+
+    def set_std(self, std: str):
+        self.event["std"] = std
+        return self
+
+    def set_delay_reason(self, reason: str):
+        self.event["delayReason"] = reason
+        return self
+
+    def set_subsequent_calling_points(self, calling_points: list[MockCallingPoint]):
+        self.event["subsequentCallingPoints"] = [
+            {
+                "callingPoint": [cp.build() for cp in calling_points],
+                "serviceType": "train",
+                "serviceChangeRequired": False,
+                "assocIsCancelled": False,
+            }
+        ]
+        return self
+
+    def clear_subsequent_calling_points(self):
+        if "subsequentCallingPoints" in self.event:
+            del self.event["subsequentCallingPoints"]
+        return self
+
+    def set_filter_location_cancelled(self):
+        self.event["filterLocationCancelled"] = True
+        return self
+
+
+class MockDepartureData:
+
+    def __init__(self):
+        self.event = {
+            "areServicesAvailable": True,
+            "Xmlns": {"Count": 5},
+            "crs": "RDG",
+            "locationName": "Reading",
+            "filtercrs": "OXF",
+            "filterLocationName": "Oxford",
+            "platformAvailable": True,
+            "trainServices": [],
+        }
+
+    def set_count(self, count: int):
+        self.event["Xmlns"] = {"Count": count}
+        return self
+
+    def set_train_services(self, train_services: list[dict]):
+        self.event["trainServices"] = train_services
+        return self
+
+    def set_service_available(self):
+        self.event["areServicesAvailable"] = True
+        return self
+
+    def set_service_not_available(self):
+        self.event["areServicesAvailable"] = False
+        return self
+
+    def set_nrcc_messages(self, messages: list[str]):
+        self.event["nrccMessages"] = [{"Value": message} for message in messages]
+        return self
+
+    def build(self):
+        return self.event