pyrailworks

Python client library for the Public RO Railworks API (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

pip install pyrailworks

Quick Start

Synchronous Client

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

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())

Compatibility

The Railworks API only makes additive changes within /v1: new fields, endpoints and query parameters, and new enum values. pyrailworks is built to keep working through all of them:

• Unknown fields are ignored.

• Unknown enum values (a new effect kind, change-event type or status) parse as an UNKNOWN member that keeps the raw value, still compares equal to the string, and has is_known == False:

  for event in client.iter_changes():
      if not event.type.is_known:
          log.info("new event type %s: consider upgrading pyrailworks", event.type.value)
  

• Requests identify the client version (User-Agent: pyrailworks/<version>), so the API can see which versions are in use before retiring anything.

A breaking change would ship as /v2, alongside /v1, with Deprecation and Sunset headers on what's being retired. The railworks repository runs this package's integration tests against every change to the API, and a nightly job here runs them against the live API and opens an issue if they fail.

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().