tarifftrust 0.1.0__py3-none-any.whl

tarifftrust/__init__.py

@@ -0,0 +1,39 @@
+"""Official Python client for the TariffTrust API: every US import duty and fee for an HTS code,
+an origin and a value, each with its official source. https://tarifftrust.com/api/"""
+
+from ._client import AsyncTariffTrust, TariffTrust
+from ._errors import (
+    AccessRequiredError,
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    InvalidInputError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServiceUnavailableError,
+    TariffTrustError,
+)
+from ._version import __version__
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AccessRequiredError",
+    "AsyncTariffTrust",
+    "AuthenticationError",
+    "ConflictError",
+    "InvalidInputError",
+    "NotFoundError",
+    "PayloadTooLargeError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "TariffTrust",
+    "TariffTrustError",
+    "__version__",
+]

tarifftrust/_client.py

@@ -0,0 +1,326 @@
+"""The clients: the key, the retries, the idempotency key and the errors around each operation."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import platform
+import random
+import time
+import uuid
+from collections.abc import Mapping
+from datetime import date
+from decimal import Decimal
+from types import TracebackType
+from typing import Any, TypeVar
+
+import httpx
+
+from ._errors import (
+    BY_STATUS,
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    TariffTrustError,
+)
+from ._model import Model
+from ._operations import AsyncOperations, Operations
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.tarifftrust.com"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_MAX_RETRY_WAIT = 60.0
+# What a gateway answers when the service behind it is away, without the API's error.
+GATEWAY_STATUSES = {429, 502, 503, 504}
+USER_AGENT = f"tarifftrust-python/{__version__} python/{platform.python_version()}"
+_M = TypeVar("_M", bound=Model)
+
+
+def _encode(value: Any) -> str:
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, date):
+        return value.isoformat()
+    raise TypeError(f"{type(value).__name__} cannot be sent to the API")
+
+
+def _sent(fields: Mapping[str, Any] | None) -> dict[str, Any]:
+    """The arguments given: one left at None is not sent, and the API takes its default."""
+    return {name: value for name, value in (fields or {}).items() if value is not None}
+
+
+def _retry_after(response: httpx.Response) -> int | None:
+    value = response.headers.get("Retry-After", "")
+    return int(value) if value.isdigit() else None
+
+
+def _error(response: httpx.Response) -> APIError:
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    error = body.get("error") if isinstance(body, dict) else None
+    # The admin-style error of a proxy may be a plain string: only an object is the API's.
+    error = error if isinstance(error, dict) else {}
+    kind = BY_STATUS.get(response.status_code, APIError)
+    return kind(
+        error.get("message") or f"HTTP {response.status_code}",
+        status=response.status_code,
+        code=error.get("code"),
+        fields=error.get("fields"),
+        request_id=(body.get("request_id") if isinstance(body, dict) else None)
+        or response.headers.get("X-Request-ID"),
+        retry_after=_retry_after(response),
+        body=body,
+    )
+
+
+def _backoff(attempt: int) -> float:
+    return min(0.5 * float(2**attempt), 8.0) * random.uniform(0.5, 1.0)
+
+
+def _wait_before_retry(error: APIError, attempt: int, longest: float) -> float | None:
+    """How long to wait before trying again, None when trying again cannot help. The API says so
+    by its Retry-After: a refusal without one stays refused, and one too long is the caller's."""
+    if error.retry_after is not None:
+        return float(error.retry_after) if error.retry_after <= longest else None
+    if error.code is None and error.status in GATEWAY_STATUSES:
+        return _backoff(attempt)
+    return None
+
+
+def _answer(response: httpx.Response, model: type[_M]) -> _M:
+    try:
+        return model(response.json())
+    except ValueError as exc:
+        status = response.status_code
+        raise TariffTrustError(f"The API's answer is not JSON (HTTP {status})") from exc
+
+
+def _unreachable(exc: httpx.RequestError) -> APIConnectionError:
+    if isinstance(exc, httpx.TimeoutException):
+        return APITimeoutError(f"The API did not answer in time: {exc}")
+    return APIConnectionError(f"The API could not be reached: {exc}")
+
+
+class _Settings:
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str | None,
+        timeout: float,
+        max_retries: int,
+        max_retry_wait: float,
+    ) -> None:
+        # A stray newline would be refused as a header, with the key in the message.
+        self.api_key = (api_key or os.environ.get("TARIFFTRUST_API_KEY") or "").strip() or None
+        self.timeout = timeout
+        found = base_url or os.environ.get("TARIFFTRUST_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = found.rstrip("/")
+        self.max_retries = max_retries
+        self.max_retry_wait = max_retry_wait
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None,
+        body: Mapping[str, Any] | None,
+        auth: bool,
+        idempotent: bool,
+        idempotency_key: str | None,
+    ) -> dict[str, Any]:
+        """What each attempt of a call sends: the idempotency key is the call's, so that a retry
+        counts once."""
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+        if auth:
+            if not self.api_key:
+                raise AuthenticationError(
+                    "No API key: pass api_key or set TARIFFTRUST_API_KEY", status=401
+                )
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if idempotent:
+            if idempotency_key and not idempotency_key.isascii():
+                raise ValueError("An idempotency key is a header: use only ASCII characters")
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        request: dict[str, Any] = {
+            "method": method,
+            "url": self.base_url + path,
+            "headers": headers,
+            "params": _sent(query),
+            "timeout": self.timeout,
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            request["content"] = json.dumps(_sent(body), default=_encode)
+        return request
+
+    def wait_after_failure(self, failure: httpx.RequestError, attempt: int) -> float:
+        """The seconds before trying again after a failure to reach the API, or what it raises."""
+        if attempt >= self.max_retries:
+            raise _unreachable(failure) from failure
+        return _backoff(attempt)
+
+    def wait_after_refusal(self, response: httpx.Response, attempt: int) -> float:
+        """The seconds before trying again after a refusal, or the error the call ends with."""
+        error = _error(response)
+        wait = _wait_before_retry(error, attempt, self.max_retry_wait)
+        if wait is None or attempt >= self.max_retries:
+            raise error
+        return wait
+
+
+class TariffTrust(Operations):
+    """The TariffTrust API. Each operation of the API is a method under its operationId.
+
+    Args:
+        api_key: The key, or TARIFFTRUST_API_KEY. Keep it on your server. Only ``get_status``
+            works without one.
+        base_url: The API's address, or TARIFFTRUST_BASE_URL; the production's otherwise.
+        timeout: The seconds to wait at each step of an attempt: connecting, sending, each read.
+            It applies to your own ``http_client`` too.
+        max_retries: How many times a call is tried again: after a connection failure, a timeout
+            or a gateway error, or when the API gives a Retry-After. An idempotency key makes these
+            retries count once.
+        max_retry_wait: The longest Retry-After waited for, in seconds; a longer one is raised.
+        http_client: Your own ``httpx.Client`` (a proxy, your certificates): yours to close.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_retry_wait: float = DEFAULT_MAX_RETRY_WAIT,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._settings = _Settings(api_key, base_url, timeout, max_retries, max_retry_wait)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        model: type[_M],
+        query: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        auth: bool = True,
+        idempotent: bool = False,
+        idempotency_key: str | None = None,
+    ) -> _M:
+        settings = self._settings
+        request = settings.request(
+            method,
+            path,
+            query=query,
+            body=body,
+            auth=auth,
+            idempotent=idempotent,
+            idempotency_key=idempotency_key,
+        )
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(**request)
+            except httpx.RequestError as exc:
+                wait = settings.wait_after_failure(exc, attempt)
+            else:
+                if response.is_success:
+                    return _answer(response, model)
+                wait = settings.wait_after_refusal(response, attempt)
+            time.sleep(wait)
+            attempt += 1
+
+    def close(self) -> None:
+        """Close the connections; your own ``http_client`` stays open."""
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> TariffTrust:
+        return self
+
+    def __exit__(
+        self,
+        kind: type[BaseException] | None,
+        value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncTariffTrust(AsyncOperations):
+    """The TariffTrust API for ``asyncio``: the methods and arguments of ``TariffTrust``, awaited.
+    ``http_client`` is your own ``httpx.AsyncClient``: yours to close."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_retry_wait: float = DEFAULT_MAX_RETRY_WAIT,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._settings = _Settings(api_key, base_url, timeout, max_retries, max_retry_wait)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        model: type[_M],
+        query: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        auth: bool = True,
+        idempotent: bool = False,
+        idempotency_key: str | None = None,
+    ) -> _M:
+        settings = self._settings
+        request = settings.request(
+            method,
+            path,
+            query=query,
+            body=body,
+            auth=auth,
+            idempotent=idempotent,
+            idempotency_key=idempotency_key,
+        )
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(**request)
+            except httpx.RequestError as exc:
+                wait = settings.wait_after_failure(exc, attempt)
+            else:
+                if response.is_success:
+                    return _answer(response, model)
+                wait = settings.wait_after_refusal(response, attempt)
+            await asyncio.sleep(wait)
+            attempt += 1
+
+    async def close(self) -> None:
+        """Close the connections; your own ``http_client`` stays open."""
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncTariffTrust:
+        return self
+
+    async def __aexit__(
+        self,
+        kind: type[BaseException] | None,
+        value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.close()

tarifftrust/_errors.py

@@ -0,0 +1,105 @@
+"""What a call may raise: the API's refusals by their status, and the failures to reach it."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class TariffTrustError(Exception):
+    """What a call raises when the API refuses it or cannot be reached. An argument that cannot
+    be sent at all is a ``TypeError`` or a ``ValueError``, before any request."""
+
+
+class APIConnectionError(TariffTrustError):
+    """The API could not be reached, after the retries."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The API did not answer in time, after the retries."""
+
+
+class APIError(TariffTrustError):
+    """The API refused the request. ``code`` is for a program, ``message`` for a person,
+    ``fields`` names what invalid_input refused, ``request_id`` is what to quote to support, and
+    ``retry_after`` the seconds to wait when trying again helps, None otherwise."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str | None = None,
+        fields: list[str] | None = None,
+        request_id: str | None = None,
+        retry_after: int | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.fields = fields or []
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.body = body
+
+    def __str__(self) -> str:
+        details = [f"HTTP {self.status}"]
+        if self.fields:
+            details.append("fields: " + ", ".join(self.fields))
+        if self.request_id:
+            details.append(f"request {self.request_id}")
+        prefix = f"{self.code}: " if self.code else ""
+        return f"{prefix}{self.message} ({'; '.join(details)})"
+
+
+class AuthenticationError(APIError):
+    """401: no valid API key."""
+
+
+class AccessRequiredError(APIError):
+    """402: no active subscription, or the quota is used up (code ``quota_exceeded``)."""
+
+
+class PermissionDeniedError(APIError):
+    """403: the key lacks the permission, or the plan the API."""
+
+
+class NotFoundError(APIError):
+    """404: nothing of that name."""
+
+
+class ConflictError(APIError):
+    """409: an idempotency key sent again with another request."""
+
+
+class PayloadTooLargeError(APIError):
+    """413: the body is larger than the API takes: send fewer products or lines."""
+
+
+class InvalidInputError(APIError):
+    """422: ``fields`` names each field refused; 400: the body is not valid JSON."""
+
+
+class RateLimitError(APIError):
+    """429: too many requests."""
+
+
+class ServiceUnavailableError(APIError):
+    """502, 503 or 504: unavailable for now."""
+
+
+BY_STATUS: dict[int, type[APIError]] = {
+    400: InvalidInputError,
+    401: AuthenticationError,
+    402: AccessRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: PayloadTooLargeError,
+    422: InvalidInputError,
+    429: RateLimitError,
+    502: ServiceUnavailableError,
+    503: ServiceUnavailableError,
+    504: ServiceUnavailableError,
+}

tarifftrust/_model.py

@@ -0,0 +1,89 @@
+"""An object of an answer: its fields as attributes, built from the JSON when first read."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, ClassVar
+
+
+class Model:
+    """An object of the API. A field the answer leaves out reads as its default in the contract,
+    or None; a field newer than this package reads as an attribute too; ``to_dict()`` gives the
+    object as the API sent it."""
+
+    _registry: ClassVar[dict[str, type[Model]]] = {}
+    _fields: ClassVar[frozenset[str]] = frozenset()
+    _required: ClassVar[frozenset[str]] = frozenset()
+    _nested: ClassVar[dict[str, Any]] = {}
+    _defaults: ClassVar[dict[str, Any]] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        Model._registry[cls.__name__] = cls
+
+    def __init__(self, data: Mapping[str, Any]) -> None:
+        self._data = data
+        self._read: dict[str, Any] = {}
+
+    def __getattr__(self, name: str) -> Any:
+        # Only for what is not found otherwise; a private name is never a field.
+        if name.startswith("_"):
+            raise AttributeError(name)
+        field = name.removesuffix("_")
+        if field in self._read:
+            return self._read[field]
+        if field in self._data:
+            value = _build(self._nested.get(field), self._data[field])
+        elif field in self._fields:
+            value = _copy(self._defaults.get(field))
+        else:
+            raise AttributeError(f"{type(self).__name__} has no field {name!r}")
+        self._read[field] = value
+        return value
+
+    def __dir__(self) -> list[str]:
+        return sorted({*object.__dir__(self), *self._fields, *self._data})
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, type(self))
+            and type(other) is type(self)
+            and other._data == self._data
+        )
+
+    __hash__ = None  # type: ignore[assignment]
+
+    def __repr__(self) -> str:
+        scalars = [
+            f"{field}={value!r}"
+            for field, value in self._data.items()
+            if not isinstance(value, (dict, list))
+        ]
+        return f"{type(self).__name__}({', '.join(scalars[:6])}{', ...' if scalars[6:] else ''})"
+
+    def to_dict(self) -> dict[str, Any]:
+        """The object as the API sent it, as plain JSON values."""
+        return dict(self._data)
+
+
+def _copy(value: Any) -> Any:
+    return list(value) if isinstance(value, list) else value
+
+
+def _build(spec: Any, value: Any) -> Any:
+    """A JSON value as the objects ``spec`` names: a name, [of a list], {"*": of a map}, (union)."""
+    if spec is None or value is None:
+        return value
+    if isinstance(spec, str):
+        return Model._registry[spec](value) if isinstance(value, Mapping) else value
+    if isinstance(spec, list):
+        return [_build(spec[0], item) for item in value] if isinstance(value, list) else value
+    if isinstance(spec, dict):
+        if not isinstance(value, Mapping):
+            return value
+        return {key: _build(spec["*"], item) for key, item in value.items()}
+    if isinstance(value, Mapping):
+        for name in spec:
+            if Model._registry[name]._required <= value.keys():
+                return Model._registry[name](value)
+    return value