bolster.data_sources.translink.timetable
========================================

.. py:module:: bolster.data_sources.translink.timetable

.. autoapi-nested-parse::

   Translink timetable — trip stop sequences from ATCO-CIF archives.

   Parses the QD/QS/QO/QI/QT records from the Metro/Glider and Ulsterbus/GoldLine
   CIF zips to build a queryable trip database: for any stop you can find all
   services that call there, and for any pair of stops you can find direct services
   that serve both in order.

   Record formats parsed:
   - QD  Journey header: operator, line number, description
   - QS  Journey schedule: departure time, date range, days of week, direction
   - QO7 Origin timing point: first stop ATCO, departure time
   - QI7 Intermediate timing point: stop ATCO, arrival, departure times
   - QT7 Terminus timing point: last stop ATCO, arrival time

   ATCO code mapping: trip records store 11-digit codes (e.g. ``00000009264``)
   while QL/QB stop records use 12-digit codes starting with ``7``
   (e.g. ``700000009264``).  The relation is ``stop_atco = '7' + trip_atco[0:11]``.

   .. rubric:: Example

   >>> trips = get_trip_index()
   >>> trips["700000001661"]  # stops serving Victoria Square
   [TripStop(...), ...]



Attributes
----------

.. autoapisummary::

   bolster.data_sources.translink.timetable.logger


Classes
-------

.. autoapisummary::

   bolster.data_sources.translink.timetable.TripStop
   bolster.data_sources.translink.timetable.Trip


Functions
---------

.. autoapisummary::

   bolster.data_sources.translink.timetable.get_trip_index
   bolster.data_sources.translink.timetable.find_services_at_stop
   bolster.data_sources.translink.timetable.find_direct_trips


Module Contents
---------------

.. py:data:: logger

.. py:class:: TripStop

   A single stop within a trip's stop sequence.


   .. py:attribute:: atco
      :type:  str


   .. py:attribute:: arrive
      :type:  str


   .. py:attribute:: depart
      :type:  str


   .. py:attribute:: seq
      :type:  int


.. py:class:: Trip

   A single scheduled trip (one journey on one day pattern).


   .. py:attribute:: operator
      :type:  str


   .. py:attribute:: line
      :type:  str


   .. py:attribute:: description
      :type:  str


   .. py:attribute:: depart_hhmm
      :type:  str


   .. py:attribute:: date_from
      :type:  str


   .. py:attribute:: date_to
      :type:  str


   .. py:attribute:: days
      :type:  str


   .. py:attribute:: direction
      :type:  str


   .. py:attribute:: stops
      :type:  list[TripStop]
      :value: []



.. py:function:: get_trip_index(force_refresh = False)

   Return the stop → [(Trip, TripStop)] inverted index.

   Built on first call and cached in-process for the lifetime of the
   Python process.  The underlying CIF zips are cached on disk for one week.

   :param force_refresh: Re-download CIF zips and rebuild the index.

   :returns: Dict mapping ATCOCode → list of ``(Trip, TripStop)`` tuples for
             every scheduled trip that calls at that stop.


.. py:function:: find_services_at_stop(stop_atco, force_refresh = False)

   Return all scheduled trips that call at *stop_atco*.

   :param stop_atco: 12-digit NaPTAN ATCOCode (e.g. ``"700000001661"``).
   :param force_refresh: Rebuild the trip index from source.

   :returns: Deduplicated list of :class:`Trip` objects, ordered by origin
             departure time.


.. py:function:: find_direct_trips(origin_atco, dest_atco, force_refresh = False)

   Return all direct trips that serve *origin_atco* then *dest_atco*.

   A trip is considered direct if both stops appear in its stop sequence
   and the origin stop appears *before* the destination stop.

   :param origin_atco: 12-digit NaPTAN ATCOCode of the origin stop.
   :param dest_atco: 12-digit NaPTAN ATCOCode of the destination stop.
   :param force_refresh: Rebuild the trip index from source.

   :returns: List of ``(Trip, origin_TripStop, dest_TripStop)`` tuples, ordered
             by the trip's origin departure time.  Empty list if no direct service
             runs between the two stops.