farepy 0.1.1__tar.gz

farepy-0.1.1/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: farepy
+Version: 0.1.1
+Summary: Multi-source flight search with normalized results, caching, and batch support
+Author: Thor Whalen
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/thorwhalen/farepy
+Project-URL: Repository, https://github.com/thorwhalen/farepy
+Project-URL: Issues, https://github.com/thorwhalen/farepy/issues
+Requires-Python: >=3.10
+Provides-Extra: google-flights
+Requires-Dist: fast-flights; extra == "google-flights"
+Provides-Extra: ryanair
+Requires-Dist: ryanair-py; extra == "ryanair"
+Provides-Extra: kayak
+Requires-Dist: playwright; extra == "kayak"
+Provides-Extra: all
+Requires-Dist: fast-flights; extra == "all"
+Requires-Dist: ryanair-py; extra == "all"
+Requires-Dist: playwright; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"

farepy-0.1.1/farepy/__init__.py

@@ -0,0 +1,13 @@
+"""farepy -- Multi-source flight search with normalized results, caching, and batch support."""
+
+from farepy.core import search_flights as search_flights
+from farepy.batch import (
+    batch_search as batch_search,
+    batch_from_file as batch_from_file,
+)
+from farepy.sources import available_sources as available_sources
+from farepy.cache import (
+    list_cached_searches as list_cached_searches,
+    get_cached_result as get_cached_result,
+    clear_cache as clear_cache,
+)

farepy-0.1.1/farepy/base.py

@@ -0,0 +1,110 @@
+"""Normalized data model for multi-source flight search."""
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass
+class Segment:
+    """A single flight leg (one takeoff-to-landing)."""
+
+    departure_airport: str  # IATA code, e.g. "MRS"
+    arrival_airport: str  # IATA code, e.g. "REK"
+    departure_time: str  # ISO 8601: "2026-04-18T06:30:00"
+    arrival_time: str  # ISO 8601: "2026-04-18T10:45:00"
+    carrier: str  # Airline IATA code, e.g. "FI"
+    carrier_name: str | None = None  # Full name if available
+    flight_number: str | None = None  # e.g. "FI543"
+    duration_minutes: int | None = None
+    aircraft: str | None = None
+
+
+@dataclass
+class Itinerary:
+    """One direction of travel (outbound or return)."""
+
+    segments: list[Segment]
+    duration_minutes: int | None = None  # Total itinerary duration
+
+    @property
+    def departure_time(self) -> str:
+        return self.segments[0].departure_time
+
+    @property
+    def arrival_time(self) -> str:
+        return self.segments[-1].arrival_time
+
+    @property
+    def departure_airport(self) -> str:
+        return self.segments[0].departure_airport
+
+    @property
+    def arrival_airport(self) -> str:
+        return self.segments[-1].arrival_airport
+
+    @property
+    def stops(self) -> int:
+        return len(self.segments) - 1
+
+
+@dataclass
+class FlightOffer:
+    """A single bookable flight option, normalized across all sources."""
+
+    source: str  # "google_flights" | "ryanair" | "kayak"
+    outbound: Itinerary
+    price: float
+    currency: str
+    airlines: list[str]  # Unique carrier codes across all segments
+    inbound: Itinerary | None = None  # None for one-way
+    booking_url: str | None = None
+    raw: dict | None = field(default=None, repr=False)
+
+
+@dataclass
+class SearchRequest:
+    """Normalized search parameters."""
+
+    origin: str  # IATA code
+    destination: str  # IATA code
+    departure_date: str  # YYYY-MM-DD
+    return_date: str | None = None
+    adults: int = 1
+    currency: str = "EUR"
+    max_results: int = 50
+    non_stop: bool | None = None
+    # Time range filters (HH:MM format)
+    outbound_departure_after: str | None = None
+    outbound_departure_before: str | None = None
+    outbound_arrival_after: str | None = None
+    outbound_arrival_before: str | None = None
+    inbound_departure_after: str | None = None
+    inbound_departure_before: str | None = None
+    inbound_arrival_after: str | None = None
+    inbound_arrival_before: str | None = None
+
+
+@dataclass
+class SearchResult:
+    """Container for search results with metadata."""
+
+    request: SearchRequest
+    offers: list[FlightOffer]
+    sources_queried: list[str]
+    sources_failed: dict[str, str]  # source -> error message
+    searched_at: str  # ISO 8601 timestamp
+    cached: bool = False
+
+
+class FlightSource(Protocol):
+    """Protocol that all source adapters implement."""
+
+    name: str
+
+    def search(self, request: SearchRequest) -> list[FlightOffer]:
+        """Search for flights. Returns empty list on no results."""
+        ...
+
+    def is_available(self) -> tuple[bool, str]:
+        """Check availability. Returns (available, message)."""
+        ...

farepy-0.1.1/farepy/batch.py

@@ -0,0 +1,140 @@
+"""Batch flight search -- cartesian combinations and file parsing."""
+
+from itertools import product
+
+from farepy.core import search_flights
+
+
+def batch_search(
+    legs: list[str],
+    departure_dates: list[str],
+    *,
+    return_dates: list[str] | None = None,
+    sources: list[str] | None = None,
+    currency: str = "EUR",
+    adults: int = 1,
+    non_stop: bool | None = None,
+    max_results: int = 50,
+    use_cache: bool = True,
+    cache_dir: str | None = None,
+    cache_ttl_hours: float = 24,
+) -> list[dict]:
+    """Run a cartesian product of legs x departure_dates x return_dates.
+
+    Each combination is searched sequentially to respect API rate limits.
+    Caching ensures repeated combinations are not re-queried.
+
+    Args:
+        legs: List of IATA pairs, e.g. ["MRS-REK", "CDG-KEF"]
+        departure_dates: List of YYYY-MM-DD dates
+        return_dates: List of YYYY-MM-DD dates (None for one-way)
+        sources: Which sources to query (None = all available)
+        currency: ISO 4217 currency code
+        adults: Number of adult travelers
+        non_stop: Direct flights only
+        max_results: Max results per source per search
+        use_cache: Use cached results
+        cache_dir: Override cache directory
+        cache_ttl_hours: Cache TTL
+
+    Returns:
+        List of SearchResult dicts, one per combination.
+    """
+    ret_dates = return_dates or [None]
+    combos = list(product(legs, departure_dates, ret_dates))
+
+    results = []
+    for leg, dep_date, ret_date in combos:
+        result = search_flights(
+            leg=leg,
+            departure_date=dep_date,
+            return_date=ret_date,
+            sources=sources,
+            currency=currency,
+            adults=adults,
+            non_stop=non_stop,
+            max_results=max_results,
+            use_cache=use_cache,
+            cache_dir=cache_dir,
+            cache_ttl_hours=cache_ttl_hours,
+        )
+        results.append(result)
+
+    return results
+
+
+def parse_batch_file(file_content: str) -> list[dict]:
+    """Parse a batch file into search parameter dicts.
+
+    Format: one search per line
+        ORIGIN-DEST YYYY-MM-DD [YYYY-MM-DD]
+
+    Examples:
+        MRS-REK 2026-04-18
+        MRS-REK 2026-04-18 2026-04-30
+        CDG-KEF 2026-05-01 2026-05-15
+
+    Returns:
+        List of dicts with keys: leg, departure_date, return_date
+    """
+    searches = []
+    for line_num, line in enumerate(file_content.strip().splitlines(), 1):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split()
+        if len(parts) < 2:
+            raise ValueError(
+                f'Line {line_num}: expected "LEG DATE [RETURN_DATE]", got: {line!r}'
+            )
+        searches.append(
+            {
+                "leg": parts[0],
+                "departure_date": parts[1],
+                "return_date": parts[2] if len(parts) > 2 else None,
+            }
+        )
+    return searches
+
+
+def batch_from_file(
+    file_content: str,
+    *,
+    sources: list[str] | None = None,
+    currency: str = "EUR",
+    adults: int = 1,
+    non_stop: bool | None = None,
+    max_results: int = 50,
+    use_cache: bool = True,
+    cache_dir: str | None = None,
+    cache_ttl_hours: float = 24,
+) -> list[dict]:
+    """Parse a batch file and run all searches.
+
+    Args:
+        file_content: The text content of the batch file.
+        (other args same as batch_search)
+
+    Returns:
+        List of SearchResult dicts.
+    """
+    searches = parse_batch_file(file_content)
+
+    results = []
+    for s in searches:
+        result = search_flights(
+            leg=s["leg"],
+            departure_date=s["departure_date"],
+            return_date=s["return_date"],
+            sources=sources,
+            currency=currency,
+            adults=adults,
+            non_stop=non_stop,
+            max_results=max_results,
+            use_cache=use_cache,
+            cache_dir=cache_dir,
+            cache_ttl_hours=cache_ttl_hours,
+        )
+        results.append(result)
+
+    return results

farepy-0.1.1/farepy/cache.py

@@ -0,0 +1,148 @@
+"""JSON file-based caching for flight search results."""
+
+import hashlib
+import json
+from dataclasses import asdict
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from farepy.base import SearchRequest, SearchResult
+
+DEFAULT_CACHE_DIR = Path.home() / ".local" / "share" / "farepy" / "cache"
+DEFAULT_TTL_HOURS = 24
+
+
+def _cache_dir(cache_dir: str | None = None) -> Path:
+    d = Path(cache_dir) if cache_dir else DEFAULT_CACHE_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def cache_key(request: SearchRequest, sources: list[str]) -> str:
+    """Generate a deterministic cache key from search parameters."""
+    key_data = {
+        "origin": request.origin,
+        "destination": request.destination,
+        "departure_date": request.departure_date,
+        "return_date": request.return_date,
+        "currency": request.currency,
+        "adults": request.adults,
+        "non_stop": request.non_stop,
+        "sources": sorted(sources),
+    }
+    return hashlib.sha256(json.dumps(key_data, sort_keys=True).encode()).hexdigest()[
+        :12
+    ]
+
+
+def _cache_filename(request: SearchRequest, sources: list[str]) -> str:
+    h = cache_key(request, sources)
+    ret = f"_{request.return_date}" if request.return_date else ""
+    return (
+        f"{request.departure_date}_{request.origin}_{request.destination}{ret}_{h}.json"
+    )
+
+
+def get_cached(
+    request: SearchRequest,
+    sources: list[str],
+    *,
+    cache_dir: str | None = None,
+    ttl_hours: float = DEFAULT_TTL_HOURS,
+) -> dict | None:
+    """Return cached result dict if fresh, else None."""
+    d = _cache_dir(cache_dir)
+    fname = _cache_filename(request, sources)
+    path = d / fname
+
+    if not path.exists():
+        return None
+
+    try:
+        data = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    # Check TTL
+    searched_at = data.get("searched_at", "")
+    if searched_at:
+        try:
+            ts = datetime.fromisoformat(searched_at.replace("Z", "+00:00"))
+            if datetime.now(ts.tzinfo) - ts > timedelta(hours=ttl_hours):
+                return None  # Expired
+        except (ValueError, TypeError):
+            pass
+
+    data["cached"] = True
+    return data
+
+
+def put_cache(
+    result: SearchResult,
+    sources: list[str],
+    *,
+    cache_dir: str | None = None,
+) -> str:
+    """Cache a SearchResult. Returns the cache filename."""
+    d = _cache_dir(cache_dir)
+    fname = _cache_filename(result.request, sources)
+    path = d / fname
+
+    data = asdict(result)
+    # Strip raw source data from cache to save space
+    for offer in data.get("offers", []):
+        offer.pop("raw", None)
+
+    path.write_text(json.dumps(data, indent=2, default=str))
+    return fname
+
+
+def list_cached_searches(*, cache_dir: str | None = None) -> list[dict]:
+    """Return summaries of all cached results."""
+    d = _cache_dir(cache_dir)
+    results = []
+
+    for path in sorted(d.glob("*.json"), reverse=True):
+        try:
+            data = json.loads(path.read_text())
+            req = data.get("request", {})
+            results.append(
+                {
+                    "cache_id": path.stem,
+                    "filename": path.name,
+                    "origin": req.get("origin", ""),
+                    "destination": req.get("destination", ""),
+                    "departure_date": req.get("departure_date", ""),
+                    "return_date": req.get("return_date"),
+                    "num_offers": len(data.get("offers", [])),
+                    "sources_queried": data.get("sources_queried", []),
+                    "searched_at": data.get("searched_at", ""),
+                }
+            )
+        except (json.JSONDecodeError, OSError):
+            continue
+
+    return results
+
+
+def get_cached_result(cache_id: str, *, cache_dir: str | None = None) -> dict:
+    """Get a specific cached result by its ID (filename stem)."""
+    d = _cache_dir(cache_dir)
+    path = d / f"{cache_id}.json"
+
+    if not path.exists():
+        raise FileNotFoundError(f"Cache entry not found: {cache_id}")
+
+    data = json.loads(path.read_text())
+    data["cached"] = True
+    return data
+
+
+def clear_cache(*, cache_dir: str | None = None) -> dict:
+    """Clear all cached results. Returns count of files removed."""
+    d = _cache_dir(cache_dir)
+    count = 0
+    for path in d.glob("*.json"):
+        path.unlink()
+        count += 1
+    return {"cleared": count}

farepy-0.1.1/farepy/core.py

@@ -0,0 +1,227 @@
+"""Search orchestration -- the main entry point for flight searches."""
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import asdict
+
+from farepy.base import FlightOffer, SearchRequest, SearchResult
+from farepy.cache import get_cached, put_cache
+from farepy.sources import ALL_SOURCES, make_source
+from farepy.util import extract_time, now_iso, parse_leg, time_in_range
+
+
+def search_flights(
+    leg: str,
+    departure_date: str,
+    *,
+    return_date: str | None = None,
+    sources: list[str] | None = None,
+    currency: str = "EUR",
+    adults: int = 1,
+    non_stop: bool | None = None,
+    max_results: int = 50,
+    outbound_departure_after: str | None = None,
+    outbound_departure_before: str | None = None,
+    outbound_arrival_after: str | None = None,
+    outbound_arrival_before: str | None = None,
+    inbound_departure_after: str | None = None,
+    inbound_departure_before: str | None = None,
+    inbound_arrival_after: str | None = None,
+    inbound_arrival_before: str | None = None,
+    use_cache: bool = True,
+    cache_dir: str | None = None,
+    cache_ttl_hours: float = 24,
+) -> dict:
+    """Search for flights across selected sources.
+
+    Args:
+        leg: IATA pair like "MRS-REK"
+        departure_date: YYYY-MM-DD
+        return_date: YYYY-MM-DD or None for one-way
+        sources: List of source names (e.g. ["google_flights", "ryanair"]).
+            None means all available.
+        currency: ISO 4217 currency code
+        adults: Number of adult travelers
+        non_stop: If True, direct flights only
+        max_results: Max results per source
+        outbound_departure_after: HH:MM filter
+        outbound_departure_before: HH:MM filter
+        outbound_arrival_after: HH:MM filter
+        outbound_arrival_before: HH:MM filter
+        inbound_departure_after: HH:MM filter
+        inbound_departure_before: HH:MM filter
+        inbound_arrival_after: HH:MM filter
+        inbound_arrival_before: HH:MM filter
+        use_cache: Whether to use cached results
+        cache_dir: Override default cache directory
+        cache_ttl_hours: Cache time-to-live in hours
+
+    Returns:
+        SearchResult as a dict.
+    """
+    origin, destination = parse_leg(leg)
+
+    request = SearchRequest(
+        origin=origin,
+        destination=destination,
+        departure_date=departure_date,
+        return_date=return_date,
+        adults=adults,
+        currency=currency,
+        max_results=max_results,
+        non_stop=non_stop,
+        outbound_departure_after=outbound_departure_after,
+        outbound_departure_before=outbound_departure_before,
+        outbound_arrival_after=outbound_arrival_after,
+        outbound_arrival_before=outbound_arrival_before,
+        inbound_departure_after=inbound_departure_after,
+        inbound_departure_before=inbound_departure_before,
+        inbound_arrival_after=inbound_arrival_after,
+        inbound_arrival_before=inbound_arrival_before,
+    )
+
+    # Determine which sources to query
+    if sources is None:
+        sources_to_query = [
+            name for name in ALL_SOURCES if make_source(name).is_available()[0]
+        ]
+    else:
+        sources_to_query = [s for s in sources if s in ALL_SOURCES]
+
+    if not sources_to_query:
+        return asdict(
+            SearchResult(
+                request=request,
+                offers=[],
+                sources_queried=[],
+                sources_failed={
+                    "all": "No sources available. Install a source package: "
+                    "pip install farepy[google_flights] or pip install farepy[ryanair]"
+                },
+                searched_at=now_iso(),
+            )
+        )
+
+    # Check cache (time filters are applied post-query, so cache key ignores them)
+    if use_cache:
+        cached = get_cached(
+            request,
+            sources_to_query,
+            cache_dir=cache_dir,
+            ttl_hours=cache_ttl_hours,
+        )
+        if cached is not None:
+            # Apply time filters to cached results
+            cached["offers"] = _apply_time_filters(cached.get("offers", []), request)
+            return cached
+
+    # Query sources in parallel
+    all_offers: list[FlightOffer] = []
+    sources_failed: dict[str, str] = {}
+
+    def _query_source(name: str) -> tuple[str, list[FlightOffer] | str]:
+        try:
+            source = make_source(name)
+            return name, source.search(request)
+        except Exception as e:
+            return name, str(e)
+
+    with ThreadPoolExecutor(max_workers=len(sources_to_query)) as executor:
+        futures = {
+            executor.submit(_query_source, name): name for name in sources_to_query
+        }
+        for future in as_completed(futures):
+            name, result = future.result()
+            if isinstance(result, str):
+                sources_failed[name] = result
+            else:
+                all_offers.extend(result)
+
+    # Sort by price
+    all_offers.sort(key=lambda o: o.price)
+
+    result = SearchResult(
+        request=request,
+        offers=all_offers,
+        sources_queried=sources_to_query,
+        sources_failed=sources_failed,
+        searched_at=now_iso(),
+    )
+
+    # Cache the unfiltered results
+    if use_cache:
+        put_cache(result, sources_to_query, cache_dir=cache_dir)
+
+    # Apply time filters to the result
+    result_dict = asdict(result)
+    result_dict["offers"] = _apply_time_filters(result_dict["offers"], request)
+
+    return result_dict
+
+
+def _apply_time_filters(offers: list[dict], request: SearchRequest) -> list[dict]:
+    """Filter offers by time ranges (post-query)."""
+    has_outbound_filter = any(
+        [
+            request.outbound_departure_after,
+            request.outbound_departure_before,
+            request.outbound_arrival_after,
+            request.outbound_arrival_before,
+        ]
+    )
+    has_inbound_filter = any(
+        [
+            request.inbound_departure_after,
+            request.inbound_departure_before,
+            request.inbound_arrival_after,
+            request.inbound_arrival_before,
+        ]
+    )
+
+    if not has_outbound_filter and not has_inbound_filter:
+        return offers
+
+    filtered = []
+    for offer in offers:
+        outbound = offer.get("outbound", {})
+        segments = outbound.get("segments", [])
+
+        if has_outbound_filter and segments:
+            dep_time = extract_time(segments[0].get("departure_time", ""))
+            arr_time = extract_time(segments[-1].get("arrival_time", ""))
+
+            if not time_in_range(
+                dep_time,
+                after=request.outbound_departure_after,
+                before=request.outbound_departure_before,
+            ):
+                continue
+            if not time_in_range(
+                arr_time,
+                after=request.outbound_arrival_after,
+                before=request.outbound_arrival_before,
+            ):
+                continue
+
+        inbound = offer.get("inbound")
+        if has_inbound_filter and inbound:
+            in_segments = inbound.get("segments", [])
+            if in_segments:
+                dep_time = extract_time(in_segments[0].get("departure_time", ""))
+                arr_time = extract_time(in_segments[-1].get("arrival_time", ""))
+
+                if not time_in_range(
+                    dep_time,
+                    after=request.inbound_departure_after,
+                    before=request.inbound_departure_before,
+                ):
+                    continue
+                if not time_in_range(
+                    arr_time,
+                    after=request.inbound_arrival_after,
+                    before=request.inbound_arrival_before,
+                ):
+                    continue
+
+        filtered.append(offer)
+
+    return filtered

farepy-0.1.1/farepy/sources/__init__.py

@@ -0,0 +1,32 @@
+"""Flight data source registry."""
+
+from farepy.sources.google_flights_source import GoogleFlightsSource
+from farepy.sources.ryanair_source import RyanairSource
+from farepy.sources.kayak_source import KayakSource
+
+ALL_SOURCES = {
+    "google_flights": GoogleFlightsSource,
+    "ryanair": RyanairSource,
+    "kayak": KayakSource,
+}
+
+
+def make_source(name: str, **kwargs):
+    """Create a source instance by name, passing config kwargs."""
+    cls = ALL_SOURCES.get(name)
+    if cls is None:
+        raise ValueError(f"Unknown source: {name!r}. Available: {list(ALL_SOURCES)}")
+    return cls(**kwargs)
+
+
+def available_sources(**kwargs) -> list[dict]:
+    """Return status of all sources.
+
+    Each dict has: name, available (bool), message (str).
+    """
+    result = []
+    for name, cls in ALL_SOURCES.items():
+        source = cls(**kwargs)
+        avail, msg = source.is_available()
+        result.append({"name": name, "available": avail, "message": msg})
+    return result