Skip to content

armgit / fli

Public Imported from GitHub
0

Google Flights MCP, CLI and Python Library

9.1 KB
Raw Blame
#!/usr/bin/env python3
"""Script to generate Airport and Airline enums from CSV data files.

This script reads airport and airline data from CSV files and generates
corresponding Python ``Enum`` classes. The generated enums are used
throughout the application to ensure consistent handling of airport and
airline codes.

The script expects CSV files in the following locations:
- ``data/airports.csv``: Contains airport codes and names
- ``data/airlines.csv``: Contains airline IATA codes and names

The generated enum files are written to:
- ``fli/models/airport.py``: Contains the ``Airport`` enum
- ``fli/models/airline.py``: Contains the ``Airline`` enum

Output format
-------------

We emit a single dict literal containing every (code → human name) pair
and construct the ``Enum`` programmatically via ``Enum(name, mapping)``.
This is dramatically faster to import than the previous per-member
``class`` body — a 7,883-member ``Airport`` enum import drops from
~310ms to ~70ms because Python parses one dict literal instead of
running 7,883 metaclass-driven attribute assignments. The runtime API
(``Airport.JFK``, ``isinstance``, Pydantic compat, ``__members__``,
iteration) is identical to the previous form.
"""

import csv
from collections import Counter
from pathlib import Path

PROJECT_DIR = Path(__file__).parents[1].resolve()


def _disambiguate_names(entries: list[tuple[str, str]]) -> list[tuple[str, str]]:
    """Append IATA codes to duplicate names so every Enum value is unique.

    Python's ``Enum`` treats members with the same value as aliases — the
    second silently becomes an alias for the first.  This function detects
    duplicate human-readable names and appends `` (CODE)`` to *all*
    members of each duplicate group (including the first) so every entry
    gets its own distinct Enum member.

    Entries with unique names are left untouched.
    """
    name_counts = Counter(name for _, name in entries)
    duplicates = {name for name, count in name_counts.items() if count > 1}
    if not duplicates:
        return entries
    return [(code, f"{name} ({code})" if name in duplicates else name) for code, name in entries]


def _assert_unique(entries: list[tuple[str, str]], enum_name: str) -> None:
    """Raise ``ValueError`` if any sanitized code or final name repeats.

    Must run *after* :func:`_disambiguate_names` so it validates exactly
    what :func:`_write_enum_module` is about to emit as
    ``Enum(name, mapping)``: duplicate sanitized identifiers collide as
    dict keys (the later entry silently overwrites the earlier one), and
    duplicate names collide as dict values (Python's ``Enum`` silently
    turns the second member into an alias of the first — the original bug
    this script exists to prevent).
    """
    allow_digit_prefix = enum_name == "Airline"
    sanitized_codes = [_sanitize_code(code, allow_digit_prefix) for code, _ in entries]
    code_counts = Counter(sanitized_codes)
    dup_codes = sorted(code for code, count in code_counts.items() if count > 1)
    if dup_codes:
        raise ValueError(
            f"Duplicate sanitized {enum_name} codes after sanitization: {', '.join(dup_codes)}"
        )

    name_counts = Counter(name for _, name in entries)
    dup_names = sorted(name for name, count in name_counts.items() if count > 1)
    if dup_names:
        raise ValueError(
            f"Duplicate {enum_name} names remain after disambiguation: {', '.join(dup_names)}"
        )


def _sanitize_code(code: str, allow_digit_prefix: bool = False) -> str:
    """Return a valid Python identifier for an IATA code.

    Airline codes that start with a digit (e.g. ``3F``) are prefixed
    with an underscore to keep them Python-legal. Airport codes never
    start with a digit, so the prefix is gated on the caller.
    """
    sanitized = "".join(c if c.isalnum() else "_" for c in code)
    if allow_digit_prefix and sanitized and sanitized[0].isdigit():
        sanitized = f"_{sanitized}"
    return sanitized


def _write_enum_module(
    output_path: Path,
    enum_name: str,
    doc: str,
    source_csv: str,
    entries: list[tuple[str, str]],
) -> None:
    """Write a Python module that defines ``enum_name`` from a dict literal.

    The generated module exposes two public names at module scope:

    * ``<enum_name>`` — the ``Enum`` class users import (e.g. ``Airport``).
      Identical public surface to a class-body-defined Enum: attribute
      access, value lookup, isinstance checks, Pydantic field typing,
      and iteration all behave the same way. Built through the
      :class:`enum.Enum` functional API so the metaclass only walks the
      mapping once at module load instead of once per member, cutting
      import time ~5x for a 7,883-entry enum.

    * ``<ENUM_NAME>_NAMES`` — the underlying ``dict[str, str]`` of
      ``IATA-code → human-readable-name``. Public so callers that want
      raw dict semantics (cheap ``in`` checks, iteration without paying
      Enum-member overhead, JSON dumping) can use it directly. The
      ``Enum`` stays the canonical type for typed APIs; the dict is the
      fast path.
    """
    output_path.parent.mkdir(parents=True, exist_ok=True)
    map_name = f"{enum_name.upper()}_NAMES"
    with open(output_path, "w", encoding="utf-8") as fh:
        fh.write(f'"""{doc}\n\n')
        fh.write(f"Auto-generated from {source_csv}.\n\n")
        fh.write("Exports:\n\n")
        fh.write(
            f"* :data:`{enum_name}` — the ``Enum`` class for typed APIs.\n"
            f"* :data:`{map_name}` — the underlying ``dict[code, name]``\n"
            f"  for callers that want raw dict speed.\n"
        )
        fh.write('"""\n\n')
        fh.write("from enum import Enum\n\n")
        fh.write(
            "# A single dict literal — Python parses this in one pass.\n"
            "# Defining the same data as ``class <Enum>(Enum):`` members\n"
            "# costs one metaclass call per member; ``Enum(name, mapping)``\n"
            "# below walks the dict once instead.\n"
        )
        fh.write(f"{map_name}: dict[str, str] = {{\n")
        for code, name in entries:
            sanitized = _sanitize_code(code, allow_digit_prefix=(enum_name == "Airline"))
            # Use repr() for proper escaping of any quotes/backslashes.
            fh.write(f"    {sanitized!r}: {name!r},\n")
        fh.write("}\n\n")
        fh.write(
            f'{enum_name} = Enum({enum_name!r}, {map_name})\n{enum_name}.__doc__ = """{doc}"""\n'
        )


def generate_airport_enum() -> None:
    """Generate ``Airport`` enum from ``data/airports.csv``."""
    csv_path = PROJECT_DIR / "data" / "airports.csv"
    out_path = PROJECT_DIR / "fli" / "models" / "airport.py"
    if not csv_path.exists():
        raise FileNotFoundError(f"CSV file not found: {csv_path}")

    try:
        with open(csv_path, encoding="utf-8", newline="") as fh:
            reader = csv.DictReader(fh)
            entries = [(row["Code"].strip().upper(), row["Name"].strip()) for row in reader]
    except (KeyError, csv.Error) as e:
        raise ValueError(f"Error reading CSV file: {e}") from e

    entries = _disambiguate_names(entries)
    _assert_unique(entries, enum_name="Airport")
    _write_enum_module(
        out_path,
        enum_name="Airport",
        doc="Airport IATA codes.",
        source_csv="data/airports.csv",
        entries=entries,
    )
    print(f"Generated {len(entries)} Airport members in {out_path}")


def generate_airline_enum() -> None:
    """Generate ``Airline`` enum from ``data/airlines.csv``.

    Three manual aliases — ``ONEWORLD``, ``SKYTEAM``, ``STAR_ALLIANCE`` —
    are appended after the CSV-derived entries. Those values are not
    actual IATA airline codes, but Google's flight-search API accepts
    them in the ``airlines`` filter as alliance pseudo-codes and the
    parser surfaces them as :class:`Airline` members. Keep them in sync
    with :data:`fli.models.google_flights.base.Alliance`.
    """
    csv_path = PROJECT_DIR / "data" / "airlines.csv"
    out_path = PROJECT_DIR / "fli" / "models" / "airline.py"
    if not csv_path.exists():
        raise FileNotFoundError(f"CSV file not found: {csv_path}")

    try:
        with open(csv_path, encoding="utf-8", newline="") as fh:
            reader = csv.DictReader(fh)
            entries = [(row["IATA"].strip().upper(), row["Airline"].strip()) for row in reader]
    except (KeyError, csv.Error) as e:
        raise ValueError(f"Error reading CSV file: {e}") from e

    # Append alliance pseudo-codes. Position matters only for
    # iteration order — value-based lookups (``Airline("Oneworld")``)
    # work regardless.
    entries.extend(
        [
            ("ONEWORLD", "Oneworld"),
            ("SKYTEAM", "SkyTeam"),
            ("STAR_ALLIANCE", "Star Alliance"),
        ]
    )

    entries = _disambiguate_names(entries)
    _assert_unique(entries, enum_name="Airline")
    _write_enum_module(
        out_path,
        enum_name="Airline",
        doc="Airline IATA codes.",
        source_csv="data/airlines.csv",
        entries=entries,
    )
    print(f"Generated {len(entries)} Airline members in {out_path}")


if __name__ == "__main__":
    generate_airport_enum()
    generate_airline_enum()