pyrailworks 0.1.0__py3-none-any.whl

pyrailworks/__init__.py

@@ -0,0 +1,81 @@
+"""pyrailworks - Python client for the Public RO Railworks API."""
+from pyrailworks.client import AsyncRailworksClient, RailworksClient
+from pyrailworks.exceptions import (
+    BadRequestError,
+    NotFoundError,
+    ProblemError,
+    RailworksError,
+    StationsLoadingError,
+)
+from pyrailworks.models import (
+    AlterationChange,
+    ChangeEvent,
+    ChangeEventType,
+    ChangesResponse,
+    DateInference,
+    DateInferenceMethod,
+    DaySection,
+    Effect,
+    EffectKind,
+    Extraction,
+    ExtractionStatus,
+    Health,
+    LineName,
+    NoticeResponse,
+    NoticeStatus,
+    NoticesResponse,
+    RawNoticeResponse,
+    Revision,
+    SegmentExpansion,
+    ServiceAlteration,
+    Source,
+    Station,
+    StationDay,
+    StationDaysResponse,
+    StationLine,
+    StationResponse,
+    StationsResponse,
+    TimeScope,
+    WorksNotice,
+    WorksSegment,
+)
+
+__all__ = [
+    "RailworksClient",
+    "AsyncRailworksClient",
+    "RailworksError",
+    "ProblemError",
+    "BadRequestError",
+    "NotFoundError",
+    "StationsLoadingError",
+    "LineName",
+    "NoticeStatus",
+    "EffectKind",
+    "AlterationChange",
+    "ExtractionStatus",
+    "DateInferenceMethod",
+    "SegmentExpansion",
+    "ChangeEventType",
+    "Source",
+    "DateInference",
+    "DaySection",
+    "WorksSegment",
+    "Effect",
+    "ServiceAlteration",
+    "Extraction",
+    "Revision",
+    "WorksNotice",
+    "ChangeEvent",
+    "StationLine",
+    "Station",
+    "TimeScope",
+    "StationDay",
+    "Health",
+    "NoticesResponse",
+    "NoticeResponse",
+    "RawNoticeResponse",
+    "ChangesResponse",
+    "StationsResponse",
+    "StationResponse",
+    "StationDaysResponse",
+]

pyrailworks/client.py

@@ -0,0 +1,453 @@
+"""HTTP Client implementation for pyrailworks."""
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import (
+    Any,
+    AsyncIterator,
+    Dict,
+    Iterator,
+    List,
+    Optional,
+    Union,
+)
+import httpx
+
+from pyrailworks.exceptions import (
+    BadRequestError,
+    NotFoundError,
+    ProblemError,
+    RailworksError,
+    StationsLoadingError,
+)
+from pyrailworks.models import (
+    ChangeEvent,
+    ChangesResponse,
+    Health,
+    LineName,
+    NoticeResponse,
+    NoticeStatus,
+    NoticesResponse,
+    RawNoticeResponse,
+    StationDay,
+    StationDaysResponse,
+    StationResponse,
+    StationsResponse,
+    WorksNotice,
+    Station,
+)
+
+DEFAULT_BASE_URL = "https://railworks.paddez.com"
+
+
+def _format_date(val: Union[date, str, None]) -> Optional[str]:
+    if val is None:
+        return None
+    if isinstance(val, (date, datetime)):
+        return val.strftime("%Y-%m-%d")
+    return str(val)
+
+
+def _format_datetime(val: Union[datetime, str, None]) -> Optional[str]:
+    if val is None:
+        return None
+    if isinstance(val, datetime):
+        return val.isoformat()
+    return str(val)
+
+
+def _format_status(
+    status: Union[NoticeStatus, str, List[Union[NoticeStatus, str]], None]
+) -> Optional[str]:
+    if status is None:
+        return None
+    if isinstance(status, (list, tuple, set)):
+        return ",".join(
+            s.value if isinstance(s, NoticeStatus) else str(s) for s in status
+        )
+    if isinstance(status, NoticeStatus):
+        return status.value
+    return str(status)
+
+
+def _handle_error_response(response: httpx.Response) -> None:
+    if response.is_success or response.status_code == 304:
+        return
+
+    content_type = response.headers.get("content-type", "")
+    if "application/problem+json" in content_type:
+        try:
+            data = response.json()
+            title = data.get("title", "Error")
+            detail = data.get("detail", response.text)
+            type_ = data.get("type")
+            status = data.get("status", response.status_code)
+
+            if status == 400:
+                raise BadRequestError(status=status, title=title, detail=detail, type_=type_)
+            if status == 404:
+                raise NotFoundError(status=status, title=title, detail=detail, type_=type_)
+            if status == 503:
+                raise StationsLoadingError(status=status, title=title, detail=detail, type_=type_)
+
+            raise ProblemError(status=status, title=title, detail=detail, type_=type_)
+        except (ValueError, KeyError):
+            pass
+
+    response.raise_for_status()
+
+
+class RailworksClient:
+    """Synchronous client for the Railworks API."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = 30.0,
+        client: Optional[httpx.Client] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        default_headers = {
+            "User-Agent": "pyrailworks/0.1.0",
+            "Accept": "application/json",
+        }
+        if headers:
+            default_headers.update(headers)
+
+        if client is not None:
+            self._client = client
+            self._owns_client = False
+        else:
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                timeout=timeout,
+                headers=default_headers,
+                follow_redirects=True,
+            )
+            self._owns_client = True
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> RailworksClient:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None) -> httpx.Response:
+        filtered_params = {k: v for k, v in (params or {}).items() if v is not None}
+        resp = self._client.get(path, params=filtered_params, headers=headers)
+        _handle_error_response(resp)
+        return resp
+
+    def get_health(self) -> Health:
+        """Get health status, freshness and backend diagnostics."""
+        resp = self._get("/v1/health")
+        return Health.model_validate(resp.json())
+
+    def list_notices(
+        self,
+        *,
+        from_date: Union[date, str, None] = None,
+        to_date: Union[date, str, None] = None,
+        status: Union[NoticeStatus, str, List[Union[NoticeStatus, str]], None] = None,
+        station: Optional[str] = None,
+        line: Union[LineName, str, None] = None,
+        group: Optional[str] = None,
+        min_confidence: Optional[float] = None,
+    ) -> NoticesResponse:
+        """List Works Notices with any day in the given window."""
+        params: Dict[str, Any] = {
+            "from": _format_date(from_date),
+            "to": _format_date(to_date),
+            "status": _format_status(status),
+            "station": station,
+            "line": line.value if isinstance(line, LineName) else line,
+            "group": group,
+            "min_confidence": min_confidence,
+        }
+        resp = self._get("/v1/notices", params=params)
+        return NoticesResponse.model_validate(resp.json())
+
+    def get_notice(self, notice_id: str) -> WorksNotice:
+        """Get a full Works Notice by id with revisions, day sections and alterations."""
+        resp = self._get(f"/v1/notices/{notice_id}")
+        data = resp.json()
+        return WorksNotice.model_validate(data["notice"])
+
+    def get_notice_raw(self, notice_id: str) -> RawNoticeResponse:
+        """Get verbatim upstream HTML for all revisions of a notice."""
+        resp = self._get(f"/v1/notices/{notice_id}/raw")
+        return RawNoticeResponse.model_validate(resp.json())
+
+    def list_changes(
+        self,
+        *,
+        after: Optional[str] = None,
+        since: Union[datetime, str, None] = None,
+        limit: Optional[int] = None,
+    ) -> ChangesResponse:
+        """Fetch a page of change events from the append-only change log."""
+        params: Dict[str, Any] = {
+            "after": after,
+            "since": _format_datetime(since),
+            "limit": limit,
+        }
+        resp = self._get("/v1/changes", params=params)
+        return ChangesResponse.model_validate(resp.json())
+
+    def iter_changes(
+        self,
+        *,
+        since: Union[datetime, str, None] = None,
+        after: Optional[str] = None,
+        limit: int = 500,
+    ) -> Iterator[ChangeEvent]:
+        """Convenience generator that yields change events and automatically traverses pages."""
+        cursor = after
+        initial_since = since if cursor is None else None
+
+        while True:
+            resp = self.list_changes(after=cursor, since=initial_since, limit=limit)
+            initial_since = None
+            if not resp.events:
+                break
+            for event in resp.events:
+                yield event
+            if resp.next == cursor:
+                break
+            cursor = resp.next
+
+    def list_stations(self) -> List[Station]:
+        """List all Irish Rail stations served by timetabled trains."""
+        resp = self._get("/v1/stations")
+        data = resp.json()
+        return StationsResponse.model_validate(data).stations
+
+    def get_station(self, code: str) -> Station:
+        """Get details for a single station by code."""
+        resp = self._get(f"/v1/stations/{code}")
+        data = resp.json()
+        return StationResponse.model_validate(data).station
+
+    def get_station_days(
+        self,
+        code: str,
+        *,
+        from_date: Union[date, str, None] = None,
+        to_date: Union[date, str, None] = None,
+    ) -> StationDaysResponse:
+        """Check whether a station is affected, and on which dates."""
+        params: Dict[str, Any] = {
+            "from": _format_date(from_date),
+            "to": _format_date(to_date),
+        }
+        resp = self._get(f"/v1/stations/{code}/days", params=params)
+        return StationDaysResponse.model_validate(resp.json())
+
+    def get_calendar_feed(
+        self,
+        *,
+        from_date: Union[date, str, None] = None,
+        station: Optional[str] = None,
+        line: Union[LineName, str, None] = None,
+        group: Optional[str] = None,
+        min_confidence: Optional[float] = None,
+    ) -> str:
+        """Download the raw iCalendar (ICS) text."""
+        params: Dict[str, Any] = {
+            "from": _format_date(from_date),
+            "station": station,
+            "line": line.value if isinstance(line, LineName) else line,
+            "group": group,
+            "min_confidence": min_confidence,
+        }
+        resp = self._get(
+            "/v1/feeds/notices.ics",
+            params=params,
+            headers={"Accept": "text/calendar, text/plain"},
+        )
+        return resp.text
+
+
+class AsyncRailworksClient:
+    """Asynchronous client for the Railworks API."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = 30.0,
+        client: Optional[httpx.AsyncClient] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        default_headers = {
+            "User-Agent": "pyrailworks/0.1.0",
+            "Accept": "application/json",
+        }
+        if headers:
+            default_headers.update(headers)
+
+        if client is not None:
+            self._client = client
+            self._owns_client = False
+        else:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=timeout,
+                headers=default_headers,
+                follow_redirects=True,
+            )
+            self._owns_client = True
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncRailworksClient:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()
+
+    async def _get(
+        self, path: str, params: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None
+    ) -> httpx.Response:
+        filtered_params = {k: v for k, v in (params or {}).items() if v is not None}
+        resp = await self._client.get(path, params=filtered_params, headers=headers)
+        _handle_error_response(resp)
+        return resp
+
+    async def get_health(self) -> Health:
+        """Get health status, freshness and backend diagnostics."""
+        resp = await self._get("/v1/health")
+        return Health.model_validate(resp.json())
+
+    async def list_notices(
+        self,
+        *,
+        from_date: Union[date, str, None] = None,
+        to_date: Union[date, str, None] = None,
+        status: Union[NoticeStatus, str, List[Union[NoticeStatus, str]], None] = None,
+        station: Optional[str] = None,
+        line: Union[LineName, str, None] = None,
+        group: Optional[str] = None,
+        min_confidence: Optional[float] = None,
+    ) -> NoticesResponse:
+        """List Works Notices with any day in the given window."""
+        params: Dict[str, Any] = {
+            "from": _format_date(from_date),
+            "to": _format_date(to_date),
+            "status": _format_status(status),
+            "station": station,
+            "line": line.value if isinstance(line, LineName) else line,
+            "group": group,
+            "min_confidence": min_confidence,
+        }
+        resp = await self._get("/v1/notices", params=params)
+        return NoticesResponse.model_validate(resp.json())
+
+    async def get_notice(self, notice_id: str) -> WorksNotice:
+        """Get a full Works Notice by id with revisions, day sections and alterations."""
+        resp = await self._get(f"/v1/notices/{notice_id}")
+        data = resp.json()
+        return WorksNotice.model_validate(data["notice"])
+
+    async def get_notice_raw(self, notice_id: str) -> RawNoticeResponse:
+        """Get verbatim upstream HTML for all revisions of a notice."""
+        resp = await self._get(f"/v1/notices/{notice_id}/raw")
+        return RawNoticeResponse.model_validate(resp.json())
+
+    async def list_changes(
+        self,
+        *,
+        after: Optional[str] = None,
+        since: Union[datetime, str, None] = None,
+        limit: Optional[int] = None,
+    ) -> ChangesResponse:
+        """Fetch a page of change events from the append-only change log."""
+        params: Dict[str, Any] = {
+            "after": after,
+            "since": _format_datetime(since),
+            "limit": limit,
+        }
+        resp = await self._get("/v1/changes", params=params)
+        return ChangesResponse.model_validate(resp.json())
+
+    async def iter_changes(
+        self,
+        *,
+        since: Union[datetime, str, None] = None,
+        after: Optional[str] = None,
+        limit: int = 500,
+    ) -> AsyncIterator[ChangeEvent]:
+        """Convenience async generator that yields change events and automatically traverses pages."""
+        cursor = after
+        initial_since = since if cursor is None else None
+
+        while True:
+            resp = await self.list_changes(after=cursor, since=initial_since, limit=limit)
+            initial_since = None
+            if not resp.events:
+                break
+            for event in resp.events:
+                yield event
+            if resp.next == cursor:
+                break
+            cursor = resp.next
+
+    async def list_stations(self) -> List[Station]:
+        """List all Irish Rail stations served by timetabled trains."""
+        resp = await self._get("/v1/stations")
+        data = resp.json()
+        return StationsResponse.model_validate(data).stations
+
+    async def get_station(self, code: str) -> Station:
+        """Get details for a single station by code."""
+        resp = await self._get(f"/v1/stations/{code}")
+        data = resp.json()
+        return StationResponse.model_validate(data).station
+
+    async def get_station_days(
+        self,
+        code: str,
+        *,
+        from_date: Union[date, str, None] = None,
+        to_date: Union[date, str, None] = None,
+    ) -> StationDaysResponse:
+        """Check whether a station is affected, and on which dates."""
+        params: Dict[str, Any] = {
+            "from": _format_date(from_date),
+            "to": _format_date(to_date),
+        }
+        resp = await self._get(f"/v1/stations/{code}/days", params=params)
+        return StationDaysResponse.model_validate(resp.json())
+
+    async def get_calendar_feed(
+        self,
+        *,
+        from_date: Union[date, str, None] = None,
+        station: Optional[str] = None,
+        line: Union[LineName, str, None] = None,
+        group: Optional[str] = None,
+        min_confidence: Optional[float] = None,
+    ) -> str:
+        """Download the raw iCalendar (ICS) text."""
+        params: Dict[str, Any] = {
+            "from": _format_date(from_date),
+            "station": station,
+            "line": line.value if isinstance(line, LineName) else line,
+            "group": group,
+            "min_confidence": min_confidence,
+        }
+        resp = await self._get(
+            "/v1/feeds/notices.ics",
+            params=params,
+            headers={"Accept": "text/calendar, text/plain"},
+        )
+        return resp.text

pyrailworks/exceptions.py

@@ -0,0 +1,35 @@
+"""Exception classes for pyrailworks."""
+from typing import Optional
+
+
+class RailworksError(Exception):
+    """Base exception for all railworks errors."""
+
+
+class ProblemError(RailworksError):
+    """RFC 9457 Problem Details error returned by the Railworks API."""
+
+    def __init__(
+        self,
+        status: int,
+        title: str,
+        detail: str,
+        type_: Optional[str] = None,
+    ) -> None:
+        self.status = status
+        self.title = title
+        self.detail = detail
+        self.type_ = type_
+        super().__init__(f"[{status}] {title}: {detail}")
+
+
+class BadRequestError(ProblemError):
+    """400 Bad Request: bad or unknown query parameter."""
+
+
+class NotFoundError(ProblemError):
+    """404 Not Found: no such notice, station or resource."""
+
+
+class StationsLoadingError(ProblemError):
+    """503 Service Unavailable: station list hasn't loaded yet."""

pyrailworks/models.py

@@ -0,0 +1,286 @@
+"""Pydantic data models for the Railworks API."""
+from __future__ import annotations
+
+from datetime import date, datetime
+from enum import Enum
+from typing import Any, List, Optional
+from pydantic import BaseModel, Field
+
+
+class LineName(str, Enum):
+    DART = "dart"
+    NORTHERN_COMMUTERS = "northern-commuters"
+    BELFAST = "belfast"
+    ROSSLARE = "rosslare"
+    MAYNOOTH_LONGFORD_SLIGO = "maynooth-longford-sligo"
+    PORTLAOISE_COMMUTERS = "portlaoise-commuters"
+    CORK_LIMERICK_TRALEE = "cork-limerick-tralee"
+    COBH_MIDLETON = "cobh-midleton"
+    GALWAY_WESTPORT = "galway-westport"
+    WATERFORD = "waterford"
+    WESTERN_RAIL_CORRIDOR = "western-rail-corridor"
+    WATERFORD_TO_LIMERICK = "waterford-to-limerick"
+    BALLYBROPHY = "ballybrophy"
+
+
+class NoticeStatus(str, Enum):
+    ACTIVE = "active"
+    EXPIRED = "expired"
+    WITHDRAWN = "withdrawn"
+
+
+class EffectKind(str, Enum):
+    NO_SERVICE = "no_service"
+    STATION_CLOSED = "station_closed"
+    BUS_REPLACEMENT = "bus_replacement"
+    REDUCED_SERVICE = "reduced_service"
+    OTHER = "other"
+
+
+class AlterationChange(str, Enum):
+    CANCELLED = "cancelled"
+    BUS_REPLACED = "bus_replaced"
+    TERMINATES_SHORT = "terminates_short"
+    STARTS_SHORT = "starts_short"
+    RETIMED = "retimed"
+    SKIPS_STOPS = "skips_stops"
+    OTHER = "other"
+
+
+class ExtractionStatus(str, Enum):
+    DISABLED = "disabled"
+    PENDING = "pending"
+    DONE = "done"
+    FAILED = "failed"
+
+
+class DateInferenceMethod(str, Enum):
+    WEEKDAY = "weekday"
+    NEXT_OCCURRENCE = "next_occurrence"
+
+
+class SegmentExpansion(str, Enum):
+    OK = "ok"
+    AMBIGUOUS = "ambiguous"
+    UNRESOLVED = "unresolved"
+
+
+class ChangeEventType(str, Enum):
+    CREATED = "created"
+    REVISED = "revised"
+    EXPIRED = "expired"
+    WITHDRAWN = "withdrawn"
+    EXTRACTED = "extracted"
+
+
+class Source(BaseModel):
+    built_at: Optional[datetime] = None
+    fetched_at: Optional[datetime] = None
+    checked_at: Optional[datetime] = None
+    stale: bool
+
+
+class DateCorrection(BaseModel):
+    from_: date = Field(..., alias="from")
+    to: date
+
+
+class DateInference(BaseModel):
+    method: DateInferenceMethod
+    corrections: List[DateCorrection] = Field(default_factory=list)
+    conflicts: List[date] = Field(default_factory=list)
+    prose_missing: List[date] = Field(default_factory=list)
+    prose_extra: List[date] = Field(default_factory=list)
+
+
+class DaySection(BaseModel):
+    heading: str
+    days: List[date] = Field(default_factory=list)
+
+
+class WorksSegment(BaseModel):
+    clause: str
+    from_: Optional[str] = Field(None, alias="from")
+    to: Optional[str] = None
+    from_codes: List[str] = Field(default_factory=list)
+    to_codes: List[str] = Field(default_factory=list)
+    stations: List[str] = Field(default_factory=list)
+    from_time: Optional[str] = None
+    until_time: Optional[str] = None
+    expansion: SegmentExpansion
+    quote: str
+
+
+class Effect(BaseModel):
+    kind: EffectKind
+    from_: Optional[str] = Field(None, alias="from")
+    to: Optional[str] = None
+    station_codes: List[str] = Field(default_factory=list)
+    from_time: Optional[str] = None
+    until_time: Optional[str] = None
+    quote: str
+
+
+class ServiceAlteration(BaseModel):
+    departs: str
+    origin: str
+    destination: str
+    changes: List[AlterationChange] = Field(default_factory=list)
+    stations: List[str] = Field(default_factory=list)
+    retimed_to: Optional[str] = None
+    bus_departs: Optional[str] = None
+    quote: str
+    origin_codes: List[str] = Field(default_factory=list)
+    destination_codes: List[str] = Field(default_factory=list)
+    station_codes: List[str] = Field(default_factory=list)
+
+
+class Extraction(BaseModel):
+    status: ExtractionStatus
+    extractor: Optional[str] = None
+    rejected: int = 0
+
+
+class Revision(BaseModel):
+    build: datetime
+    seen_at: datetime
+    content_hash: str
+    trim: bool
+    summary: str
+    html: Optional[str] = None
+
+
+class WorksNotice(BaseModel):
+    id: str
+    service_group: str
+    status: NoticeStatus
+    heading: str
+    days: List[date]
+    starts_on: date
+    ends_on: date
+    until: date
+    date_inference: DateInference
+    first_seen: datetime
+    last_seen: datetime
+    revision_count: int
+    works_segments: List[WorksSegment] = Field(default_factory=list)
+    effects: List[Effect] = Field(default_factory=list)
+    stations: List[str] = Field(default_factory=list)
+    confidence: float
+    extraction: Extraction
+    day_sections: Optional[List[DaySection]] = None
+    detail: Optional[str] = None
+    alterations: Optional[List[ServiceAlteration]] = None
+    revisions: Optional[List[Revision]] = None
+
+
+class ChangeEvent(BaseModel):
+    cursor: str
+    type: ChangeEventType
+    notice_id: str
+    build: datetime
+    at: datetime
+    trim: Optional[bool] = None
+
+
+class StationLine(BaseModel):
+    line: str
+    position: int
+
+
+class Station(BaseModel):
+    code: str
+    name: str
+    names: List[str] = Field(default_factory=list)
+    alias_codes: List[str] = Field(default_factory=list)
+    lat: float
+    lon: float
+    lines: List[StationLine] = Field(default_factory=list)
+
+
+class StationSummary(BaseModel):
+    code: str
+    name: str
+
+
+class TimeScope(BaseModel):
+    from_: Optional[str] = Field(None, alias="from")
+    until: Optional[str] = None
+
+
+class StationDay(BaseModel):
+    date: date
+    effect: EffectKind
+    time_scope: Optional[TimeScope] = None
+    notices: List[str] = Field(default_factory=list)
+
+
+class NoticeRef(BaseModel):
+    id: str
+    service_group: str
+    heading: str
+
+
+class LowConfidenceNoticeRef(NoticeRef):
+    confidence: Optional[float] = None
+
+
+class LastFailure(BaseModel):
+    at: datetime
+    error: str
+
+
+class HealthExtraction(BaseModel):
+    extractor: Optional[str] = None
+    pending: int = 0
+    failed: int = 0
+    last_error: str = ""
+
+
+class Health(BaseModel):
+    source: Source
+    last_failure: Optional[LastFailure] = None
+    held_notices: List[NoticeRef] = Field(default_factory=list)
+    graph_removals: List[List[str]] = Field(default_factory=list)
+    unmapped_groups: List[str] = Field(default_factory=list)
+    low_confidence: List[LowConfidenceNoticeRef] = Field(default_factory=list)
+    unresolved_names: List[dict[str, Any]] = Field(default_factory=list)
+    extraction: HealthExtraction
+
+
+# Response wrapper envelopes
+class NoticesResponse(BaseModel):
+    source: Source
+    notices: List[WorksNotice]
+
+
+class NoticeResponse(BaseModel):
+    source: Source
+    notice: WorksNotice
+
+
+class RawNoticeResponse(BaseModel):
+    source: Source
+    revisions: List[Revision]
+
+
+class ChangesResponse(BaseModel):
+    source: Source
+    events: List[ChangeEvent]
+    next: str
+
+
+class StationsResponse(BaseModel):
+    source: Source
+    stations: List[Station]
+
+
+class StationResponse(BaseModel):
+    source: Source
+    station: Station
+
+
+class StationDaysResponse(BaseModel):
+    source: Source
+    station: StationSummary
+    days: List[StationDay]

pyrailworks/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.

pyrailworks-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: pyrailworks
+Version: 0.1.0
+Summary: Python client library for the Public RO Railworks Irish Rail Engineering Works API
+Author: Irishsmurf
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyrailworks
+
+Python client library for the Public RO Railworks API ([https://railworks.paddez.com/docs](https://railworks.paddez.com/docs)).
+
+Provides queryable access to Iarnród Éireann's (Irish Rail) planned engineering works, station days, change logs, and iCalendar feeds.
+
+## Installation
+
+```bash
+pip install pyrailworks
+```
+
+## Quick Start
+
+### Synchronous Client
+
+```python
+from pyrailworks import RailworksClient, LineName
+
+with RailworksClient() as client:
+    # 1. Health check
+    health = client.get_health()
+    print("Upstream checked at:", health.source.checked_at)
+
+    # 2. List stations
+    stations = client.list_stations()
+    print(f"Total stations: {len(stations)}")
+
+    # 3. Check affected days for a station
+    days_resp = client.get_station_days("WBROK")
+    for day in days_resp.days:
+        print(f"Station {days_resp.station.name} affected on {day.date}: {day.effect.value}")
+
+    # 4. List active notices on a line
+    notices = client.list_notices(line=LineName.DART, status="active")
+    for notice in notices.notices:
+        print(f"Notice {notice.id}: {notice.heading} ({notice.starts_on} to {notice.ends_on})")
+
+    # 5. Follow changes with automatic cursor traversal
+    for event in client.iter_changes():
+        print(f"Change event: {event.type.value} on notice {event.notice_id}")
+```
+
+### Asynchronous Client
+
+```python
+import asyncio
+from pyrailworks import AsyncRailworksClient
+
+async def main():
+    async with AsyncRailworksClient() as client:
+        health = await client.get_health()
+        print("Backend stale:", health.source.stale)
+
+        async for event in client.iter_changes():
+            print("Notice changed:", event.notice_id)
+
+asyncio.run(main())
+```
+
+## Features
+
+- **Both Sync & Async**: `RailworksClient` and `AsyncRailworksClient` powered by `httpx`.
+- **Strict Data Validation**: Pydantic v2 data models for type safety, validation, and auto-completion.
+- **Problem Details Handling**: Full support for RFC 9457 errors with specific exceptions (`BadRequestError`, `NotFoundError`, `StationsLoadingError`).
+- **Change Log Streaming**: Helper generators (`iter_changes()`) handling opaque cursor pagination.
+- **Calendar Feeds**: Raw iCalendar text download via `get_calendar_feed()`.

pyrailworks-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyrailworks/__init__.py,sha256=smjpJVrF39TffgALMiUNFfKGLBnOI-o6wBfKLaeFX1w,1654
+pyrailworks/client.py,sha256=xlako8NWmDgwg8Wid2vWFfxaxvsCOmfeRqzIma5HRh8,15408
+pyrailworks/exceptions.py,sha256=YS5XEO37jgp3crfCczkmcIkMmWnW6Mb3FYqdvjfngmQ,890
+pyrailworks/models.py,sha256=IbRBJoqOQ5m6tUuUOKG4TdRln9ogTBEJZlzDMSCl69M,6954
+pyrailworks/py.typed,sha256=bWew9mHgMy8LqMu7RuqQXFXLBxh2CRx0dUbSx-3wE48,27
+pyrailworks-0.1.0.dist-info/METADATA,sha256=s5B4ogkhkNtySWHHaf6a_aEPWFmG4vJSdYs6GePPo78,3067
+pyrailworks-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pyrailworks-0.1.0.dist-info/RECORD,,

pyrailworks-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any