awesome-cheap-flights 1.0.1

Weekend-hopper toolkit for ICN short-haul scouting

Awesome Cheap Flights

Weekend-hopper toolkit for spotting cheap ICN short-hauls without opening browser.

Highlights

• Hidden-leg discovery merges with regular legs automatically.
• Hidden-leg discovery only bridges a single intermediate stop.
• Plans expand airport pools and date windows per leg.
• Duplicate flights per journey leg collapse into a single row.
• Progress logs now surface a sample flight summary per batch.
• Automatic itinerary workbooks enumerate every leg combination with totals.
• CSV rows expose variant metadata for hidden journeys.
• Rich logging prints overview tables and elapsed minutes.

Examples

Example 1. Quick uvx run.

uvx awesome-cheap-flights@latest --config sample.config.yaml --plan sample-hop

Example 2. Local CLI run.

uv run python -m awesome_cheap_flights.cli --config sample.config.yaml --plan sample-hop

Example 3. macOS uv install.

curl -Ls https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"
uvx awesome-cheap-flights@latest --config sample.config.yaml --plan sample-hop

Example 4. Windows uv install.

powershell -ExecutionPolicy Bypass -Command "iwr https://astral.sh/uv/install.ps1 -useb | iex"
uvx awesome-cheap-flights@latest --config sample.config.yaml --plan sample-hop

Example 5. Android uv install.

pkg update
pkg install curl python
curl -Ls https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"
uvx awesome-cheap-flights@latest --config sample.config.yaml --plan sample-hop

After each run, open the CSV and sort by price.

Development mode

Run the CLI locally for iterative tweaks.

uv run python -m awesome_cheap_flights.cli --config config.yaml --output output/dev.csv

• Copy sample.config.yaml into config.yaml before editing routes.
• Update config.yaml to adjust places, paths, or windows.
• Set UV_CACHE_DIR=$(pwd)/.cache/uv to isolate uv cache.
• Omit --output to write timestamped files inside output/ automatically.
• Combine CLI overrides with commas or repeated flags for airports.
• Sample plan completes within five minutes on modern laptops.

Troubleshooting

• Upgrade typing_extensions when imports complain about missing features.
• Append --debug for full provider payload dumps during runs.
• Press Ctrl+C to save draft CSV and resume later minutes.
• Update to this revision if python -m awesome_cheap_flights.cli printed nothing.
• Install openpyxl>=3.1 if itinerary workbooks fail to generate.

Configuration

• Set schema_version: v2 to enable the DSL.
• Fill defaults with currency, passenger count, and request minutes.
• Request delay accepts fractional seconds for rate limiting.
• Filters hold max_stops, include_hidden, and max_hidden_hops limits.
• Departures allow per-leg max_stops overrides alongside date selectors.
• Output directory and filename_pattern customize CSV targets.
• Plans list places, path, departures, filters, and options blocks.
• Options include include_hidden toggles and hop caps per plan.
• CLI overrides accept plan, currency, passengers, proxy, concurrency, debug.

YAML sample

schema_version: v2
defaults:
  currency: USD
  passengers: 1
  request:
    delay: 0.5
    retries: 1
    max_leg_results: 3
  filters:
    max_stops: 1
    include_hidden: true
    max_hidden_hops: 1
  output:
    directory: output
    filename_pattern: "{plan}_{timestamp}.csv"
plans:
  - name: sample-hop
    places:
      home: [ICN]
      city: [FUK, HKG]
    path: [home, city, home]
    departures:
      "home->city":
        dates: ["2026-01-01", "2026-01-02"]
        max_stops: 0
      "city->home":
        window:
          start: "2026-01-04"
          end: "2026-01-05"
    filters:
      "home->city":
        max_stops: 0
    options:
      include_hidden: true
      max_hidden_hops: 1
http_proxy: null
concurrency: 1

Each plan expands airport combinations and departure calendars automatically.

Output fields

• plan_name marks the source plan for grouping.
• journey_id stores a stable slug per journey.
• journey_label summarizes path and chosen dates.
• variant denotes scheduled legs or hidden discoveries.
• leg_sequence tracks zero-based leg ordering.
• origin_place and destination_place map to place identifiers.
• origin_code and destination_code store airport selections.
• hidden_via_places and hidden_via_codes capture intermediary hops.
• departure_date, departure_time, departure_at hold normalized timestamps.
• duration_hours stores decimal leg durations.
• airline holds the carrier label.
• stops and stop_notes capture layover counts and codes.
• price stores integer fare digits.
• is_best mirrors Google Flights highlights.
• currency shows the fare currency code.

Excel itinerary workbook

• Each run emits <csv_stem>_itineraries.xlsx alongside the CSV export.
• Columns follow <origin_place>-><destination_place>_<field> naming (e.g., home->las_price).
• Per-leg fields cover price, currency, departure timestamps, airline, stops, stop_notes, duration_hours, and variant flags.
• Totals include total_price, total_currency, and aggregated total_duration_hours when data is complete.
• For practicality the workbook samples the first 10 flights per leg before computing every combination.

Project layout

• awesome_cheap_flights/cli.py handles CLI parsing and config loading.
• awesome_cheap_flights/main.py enables python -m execution.
• awesome_cheap_flights/pipeline.py runs scraping, expansion, and CSV export.

Release automation

• Pushing main triggers release workflow when relevant files change.
• Append [minor] to bump the minor version automatically.
• Use workflow_dispatch for manual bumps when needed.
• Provide a PYPI_TOKEN secret with publish permissions.
• Select current to reuse the existing version during manual runs.

Last commit id: 63ccbe0b806376b562debd98600dfef51f1b9a07