avia-api 0.1.0__py3-none-any.whl

avia_api/__init__.py

@@ -0,0 +1,34 @@
+"""Async Python client for the Travelpayouts / Aviasales Data API."""
+
+import logging
+
+from ._client import AviaApiClient
+from .exceptions import (
+    AviaApiAuthenticationError,
+    AviaApiConnectionError,
+    AviaApiError,
+    AviaApiHTTPStatusError,
+    AviaApiRateLimitError,
+    AviaApiResponseError,
+    AviaApiServerError,
+    AviaApiValidationError,
+)
+
+# Libraries should never configure handlers themselves - this only silences
+# the "No handlers could be found" warning until the application attaches
+# its own. See https://docs.python.org/3/howto/logging.html#library-config
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AviaApiClient",
+    "AviaApiError",
+    "AviaApiConnectionError",
+    "AviaApiHTTPStatusError",
+    "AviaApiAuthenticationError",
+    "AviaApiRateLimitError",
+    "AviaApiServerError",
+    "AviaApiResponseError",
+    "AviaApiValidationError",
+]

avia_api/_client.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import TypeAdapter, ValidationError
+from pyrate_limiter import Rate
+
+from ._params import clean_params
+from ._transport import build_transport
+from ._utils import parse_retry_after
+from .exceptions import (
+    AviaApiAuthenticationError,
+    AviaApiConnectionError,
+    AviaApiHTTPStatusError,
+    AviaApiRateLimitError,
+    AviaApiResponseError,
+    AviaApiServerError,
+    AviaApiValidationError,
+)
+from .resources import DirectionsResource, PricesResource, ReferenceResource
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BASE_URL = "https://api.travelpayouts.com"
+TOKEN_ENV_VAR = "TRAVELPAYOUTS_TOKEN"
+
+T = TypeVar("T")
+
+
+class AviaApiClient:
+    """Async client for the Travelpayouts / Aviasales Data API.
+
+    Example:
+        async with AviaApiClient(token="...") as client:
+            prices = await client.prices.cheap(origin="MOW", destination="LED")
+
+    Args:
+        token: API token from the partner's Travelpayouts account. Falls
+            back to the ``TRAVELPAYOUTS_TOKEN`` environment variable. Most
+            endpoints work without one at a reduced quota, but reads always
+            attach it when available.
+        base_url: Overridable mainly for testing.
+        timeout: Passed straight to ``httpx``.
+        rate: A ``pyrate_limiter.Rate`` (or list of rates) capping outbound
+            request throughput. Defaults to 5 requests/second.
+        max_retries: Attempts for requests that fail with a connection error
+            or a 429/5xx status, with exponential backoff (honoring
+            ``Retry-After`` when present).
+        cache_ttl: How long a successful GET response is reused for, in
+            seconds. ``None`` disables the cache.
+        cache_path: SQLite file backing the cache (relative paths land under
+            ``.cache/hishel/``, matching hishel's own convention).
+        transport: Escape hatch for tests or advanced setups - supplying this
+            bypasses rate limiting/retries/caching entirely.
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = 10.0,
+        rate: Rate | list[Rate] | None = None,
+        max_retries: int = 3,
+        cache_ttl: float | None = 1800.0,
+        cache_path: str | Path = "avia_api.db",
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        token = token or os.environ.get(TOKEN_ENV_VAR)
+        headers = {"X-Access-Token": token} if token else {}
+        if transport is None:
+            transport = build_transport(
+                rate=rate,
+                max_retries=max_retries,
+                cache_ttl=cache_ttl,
+                cache_path=cache_path,
+            )
+        self._http = httpx.AsyncClient(base_url=base_url, headers=headers, timeout=timeout, transport=transport)
+
+        self.prices = PricesResource(self)
+        self.directions = DirectionsResource(self)
+        self.reference = ReferenceResource(self)
+
+    async def __aenter__(self) -> AviaApiClient:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _get_json(self, path: str, *, params: dict[str, Any], adapter: TypeAdapter[T]) -> T:
+        cleaned_params = clean_params(params)
+        logger.debug("GET %s params=%r", path, cleaned_params)
+        try:
+            response = await self._http.get(path, params=cleaned_params)
+        except httpx.TransportError as exc:
+            logger.error("GET %s failed: %s", path, exc)
+            raise AviaApiConnectionError(str(exc)) from exc
+
+        self._raise_for_status(response)
+
+        payload = response.json()
+        if isinstance(payload, dict) and payload.get("success") is False:
+            logger.warning("GET %s returned success=false: %s", path, payload.get("error"))
+            raise AviaApiResponseError(payload.get("error") or "Aviasales API returned an error", payload=payload)
+
+        try:
+            result = adapter.validate_python(payload)
+        except ValidationError as exc:
+            logger.error("GET %s response failed schema validation: %s", path, exc)
+            raise AviaApiValidationError(str(exc)) from exc
+
+        logger.debug("GET %s -> %d", path, response.status_code)
+        return result
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.status_code < 400:
+            return
+        if response.status_code in (401, 403):
+            logger.warning("%s -> %d (authentication error)", response.request.url, response.status_code)
+            raise AviaApiAuthenticationError(response)
+        if response.status_code == 429:
+            retry_after = parse_retry_after(response.headers.get("retry-after"))
+            logger.warning("%s -> 429 (rate limited); retry_after=%s", response.request.url, retry_after)
+            raise AviaApiRateLimitError(response, retry_after=retry_after)
+        if response.status_code >= 500:
+            logger.error("%s -> %d (server error)", response.request.url, response.status_code)
+            raise AviaApiServerError(response)
+        logger.warning("%s -> %d", response.request.url, response.status_code)
+        raise AviaApiHTTPStatusError(response)

avia_api/_params.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+def clean_params(params: Mapping[str, Any]) -> dict[str, Any]:
+    """Drop ``None`` values for use as query params.
+
+    httpx serializes booleans as ``true``/``false`` on its own, but it has no
+    special handling for ``None`` - it would be sent as an empty string
+    otherwise - so that's filtered out here before the request is built.
+    """
+    return {key: value for key, value in params.items() if value is not None}

avia_api/_transport.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import logging
+import time
+from pathlib import Path
+
+import hishel
+import httpx
+import tenacity
+from hishel.httpx import AsyncCacheTransport
+from pyrate_limiter import Duration, Limiter, Rate
+
+from ._utils import parse_retry_after
+
+logger = logging.getLogger(__name__)
+
+#: Conservative default: Travelpayouts does not publish a single documented
+#: number for the Data API, so this stays well under the limits mentioned for
+#: other methods rather than assume the account's actual quota.
+DEFAULT_RATE = Rate(5, Duration.SECOND)
+
+RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+
+_EXPONENTIAL_WAIT = tenacity.wait_exponential_jitter(initial=0.5, max=8.0)
+
+#: Only logged when the rate limiter actually delayed a request by more than
+#: this many seconds - avoids a debug line on every single request.
+_RATE_LIMIT_LOG_THRESHOLD = 0.01
+
+#: Upper bound for a single retry wait derived from a server-supplied
+#: ``Retry-After`` header. Without this, a large (or misconfigured) value -
+#: Travelpayouts documents nothing here, and some APIs send minutes during
+#: incidents - would stall a request for that long on every retried attempt,
+#: since ``stop_after_attempt`` only bounds the number of attempts, not how
+#: long each one is allowed to wait.
+MAX_RETRY_AFTER_WAIT = 60.0
+
+
+class _RetryableStatusError(Exception):
+    """Internal signal: the response's status code should trigger a retry."""
+
+    def __init__(self, retry_after: float | None, *, status_code: int | None = None) -> None:
+        self.retry_after = retry_after
+        self.status_code = status_code
+
+
+def _wait(retry_state: tenacity.RetryCallState) -> float:
+    exc = retry_state.outcome.exception() if retry_state.outcome else None
+    if isinstance(exc, _RetryableStatusError) and exc.retry_after is not None:
+        if exc.retry_after > MAX_RETRY_AFTER_WAIT:
+            logger.warning(
+                "Server requested Retry-After=%.1fs; capping wait to %.1fs",
+                exc.retry_after,
+                MAX_RETRY_AFTER_WAIT,
+            )
+        return min(exc.retry_after, MAX_RETRY_AFTER_WAIT)
+    return _EXPONENTIAL_WAIT(retry_state)
+
+
+class _ResilientTransport(httpx.AsyncBaseTransport):
+    """Applies client-side rate limiting and retries transient failures.
+
+    Sits directly on top of the network transport, underneath the cache
+    transport, so cache hits never touch the limiter or the retry loop.
+    """
+
+    def __init__(
+        self,
+        transport: httpx.AsyncBaseTransport,
+        *,
+        rate: Rate | list[Rate],
+        max_retries: int,
+    ) -> None:
+        self._transport = transport
+        self._limiter = Limiter(rate)
+        self._max_retries = max(max_retries, 1)
+
+    def _before_sleep(self, request: httpx.Request, retry_state: tenacity.RetryCallState) -> None:
+        exc = retry_state.outcome.exception() if retry_state.outcome else None
+        wait = retry_state.next_action.sleep if retry_state.next_action else 0.0
+        reason = f"HTTP {exc.status_code}" if isinstance(exc, _RetryableStatusError) else repr(exc)
+        logger.warning(
+            "%s %s failed on attempt %d/%d (%s); retrying in %.2fs",
+            request.method,
+            request.url,
+            retry_state.attempt_number,
+            self._max_retries,
+            reason,
+            wait,
+        )
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        response: httpx.Response
+        retrying = tenacity.AsyncRetrying(
+            stop=tenacity.stop_after_attempt(self._max_retries),
+            wait=_wait,
+            retry=tenacity.retry_if_exception_type((httpx.TransportError, _RetryableStatusError)),
+            reraise=True,
+            before_sleep=lambda retry_state: self._before_sleep(request, retry_state),
+        )
+        try:
+            async for attempt in retrying:
+                with attempt:
+                    start = time.monotonic()
+                    await self._limiter.try_acquire_async("avia-api")
+                    delay = time.monotonic() - start
+                    if delay > _RATE_LIMIT_LOG_THRESHOLD:
+                        logger.debug("Rate limiter delayed %s %s by %.3fs", request.method, request.url, delay)
+                    response = await self._transport.handle_async_request(request)
+                    if response.status_code in RETRYABLE_STATUS_CODES:
+                        # Read the body before closing so the caller can still
+                        # inspect status/headers/content once retries run out.
+                        await response.aread()
+                        retry_after = parse_retry_after(response.headers.get("retry-after"))
+                        await response.aclose()
+                        raise _RetryableStatusError(retry_after, status_code=response.status_code)
+        except _RetryableStatusError as exc:
+            # Retry budget exhausted on a bad status: hand the last response
+            # back to the caller instead of leaking this internal signal.
+            logger.warning(
+                "%s %s exhausted retry budget (%d attempt(s)); giving up with status %d",
+                request.method,
+                request.url,
+                self._max_retries,
+                exc.status_code,
+            )
+            return response
+        except httpx.TransportError:
+            logger.warning(
+                "%s %s exhausted retry budget (%d attempt(s)); giving up",
+                request.method,
+                request.url,
+                self._max_retries,
+            )
+            raise
+        logger.debug("%s %s -> %d", request.method, request.url, response.status_code)
+        return response
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+
+def build_transport(
+    *,
+    rate: Rate | list[Rate] | None,
+    max_retries: int,
+    cache_ttl: float | None,
+    cache_path: str | Path,
+) -> httpx.AsyncBaseTransport:
+    """Build the layered transport: cache -> rate limit/retry -> network.
+
+    ``cache_ttl=None`` disables caching entirely, leaving just the resilient
+    transport in place.
+    """
+    network = httpx.AsyncHTTPTransport(retries=0)
+    resilient: httpx.AsyncBaseTransport = _ResilientTransport(
+        network, rate=rate or DEFAULT_RATE, max_retries=max_retries
+    )
+    if cache_ttl is None:
+        return resilient
+
+    # Travelpayouts responses carry no Cache-Control/ETag headers, so a
+    # spec-compliant (RFC 9111) cache policy would never store anything.
+    # FilterPolicy with no filters caches every response unconditionally,
+    # and the storage's own default_ttl governs expiry instead.
+    storage = hishel.AsyncSqliteStorage(database_path=cache_path, default_ttl=cache_ttl)
+    return AsyncCacheTransport(next_transport=resilient, storage=storage, policy=hishel.FilterPolicy())

avia_api/_utils.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from datetime import datetime
+from email.utils import parsedate_to_datetime
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    """Parse a ``Retry-After`` header into a number of seconds.
+
+    Supports both the delay-seconds and HTTP-date forms defined by RFC 9110.
+    Returns ``None`` if the header is missing or unparsable.
+    """
+    if not value:
+        return None
+    value = value.strip()
+    if value.isdigit():
+        return float(value)
+    try:
+        retry_at = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if retry_at.tzinfo is None:
+        return None
+    return max((retry_at - datetime.now(retry_at.tzinfo)).total_seconds(), 0.0)

avia_api/exceptions.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class AviaApiError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class AviaApiConnectionError(AviaApiError):
+    """The request could not be sent, or no response was received.
+
+    Raised after the underlying network error survived all retry attempts.
+    """
+
+
+class AviaApiHTTPStatusError(AviaApiError):
+    """The server responded with an HTTP error status.
+
+    This is only raised for statuses that are not retried automatically
+    (or that survived every retry attempt).
+    """
+
+    def __init__(self, response: httpx.Response) -> None:
+        self.response = response
+        self.status_code = response.status_code
+        super().__init__(f"{response.status_code} {response.reason_phrase} for url {response.request.url}")
+
+
+class AviaApiAuthenticationError(AviaApiHTTPStatusError):
+    """Raised on HTTP 401/403 - the API token is missing or invalid."""
+
+
+class AviaApiRateLimitError(AviaApiHTTPStatusError):
+    """Raised on HTTP 429 after the retry budget was exhausted."""
+
+    def __init__(self, response: httpx.Response, *, retry_after: float | None) -> None:
+        super().__init__(response)
+        self.retry_after = retry_after
+
+
+class AviaApiServerError(AviaApiHTTPStatusError):
+    """Raised on HTTP 5xx after the retry budget was exhausted."""
+
+
+class AviaApiResponseError(AviaApiError):
+    """The API responded with HTTP 200 but ``{"success": false}`` in the body."""
+
+    def __init__(self, message: str, *, payload: Any = None) -> None:
+        super().__init__(message)
+        self.payload = payload
+
+
+class AviaApiValidationError(AviaApiError):
+    """The response body did not match the expected schema.
+
+    This usually means the API changed shape; it is kept distinct from
+    transport-level errors so callers can tell "we got a bad response" apart
+    from "we couldn't reach the server".
+    """

avia_api/models/__init__.py

@@ -0,0 +1,41 @@
+from .common import Envelope
+from .directions import CityDirectionPrice
+from .prices import (
+    CalendarPrice,
+    LatestPriceEntry,
+    MatrixPriceEntry,
+    MonthlyPrice,
+    NearestPlacesMatrixPrice,
+    NearestPlacesMatrixResponse,
+    SimplePrice,
+)
+from .reference import (
+    Airline,
+    AirlineAlliance,
+    Airport,
+    City,
+    Coordinates,
+    Country,
+    Plane,
+    Route,
+)
+
+__all__ = [
+    "Envelope",
+    "SimplePrice",
+    "CalendarPrice",
+    "MonthlyPrice",
+    "LatestPriceEntry",
+    "MatrixPriceEntry",
+    "NearestPlacesMatrixPrice",
+    "NearestPlacesMatrixResponse",
+    "CityDirectionPrice",
+    "Coordinates",
+    "Country",
+    "City",
+    "Airport",
+    "Airline",
+    "AirlineAlliance",
+    "Plane",
+    "Route",
+]

avia_api/models/common.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Annotated, Generic, TypeVar
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict
+
+T = TypeVar("T")
+
+
+def _empty_str_to_none(value: object) -> object:
+    return None if value == "" else value
+
+
+#: Several endpoints use ``""`` instead of omitting the field for a one-way
+#: trip's missing return date/datetime.
+OptionalDate = Annotated[date | None, BeforeValidator(_empty_str_to_none)]
+OptionalDateTime = Annotated[datetime | None, BeforeValidator(_empty_str_to_none)]
+
+
+class AviaBaseModel(BaseModel):
+    """Base for all response models.
+
+    ``extra="allow"`` means fields the API adds later show up on
+    ``model_extra`` instead of raising, so a new, undocumented field never
+    breaks parsing of the fields we do know about.
+    """
+
+    model_config = ConfigDict(extra="allow", frozen=True)
+
+
+class Envelope(AviaBaseModel, Generic[T]):
+    """The ``{"success", "data", "error"}`` shape shared by most v1/v2 endpoints."""
+
+    success: bool
+    data: T
+    error: str | None = None
+    currency: str | None = None

avia_api/models/directions.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from .common import AviaBaseModel, OptionalDateTime
+
+
+class CityDirectionPrice(AviaBaseModel):
+    """An entry from ``/v1/city-directions``."""
+
+    origin: str
+    destination: str
+    price: int
+    transfers: int
+    airline: str
+    flight_number: int
+    departure_at: datetime
+    return_at: OptionalDateTime = None
+    expires_at: datetime

avia_api/models/prices.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import Field
+
+from .common import AviaBaseModel, OptionalDate, OptionalDateTime
+
+
+class SimplePrice(AviaBaseModel):
+    """An entry from ``/v1/prices/cheap`` or ``/v1/prices/direct``."""
+
+    price: int
+    airline: str
+    flight_number: int
+    departure_at: datetime
+    return_at: OptionalDateTime = None
+    expires_at: datetime
+
+
+class CalendarPrice(AviaBaseModel):
+    """An entry from ``/v1/prices/calendar`` (and reused for city-directions)."""
+
+    origin: str
+    destination: str
+    price: int
+    transfers: int
+    airline: str
+    flight_number: int
+    departure_at: datetime
+    return_at: OptionalDateTime = None
+    expires_at: datetime
+
+
+class MonthlyPrice(CalendarPrice):
+    """An entry from ``/v1/prices/monthly``. Same shape as :class:`CalendarPrice`."""
+
+
+class LatestPriceEntry(AviaBaseModel):
+    """An entry from ``/v2/prices/latest``."""
+
+    show_to_affiliates: bool
+    trip_class: int
+    origin: str
+    destination: str
+    depart_date: OptionalDate = None
+    return_date: OptionalDate = None
+    number_of_changes: int
+    value: float
+    found_at: datetime
+    distance: int | None = None
+    actual: bool
+
+
+class MatrixPriceEntry(LatestPriceEntry):
+    """An entry from ``/v2/prices/month-matrix`` or ``/v2/prices/week-matrix``.
+
+    Same shape as :class:`LatestPriceEntry`.
+    """
+
+
+class NearestPlacesMatrixPrice(AviaBaseModel):
+    """A price entry from ``/v2/prices/nearest-places-matrix``."""
+
+    value: float
+    trip_class: int
+    show_to_affiliates: bool
+    origin: str
+    destination: str
+    depart_date: OptionalDate = None
+    return_date: OptionalDate = None
+    number_of_changes: int
+    gate: str | None = None
+    found_at: datetime
+    duration: int | None = None
+    distance: int | None = None
+    actual: bool
+
+
+class NearestPlacesMatrixResponse(AviaBaseModel):
+    """The body of ``/v2/prices/nearest-places-matrix``.
+
+    Unlike the other v1/v2 endpoints, this one is not wrapped in an
+    ``Envelope`` - it has its own top-level shape.
+    """
+
+    prices: list[NearestPlacesMatrixPrice] = Field(default_factory=list)
+    origins: list[str] = Field(default_factory=list)
+    destinations: list[str] = Field(default_factory=list)
+    errors: dict[str, object] = Field(default_factory=dict)

avia_api/models/reference.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from .common import AviaBaseModel
+
+
+class Coordinates(AviaBaseModel):
+    lon: float
+    lat: float
+
+
+class Country(AviaBaseModel):
+    code: str
+    name: str
+    currency: str | None = None
+    name_translations: dict[str, str] = Field(default_factory=dict)
+
+
+class City(AviaBaseModel):
+    code: str
+    name: str
+    coordinates: Coordinates | None = None
+    time_zone: str | None = None
+    name_translations: dict[str, str] = Field(default_factory=dict)
+    country_code: str | None = None
+
+
+class Airport(AviaBaseModel):
+    code: str
+    name: str
+    coordinates: Coordinates | None = None
+    time_zone: str | None = None
+    name_translations: dict[str, str] = Field(default_factory=dict)
+    country_code: str | None = None
+    city_code: str | None = None
+
+
+class Airline(AviaBaseModel):
+    name: str
+    alias: str | None = None
+    iata: str | None = None
+    icao: str | None = None
+    callsign: str | None = None
+    country: str | None = None
+    is_active: bool = True
+
+
+class AirlineAlliance(AviaBaseModel):
+    name: str
+    airlines: list[str] = Field(default_factory=list)
+
+
+class Plane(AviaBaseModel):
+    code: str
+    name: str
+
+
+class Route(AviaBaseModel):
+    airline_iata: str | None = None
+    airline_icao: str | None = None
+    departure_airport_iata: str | None = None
+    departure_airport_icao: str | None = None
+    arrival_airport_iata: str | None = None
+    arrival_airport_icao: str | None = None
+    codeshare: bool = False
+    transfers: int = 0
+    planes: list[str] = Field(default_factory=list)

avia_api/resources/__init__.py

@@ -0,0 +1,5 @@
+from .directions import DirectionsResource
+from .prices import PricesResource
+from .reference import ReferenceResource
+
+__all__ = ["PricesResource", "DirectionsResource", "ReferenceResource"]

avia_api/resources/_base.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import typing as t
+
+from pydantic import TypeAdapter
+
+if t.TYPE_CHECKING:
+    from .._client import AviaApiClient
+
+T = t.TypeVar("T")
+
+
+class BaseResource:
+    def __init__(self, client: AviaApiClient) -> None:
+        self._client = client
+
+    async def _get(self, path: str, params: dict[str, t.Any], adapter: TypeAdapter[T]) -> T:
+        return await self._client._get_json(path, params=params, adapter=adapter)

avia_api/resources/directions.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pydantic import TypeAdapter
+
+from .._params import clean_params
+from ..models.common import Envelope
+from ..models.directions import CityDirectionPrice
+from ._base import BaseResource
+
+_AIRLINE_ADAPTER = TypeAdapter(Envelope[dict[str, int]])
+_CITY_ADAPTER = TypeAdapter(Envelope[dict[str, CityDirectionPrice]])
+
+
+class DirectionsResource(BaseResource):
+    """Popular routes: ``/v1/airline-directions`` and ``/v1/city-directions``."""
+
+    async def airline(
+        self,
+        airline_code: str,
+        *,
+        limit: int | None = None,
+    ) -> dict[str, int]:
+        """Popular routes for one airline, mapped to their cheapest price.
+
+        ``GET /v1/airline-directions``
+        """
+        params = clean_params(dict(airline_code=airline_code, limit=limit))
+        envelope = await self._get("/v1/airline-directions", params, _AIRLINE_ADAPTER)
+        return envelope.data
+
+    async def city(
+        self,
+        origin: str,
+        *,
+        currency: str | None = None,
+    ) -> dict[str, CityDirectionPrice]:
+        """Popular destinations from one city, with the cheapest ticket found.
+
+        ``GET /v1/city-directions``
+        """
+        params = clean_params(dict(origin=origin, currency=currency))
+        envelope = await self._get("/v1/city-directions", params, _CITY_ADAPTER)
+        return envelope.data

avia_api/resources/prices.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+from pydantic import TypeAdapter
+
+from .._params import clean_params
+from ..models.common import Envelope
+from ..models.prices import (
+    CalendarPrice,
+    LatestPriceEntry,
+    MatrixPriceEntry,
+    MonthlyPrice,
+    NearestPlacesMatrixResponse,
+    SimplePrice,
+)
+from ._base import BaseResource
+
+_CHEAP_ADAPTER = TypeAdapter(Envelope[dict[str, dict[str, SimplePrice]]])
+_CALENDAR_ADAPTER = TypeAdapter(Envelope[dict[str, CalendarPrice]])
+_MONTHLY_ADAPTER = TypeAdapter(Envelope[dict[str, MonthlyPrice]])
+_LATEST_ADAPTER = TypeAdapter(Envelope[list[LatestPriceEntry]])
+_MATRIX_ADAPTER = TypeAdapter(Envelope[list[MatrixPriceEntry]])
+_NEAREST_PLACES_ADAPTER = TypeAdapter(NearestPlacesMatrixResponse)
+
+
+class PricesResource(BaseResource):
+    """Cached ticket prices: ``/v1/prices/*`` and ``/v2/prices/*``.
+
+    Date-like parameters are plain strings - the API accepts either
+    ``"YYYY-MM-DD"`` or, on some endpoints, a month-only ``"YYYY-MM"``, and
+    :class:`datetime.date` can't represent the latter, so the choice of
+    format is left to the caller instead of guessing at a conversion.
+    """
+
+    async def cheap(
+        self,
+        origin: str,
+        destination: str,
+        *,
+        depart_date: str | None = None,
+        return_date: str | None = None,
+        currency: str | None = None,
+        page: int | None = None,
+    ) -> dict[str, dict[str, SimplePrice]]:
+        """The cheapest tickets found for each destination, grouped by index.
+
+        ``GET /v1/prices/cheap``. ``depart_date``/``return_date``: ``"YYYY-MM"`` or ``"YYYY-MM-DD"``.
+        """
+        params = clean_params(
+            dict(
+                origin=origin,
+                destination=destination,
+                depart_date=depart_date,
+                return_date=return_date,
+                currency=currency,
+                page=page,
+            )
+        )
+        envelope = await self._get("/v1/prices/cheap", params, _CHEAP_ADAPTER)
+        return envelope.data
+
+    async def direct(
+        self,
+        origin: str,
+        destination: str,
+        *,
+        depart_date: str | None = None,
+        return_date: str | None = None,
+        currency: str | None = None,
+        page: int | None = None,
+    ) -> dict[str, dict[str, SimplePrice]]:
+        """The cheapest non-stop tickets found for each destination.
+
+        ``GET /v1/prices/direct``. ``depart_date``/``return_date``: ``"YYYY-MM"`` or ``"YYYY-MM-DD"``.
+        """
+        params = clean_params(
+            dict(
+                origin=origin,
+                destination=destination,
+                depart_date=depart_date,
+                return_date=return_date,
+                currency=currency,
+                page=page,
+            )
+        )
+        envelope = await self._get("/v1/prices/direct", params, _CHEAP_ADAPTER)
+        return envelope.data
+
+    async def calendar(
+        self,
+        origin: str,
+        destination: str,
+        depart_date: str,
+        *,
+        calendar_type: str = "departure_date",
+        return_date: str | None = None,
+        length: int | None = None,
+        currency: str | None = None,
+    ) -> dict[str, CalendarPrice]:
+        """The cheapest ticket for each day of the month around ``depart_date``.
+
+        ``GET /v1/prices/calendar``. ``depart_date``/``return_date``: ``"YYYY-MM"`` or ``"YYYY-MM-DD"``.
+        """
+        params = clean_params(
+            dict(
+                origin=origin,
+                destination=destination,
+                depart_date=depart_date,
+                calendar_type=calendar_type,
+                return_date=return_date,
+                length=length,
+                currency=currency,
+            )
+        )
+        envelope = await self._get("/v1/prices/calendar", params, _CALENDAR_ADAPTER)
+        return envelope.data
+
+    async def monthly(
+        self,
+        origin: str,
+        destination: str,
+        *,
+        currency: str | None = None,
+    ) -> dict[str, MonthlyPrice]:
+        """The cheapest ticket for each of the next several months.
+
+        ``GET /v1/prices/monthly``
+        """
+        params = clean_params(dict(origin=origin, destination=destination, currency=currency))
+        envelope = await self._get("/v1/prices/monthly", params, _MONTHLY_ADAPTER)
+        return envelope.data
+
+    async def latest(
+        self,
+        *,
+        currency: str | None = None,
+        origin: str | None = None,
+        destination: str | None = None,
+        beginning_of_period: str | None = None,
+        period_type: str | None = None,
+        one_way: bool | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        show_to_affiliates: bool | None = None,
+        sorting: str | None = None,
+    ) -> list[LatestPriceEntry]:
+        """The most recently found prices across all of Aviasales' search history.
+
+        ``GET /v2/prices/latest``. ``beginning_of_period``: ``"YYYY-MM-DD"``.
+        """
+        params = clean_params(
+            dict(
+                currency=currency,
+                origin=origin,
+                destination=destination,
+                beginning_of_period=beginning_of_period,
+                period_type=period_type,
+                one_way=one_way,
+                page=page,
+                limit=limit,
+                show_to_affiliates=show_to_affiliates,
+                sorting=sorting,
+            )
+        )
+        envelope = await self._get("/v2/prices/latest", params, _LATEST_ADAPTER)
+        return envelope.data
+
+    async def month_matrix(
+        self,
+        origin: str,
+        destination: str,
+        *,
+        currency: str | None = None,
+        month: str | None = None,
+        show_to_affiliates: bool | None = None,
+    ) -> list[MatrixPriceEntry]:
+        """A price calendar for every day of one month.
+
+        ``GET /v2/prices/month-matrix``. ``month``: ``"YYYY-MM-DD"``.
+        """
+        params = clean_params(
+            dict(
+                origin=origin,
+                destination=destination,
+                currency=currency,
+                month=month,
+                show_to_affiliates=show_to_affiliates,
+            )
+        )
+        envelope = await self._get("/v2/prices/month-matrix", params, _MATRIX_ADAPTER)
+        return envelope.data
+
+    async def week_matrix(
+        self,
+        origin: str,
+        destination: str,
+        *,
+        currency: str | None = None,
+        depart_date: str | None = None,
+        return_date: str | None = None,
+        show_to_affiliates: bool | None = None,
+    ) -> list[MatrixPriceEntry]:
+        """A price calendar for the week around ``depart_date``.
+
+        ``GET /v2/prices/week-matrix``. ``depart_date``/``return_date``: ``"YYYY-MM"`` or ``"YYYY-MM-DD"``.
+        """
+        params = clean_params(
+            dict(
+                origin=origin,
+                destination=destination,
+                currency=currency,
+                depart_date=depart_date,
+                return_date=return_date,
+                show_to_affiliates=show_to_affiliates,
+            )
+        )
+        envelope = await self._get("/v2/prices/week-matrix", params, _MATRIX_ADAPTER)
+        return envelope.data
+
+    async def nearest_places_matrix(
+        self,
+        origin: str,
+        destination: str,
+        *,
+        currency: str | None = None,
+        limit: int | None = None,
+        show_to_affiliates: bool | None = None,
+        depart_date: str | None = None,
+        return_date: str | None = None,
+        flexibility: int | None = None,
+        distance: int | None = None,
+    ) -> NearestPlacesMatrixResponse:
+        """Prices for nearby origin/destination airports, when the exact route is expensive.
+
+        ``GET /v2/prices/nearest-places-matrix``. ``depart_date``/``return_date``: ``"YYYY-MM"`` or ``"YYYY-MM-DD"``.
+        """
+        params = clean_params(
+            dict(
+                origin=origin,
+                destination=destination,
+                currency=currency,
+                limit=limit,
+                show_to_affiliates=show_to_affiliates,
+                depart_date=depart_date,
+                return_date=return_date,
+                flexibility=flexibility,
+                distance=distance,
+            )
+        )
+        return await self._get("/v2/prices/nearest-places-matrix", params, _NEAREST_PLACES_ADAPTER)

avia_api/resources/reference.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pydantic import TypeAdapter
+
+from ..models.reference import Airline, AirlineAlliance, Airport, City, Country, Plane, Route
+from ._base import BaseResource
+
+_COUNTRIES_ADAPTER = TypeAdapter(list[Country])
+_CITIES_ADAPTER = TypeAdapter(list[City])
+_AIRPORTS_ADAPTER = TypeAdapter(list[Airport])
+_AIRLINES_ADAPTER = TypeAdapter(list[Airline])
+_ALLIANCES_ADAPTER = TypeAdapter(list[AirlineAlliance])
+_PLANES_ADAPTER = TypeAdapter(list[Plane])
+_ROUTES_ADAPTER = TypeAdapter(list[Route])
+
+
+class ReferenceResource(BaseResource):
+    """Static reference data: ``/data/*.json``.
+
+    These are plain, unauthenticated JSON files that change rarely, so they
+    benefit the most from the client's response cache.
+    """
+
+    async def countries(self, *, language: str = "en") -> list[Country]:
+        """``GET /data/{language}/countries.json``"""
+        return await self._get(f"/data/{language}/countries.json", {}, _COUNTRIES_ADAPTER)
+
+    async def cities(self, *, language: str = "en") -> list[City]:
+        """``GET /data/{language}/cities.json``"""
+        return await self._get(f"/data/{language}/cities.json", {}, _CITIES_ADAPTER)
+
+    async def airports(self, *, language: str = "en") -> list[Airport]:
+        """``GET /data/{language}/airports.json``"""
+        return await self._get(f"/data/{language}/airports.json", {}, _AIRPORTS_ADAPTER)
+
+    async def airlines(self, *, language: str = "en") -> list[Airline]:
+        """``GET /data/{language}/airlines.json``"""
+        return await self._get(f"/data/{language}/airlines.json", {}, _AIRLINES_ADAPTER)
+
+    async def airline_alliances(self, *, language: str = "en") -> list[AirlineAlliance]:
+        """``GET /data/{language}/airlines_alliances.json``"""
+        return await self._get(f"/data/{language}/airlines_alliances.json", {}, _ALLIANCES_ADAPTER)
+
+    async def planes(self) -> list[Plane]:
+        """``GET /data/planes.json``"""
+        return await self._get("/data/planes.json", {}, _PLANES_ADAPTER)
+
+    async def routes(self) -> list[Route]:
+        """``GET /data/routes.json``"""
+        return await self._get("/data/routes.json", {}, _ROUTES_ADAPTER)

avia_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: avia-api
+Version: 0.1.0
+Summary: Async Python client for the Travelpayouts / Aviasales Data API
+License-Expression: MIT
+License-File: LICENSE
+Keywords: travelpayouts,aviasales,flights,airline-tickets,prices,api-client,async,httpx,pydantic
+Author: Ivan Sladkov
+Author-email: ivan.sladkov@yandex.ru
+Requires-Python: >=3.11
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: hishel[httpx] (>=1.3.1,<2.0.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.13.5,<3.0.0)
+Requires-Dist: pyrate-limiter (>=4.5.0,<5.0.0)
+Requires-Dist: tenacity (>=9.1.4,<10.0.0)
+Project-URL: Changelog, https://github.com/sliv2001/avia-api/blob/master/CHANGELOG.md
+Project-URL: Homepage, https://github.com/sliv2001/avia-api
+Project-URL: Issues, https://github.com/sliv2001/avia-api/issues
+Project-URL: Repository, https://github.com/sliv2001/avia-api
+Description-Content-Type: text/markdown
+
+# avia-api
+
+[![CI](https://github.com/sliv2001/avia-api/actions/workflows/ci.yml/badge.svg)](https://github.com/sliv2001/avia-api/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/badge/coverage-99%25%2B-brightgreen)](https://github.com/sliv2001/avia-api/blob/master/pyproject.toml)
+[![python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://github.com/sliv2001/avia-api)
+[![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/sliv2001/avia-api/blob/master/LICENSE)
+
+Async Python client for the [Aviasales / Travelpayouts Data API](https://support.travelpayouts.com/hc/ru/sections/201008338-Aviasales-flight-data-API) - historical/cached ticket prices, price calendars, and reference data (countries, cities, airports, airlines, routes).
+
+Not covered: real-time search (`Aviasales Flights Search API`) and the GraphQL API - these are separate products with a different interaction model.
+
+## Installation
+
+The package is available through any standard package manager:
+
+```bash
+pip install avia-api
+# or
+uv add avia-api
+# or
+poetry add avia-api
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+import asyncio
+from avia_api import AviaApiClient
+
+async def main() -> None:
+    async with AviaApiClient(token="YOUR_TOKEN") as client:
+        prices = await client.prices.cheap(origin="MOW", destination="LED")
+        for destination, by_index in prices.items():
+            for entry in by_index.values():
+                print(destination, entry.price, entry.airline, entry.departure_at)
+
+asyncio.run(main())
+```
+
+You can also skip passing the token explicitly and put it in the `TRAVELPAYOUTS_TOKEN` environment variable - the client will pick it up automatically. Get a token in your personal dashboard: https://www.travelpayouts.com/programs/100/tools/api
+
+## Resources and endpoints
+
+All methods return models validated by [pydantic](https://docs.pydantic.dev/)
+
+### `client.prices` - prices
+
+| Method                                            | Endpoint                               | Description                                      |
+| ------------------------------------------------- | -------------------------------------- | ------------------------------------------------ |
+| `cheap(origin, destination, ...)`                 | `GET /v1/prices/cheap`                 | Cheapest tickets for a route                     |
+| `direct(origin, destination, ...)`                | `GET /v1/prices/direct`                | Same, but direct flights only                    |
+| `calendar(origin, destination, depart_date, ...)` | `GET /v1/prices/calendar`              | Price calendar for every day of the month        |
+| `monthly(origin, destination, ...)`               | `GET /v1/prices/monthly`               | Lowest price by month                            |
+| `latest(...)`                                     | `GET /v2/prices/latest`                | Latest found prices across the whole search base |
+| `month_matrix(origin, destination, ...)`          | `GET /v2/prices/month-matrix`          | Price calendar for a month (v2)                  |
+| `week_matrix(origin, destination, ...)`           | `GET /v2/prices/week-matrix`           | Price calendar for a week                        |
+| `nearest_places_matrix(origin, destination, ...)` | `GET /v2/prices/nearest-places-matrix` | Prices for nearby airports/cities                |
+
+### `client.directions` - popular routes
+
+| Method                       | Endpoint                     | Description                      |
+| ---------------------------- | ---------------------------- | -------------------------------- |
+| `airline(airline_code, ...)` | `GET /v1/airline-directions` | Popular routes for an airline    |
+| `city(origin, ...)`          | `GET /v1/city-directions`    | Popular destinations from a city |
+
+### `client.reference` - reference data
+
+Public, rarely changing JSON files:
+
+| Method                             | Endpoint                                       |
+| ---------------------------------- | ---------------------------------------------- |
+| `countries(language="en")`         | `GET /data/{language}/countries.json`          |
+| `cities(language="en")`            | `GET /data/{language}/cities.json`             |
+| `airports(language="en")`          | `GET /data/{language}/airports.json`           |
+| `airlines(language="en")`          | `GET /data/{language}/airlines.json`           |
+| `airline_alliances(language="en")` | `GET /data/{language}/airlines_alliances.json` |
+| `planes()`                         | `GET /data/planes.json`                        |
+| `routes()`                         | `GET /data/routes.json`                        |
+
+## Client configuration
+
+```python
+from avia_api import AviaApiClient
+from pyrate_limiter import Rate, Duration
+
+client = AviaApiClient(
+    token="...",
+    rate=Rate(5, Duration.SECOND),   # outgoing request rate limit (pyrate-limiter)
+    max_retries=3,                   # retries on 429/5xx and connection drops
+    cache_ttl=1800,                  # seconds; None disables the response cache
+    cache_path="avia_api.db",        # sqlite cache file (hishel), relative path
+                                      # goes under .cache/hishel/
+    timeout=10.0,
+)
+```
+
+- **Rate limiting** - [pyrate-limiter](https://github.com/vutran1710/PyrateLimiter), a single bucket per client. Limits the rate of outgoing requests before they're sent, to avoid getting a `429` from the API.
+- **Retries** - [tenacity](https://github.com/jd/tenacity) with exponential backoff and jitter; on `429` the `Retry-After` header is honored if present, but capped at 60 seconds per attempt - an unusually large value from the server (e.g. during an incident on its side) can't stall a request indefinitely.
+- **Cache** - [hishel](https://hishel.com) on top of sqlite. Travelpayouts responses don't send `Cache-Control`, so `FilterPolicy` is used (any successful `GET` is cached, with entry lifetime governed by `cache_ttl`) instead of RFC 9111.
+
+For tests or non-standard scenarios you can pass `transport=...` - your own `httpx.AsyncBaseTransport`, which fully disables rate limiting/retry/cache, and requests go straight through it (see `respx` or `httpx.MockTransport`).
+
+## Error handling
+
+All exceptions derive from `avia_api.AviaApiError`:
+
+| Exception                    | When it occurs                                                 |
+| ---------------------------- | -------------------------------------------------------------- |
+| `AviaApiConnectionError`     | Network unavailable / timeout - after retries are exhausted    |
+| `AviaApiAuthenticationError` | HTTP 401/403 - token missing or invalid                        |
+| `AviaApiRateLimitError`      | HTTP 429 - after retries are exhausted; has `.retry_after`     |
+| `AviaApiServerError`         | HTTP 5xx - after retries are exhausted                         |
+| `AviaApiHTTPStatusError`     | Other HTTP errors                                              |
+| `AviaApiResponseError`       | HTTP 200, but `{"success": false}` in the body; has `.payload` |
+| `AviaApiValidationError`     | Response doesn't match the expected schema (API changed)       |
+
+## Logging
+
+The library uses standard `logging`. To see logs, enable the desired level for the `avia_api` logger:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("avia_api").setLevel(logging.DEBUG)
+```
+
+What is logged and at what level:
+
+| Logger                | Level     | Event                                                                      |
+| --------------------- | --------- | -------------------------------------------------------------------------- |
+| `avia_api._transport` | `DEBUG`   | Delay in the rate limiter; successful request and its status               |
+| `avia_api._transport` | `WARNING` | Retry after a transient error/status; retry budget exhausted               |
+| `avia_api._client`    | `DEBUG`   | Outgoing request (path + query parameters) and response status             |
+| `avia_api._client`    | `WARNING` | HTTP 401/403/429/4xx; `{"success": false}` in the response body            |
+| `avia_api._client`    | `ERROR`   | HTTP 5xx; network error after retries; response failed the pydantic schema |
+

avia_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+avia_api/__init__.py,sha256=lsCKDjZg1jJHh_Z96BgGFDiX-woUyWZWcjFwHMjbXwM,935
+avia_api/_client.py,sha256=ICWTeYWzm9z7Qpan2PJMJST_lkZIMCpHoicTAIEq8hs,5467
+avia_api/_params.py,sha256=2zSYyM_Yis_eKe7z3pzuytDMjpdmJXBIlgH2Oys5LEU,523
+avia_api/_transport.py,sha256=_gGjTUS3MTFI4xLbTZHaUsGitOH_kDwloV8gILt1VCM,6871
+avia_api/_utils.py,sha256=Fdp6DlB_f2iCM1iEpvkGKm6PEPi7iBP2USSFitx5dTE,744
+avia_api/exceptions.py,sha256=aWGfdGyMEo0nIRiM6yc_ymdRrrEMRZzAu-tF0Lu8_oY,1940
+avia_api/models/__init__.py,sha256=mz8HCY5jj9hUVd4RjcCxSgpqKM5cWd28yqK76Pl4uAA,750
+avia_api/models/common.py,sha256=eBZeqgBlJySdTFgK88IkCCqjcekJNIahYh_2b7Al9M4,1119
+avia_api/models/directions.py,sha256=AXYzId8qB-2QGm1kEeCn__ibk2RpAzA_us4UwnMzj10,414
+avia_api/models/prices.py,sha256=oECbmUbT2J5QOyZcBTykGBRYdS_eC1jKnf7A0M_Vu1k,2339
+avia_api/models/reference.py,sha256=2C_VL-GIEFutEQ3qqLZjyKygWVTcVN46xhu040483-Q,1606
+avia_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+avia_api/resources/__init__.py,sha256=Csi6VoJMmVNmPfnK-aFVQcfLGi6eFgxkV8LlwYzNGKo,192
+avia_api/resources/_base.py,sha256=wo3g8FyISuSCvdCuzgZvF3zspo_sZOY4emMfbSB1g9Q,453
+avia_api/resources/directions.py,sha256=p_vufhkB7zmOQ-SAC92hL2vTGx8GBhobFnM1nXwq0SQ,1382
+avia_api/resources/prices.py,sha256=JnTewXaDOGDUkcGOkQrWFU6QtO5NCYknkeM7SY9H-W8,8416
+avia_api/resources/reference.py,sha256=uNVIO1uWckNpCCepgWgthC2ibX4iWcF3lDHkUslh1Qk,2172
+avia_api-0.1.0.dist-info/METADATA,sha256=PgV2VY1R3QqlOatL0qQkEpn3DmkFWDxWeeFMSyCHbP8,9797
+avia_api-0.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+avia_api-0.1.0.dist-info/licenses/LICENSE,sha256=tpswo9THJKwmCeqW6gtxT8nVMqSYvasT4D3ddYjgeOs,1069
+avia_api-0.1.0.dist-info/RECORD,,

avia_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

avia_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Sladkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.