contrails 0.4.0__py3-none-any.whl

contrail/__init__.py

@@ -0,0 +1,10 @@
+"""contrail: estimate and log the CO2e emissions of flights you've taken or booked."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("contrail")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

contrail/airlines.py

@@ -0,0 +1,268 @@
+"""Resolving an airline to its IATA code, from a name or from an ICAO code.
+
+Two importers need this and neither has the code TIM wants:
+
+- A calendar feed names the *operating* airline in prose ("British Airways 458")
+  while TIM's ``operatingCarrierCode`` wants ``BA``.
+- A Flighty export gives the airline as ICAO (``BAW``), which TIM will not take
+  either.
+
+One table answers both. Three sources, cheapest first:
+
+1. **The feed itself.** On a non-codeshare segment the description repeats the
+   flight already given in the summary, which hands us a (name -> code) pair for
+   free. Someone who flies BA directly and also holds a BA-operated Iberia
+   codeshare gets the codeshare resolved with no network call at all.
+2. **The bundled table** (``data/airline_codes.csv``), generated from Wikidata
+   and shipped in the wheel. Offline and deterministic, and it covers the great
+   majority of both lookups — a 261-flight Flighty export would otherwise mean
+   dozens of HTTP round trips on every daily sync, for data that changes about
+   never.
+3. **Wikidata live**, for the names and codes the table misses. ``P229`` is the
+   IATA designator and ``P230`` the ICAO one. Structured data beats scraping the
+   Wikipedia infobox, whose wikitext yields things like ``BAW; SHT`` for a single
+   ICAO field.
+
+``airline_lookup: false`` disables step 3 only. It exists to opt out of the
+network call, and steps 1 and 2 need no network.
+
+Every failure is soft: an unresolvable airline leaves the flight priced under its
+marketing number, which is exactly what contrail did before any of this.
+
+The table is derived from Wikidata, which is CC0, and is regenerated by
+``scripts/refresh_airline_codes.py``. Nothing in it is hand-edited — fix it
+upstream and re-run, or the next refresh silently reverts the change.
+"""
+
+from __future__ import annotations
+
+import csv
+from importlib.resources import files
+
+import requests
+
+from contrail import __version__
+
+WIKIDATA_API = "https://www.wikidata.org/w/api.php"
+IATA_PROPERTY = "P229"  # IATA airline designator
+ICAO_PROPERTY = "P230"  # ICAO airline designator
+SEARCH_LIMIT = 8
+REQUEST_TIMEOUT = 15
+
+# Wikimedia asks for a descriptive User-Agent identifying the tool. Built from
+# the installed version so there's no second literal to keep in step.
+USER_AGENT = f"contrail/{__version__} (https://github.com/atdr/contrail)"
+
+_BY_ICAO: dict[str, str] | None = None
+_BY_NAME: dict[str, str] | None = None
+
+
+def _normalize(name: str) -> str:
+    """Whitespace-collapsed casefold, the key both the table and the cache use."""
+    return " ".join(name.split()).casefold()
+
+
+def _load_table() -> tuple[dict[str, str], dict[str, str]]:
+    """Read the bundled airline table once, on first use.
+
+    Lazy for the same reason ``airports._airports()`` is: a ``contrail sources``
+    or a config error should not pay to parse a couple of thousand rows.
+    """
+    global _BY_ICAO, _BY_NAME
+    if _BY_ICAO is None or _BY_NAME is None:
+        by_icao: dict[str, str] = {}
+        by_name: dict[str, str] = {}
+        data = files("contrail.data").joinpath("airline_codes.csv")
+        with data.open(newline="", encoding="utf-8") as f:
+            for row in csv.DictReader(f):
+                iata = row["iata"]
+                by_icao[row["icao"]] = iata
+                for name in [row["name"], *row["aliases"].split("|")]:
+                    if name:
+                        by_name.setdefault(_normalize(name), iata)
+        _BY_ICAO, _BY_NAME = by_icao, by_name
+    return _BY_ICAO, _BY_NAME
+
+
+def _iata_from_claims(entity: dict) -> str | None:
+    claims = entity.get("claims", {}).get(IATA_PROPERTY)
+    if not claims:
+        return None
+    try:
+        code = claims[0]["mainsnak"]["datavalue"]["value"]
+    except (KeyError, IndexError, TypeError):
+        return None
+    return code if isinstance(code, str) and code.strip() else None
+
+
+def wikidata_iata_code(name: str, session: requests.Session | None = None) -> str | None:
+    """Look up an airline's IATA code on Wikidata, or None.
+
+    Searches by name and returns the first hit that actually carries an IATA
+    designator. That check is what disambiguates: searching "Iberia" surfaces
+    the Iberian Peninsula first, and only the airline has a P229.
+    """
+    if not name or not name.strip():
+        return None
+    session = session or requests.Session()
+    headers = {"User-Agent": USER_AGENT}
+
+    resp = session.get(
+        WIKIDATA_API,
+        params={
+            "action": "wbsearchentities",
+            "search": name.strip(),
+            "language": "en",
+            "limit": SEARCH_LIMIT,
+            "format": "json",
+        },
+        headers=headers,
+        timeout=REQUEST_TIMEOUT,
+    )
+    resp.raise_for_status()
+    ids = [hit["id"] for hit in resp.json().get("search", []) if hit.get("id")]
+    if not ids:
+        return None
+
+    resp = session.get(
+        WIKIDATA_API,
+        params={
+            "action": "wbgetentities",
+            "props": "claims",
+            "ids": "|".join(ids),
+            "format": "json",
+        },
+        headers=headers,
+        timeout=REQUEST_TIMEOUT,
+    )
+    resp.raise_for_status()
+    entities = resp.json().get("entities", {})
+
+    for qid in ids:  # preserve the search ranking
+        code = _iata_from_claims(entities.get(qid, {}))
+        if code:
+            return code
+    return None
+
+
+def wikidata_iata_for_icao(icao: str, session: requests.Session | None = None) -> str | None:
+    """Look up an airline's IATA code from its ICAO code on Wikidata, or None.
+
+    Searches by statement rather than by text: ``haswbstatement:P230=BAW`` asks
+    for the entity that actually holds that designator. A plain text search for
+    "BAW" would return whatever mentions the string, which for a three-letter
+    code is a great deal.
+    """
+    if not icao or not icao.strip():
+        return None
+    session = session or requests.Session()
+    headers = {"User-Agent": USER_AGENT}
+
+    resp = session.get(
+        WIKIDATA_API,
+        params={
+            "action": "query",
+            "list": "search",
+            "srsearch": f"haswbstatement:{ICAO_PROPERTY}={icao.strip().upper()}",
+            "srlimit": SEARCH_LIMIT,
+            "format": "json",
+        },
+        headers=headers,
+        timeout=REQUEST_TIMEOUT,
+    )
+    resp.raise_for_status()
+    ids = [
+        hit["title"] for hit in resp.json().get("query", {}).get("search", []) if hit.get("title")
+    ]
+    if not ids:
+        return None
+
+    resp = session.get(
+        WIKIDATA_API,
+        params={
+            "action": "wbgetentities",
+            "props": "claims",
+            "ids": "|".join(ids),
+            "format": "json",
+        },
+        headers=headers,
+        timeout=REQUEST_TIMEOUT,
+    )
+    resp.raise_for_status()
+    entities = resp.json().get("entities", {})
+
+    for qid in ids:  # preserve the search ranking
+        code = _iata_from_claims(entities.get(qid, {}))
+        if code:
+            return code
+    return None
+
+
+class AirlineResolver:
+    """Resolves airline names and ICAO codes to IATA codes, caching within a run."""
+
+    def __init__(self, lookup: bool = True, session: requests.Session | None = None):
+        self.lookup = lookup
+        self.session = session
+        self._learned: dict[str, str] = {}
+        self._cache: dict[str, str | None] = {}
+        self._icao_cache: dict[str, str | None] = {}
+
+    @staticmethod
+    def _key(name: str) -> str:
+        return _normalize(name)
+
+    def learn(self, name: str, code: str) -> None:
+        """Record a (name -> code) pair observed directly in the source data."""
+        if name and code:
+            self._learned.setdefault(self._key(name), code)
+
+    def resolve(self, name: str | None) -> str | None:
+        """IATA code for an airline name, or None if it can't be determined."""
+        if not name or not name.strip():
+            return None
+        key = self._key(name)
+        if key in self._learned:
+            return self._learned[key]
+        if key in self._cache:
+            return self._cache[key]
+
+        _, by_name = _load_table()
+        if key in by_name:
+            return by_name[key]
+
+        if not self.lookup:
+            return None
+
+        try:
+            code = wikidata_iata_code(name, self.session)
+        except requests.RequestException:
+            # A lookup service being unreachable must never fail a sync.
+            code = None
+        self._cache[key] = code
+        return code
+
+    def resolve_icao(self, icao: str | None) -> str | None:
+        """IATA code for an airline's ICAO code, or None if it can't be determined.
+
+        Unresolved is survivable: the flight keeps its ICAO code and prices to a
+        route average, which is market-based and needs no carrier code at all.
+        """
+        if not icao or not icao.strip():
+            return None
+        code = icao.strip().upper()
+
+        by_icao, _ = _load_table()
+        if code in by_icao:
+            return by_icao[code]
+        if code in self._icao_cache:
+            return self._icao_cache[code]
+        if not self.lookup:
+            return None
+
+        try:
+            resolved = wikidata_iata_for_icao(code, self.session)
+        except requests.RequestException:
+            resolved = None
+        self._icao_cache[code] = resolved
+        return resolved

contrail/airports.py

@@ -0,0 +1,101 @@
+"""Airport timezone lookup, used to derive a flight's local departure date.
+
+The TIM API is explicit that ``departureDate`` is "the date of the flight in the
+time zone of the origin airport". Calendar feeds routinely give departure times
+in UTC instead — TripIt's does — so an evening departure west of Greenwich, or
+an early-morning one far to the east, lands on the wrong calendar day if the UTC
+date is taken at face value.
+
+That costs twice over: the stored ``flight_date`` is wrong, *and* the exact
+emissions lookup misses, silently downgrading the row to a route average.
+
+Note that TIM wants a date, not a timestamp. The zone is only ever scaffolding
+for picking the right calendar day.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import airportsdata
+
+_AIRPORTS: dict | None = None
+_ZONES: dict[str, ZoneInfo | None] = {}
+
+
+def _airports() -> dict:
+    """Load the bundled IATA database once, on first use."""
+    global _AIRPORTS
+    if _AIRPORTS is None:
+        _AIRPORTS = airportsdata.load("IATA")
+    return _AIRPORTS
+
+
+def timezone_for(iata: str | None) -> ZoneInfo | None:
+    """IANA timezone for an IATA airport code, or None if it isn't known."""
+    if not iata:
+        return None
+    code = iata.strip().upper()
+    if code in _ZONES:
+        return _ZONES[code]
+
+    entry = _airports().get(code)
+    zone: ZoneInfo | None = None
+    if entry and entry.get("tz"):
+        try:
+            zone = ZoneInfo(entry["tz"])
+        except (ZoneInfoNotFoundError, ValueError):
+            zone = None  # no tz database on this platform
+    _ZONES[code] = zone
+    return zone
+
+
+def today_at(origin: str | None, now: datetime) -> date:
+    """The current calendar date at an airport.
+
+    The freeze boundary compares a stored ``flight_date`` — which is local to the
+    origin — against "today". Using the UTC date instead is wrong for part of
+    every day by the origin's offset: east of UTC it keeps a departed flight
+    looking upcoming, west of UTC it freezes one that hasn't left yet.
+    """
+    zone = timezone_for(origin)
+    return now.astimezone(zone).date() if zone else now.date()
+
+
+def departure_datetime(dtstart, origin: str | None) -> datetime | None:
+    """The departure as an instant, expressed in the origin's own timezone.
+
+    Stored so the boundary can be exact rather than a date comparison. All-day
+    events have no time and yield None; a naive time is RFC 5545 floating, i.e.
+    already local, so it is left as-is rather than shifted.
+    """
+    if not isinstance(dtstart, datetime):
+        return None
+    if dtstart.tzinfo is None:
+        return dtstart
+    zone = timezone_for(origin)
+    return dtstart.astimezone(zone) if zone else dtstart
+
+
+def departure_date(dtstart, origin: str | None) -> date | None:
+    """The local calendar date of a departure at ``origin``.
+
+    Falls back to the value as given whenever the conversion can't be trusted:
+
+    - an all-day event has no time to convert
+    - a naive datetime is already a local wall-clock time (RFC 5545 "floating"),
+      so converting it would be wrong
+    - an unrecognised airport code leaves nothing to convert against
+    """
+    if dtstart is None:
+        return None
+    if not isinstance(dtstart, datetime):
+        return dtstart  # already a plain date
+    if dtstart.tzinfo is None:
+        return dtstart.date()
+
+    zone = timezone_for(origin)
+    if zone is None:
+        return dtstart.date()
+    return dtstart.astimezone(zone).date()