flights - Moses Yebei

The Problem

Clients that need programmatic access to Google Flights data must either scrape HTML (fragile) or rely on undocumented internal APIs (unstable). Maintaining a reliable, typed Python wrapper that hides the parsing details and offers a clean query object is the missing piece for many travel‑tech services.

What This Does

fast-flights provides a strongly‑typed wrapper around Google Flights. The public API lives in fast_flights/__init__.py, exposing FlightQuery, Passengers, create_query, and get_flights. Query objects are assembled in fast_flights/querying.py (pb, to_bytes, url, params) and passed to fast_flights/fetcher.py where get_flights orchestrates the request‑response cycle. Optional integrations (Bright Data, SearchApi) are in fast_flights/integrations/, each subclassing the base integration in fast_flights/integrations/base.py.

How It Is Wired

Execution begins when a consumer calls get_flights(query, integration=…) (defined in fast_flights/fetcher.py).

get_flights → fetch_flights_html (same file) builds the request URL via url (querying.py) and serialises the query with to_bytes.
fetch_flights_html → fetch_html (integrations/base.py) performs the outbound HTTP GET. fetch_html pulls credentials with get_env and respects the chosen integration class.
fetch_html returns raw HTML/JS payload → parse (fast_flights/parser.py) which calls parse_js.
parse_js constructs model objects (Airport, SimpleDatetime, etc.) from the protobuf‑derived data (fast_flights/pb/flights_pb2.py).
The result list is transformed by to_result_model in fast_flights/integrations/searchapi.py (when using SearchApi) or by the generic mapper in fetcher.py for the default path.

Key hubs:

fast_flights/querying.py (imported by 4 modules, 14 functions) builds the request.
fast_flights/integrations/base.py (2 callers, makes the only network call).
fast_flights/fetcher.py (5 functions, orchestrates the flow).

No circular imports were detected; the call graph has 67 internal edges, with create_query, FlightQuery, to_bytes, and Airport each invoked from four distinct locations, giving them the widest blast radius.

How To Use It

# Clone and install the package locally
git clone https://github.com/moses-y/flights
cd flights
pip install -e .          # installs fast_flights and its deps

from fast_flights import FlightQuery, Passengers, create_query, get_flights

query = create_query(
    flights=[FlightQuery(date="2024-12-01", from_airport="NYC", to_airport="LON")],
    seat="economy",
    passengers=Passengers(adults=1),
    language="en-US",
)

result = get_flights(query)          # default (no integration)
# result is a list of typed flight objects

If using Bright Data or SearchApi, instantiate the integration class (BrightData(zone="...") or SearchApi()) and pass it to get_flights. Those classes read required secrets via fast_flights/integrations/base.get_env, so set the appropriate environment variables before runtime.

Real‑World Use

A travel‑booking backend can call create_query for each itinerary, invoke get_flights, and store the returned Flight objects (with price, airline, carbon emissions) in its own database. The strong typing eliminates ad‑hoc dict handling and the single‑function entry point (get_flights) makes it easy to wrap in an async task queue.

Code Health & Issues

High – Pin GitHub Action versions – .github/workflows/*.yml uses pypa/gh-action-pypi-publish@release/v1. Pin to a commit SHA.
High – Missing lockfile – pyproject.toml present without poetry.lock/requirements.lock. Commit a lockfile to freeze transitive deps.
High – CI never runs tests – Workflows contain no test step despite four test files. Add a pytest step.
Medium – Enable Dependabot – No auto‑update config; add .github/dependabot.yml.
Medium – No vulnerability scan – Add dependency-review-action or osv-scanner to PR checks.
Medium – Checkout persists token – In python-publish.yml set persist-credentials: false.
Low – No job timeout – Add timeout-minutes to docs.yml jobs.
High – Oversized generated enum – enums/_generated_enum.py (3,313 lines) should be split into logical groups.
Medium – Duplicated test code – Repeated 6‑line block in tests/general.py and tests/searchapi.py; extract a helper module.

Dependency note: protobuf >=5.27.0 is two major versions behind the latest 7.x release; consider updating to avoid compatibility surprises.

The Bottom Line

fast-flights delivers a clean, typed interface for Google Flights data with a modest codebase and clear separation of concerns. The core request‑response path is well‑encapsulated, but the repo lacks a locked dependency set, proper CI test execution, and has a few maintainability pain points (large generated enum, duplicated test helpers). It is suitable for teams comfortable with Python packaging and willing to address the CI and dependency hygiene gaps before production use.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

47 files

Python21
Markdown5
YAML3
CSS1
HTML1
Protocol Buffers1

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["fast_flights<br/>13 modules"] g1["tests<br/>4 modules"] g2["enums<br/>2 modules"] g3["scripts<br/>2 modules"] g1 -->|5| g0

Module dependencies

The 10 most depended-upon modules of 21, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_fast_flights_querying["querying"] n1_st_flights_integrations_base["base"] n2_fast_flights___init__["__init__"] n3_fast_flights_pb_flights_pb2["flights_pb2"] n4_fast_flights_fetcher["fetcher"] n5_fast_flights_parser["parser"] n6_fast_flights_exceptions["exceptions"] n7_lights_integrations___init__["__init__"] n8_hts_integrations_bright_data["bright_data"] n9_ights_integrations_searchapi["searchapi"] n2_fast_flights___init__ --> n6_fast_flights_exceptions n2_fast_flights___init__ --> n4_fast_flights_fetcher n2_fast_flights___init__ --> n5_fast_flights_parser n2_fast_flights___init__ --> n0_fast_flights_querying n4_fast_flights_fetcher --> n1_st_flights_integrations_base n4_fast_flights_fetcher --> n5_fast_flights_parser n4_fast_flights_fetcher --> n0_fast_flights_querying n7_lights_integrations___init__ --> n1_st_flights_integrations_base n7_lights_integrations___init__ --> n8_hts_integrations_bright_data n7_lights_integrations___init__ --> n9_ights_integrations_searchapi n1_st_flights_integrations_base --> n0_fast_flights_querying n8_hts_integrations_bright_data --> n4_fast_flights_fetcher n8_hts_integrations_bright_data --> n0_fast_flights_querying n8_hts_integrations_bright_data --> n1_st_flights_integrations_base n9_ights_integrations_searchapi --> n3_fast_flights_pb_flights_pb2 n9_ights_integrations_searchapi --> n0_fast_flights_querying n9_ights_integrations_searchapi --> n1_st_flights_integrations_base n5_fast_flights_parser --> n6_fast_flights_exceptions

Dependencies

1 of 5 declared dependencies are a major version behind. Resolved 4 of 5 against the registry.

Package	Declared	Latest	Behind
`protobuf`	>=5.27.0	7.35.1	2 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium3

low1

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

pypa/gh-action-pypi-publish@release/v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Make CI invoke the test suite it hashigh4 occurrences

.github/workflows

4 test files, no test command in any workflow

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/python-publish.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/docs.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.