avia-api 0.1.0__tar.gz

avia_api-0.1.0/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.

avia_api-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,138 @@
+# 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/pyproject.toml

@@ -0,0 +1,101 @@
+[project]
+name = "avia-api"
+version = "0.1.0"
+description = "Async Python client for the Travelpayouts / Aviasales Data API"
+authors = [
+    {name = "Ivan Sladkov",email = "ivan.sladkov@yandex.ru"}
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = [
+    "travelpayouts",
+    "aviasales",
+    "flights",
+    "airline-tickets",
+    "prices",
+    "api-client",
+    "async",
+    "httpx",
+    "pydantic",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+    "Framework :: AsyncIO",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx (>=0.28.1,<0.29.0)",
+    "pyrate-limiter (>=4.5.0,<5.0.0)",
+    "tenacity (>=9.1.4,<10.0.0)",
+    "pydantic (>=2.13.5,<3.0.0)",
+    "hishel[httpx] (>=1.3.1,<2.0.0)"
+]
+
+[project.urls]
+Homepage = "https://github.com/sliv2001/avia-api"
+Repository = "https://github.com/sliv2001/avia-api"
+Issues = "https://github.com/sliv2001/avia-api/issues"
+Changelog = "https://github.com/sliv2001/avia-api/blob/master/CHANGELOG.md"
+
+[tool.poetry]
+packages = [{include = "avia_api", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.1.1,<10.0.0)",
+    "pytest-asyncio (>=1.4.0,<2.0.0)",
+    "respx (>=0.23.1,<0.24.0)",
+    "pytest-cov (>=7.1.0,<8.0.0)",
+    "ruff (>=0.14.0,<0.15.0)",
+    "mypy (>=1.19.0,<2.0.0)"
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["src/avia_api"]
+
+[tool.coverage.report]
+fail_under = 99
+exclude_also = [
+    "if t\\.TYPE_CHECKING:",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/avia_api"]
+
+[[tool.mypy.overrides]]
+module = "hishel.*"
+ignore_missing_imports = true

avia_api-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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}