flightbyte 1.0.0__py3-none-any.whl

flightbyte/__init__.py

@@ -0,0 +1,136 @@
+"""The official Python client for the FlightByte flight status API.
+
+Look flights up, watch them with signed webhooks and verify every delivery::
+
+    import os
+    from flightbyte import FlightByte
+
+    client = FlightByte(api_key=os.environ["FLIGHTBYTE_API_KEY"])
+    flight = client.flights.get("TK", "1848", "2026-09-08")
+    print(flight["status"]["label"], flight["departure"].get("gate"))
+
+Webhooks are verified with ``Webhook.construct_event``. Every error is a
+``FlightByteError``.
+"""
+
+from ._client import FlightByte
+from ._countries import Countries
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    FlightByteError,
+    NotFoundError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    UnexpectedStatusError,
+    UpstreamError,
+    WebhookSignatureError,
+)
+from ._flights import Flights
+from ._models import (
+    DELIVERY_STATUSES,
+    FLIGHT_CHANGE_TYPES,
+    FLIGHT_PHASES,
+    SUBSCRIPTION_STATUSES,
+    WEBHOOK_EVENT_TYPES,
+    AirportRef,
+    AmbiguousLeg,
+    CarrierRef,
+    CodeshareRef,
+    Country,
+    CountryRef,
+    CreatedSubscription,
+    DeliveryRecord,
+    DeliveryStatus,
+    DurationInfo,
+    EndpointTimes,
+    EquipmentInfo,
+    FlightChange,
+    FlightChangeType,
+    FlightEndpoint,
+    FlightLegRef,
+    FlightPhase,
+    FlightSnapshot,
+    FlightStatusInfo,
+    FlightTime,
+    FlightTimeline,
+    Subscription,
+    SubscriptionPage,
+    SubscriptionStatus,
+    TimelineEntry,
+    WebhookEvent,
+    WebhookEventType,
+    best_gate_time,
+    is_terminal_phase,
+)
+from ._rate_limit import RateLimit, RateLimitWindow
+from ._subscriptions import Subscriptions, mask_secret
+from ._transport import NOT_GIVEN, NotGiven
+from ._version import __version__
+from ._webhook import Webhook, WebhookPayload
+
+__all__ = [
+    "DELIVERY_STATUSES",
+    "FLIGHT_CHANGE_TYPES",
+    "FLIGHT_PHASES",
+    "NOT_GIVEN",
+    "SUBSCRIPTION_STATUSES",
+    "WEBHOOK_EVENT_TYPES",
+    "APIConnectionError",
+    "APIError",
+    "AirportRef",
+    "AmbiguousLeg",
+    "AuthenticationError",
+    "BadRequestError",
+    "CarrierRef",
+    "CodeshareRef",
+    "Countries",
+    "Country",
+    "CountryRef",
+    "CreatedSubscription",
+    "DeliveryRecord",
+    "DeliveryStatus",
+    "DurationInfo",
+    "EndpointTimes",
+    "EquipmentInfo",
+    "FlightByte",
+    "FlightByteError",
+    "FlightChange",
+    "FlightChangeType",
+    "FlightEndpoint",
+    "FlightLegRef",
+    "FlightPhase",
+    "FlightSnapshot",
+    "FlightStatusInfo",
+    "FlightTime",
+    "FlightTimeline",
+    "Flights",
+    "NotFoundError",
+    "NotGiven",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "RateLimit",
+    "RateLimitError",
+    "RateLimitWindow",
+    "ServerError",
+    "Subscription",
+    "SubscriptionPage",
+    "SubscriptionStatus",
+    "Subscriptions",
+    "TimelineEntry",
+    "UnexpectedStatusError",
+    "UpstreamError",
+    "Webhook",
+    "WebhookEvent",
+    "WebhookEventType",
+    "WebhookPayload",
+    "WebhookSignatureError",
+    "__version__",
+    "best_gate_time",
+    "is_terminal_phase",
+    "mask_secret",
+]

flightbyte/_client.py

@@ -0,0 +1,157 @@
+"""The FlightByte client."""
+
+from __future__ import annotations
+
+import urllib.parse
+from datetime import date, datetime, tzinfo
+from typing import Final
+
+from ._countries import Countries
+from ._flights import Flights
+from ._rate_limit import RateLimit
+from ._subscriptions import Subscriptions
+from ._transport import Transport, check_header_value, check_timeout
+from ._version import __version__
+
+__all__ = ["FlightByte"]
+
+
+class FlightByte:
+    """A client for the FlightByte API. Create one and share it.
+
+    ::
+
+        import os
+        from flightbyte import FlightByte
+
+        client = FlightByte(api_key=os.environ["FLIGHTBYTE_API_KEY"])
+        flight = client.flights.get("TK", "1848", "2026-09-08")
+        print(flight["status"]["label"])
+
+    A client is safe to share across threads. It keeps no connection open, so
+    there is nothing to close.
+
+    Keep API keys on a server you control. A key shipped inside a browser or
+    mobile app can be extracted by anyone who has the app.
+
+    Args:
+        api_key: Your API key, sent as ``x-api-key``.
+        base_url: The API root. Defaults to ``FlightByte.DEFAULT_BASE_URL``.
+        timeout: Bounds each request, response body included, in seconds.
+            ``None`` or ``0`` turns it off. Defaults to 30. Every method takes
+            a ``timeout`` of its own too.
+        user_agent: Put in front of this package's own user agent, for example
+            ``my-app/1.2``.
+
+    Raises:
+        TypeError: ``api_key`` is not a string.
+        ValueError: ``api_key`` is empty, or another argument is invalid.
+    """
+
+    DEFAULT_BASE_URL: Final = "https://api.flightbyte.dev/v1"
+    """The production API root."""
+
+    flights: Flights
+    """Flight lookups."""
+    subscriptions: Subscriptions
+    """Watched flights and their webhooks."""
+    countries: Countries
+    """Countries and flags."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = 30.0,
+        user_agent: str | None = None,
+    ) -> None:
+        if not isinstance(api_key, str):
+            raise TypeError("flightbyte: api_key is required and must be a string.")
+        key = check_header_value("api_key", api_key.strip())
+        if not key:
+            raise ValueError("flightbyte: api_key is required.")
+
+        own_agent = f"flightbyte-python/{__version__}"
+        prefix = (user_agent or "").strip()
+        agent = check_header_value("user_agent", f"{prefix} {own_agent}" if prefix else own_agent)
+
+        self._transport = Transport(
+            api_key=key,
+            base_url=_check_base_url(self.DEFAULT_BASE_URL if base_url is None else base_url),
+            timeout=check_timeout("timeout", timeout),
+            user_agent=agent,
+        )
+        self.flights = Flights(self._transport)
+        self.subscriptions = Subscriptions(self._transport)
+        self.countries = Countries(self._transport)
+
+    @property
+    def base_url(self) -> str:
+        """The API root this client talks to."""
+        return self._transport.base_url
+
+    @property
+    def timeout(self) -> float | None:
+        """The timeout of each request, in seconds, or ``None`` when there is none."""
+        return self._transport.timeout
+
+    @property
+    def last_rate_limit(self) -> RateLimit | None:
+        """The quota state from the latest response that reported one.
+
+        ``None`` before any did. It is immutable, so reading it never changes
+        what the client or another thread sees.
+        """
+        return self._transport.last_rate_limit
+
+    def __repr__(self) -> str:
+        return f"FlightByte(base_url={self.base_url!r})"
+
+    @staticmethod
+    def format_date(value: date | datetime, tz: str | tzinfo | None = None) -> str:
+        """Formats ``value`` as the ``YYYY-MM-DD`` the API expects for flight dates.
+
+        Pass the origin airport's time zone, an IANA name such as
+        ``Europe/Istanbul`` or a ``tzinfo``, to get the date there. Without
+        one, a ``datetime`` keeps its own date; a naive one is read as local
+        time when converted. A ``date`` is formatted as it is.
+
+        On Windows, IANA names need the ``tzdata`` package, or pass a ``tzinfo``.
+        """
+        if isinstance(value, datetime):
+            if tz is not None:
+                value = value.astimezone(_zone(tz))
+            return value.date().isoformat()
+        if isinstance(value, date):
+            return value.isoformat()
+        raise TypeError("flightbyte: format_date takes a date or a datetime.")
+
+
+def _zone(tz: str | tzinfo) -> tzinfo:
+    if isinstance(tz, tzinfo):
+        return tz
+    from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+    try:
+        return ZoneInfo(tz)
+    except (ZoneInfoNotFoundError, ValueError) as error:
+        raise ValueError(
+            f"flightbyte: unknown time zone {tz!r}. On Windows, install the tzdata package."
+        ) from error
+
+
+def _check_base_url(value: str) -> str:
+    if not isinstance(value, str):
+        raise TypeError("flightbyte: base_url must be a string.")
+    text = value.strip()
+    try:
+        parts = urllib.parse.urlsplit(text)
+        parts.port  # noqa: B018 - raises ValueError for a port that is not a number
+    except ValueError as error:
+        raise ValueError(f"flightbyte: base_url {value!r} is not a URL.") from error
+    if parts.scheme.lower() not in ("http", "https") or not parts.hostname:
+        raise ValueError(f"flightbyte: base_url {value!r} must be an http or https URL.")
+    if parts.query or parts.fragment or "?" in text or "#" in text:
+        raise ValueError(f"flightbyte: base_url {value!r} must not have a query or fragment.")
+    return text.rstrip("/")

flightbyte/_countries.py

@@ -0,0 +1,57 @@
+"""Country names, emoji and flags."""
+
+from __future__ import annotations
+
+import builtins
+from typing import cast
+
+from ._models import Country
+from ._transport import NOT_GIVEN, NotGiven, Transport, required
+from ._util import data_of
+
+__all__ = ["Countries"]
+
+
+class Countries:
+    """Country names, emoji and flags. Reach it as ``client.countries``."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def list(
+        self,
+        *,
+        lang: str | None = None,
+        timeout: float | NotGiven | None = NOT_GIVEN,
+    ) -> builtins.list[Country]:
+        """Every country, sorted by name.
+
+        ``lang`` is the language of the names, for example ``tr``; the API's
+        default is ``en``.
+        """
+        result = self._transport.send("GET", ["countries"], query={"lang": lang}, timeout=timeout)
+        return cast("builtins.list[Country]", data_of(result, "GET /countries"))
+
+    def get(
+        self,
+        code: str,
+        *,
+        lang: str | None = None,
+        timeout: float | NotGiven | None = NOT_GIVEN,
+    ) -> Country:
+        """One country by its ISO 3166-1 alpha-2 code."""
+        result = self._transport.send(
+            "GET", ["countries", required("code", code)], query={"lang": lang}, timeout=timeout
+        )
+        return cast(Country, result)
+
+    def flag_url(self, code: str, *, square: bool = False) -> str:
+        """The URL of a country's SVG flag: 4:3, or 1:1 with ``square``.
+
+        Flags need no API key, so the URL can go straight into an ``<img>``.
+        Nothing is sent.
+        """
+        return self._transport.url(
+            ["flags", f"{required('code', code).lower()}.svg"],
+            {"shape": "1x1" if square else None},
+        )

flightbyte/_errors.py

@@ -0,0 +1,311 @@
+"""The errors this package raises."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from ._models import AmbiguousLeg
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "BadRequestError",
+    "FlightByteError",
+    "NotFoundError",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServerError",
+    "UnexpectedStatusError",
+    "UpstreamError",
+    "WebhookSignatureError",
+]
+
+
+class FlightByteError(Exception):
+    """Base class of every error this package raises."""
+
+
+class APIConnectionError(FlightByteError):
+    """A request got no HTTP response.
+
+    No network, a DNS failure, a refused connection, a TLS failure, or the
+    timeout ran out. The underlying error is in ``__cause__``.
+    """
+
+    timed_out: bool
+    """Whether the client's own timeout ran out."""
+
+    def __init__(self, message: str, *, timed_out: bool = False) -> None:
+        super().__init__(message)
+        self.timed_out = timed_out
+
+
+class APIError(FlightByteError):
+    """The API answered with a non-2xx status.
+
+    The attributes mirror the API's error body. Catch the subclass for the
+    status you want to handle::
+
+        try:
+            client.flights.get("TK", "1", "2026-09-08")
+        except flightbyte.NotFoundError:
+            print("No such flight that day")
+        except flightbyte.RateLimitError as err:
+            time.sleep(err.retry_after or 5)
+    """
+
+    status: int
+    """The HTTP status."""
+    messages: list[str]
+    """Every message the API sent. Validation errors send one per field."""
+    body: dict[str, Any]
+    """The decoded error body; empty when it was not a JSON object."""
+    raw_body: str
+    """The body exactly as received."""
+    headers: dict[str, str]
+    """The response headers, with lower-case names."""
+
+    def __init__(
+        self,
+        status: int,
+        reason: str,
+        raw_body: str,
+        headers: Mapping[str, str],
+    ) -> None:
+        body = _decode_body(raw_body)
+        messages = _read_messages(body)
+        lower_headers = {name.lower(): value for name, value in headers.items()}
+        request_id = _string_field(body, "requestId") or lower_headers.get("x-request-id")
+        # HTTP/2 and some servers leave the reason empty; the API's own phrase fills in.
+        phrase = reason or _string_field(body, "error") or ""
+        label = f"{status} {phrase}".strip()
+        message = f"{label}: {'; '.join(messages)}" if messages else label
+        if request_id:
+            message += f" (request {request_id})"
+        super().__init__(message)
+        self.status = status
+        self.messages = messages
+        self.body = body
+        self.raw_body = raw_body
+        self.headers = lower_headers
+        self._reason = reason
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # The constructor takes the response, not the message, so pickling
+        # (multiprocessing, task queues) needs to be told how to rebuild it.
+        return (type(self), (self.status, self._reason, self.raw_body, self.headers))
+
+    @property
+    def code(self) -> str | None:
+        """A machine-readable reason, when the API sends one.
+
+        For example ``watched_flight_limit`` or ``account_suspended``.
+        """
+        return _string_field(self.body, "code")
+
+    @property
+    def request_id(self) -> str | None:
+        """Identifies the request; quote it when contacting support."""
+        return _string_field(self.body, "requestId") or self.headers.get("x-request-id")
+
+    @staticmethod
+    def from_response(
+        status: int,
+        reason: str,
+        raw_body: str,
+        headers: Mapping[str, str],
+    ) -> APIError:
+        """Builds the subclass for ``status``."""
+        return _error_class_for(status)(status, reason, raw_body, headers)
+
+
+class BadRequestError(APIError):
+    """400: the request was invalid.
+
+    When a flight number flies several legs that day and no ``origin`` chose
+    one, ``legs`` lists them.
+    """
+
+    @property
+    def legs(self) -> list[AmbiguousLeg]:
+        """The legs to choose from; pass one's ``origin`` or ``flightId`` and try again."""
+        legs = self.body.get("legs")
+        if not isinstance(legs, list):
+            return []
+        result: list[AmbiguousLeg] = []
+        for item in legs:
+            if not isinstance(item, dict):
+                continue
+            leg: AmbiguousLeg = {
+                "origin": _string_field(item, "origin") or "",
+                "destination": _string_field(item, "destination") or "",
+            }
+            carrier = _string_field(item, "carrier")
+            departure = _string_field(item, "scheduledDepartureLocal")
+            flight_id = _string_field(item, "flightId")
+            if carrier is not None:
+                leg["carrier"] = carrier
+            if departure is not None:
+                leg["scheduledDepartureLocal"] = departure
+            if flight_id is not None:
+                leg["flightId"] = flight_id
+            result.append(leg)
+        return result
+
+
+class AuthenticationError(APIError):
+    """401: the API key is missing, invalid, revoked or expired."""
+
+
+class PaymentRequiredError(APIError):
+    """402: no watched flights are left.
+
+    ``code`` says why: ``watched_flight_limit`` (the plan's cap),
+    ``overage_cap_reached`` (the account's overage cap) or
+    ``credits_exhausted`` (prepaid credits used up).
+    """
+
+    @property
+    def limit(self) -> int | float | None:
+        """Watched flights the usage period allows. Not with ``credits_exhausted``."""
+        return _number_field(self.body, "limit")
+
+    @property
+    def used(self) -> int | float | None:
+        """Watched flights created this usage period. Not with ``credits_exhausted``."""
+        return _number_field(self.body, "used")
+
+    @property
+    def resets_at(self) -> str | None:
+        """When the usage period, and so the count, resets, ISO 8601."""
+        return _string_field(self.body, "resetsAt")
+
+    @property
+    def cap_cents(self) -> int | float | None:
+        """The overage cap in US cents; only with ``overage_cap_reached``."""
+        return _number_field(self.body, "capCents")
+
+    @property
+    def balance(self) -> int | float | None:
+        """Prepaid credits left; only with ``credits_exhausted``."""
+        return _number_field(self.body, "balance")
+
+    @property
+    def expires_at(self) -> str | None:
+        """When the credits expire or expired, ISO 8601; only with ``credits_exhausted``."""
+        return _string_field(self.body, "expiresAt")
+
+
+class PermissionDeniedError(APIError):
+    """403: the account is suspended or a token lacks the scope.
+
+    ``code`` is ``account_suspended`` or ``insufficient_scope``.
+    """
+
+
+class NotFoundError(APIError):
+    """404: the flight did not operate that day, or no such subscription."""
+
+
+class RateLimitError(APIError):
+    """429: a minute, day or month quota is used up."""
+
+    @property
+    def window(self) -> str | None:
+        """The window that ran out: ``minute``, ``day`` or ``month``."""
+        return _string_field(self.body, "window")
+
+    @property
+    def retry_after(self) -> int | float | None:
+        """How many seconds to wait before retrying.
+
+        From the body's ``retryAfterSeconds``, else the ``Retry-After`` header.
+        """
+        from_body = _number_field(self.body, "retryAfterSeconds")
+        if from_body is not None:
+            return from_body
+        match = _LEADING_INTEGER.match(self.headers.get("retry-after", ""))
+        return int(match.group(1)) if match else None
+
+
+class ServerError(APIError):
+    """5xx: the API failed. ``request_id`` is what support asks for."""
+
+
+class UpstreamError(ServerError):
+    """502: the upstream flight data provider failed.
+
+    Safe to retry after a short wait. It is also a ``ServerError``.
+    """
+
+
+class UnexpectedStatusError(APIError):
+    """Any other non-2xx status, including a redirect this client does not follow.
+
+    A redirect is not followed when it points to another origin, or when the
+    request was not a GET or HEAD. Its target is in ``location``.
+    """
+
+    @property
+    def location(self) -> str | None:
+        """Where a 3xx pointed, when it did."""
+        return self.headers.get("location")
+
+
+class WebhookSignatureError(FlightByteError):
+    """The webhook signature did not verify."""
+
+
+_STATUS_CLASSES: dict[int, type[APIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    429: RateLimitError,
+    502: UpstreamError,
+}
+
+_LEADING_INTEGER = re.compile(r"\s*([+-]?[0-9]{1,15})")
+
+
+def _error_class_for(status: int) -> type[APIError]:
+    error_class = _STATUS_CLASSES.get(status)
+    if error_class is not None:
+        return error_class
+    return ServerError if 500 <= status <= 599 else UnexpectedStatusError
+
+
+def _decode_body(raw_body: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(raw_body)
+    except ValueError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _read_messages(body: Mapping[str, Any]) -> list[str]:
+    message = body.get("message")
+    if isinstance(message, str):
+        return [message]
+    if isinstance(message, list):
+        return [item if isinstance(item, str) else json.dumps(item) for item in message]
+    return []
+
+
+def _string_field(mapping: Mapping[str, Any], key: str) -> str | None:
+    value = mapping.get(key)
+    return value if isinstance(value, str) else None
+
+
+def _number_field(mapping: Mapping[str, Any], key: str) -> int | float | None:
+    value = mapping.get(key)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return value if math.isfinite(value) else None