/gtfs-realtime-translators

A set of open source Python libraries for translating custom real-time transit data to the GTFS-rt format

Primary LanguagePythonApache License 2.0Apache-2.0

gtfs-realtime-translators

Build Status Total alerts Language grade: Python

gtfs-realtime-translators translates custom arrivals formats to GTFS-realtime. It uses the Google gtfs-realtime-bindings for Python, supplemented by Intersection extensions.

Overview

Following the GTFS-realtime spec, its three pillars are:

  • TripUpdate
  • VehiclePosition
  • Alert

A FeedMessage is a list of entities, each of which is one of the types above. A FeedMessage may have entities of different types.

As of 2019-06-15, only TripUpdate is supported.

Installation

pip install -e git+https://github.com/Intersection/gtfs-realtime-translators.git@<TAG>#egg=gtfs-realtime-translators

Usage

Registry

The registry is used to return a translator for a given translator key. This is useful to decouple the translator lookup via external systems from its implementation.

from gtfs_realtime_translators.registry import TranslatorRegistry

translator_klass = TranslatorRegistry.get('la-metro')
translator = translator_klass(**kwargs)

Translators

from gtfs_realtime_translators.translators import LaMetroGtfsRealtimeTranslator

translator = LaMetroGtfsRealtimeTranslator(stop_id='80122')
feed_message = translator(la_metro_rail_input_data)

At this point, feed_message is a standard protocol buffer object and adheres to the normal Python Protocol Buffer interface.

feed_bytes = feed_message.SerializeToString()

Factories

New translators should be contributed back to this library.

from gtfs_realtime_translators.factories import TripUpdate, FeedMessage

trip_update = TripUpdate.create(entity_id=entity_id,
                                arrival_time=arrival_time,
                                departure_time=departure_time,
                                trip_id=trip_id,
                                stop_id=stop_id,
                                route_id=route_id)

entities = [ trip_update ]

feed_message = FeedMessage.create(entities=entities)

GTFS-Realtime Bindings

Source gtfs-realtime.proto

The GTFS-realtime spec is maintained in the google/transit repository. Currently, since there is no versioned way to programmatically include this in our projects, we must clone it as a manual dependency.

git clone https://github.com/google/transit.git ../google-transit
cp ../google-transit/gtfs-realtime/proto/gtfs-realtime.proto gtfs_realtime_translators/bindings/

Re-generate Bindings

For our Python libraries to understand the interface specified by the GTFS-realtime spec, we must generate language bindings.

virtualenv ~/.env/gtfs-realtime-bindings
source ~/.env/gtfs-realtime-bindings/bin/activate
pip install grpcio-tools
python3 -m grpc_tools.protoc -I gtfs_realtime_translators/bindings/ --python_out=gtfs_realtime_translators/bindings/ gtfs_realtime_translators/bindings/intersection.proto

Since we are using the published spec bindings, we must do one more step. Inside the generated file, gtfs_realtime_translators/bindings/intersection_pb2.py, change the following line

import gtfs_realtime_pb2 as gtfs__realtime__pb2

to

from google.transit import gtfs_realtime_pb2 as gtfs__realtime__pb2

Run Tests Locally

pip install -r requirements.txt
pip install -e .
pytest