openfly 0.1.0__py3-none-any.whl

fli/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI module for the fli package."""
+
+from fli.cli.main import cli
+
+__all__ = ["cli"]

fli/cli/commands/__init__.py

@@ -0,0 +1,6 @@
+"""Command functions for the CLI."""
+
+from fli.cli.commands.dates import dates
+from fli.cli.commands.flights import flights
+
+__all__ = ["flights", "dates"]

fli/cli/commands/airports.py

@@ -0,0 +1,60 @@
+"""Airport search command for looking up IATA codes."""
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from fli.cli.enums import OutputFormat
+from fli.cli.utils import emit_json
+from fli.core.airports import search_airports
+
+console = Console()
+
+
+def airports(
+    query: Annotated[
+        str,
+        typer.Argument(help="City name, airport name, or IATA code to search for"),
+    ],
+    limit: Annotated[int, typer.Option("--limit", "-n", help="Maximum results")] = 10,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", help="Output format (text or json)")
+    ] = OutputFormat.TEXT,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Deprecated alias for --format json", hidden=True),
+    ] = False,
+):
+    """Search for airports by city name, airport name, or IATA code.
+
+    Example:
+        fli airports "new york"
+        fli airports tokyo
+        fli airports JFK
+        fli airports heathrow
+
+    """
+    results = search_airports(query, limit=limit)
+
+    if not results:
+        console.print(f"[yellow]No airports found matching '{query}'[/yellow]")
+        raise typer.Exit(1)
+
+    if json_output or output_format == OutputFormat.JSON:
+        # Local serializer: search results carry ``match_type`` (which
+        # serialize_airport does not), so we keep this small shape here.
+        emit_json(
+            [{"code": r.code.name, "name": r.name, "match_type": r.match_type} for r in results]
+        )
+    else:
+        table = Table(title=f"Airports matching '{query}'")
+        table.add_column("Code", style="bold cyan", width=6)
+        table.add_column("Airport Name", style="white")
+        table.add_column("Match", style="dim")
+
+        for result in results:
+            table.add_row(result.code.name, result.name, result.match_type)
+
+        console.print(table)

fli/cli/commands/book.py

@@ -0,0 +1,109 @@
+"""`fli book` — per-vendor booking options for a chosen itinerary.
+
+The Python library and the MCP server already expose
+:meth:`fli.search.SearchFlights.get_booking_options`; this brings the same
+capability to the CLI. It runs a search, selects the itinerary identified by
+``--flight-numbers`` (via the shared :func:`match_flight_by_numbers` selector),
+then prints the airline-direct + OTA fares with their booking URLs.
+"""
+
+from typing import Annotated, Any
+
+import typer
+
+from fli.cli.enums import OutputFormat
+from fli.cli.errors import report_cli_error
+from fli.cli.utils import emit_json, normalize_cli_date
+from fli.core import (
+    build_flight_segments,
+    parse_cabin_class,
+    parse_max_stops,
+    resolve_airport,
+)
+from fli.core.parsers import ParseError
+from fli.core.selectors import match_flight_by_numbers
+from fli.models import FlightSearchFilters, PassengerInfo
+from fli.search import SearchClientError, SearchFlights
+
+
+def book(
+    origin: Annotated[str, typer.Argument(help="Departure airport IATA code (e.g. JFK)")],
+    destination: Annotated[str, typer.Argument(help="Arrival airport IATA code (e.g. LHR)")],
+    departure_date: Annotated[str, typer.Argument(help="Outbound date YYYY-MM-DD")],
+    return_date: Annotated[
+        str | None, typer.Option("--return", "-r", help="Return date YYYY-MM-DD (round trip)")
+    ] = None,
+    flight_numbers: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--flight-numbers",
+            "-f",
+            help="Flight number(s) identifying the itinerary, e.g. -f BA178 (repeatable). "
+            "Omit to price the top result.",
+        ),
+    ] = None,
+    cabin_class: Annotated[str, typer.Option("--cabin", "-c", help="Cabin class")] = "ECONOMY",
+    max_stops: Annotated[str, typer.Option("--stops", "-s", help="Max stops")] = "ANY",
+    passengers: Annotated[int, typer.Option("--passengers", "-p", help="Adults")] = 1,
+    currency: Annotated[str, typer.Option("--currency", help="ISO 4217 currency")] = "USD",
+    language: Annotated[str | None, typer.Option("--language", help="BCP-47 hl param")] = None,
+    country: Annotated[str | None, typer.Option("--country", help="ISO 3166-1 gl param")] = None,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", help="Output format")
+    ] = OutputFormat.TEXT,
+) -> None:
+    """Get bookable fares (vendor, price, URL) for a specific itinerary."""
+    try:
+        currency = currency.upper()
+        dep = normalize_cli_date(departure_date)
+        ret = normalize_cli_date(return_date)
+        segments, trip_type = build_flight_segments(
+            origin=resolve_airport(origin),
+            destination=resolve_airport(destination),
+            departure_date=dep,
+            return_date=ret,
+        )
+        filters = FlightSearchFilters(
+            trip_type=trip_type,
+            passenger_info=PassengerInfo(adults=passengers),
+            flight_segments=segments,
+            stops=parse_max_stops(max_stops),
+            seat_type=parse_cabin_class(cabin_class),
+        )
+
+        search = SearchFlights()
+        results = search.search(filters, currency=currency, language=language, country=country)
+        if not results:
+            raise SearchClientError("No flights found for the given route and date.")
+
+        flight = match_flight_by_numbers(results, flight_numbers)
+        if flight is None:
+            raise SearchClientError(
+                f"No itinerary matched flight numbers {flight_numbers}. "
+                "Run `fli flights` first to see available flight numbers."
+            )
+
+        options = search.get_booking_options(
+            flight, filters, currency=currency, language=language, country=country
+        )
+    except (ParseError, ValueError, SearchClientError) as exc:
+        raise report_cli_error(exc, command="book") from exc
+
+    payload: dict[str, Any] = {
+        "booking_options": [opt.model_dump(exclude_none=True) for opt in options]
+    }
+
+    if output_format == OutputFormat.JSON:
+        emit_json(payload)
+        return
+
+    if not options:
+        typer.echo("No bookable fares returned for this itinerary.")
+        return
+    typer.echo(f"Booking options ({len(options)}):")
+    for opt in options:
+        tag = " (airline)" if opt.is_airline_direct else ""
+        price = f"{opt.currency or currency} {opt.price:,.2f}" if opt.price is not None else "—"
+        typer.echo(f"  {opt.vendor_name or opt.vendor_code or '?'}{tag}: {price}")
+        if opt.booking_url:
+            typer.echo(f"    {opt.booking_url}")

fli/cli/commands/dates.py

@@ -0,0 +1,510 @@
+"""Date search CLI command for finding cheapest travel dates."""
+
+from datetime import datetime, timedelta
+from typing import Annotated
+
+import typer
+
+from fli.cli.enums import DayOfWeek, OutputFormat
+from fli.cli.utils import (
+    build_json_success_response,
+    display_date_results,
+    emit_cli_error,
+    emit_json,
+    filter_dates_by_days,
+    normalize_cli_date,
+    normalize_cli_time_range,
+    serialize_date_result,
+    validate_currency,
+)
+from fli.core import (
+    build_date_search_segments,
+    parse_airlines,
+    parse_alliances,
+    parse_cabin_class,
+    parse_emissions,
+    parse_max_stops,
+    resolve_airport,
+)
+from fli.models import (
+    BagsFilter,
+    DateSearchFilters,
+    LayoverRestrictions,
+    PassengerInfo,
+    PriceLimit,
+    TimeRestrictions,
+    TripType,
+)
+from fli.search import SearchDates
+
+
+def _build_selected_days(
+    *,
+    monday: bool,
+    tuesday: bool,
+    wednesday: bool,
+    thursday: bool,
+    friday: bool,
+    saturday: bool,
+    sunday: bool,
+) -> list[DayOfWeek]:
+    """Build the selected day filters list."""
+    selected_days = []
+    if monday:
+        selected_days.append(DayOfWeek.MONDAY)
+    if tuesday:
+        selected_days.append(DayOfWeek.TUESDAY)
+    if wednesday:
+        selected_days.append(DayOfWeek.WEDNESDAY)
+    if thursday:
+        selected_days.append(DayOfWeek.THURSDAY)
+    if friday:
+        selected_days.append(DayOfWeek.FRIDAY)
+    if saturday:
+        selected_days.append(DayOfWeek.SATURDAY)
+    if sunday:
+        selected_days.append(DayOfWeek.SUNDAY)
+    return selected_days
+
+
+def dates(
+    origin: Annotated[str, typer.Argument(help="Departure airport IATA code (e.g., JFK)")],
+    destination: Annotated[str, typer.Argument(help="Arrival airport IATA code (e.g., LHR)")],
+    start_date: Annotated[
+        str,
+        typer.Option("--from", help="Start date (YYYY-MM-DD)"),
+    ] = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d"),
+    end_date: Annotated[str, typer.Option("--to", help="End date (YYYY-MM-DD)")] = (
+        datetime.now() + timedelta(days=60)
+    ).strftime("%Y-%m-%d"),
+    trip_duration: Annotated[
+        int,
+        typer.Option(
+            "--duration",
+            "-d",
+            help="Trip duration in days",
+        ),
+    ] = 3,
+    airlines: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--airlines",
+            "-a",
+            help="Airline IATA codes (e.g., BA,KL or repeated --airlines BA --airlines KL)",
+        ),
+    ] = None,
+    is_round_trip: Annotated[
+        bool,
+        typer.Option(
+            "--round",
+            "-R",
+            help="Search for round-trip flights",
+        ),
+    ] = False,
+    max_stops: Annotated[
+        str,
+        typer.Option(
+            "--stops",
+            "-s",
+            help="Maximum stops (ANY, 0 for non-stop, 1 for one stop, 2+ for two stops)",
+        ),
+    ] = "ANY",
+    cabin_class: Annotated[
+        str,
+        typer.Option(
+            "--class",
+            "-c",
+            help="Cabin class (ECONOMY, PREMIUM_ECONOMY, BUSINESS, FIRST)",
+        ),
+    ] = "ECONOMY",
+    sort_by_price: Annotated[
+        bool,
+        typer.Option(
+            "--sort",
+            help="Sort results by price (lowest to highest)",
+        ),
+    ] = False,
+    monday: Annotated[
+        bool,
+        typer.Option(
+            "--monday",
+            "-mon",
+            help="Include Mondays in results",
+        ),
+    ] = False,
+    tuesday: Annotated[
+        bool,
+        typer.Option(
+            "--tuesday",
+            "-tue",
+            help="Include Tuesdays in results",
+        ),
+    ] = False,
+    wednesday: Annotated[
+        bool,
+        typer.Option(
+            "--wednesday",
+            "-wed",
+            help="Include Wednesdays in results",
+        ),
+    ] = False,
+    thursday: Annotated[
+        bool,
+        typer.Option(
+            "--thursday",
+            "-thu",
+            help="Include Thursdays in results",
+        ),
+    ] = False,
+    friday: Annotated[
+        bool,
+        typer.Option(
+            "--friday",
+            "-fri",
+            help="Include Fridays in results",
+        ),
+    ] = False,
+    saturday: Annotated[
+        bool,
+        typer.Option(
+            "--saturday",
+            "-sat",
+            help="Include Saturdays in results",
+        ),
+    ] = False,
+    sunday: Annotated[
+        bool,
+        typer.Option(
+            "--sunday",
+            "-sun",
+            help="Include Sundays in results",
+        ),
+    ] = False,
+    departure_window: Annotated[
+        str | None,
+        typer.Option(
+            "--time",
+            "-time",
+            help="Departure time window in 24h format (e.g., 6-20)",
+        ),
+    ] = None,
+    output_format: Annotated[
+        OutputFormat,
+        typer.Option(
+            "--format",
+            help="Output format",
+            case_sensitive=False,
+        ),
+    ] = OutputFormat.TEXT,
+    currency: Annotated[
+        str,
+        typer.Option(
+            "--currency",
+            callback=validate_currency,
+            help="Currency code (USD, EUR, GBP, JPY...). Passed to Google as `curr=`.",
+        ),
+    ] = "USD",
+    language: Annotated[
+        str | None,
+        typer.Option(
+            "--language",
+            help="Optional BCP-47 language code (e.g., 'en-GB') passed to Google as `hl=`.",
+        ),
+    ] = None,
+    country: Annotated[
+        str | None,
+        typer.Option(
+            "--country",
+            help="Optional ISO 3166-1 alpha-2 country code (e.g., 'GB') passed to Google as `gl=`.",
+        ),
+    ] = None,
+    exclude_airlines: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--exclude-airlines",
+            "-A",
+            help="Airline IATA codes to EXCLUDE from results.",
+        ),
+    ] = None,
+    alliance: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--alliance",
+            help="Restrict to alliances: ONEWORLD, SKYTEAM, STAR_ALLIANCE.",
+        ),
+    ] = None,
+    exclude_alliance: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--exclude-alliance",
+            help="Alliance names to EXCLUDE (ONEWORLD, SKYTEAM, STAR_ALLIANCE).",
+        ),
+    ] = None,
+    min_layover: Annotated[
+        int | None,
+        typer.Option(
+            "--min-layover",
+            help="Minimum layover duration in minutes (multi-stop trips only).",
+            min=1,
+        ),
+    ] = None,
+    max_layover: Annotated[
+        int | None,
+        typer.Option(
+            "--max-layover",
+            help="Maximum layover duration in minutes (multi-stop trips only).",
+            min=1,
+        ),
+    ] = None,
+    layover: Annotated[
+        list[str] | None,
+        typer.Option("--layover", help="Restrict layover to these airports (e.g., --layover ORD)"),
+    ] = None,
+    emissions: Annotated[
+        str, typer.Option("--emissions", help="Filter by emissions level (ALL, LESS)")
+    ] = "ALL",
+    checked_bags: Annotated[
+        int,
+        typer.Option("--bags", "-b", help="Checked bags to include in price (0, 1, or 2)", min=0,
+                     max=2),
+    ] = 0,
+    carry_on: Annotated[
+        bool, typer.Option("--carry-on", help="Include carry-on bag fee in price")
+    ] = False,
+    max_price: Annotated[
+        int | None,
+        typer.Option("--max-price", help="Maximum price in the search currency.", min=1),
+    ] = None,
+    adults: Annotated[
+        int, typer.Option("--adults", help="Number of adult passengers", min=1)
+    ] = 1,
+    children: Annotated[
+        int, typer.Option("--children", help="Number of children (2-11 years)", min=0)
+    ] = 0,
+    infants_in_seat: Annotated[
+        int, typer.Option("--infants-seat", help="Number of infants in their own seat", min=0)
+    ] = 0,
+    infants_on_lap: Annotated[
+        int, typer.Option("--infants-lap", help="Number of lap infants", min=0)
+    ] = 0,
+):
+    """Find the cheapest dates to fly between two airports.
+
+    Example:
+        fli dates LAX MIA --class BUSINESS --stops NON_STOP --friday
+        fli dates LAX MIA --alliance ONEWORLD --currency EUR
+        fli dates LAX MIA --exclude-airlines DL --max-layover 240
+
+    """
+    # Built from raw inputs so it survives an early ParseError (before any
+    # parsing/normalization has run); attached to every error response.
+    error_query = {
+        "origin": origin,
+        "destination": destination,
+        "start_date": start_date,
+        "end_date": end_date,
+        "trip_duration": trip_duration,
+        "is_round_trip": is_round_trip,
+        "cabin_class": cabin_class,
+        "max_stops": max_stops,
+        "departure_window": (
+            f"{departure_window[0]}-{departure_window[1]}"
+            if isinstance(departure_window, tuple)
+            else departure_window
+        ),
+        "airlines": airlines,
+        "sort_by_price": sort_by_price,
+        "days": [
+            day.value
+            for day in _build_selected_days(
+                monday=monday,
+                tuesday=tuesday,
+                wednesday=wednesday,
+                thursday=thursday,
+                friday=friday,
+                saturday=saturday,
+                sunday=sunday,
+            )
+        ],
+    }
+
+    try:
+        start_date = normalize_cli_date(start_date)
+        end_date = normalize_cli_date(end_date)
+        departure_window = normalize_cli_time_range(departure_window)
+
+        # Parse parameters using shared utilities
+        origin_airport = resolve_airport(origin)
+        destination_airport = resolve_airport(destination)
+        trip_type = TripType.ROUND_TRIP if is_round_trip else TripType.ONE_WAY
+        stops = parse_max_stops(max_stops)
+        seat_type = parse_cabin_class(cabin_class)
+        parsed_airlines = parse_airlines(airlines)
+        parsed_exclude_airlines = parse_airlines(exclude_airlines)
+        parsed_alliances = parse_alliances(alliance)
+        parsed_exclude_alliances = parse_alliances(exclude_alliance)
+        selected_days = _build_selected_days(
+            monday=monday,
+            tuesday=tuesday,
+            wednesday=wednesday,
+            thursday=thursday,
+            friday=friday,
+            saturday=saturday,
+            sunday=sunday,
+        )
+        query = {
+            "origin": origin_airport.name,
+            "destination": destination_airport.name,
+            "start_date": start_date,
+            "end_date": end_date,
+            "trip_duration": trip_duration,
+            "is_round_trip": is_round_trip,
+            "cabin_class": seat_type.name,
+            "max_stops": stops.name,
+            "departure_window": (
+                f"{departure_window[0]}-{departure_window[1]}" if departure_window else None
+            ),
+            "airlines": (
+                [airline.name.lstrip("_") for airline in parsed_airlines]
+                if parsed_airlines
+                else None
+            ),
+            "sort_by_price": sort_by_price,
+            "days": [day.value for day in selected_days],
+        }
+
+        # Build time restrictions from tuple
+        time_restrictions = None
+        if departure_window:
+            start_hour, end_hour = departure_window
+            time_restrictions = TimeRestrictions(
+                earliest_departure=start_hour,
+                latest_departure=end_hour,
+                earliest_arrival=None,
+                latest_arrival=None,
+            )
+
+        # Build flight segments using shared builder
+        segments, trip_type = build_date_search_segments(
+            origin=origin_airport,
+            destination=destination_airport,
+            start_date=start_date,
+            trip_duration=trip_duration,
+            is_round_trip=is_round_trip,
+            time_restrictions=time_restrictions,
+        )
+
+        # Build layover constraints (airports + min / max duration).
+        layover_airports = [resolve_airport(code) for code in layover] if layover else None
+        layover_restrictions = None
+        if layover_airports or min_layover is not None or max_layover is not None:
+            layover_restrictions = LayoverRestrictions(
+                airports=layover_airports,
+                min_duration=min_layover,
+                max_duration=max_layover,
+            )
+
+        # Build bags filter
+        bags_filter = None
+        if checked_bags > 0 or carry_on:
+            bags_filter = BagsFilter(checked_bags=checked_bags, carry_on=carry_on)
+
+        # Create search filters
+        filters = DateSearchFilters(
+            trip_type=trip_type,
+            passenger_info=PassengerInfo(
+                adults=adults,
+                children=children,
+                infants_in_seat=infants_in_seat,
+                infants_on_lap=infants_on_lap,
+            ),
+            flight_segments=segments,
+            stops=stops,
+            seat_type=seat_type,
+            airlines=parsed_airlines,
+            airlines_exclude=parsed_exclude_airlines,
+            alliances=parsed_alliances,
+            alliances_exclude=parsed_exclude_alliances,
+            layover_restrictions=layover_restrictions,
+            price_limit=PriceLimit(max_price=max_price) if max_price else None,
+            emissions=parse_emissions(emissions),
+            bags=bags_filter,
+            from_date=start_date,
+            to_date=end_date,
+            duration=trip_duration if trip_type == TripType.ROUND_TRIP else None,
+        )
+
+        # Perform search; pass currency/language/country through as URL params.
+        search_client = SearchDates()
+        results = search_client.search(
+            filters,
+            currency=currency,
+            language=language,
+            country=country,
+        )
+
+        if not results:
+            results = []
+
+        if selected_days:
+            results = filter_dates_by_days(results, selected_days, trip_type)
+
+        # Sort dates by price if sort flag is enabled
+        if sort_by_price:
+            results.sort(key=lambda x: x.price)
+
+        origin_code = origin_airport.name.lstrip("_")
+        destination_code = destination_airport.name.lstrip("_")
+
+        if output_format == OutputFormat.JSON:
+            emit_json(
+                build_json_success_response(
+                    search_type="dates",
+                    trip_type=trip_type,
+                    query=query,
+                    results_key="dates",
+                    results=[
+                        serialize_date_result(
+                            result,
+                            trip_type,
+                            default_currency=currency,
+                            origin=origin_code,
+                            destination=destination_code,
+                            currency=currency,
+                            language=language,
+                            country=country,
+                        )
+                        for result in results
+                    ],
+                )
+            )
+            return
+
+        if not results:
+            message = (
+                "No flights found for the selected days."
+                if selected_days
+                else "No flights found for these dates."
+            )
+            typer.echo(message)
+            raise typer.Exit(1)
+
+        display_date_results(
+            results,
+            trip_type,
+            default_currency=currency,
+            origin=origin_code,
+            destination=destination_code,
+            currency=currency,
+            language=language,
+            country=country,
+        )
+
+    except Exception as e:  # noqa: BLE001 — emit_cli_error classifies + reports
+        raise emit_cli_error(
+            e,
+            search_type="dates",
+            command="dates",
+            output_format=output_format,
+            query=error_query,
+        ) from e