PyGTFSLib

A python library for the GTFS format.

So far, this is only a loose, incomplete collection of rather low-level tools for parsing GTFS feeds. The motivation for this library is to consolidate GTFS related code used at geOps in a single library. This is still work in progress, so breaking changes are to be expected.

This library aims to be efficient in terms of parsing time and memory usage to allow processing a large number of feeds.

Installation

Add the latest stable release from PyPI to your project with uv:

uv add pygtfslib

Modules

Spatial

The pygtfslib.spatial module contains classes and functions related to spatial data. So far, there is only one function read_shapes that can be used to parse shapes.txt using a generic factory that accepts an iterable of pygtfslib.spatial.ShapeRow instances.

Temporal

The pygtfslib.temporal module contains classes and functions related to temporal data. So far, it provides functions to parse calendar and frequency entries and stop times. It also provides a TimeCache class that accelerates conversion of GTFS timezone, operating day and time delta to a timezone-aware python datetime.datetime and back. Converting back shifts the operating day if needed since GTFS cannot express negative times or times of 100 hours or more. GTFS times can be parsed and formatted with the cached parse_timedelta and format_timedelta functions.

MOT

The pygtfslib.mot module contains tools related to GTFS route types / mode of transportation. So far, there is a function route_type_to_mot that can convert a GTFS route type or extended route type to a MOT string that can be used in the geOps routing engine.

CSV

The pygtfslib.fast_csv module contains low-level tools for CSV parsing. There are two generator functions that allow to iterate over a CSV file yielding rows as dicts or namedtuples. They are built on top of the builtin python CSV reader but they are faster than the builtin DictReader.

Issue Tracker

Please use the GitHub issue tracker to report bugs/issues.

Development

Contributing

If you want to contribute to the pygtfslib library, you can make a pull request at GitHub. Before working on major features/changes, please consider contacting us about your plans. See our GitHub page for contact details.

Editable Installation

Clone this repo and enter the corresponding directory. Then run:

uv sync

Pre-Commit Hooks

Enable pre-commit hooks:

uv run pre-commit install

From time to time (not automated yet) run

uv run pre-commit autoupdate

to update frozen revs.

Run tests

Run tests and analyze code coverage:

uv run pytest --cov=pygtfslib --cov-report term --cov-fail-under=40 pygtfslib

Build release for PyPI

Make sure to add a git tag first and push it to geOps gitlab and github.

Install build once:

uv tool install build

Then run

pyproject-build