eltoque-python 0.1.0__py3-none-any.whl

eltoque/__init__.py

@@ -0,0 +1,44 @@
+"""Unofficial, typed Python client for the official elTOQUE exchange-rate API.
+
+Exchange rates are indicative, not official. Source: elTOQUE.
+Access requires registration and an application-specific API token.
+"""
+
+from eltoque._async_client import AsyncElToqueClient
+from eltoque._client import ElToqueClient
+from eltoque._version import __version__
+from eltoque.exceptions import (
+    ElToqueAPIError,
+    ElToqueAuthenticationError,
+    ElToqueBadRequestError,
+    ElToqueConfigurationError,
+    ElToqueDecodeError,
+    ElToqueError,
+    ElToqueNetworkError,
+    ElToqueRateLimitError,
+    ElToqueServerError,
+    ElToqueTimeoutError,
+    ElToqueUnprocessableError,
+    ElToqueValidationError,
+)
+from eltoque.models import RateLimitInfo, RatesResponse
+
+__all__ = [
+    "AsyncElToqueClient",
+    "ElToqueAPIError",
+    "ElToqueAuthenticationError",
+    "ElToqueBadRequestError",
+    "ElToqueClient",
+    "ElToqueConfigurationError",
+    "ElToqueDecodeError",
+    "ElToqueError",
+    "ElToqueNetworkError",
+    "ElToqueRateLimitError",
+    "ElToqueServerError",
+    "ElToqueTimeoutError",
+    "ElToqueUnprocessableError",
+    "ElToqueValidationError",
+    "RateLimitInfo",
+    "RatesResponse",
+    "__version__",
+]

eltoque/_async_client.py

@@ -0,0 +1,131 @@
+"""Asynchronous client. Mirrors :class:`eltoque.ElToqueClient`."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Self
+
+import httpx
+
+from eltoque._config import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, ClientConfig
+from eltoque._dates import day_range, validate_range
+from eltoque._retry import RetryPolicy
+from eltoque._transport import (
+    FOLLOW_REDIRECTS,
+    aread_limited,
+    build_request_parts,
+    parse_response,
+    translate_exception,
+)
+from eltoque.exceptions import ElToqueConfigurationError, ElToqueError
+
+if TYPE_CHECKING:
+    from datetime import date, datetime
+    from types import TracebackType
+
+    from eltoque.models import RatesResponse
+
+
+class AsyncElToqueClient:
+    """Async client for the elTOQUE ``GET /v1/trmi`` endpoint.
+
+    Exchange rates are indicative, not official. Source: elTOQUE. Every request is made
+    explicitly by the caller; nothing polls in the background.
+    """
+
+    def __init__(
+        self,
+        api_token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = 0,
+        transport: httpx.AsyncBaseTransport | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """Create a client.
+
+        ``max_retries`` (default 0, max 5) opts in to bounded retries for 429, 502/503/504 and
+        transport failures; every retry consumes API quota. ``Retry-After`` is honored and
+        waits use ``asyncio.sleep`` so cancellation propagates immediately.
+
+        ``transport`` is a test seam (e.g. ``httpx.MockTransport``). ``http_client`` lets you
+        share your own ``httpx.AsyncClient``: it is never closed by this SDK, its own timeout
+        applies (``timeout`` is ignored) and redirects are still not followed for our requests.
+        """
+        self._config = ClientConfig(
+            api_token=api_token, base_url=base_url, timeout=timeout, max_retries=max_retries
+        )
+        if http_client is not None and transport is not None:
+            raise ElToqueConfigurationError("pass either http_client or transport, not both")
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(
+            timeout=self._config.timeout, follow_redirects=FOLLOW_REDIRECTS, transport=transport
+        )
+        self._closed = False
+
+    async def __aenter__(self) -> Self:
+        self._ensure_open()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return f"AsyncElToqueClient(base_url={self._config.base_url!r})"
+
+    async def get_latest_rates(self) -> RatesResponse:
+        """Rates for the rolling last 24 hours, computed by the provider at request time."""
+        return await self._get(None)
+
+    async def get_rates(self, date_from: datetime, date_to: datetime) -> RatesResponse:
+        """Rates for an explicit window shorter than 24 hours (naive datetimes only)."""
+        return await self._get(validate_range(date_from, date_to))
+
+    async def get_rates_for_day(self, day: date) -> RatesResponse:
+        """Convenience for ``get_rates(day 00:00:00, day 23:59:59)``; one request, no loops."""
+        return await self.get_rates(*day_range(day))
+
+    async def aclose(self) -> None:
+        """Release the connection pool (only if this client created it). Idempotent."""
+        if not self._closed:
+            self._closed = True
+            if self._owns_http:
+                await self._http.aclose()
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ElToqueError("this client is closed; create a new AsyncElToqueClient")
+
+    async def _get(self, date_range: tuple[str, str] | None) -> RatesResponse:
+        self._ensure_open()
+        policy = RetryPolicy.from_config(self._config)
+        while True:
+            try:
+                return await self._get_once(date_range)
+            except ElToqueError as error:
+                delay = policy.next_delay(error)
+                if delay is None:
+                    raise
+                await asyncio.sleep(delay)
+
+    async def _get_once(self, date_range: tuple[str, str] | None) -> RatesResponse:
+        url, params, headers = build_request_parts(self._config, date_range)
+        request = self._http.build_request("GET", url, params=params or None, headers=headers)
+        try:
+            response = await self._http.send(
+                request, stream=True, follow_redirects=FOLLOW_REDIRECTS
+            )
+            try:
+                ok = 200 <= response.status_code < 300
+                body = await aread_limited(response, self._config.max_response_bytes, strict=ok)
+            finally:
+                await response.aclose()
+        except httpx.HTTPError as error:
+            raise translate_exception(error) from None
+        return parse_response(self._config, response.status_code, response.headers, body)

eltoque/_client.py

@@ -0,0 +1,136 @@
+"""Synchronous client."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Self
+
+import httpx
+
+from eltoque._config import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, ClientConfig
+from eltoque._dates import day_range, validate_range
+from eltoque._retry import RetryPolicy
+from eltoque._transport import (
+    FOLLOW_REDIRECTS,
+    build_request_parts,
+    parse_response,
+    read_limited,
+    translate_exception,
+)
+from eltoque.exceptions import ElToqueConfigurationError, ElToqueError
+
+if TYPE_CHECKING:
+    from datetime import date, datetime
+    from types import TracebackType
+
+    from eltoque.models import RatesResponse
+
+
+class ElToqueClient:
+    """Client for the elTOQUE ``GET /v1/trmi`` endpoint.
+
+    Exchange rates are indicative, not official. Source: elTOQUE. Every request is made
+    explicitly by the caller; nothing polls in the background.
+    """
+
+    def __init__(
+        self,
+        api_token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = 0,
+        transport: httpx.BaseTransport | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        """Create a client.
+
+        ``max_retries`` (default 0, max 5) opts in to bounded retries for 429, 502/503/504 and
+        transport failures; every retry consumes API quota. ``Retry-After`` is honored.
+
+        ``transport`` is a test seam (e.g. ``httpx.MockTransport``). ``http_client`` lets you
+        share your own ``httpx.Client``: it is never closed by this SDK, its own timeout
+        applies (``timeout`` is ignored) and redirects are still not followed for our requests.
+        """
+        self._config = ClientConfig(
+            api_token=api_token, base_url=base_url, timeout=timeout, max_retries=max_retries
+        )
+        if http_client is not None and transport is not None:
+            raise ElToqueConfigurationError("pass either http_client or transport, not both")
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(
+            timeout=self._config.timeout, follow_redirects=FOLLOW_REDIRECTS, transport=transport
+        )
+        self._closed = False
+
+    def __enter__(self) -> Self:
+        self._ensure_open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"ElToqueClient(base_url={self._config.base_url!r})"
+
+    def get_latest_rates(self) -> RatesResponse:
+        """Rates for the rolling last 24 hours, computed by the provider at request time."""
+        return self._get(None)
+
+    def get_rates(self, date_from: datetime, date_to: datetime) -> RatesResponse:
+        """Rates for an explicit window shorter than 24 hours.
+
+        Both bounds must be naive datetimes, sent as ``YYYY-MM-DD HH:MM:SS``. The provider's
+        time zone is undocumented, so no conversion is applied.
+        """
+        return self._get(validate_range(date_from, date_to))
+
+    def get_rates_for_day(self, day: date) -> RatesResponse:
+        """Convenience for ``get_rates(day 00:00:00, day 23:59:59)``.
+
+        The provider time zone is undocumented, so this is not a guaranteed complete local
+        calendar day. One call makes exactly one request; no multi-day assembly is offered.
+        """
+        return self.get_rates(*day_range(day))
+
+    def close(self) -> None:
+        """Release the connection pool (only if this client created it). Idempotent."""
+        if not self._closed:
+            self._closed = True
+            if self._owns_http:
+                self._http.close()
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ElToqueError("this client is closed; create a new ElToqueClient")
+
+    def _get(self, date_range: tuple[str, str] | None) -> RatesResponse:
+        self._ensure_open()
+        policy = RetryPolicy.from_config(self._config)
+        while True:
+            try:
+                return self._get_once(date_range)
+            except ElToqueError as error:
+                delay = policy.next_delay(error)
+                if delay is None:
+                    raise
+                time.sleep(delay)
+
+    def _get_once(self, date_range: tuple[str, str] | None) -> RatesResponse:
+        url, params, headers = build_request_parts(self._config, date_range)
+        request = self._http.build_request("GET", url, params=params or None, headers=headers)
+        try:
+            response = self._http.send(request, stream=True, follow_redirects=FOLLOW_REDIRECTS)
+            try:
+                ok = 200 <= response.status_code < 300
+                body = read_limited(response, self._config.max_response_bytes, strict=ok)
+            finally:
+                response.close()
+        except httpx.HTTPError as error:
+            raise translate_exception(error) from None
+        return parse_response(self._config, response.status_code, response.headers, body)

eltoque/_config.py

@@ -0,0 +1,106 @@
+"""Validated, immutable client configuration (internal)."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from urllib.parse import urlsplit
+
+import httpx
+
+from eltoque.exceptions import ElToqueConfigurationError
+
+DEFAULT_BASE_URL = "https://tasas.eltoque.com"
+LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+DEFAULT_TIMEOUT = httpx.Timeout(10.0, connect=5.0)
+MAX_RETRIES_LIMIT = 5
+DEFAULT_MAX_RETRY_DELAY = 30.0
+DEFAULT_MAX_TOTAL_RETRY_DELAY = 60.0
+DEFAULT_MAX_RESPONSE_BYTES = 5 * 1024 * 1024
+
+
+def _validate_token(token: object) -> str:
+    if not isinstance(token, str) or not token:
+        raise ElToqueConfigurationError("api_token must be a non-empty string")
+    # Printable ASCII without whitespace: blocks header injection and "Bearer " prefixes.
+    if not all("!" <= char <= "~" for char in token):
+        raise ElToqueConfigurationError(
+            "api_token contains whitespace, control or non-ASCII characters; "
+            "pass the bare token without a 'Bearer ' prefix"
+        )
+    return token
+
+
+def _validate_base_url(base_url: object) -> str:
+    if not isinstance(base_url, str) or not base_url:
+        raise ElToqueConfigurationError("base_url must be a non-empty string")
+    try:
+        parts = urlsplit(base_url)
+        host = parts.hostname
+        parts.port  # noqa: B018  (raises ValueError on an invalid port)
+    except ValueError as error:
+        raise ElToqueConfigurationError("base_url is not a valid URL") from error
+    if not host:
+        raise ElToqueConfigurationError("base_url must include a host")
+    if parts.username is not None or parts.password is not None:
+        raise ElToqueConfigurationError("base_url must not contain credentials")
+    if parts.query or parts.fragment:
+        raise ElToqueConfigurationError("base_url must not contain a query or fragment")
+    if parts.scheme == "http":
+        if host not in LOOPBACK_HOSTS:
+            raise ElToqueConfigurationError(
+                "plain http is only allowed for loopback hosts (local tests); use https"
+            )
+    elif parts.scheme != "https":
+        raise ElToqueConfigurationError("base_url must use https")
+    return base_url.rstrip("/")
+
+
+def _validate_timeout(timeout: object) -> httpx.Timeout:
+    if isinstance(timeout, httpx.Timeout):
+        return timeout
+    if isinstance(timeout, bool) or not isinstance(timeout, int | float):
+        raise ElToqueConfigurationError("timeout must be a positive number or httpx.Timeout")
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ElToqueConfigurationError("timeout must be a positive, finite number of seconds")
+    return httpx.Timeout(float(timeout))
+
+
+def _validate_non_negative(name: str, value: object, *, integer: bool = False) -> None:
+    kinds = int if integer else (int, float)
+    if isinstance(value, bool) or not isinstance(value, kinds):
+        raise ElToqueConfigurationError(f"{name} must be a number")
+    if not math.isfinite(value) or value < 0:
+        raise ElToqueConfigurationError(f"{name} must be a finite number >= 0")
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class ClientConfig:
+    """Settings shared by the sync and async clients. The token is never shown in ``repr``."""
+
+    api_token: str
+    base_url: str = DEFAULT_BASE_URL
+    timeout: httpx.Timeout | float = field(default_factory=lambda: DEFAULT_TIMEOUT)
+    max_retries: int = 0
+    max_retry_delay: float = DEFAULT_MAX_RETRY_DELAY
+    max_total_retry_delay: float = DEFAULT_MAX_TOTAL_RETRY_DELAY
+    max_response_bytes: int = DEFAULT_MAX_RESPONSE_BYTES
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "api_token", _validate_token(self.api_token))
+        object.__setattr__(self, "base_url", _validate_base_url(self.base_url))
+        object.__setattr__(self, "timeout", _validate_timeout(self.timeout))
+        _validate_non_negative("max_retries", self.max_retries, integer=True)
+        if self.max_retries > MAX_RETRIES_LIMIT:
+            raise ElToqueConfigurationError(f"max_retries must be <= {MAX_RETRIES_LIMIT}")
+        _validate_non_negative("max_retry_delay", self.max_retry_delay)
+        _validate_non_negative("max_total_retry_delay", self.max_total_retry_delay)
+        _validate_non_negative("max_response_bytes", self.max_response_bytes, integer=True)
+        if self.max_response_bytes == 0:
+            raise ElToqueConfigurationError("max_response_bytes must be > 0")
+
+    def __repr__(self) -> str:
+        return (
+            f"ClientConfig(api_token='***', base_url={self.base_url!r}, timeout={self.timeout!r}, "
+            f"max_retries={self.max_retries})"
+        )

eltoque/_dates.py

@@ -0,0 +1,53 @@
+"""Date-range validation and formatting (internal).
+
+The upstream time zone is **not documented**, so values are never converted: only naive
+``datetime`` objects are accepted and are sent exactly as written, truncated to whole seconds.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta
+
+from eltoque.exceptions import ElToqueValidationError
+
+DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+MAX_WINDOW = timedelta(hours=24)
+
+
+def _check_naive(name: str, value: object) -> datetime:
+    if not isinstance(value, datetime):
+        raise ElToqueValidationError(f"{name} must be a datetime.datetime")
+    if value.tzinfo is not None and value.utcoffset() is not None:
+        raise ElToqueValidationError(
+            f"{name} must be a naive datetime: the elTOQUE time zone is not documented, "
+            "so no conversion is attempted. Drop tzinfo after normalizing it yourself."
+        )
+    return value.replace(microsecond=0, tzinfo=None)
+
+
+def validate_range(date_from: datetime, date_to: datetime) -> tuple[str, str]:
+    """Validate an explicit window and return the ``(date_from, date_to)`` query strings.
+
+    Rules: both bounds naive, ``date_from < date_to`` and a window shorter than 24 hours
+    (checked after truncating to whole seconds, i.e. on exactly what is sent).
+    """
+    start = _check_naive("date_from", date_from)
+    end = _check_naive("date_to", date_to)
+    if start >= end:
+        raise ElToqueValidationError("date_from must be earlier than date_to")
+    if end - start >= MAX_WINDOW:
+        raise ElToqueValidationError(
+            "the interval must be shorter than 24 hours (the API answers HTTP 400 otherwise)"
+        )
+    return start.strftime(DATE_FORMAT), end.strftime(DATE_FORMAT)
+
+
+def day_range(day: date) -> tuple[datetime, datetime]:
+    """Return ``00:00:00`` and ``23:59:59`` of ``day`` as naive datetimes.
+
+    The provider's time zone is undocumented, so this is *not* a guaranteed complete
+    local calendar day; it is simply the widest whole-second window allowed in one date.
+    """
+    if isinstance(day, datetime) or not isinstance(day, date):
+        raise ElToqueValidationError("day must be a datetime.date (not a datetime)")
+    return datetime.combine(day, time(0, 0, 0)), datetime.combine(day, time(23, 59, 59))

eltoque/_retry.py

@@ -0,0 +1,59 @@
+"""Pure retry policy shared by the sync and async clients (internal). It never sleeps."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from eltoque.exceptions import (
+    ElToqueAPIError,
+    ElToqueNetworkError,
+    ElToqueRateLimitError,
+    ElToqueTimeoutError,
+)
+
+if TYPE_CHECKING:
+    from eltoque._config import ClientConfig
+    from eltoque.exceptions import ElToqueError
+
+TRANSIENT_STATUSES = frozenset({502, 503, 504})
+BACKOFF_BASE = 0.5
+
+
+@dataclass(slots=True)
+class RetryPolicy:
+    """Decides whether and how long to wait before the next attempt.
+
+    Retries are opt-in (``max_retries=0`` by default) and consume API quota. A request is
+    retried only for 429, transient gateway statuses (502/503/504) and transport failures.
+    400/401/422 are never retried. If the server asks for a wait longer than
+    ``max_retry_delay`` (or the total budget), the error is raised instead.
+    """
+
+    max_retries: int
+    max_delay: float
+    max_total_delay: float
+    retries_done: int = 0
+    total_delay: float = 0.0
+
+    @classmethod
+    def from_config(cls, config: ClientConfig) -> RetryPolicy:
+        return cls(config.max_retries, config.max_retry_delay, config.max_total_retry_delay)
+
+    @staticmethod
+    def is_retryable(error: ElToqueError) -> bool:
+        if isinstance(error, ElToqueRateLimitError | ElToqueNetworkError | ElToqueTimeoutError):
+            return True
+        return isinstance(error, ElToqueAPIError) and error.status_code in TRANSIENT_STATUSES
+
+    def next_delay(self, error: ElToqueError) -> float | None:
+        """Return seconds to wait before retrying, or ``None`` to give up and raise."""
+        if self.retries_done >= self.max_retries or not self.is_retryable(error):
+            return None
+        retry_after = error.retry_after if isinstance(error, ElToqueAPIError) else None
+        delay = retry_after if retry_after is not None else BACKOFF_BASE * 2**self.retries_done
+        if delay > self.max_delay or self.total_delay + delay > self.max_total_delay:
+            return None
+        self.retries_done += 1
+        self.total_delay += delay
+        return delay

eltoque/_transport.py

@@ -0,0 +1,165 @@
+"""Sync/async-neutral request building and response handling (internal)."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from eltoque._version import __version__
+from eltoque.exceptions import (
+    ElToqueAPIError,
+    ElToqueAuthenticationError,
+    ElToqueBadRequestError,
+    ElToqueDecodeError,
+    ElToqueError,
+    ElToqueNetworkError,
+    ElToqueRateLimitError,
+    ElToqueServerError,
+    ElToqueTimeoutError,
+    ElToqueUnprocessableError,
+)
+from eltoque.models import RateLimitInfo, RatesResponse
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from eltoque._config import ClientConfig
+
+TRMI_PATH = "/v1/trmi"
+USER_AGENT = f"eltoque-python/{__version__}"
+EXCERPT_LIMIT = 200
+# Never follow redirects: a cross-host 3xx would forward the bearer token.
+FOLLOW_REDIRECTS = False
+
+_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]+")
+_ERROR_TYPES: dict[int, tuple[type[ElToqueAPIError], str]] = {
+    400: (ElToqueBadRequestError, "bad request (the interval must be shorter than 24 hours)"),
+    401: (ElToqueAuthenticationError, "unauthorized (the token is wrong or expired)"),
+    422: (ElToqueUnprocessableError, "unprocessable entity (check the token)"),
+    429: (ElToqueRateLimitError, "rate limit exceeded"),
+}
+
+
+def build_request_parts(
+    config: ClientConfig, date_range: tuple[str, str] | None = None
+) -> tuple[str, dict[str, str], dict[str, str]]:
+    """Return ``(url, query_params, headers)`` for ``GET /v1/trmi``.
+
+    Without a date range no query parameters are sent (rolling last 24 hours).
+    """
+    params: dict[str, str] = {}
+    if date_range is not None:
+        params = {"date_from": date_range[0], "date_to": date_range[1]}
+    headers = {
+        "Authorization": f"Bearer {config.api_token}",
+        "Accept": "application/json",
+        "User-Agent": USER_AGENT,
+    }
+    return f"{config.base_url}{TRMI_PATH}", params, headers
+
+
+def make_excerpt(body: bytes, token: str) -> str | None:
+    """Return a short, single-line, token-free excerpt of a response body for diagnostics."""
+    text = body[: EXCERPT_LIMIT * 4].decode("utf-8", errors="replace")
+    text = _CONTROL_CHARS.sub(" ", text).replace(token, "***").strip()
+    if not text:
+        return None
+    return text if len(text) <= EXCERPT_LIMIT else text[:EXCERPT_LIMIT] + "..."
+
+
+def error_for_response(
+    status_code: int, headers: Mapping[str, str], body: bytes, token: str
+) -> ElToqueAPIError | None:
+    """Map an HTTP response to an SDK exception, or ``None`` for a 2xx status."""
+    if 200 <= status_code < 300:
+        return None
+    error_type, reason = _ERROR_TYPES.get(status_code, (ElToqueAPIError, "unexpected status"))
+    if status_code >= 500:
+        error_type, reason = ElToqueServerError, "server error"
+    return error_type(
+        f"HTTP {status_code}: {reason}",
+        status_code=status_code,
+        body_excerpt=make_excerpt(body, token),
+        rate_limit=RateLimitInfo.from_headers(headers),
+    )
+
+
+def _too_large(limit: int) -> ElToqueDecodeError:
+    return ElToqueDecodeError(f"response body exceeds the {limit}-byte limit")
+
+
+def check_declared_length(headers: Mapping[str, str], limit: int, *, strict: bool) -> None:
+    """Reject early when ``Content-Length`` already exceeds ``limit`` (strict mode only)."""
+    declared = headers.get("content-length", "")
+    if strict and declared.isascii() and declared.isdigit() and int(declared) > limit:
+        raise _too_large(limit)
+
+
+def read_limited(response: httpx.Response, limit: int, *, strict: bool = True) -> bytes:
+    """Read a streamed body. Over ``limit``: raise (strict) or truncate (non-strict)."""
+    check_declared_length(response.headers, limit, strict=strict)
+    chunks: list[bytes] = []
+    size = 0
+    for chunk in response.iter_bytes():
+        size += len(chunk)
+        if size > limit:
+            if strict:
+                raise _too_large(limit)
+            chunks.append(chunk[: len(chunk) - (size - limit)])
+            break
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+async def aread_limited(response: httpx.Response, limit: int, *, strict: bool = True) -> bytes:
+    """Async twin of :func:`read_limited`."""
+    check_declared_length(response.headers, limit, strict=strict)
+    chunks: list[bytes] = []
+    size = 0
+    async for chunk in response.aiter_bytes():
+        size += len(chunk)
+        if size > limit:
+            if strict:
+                raise _too_large(limit)
+            chunks.append(chunk[: len(chunk) - (size - limit)])
+            break
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def decode_json(body: bytes) -> Any:
+    """Decode a JSON body exactly as sent; never substitute ``{}`` for bad input."""
+    if not body.strip():
+        raise ElToqueDecodeError("the response body is empty; expected JSON")
+    try:
+        return json.loads(body)
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise ElToqueDecodeError("the response body is not valid JSON") from error
+
+
+def translate_exception(error: httpx.HTTPError) -> ElToqueError:
+    """Convert an httpx failure into an SDK exception without echoing URLs or headers.
+
+    Callers raise the result ``from None``: the original message is dropped on purpose, since a
+    custom transport could put arbitrary text (even credentials) in it. Only the type name stays.
+    """
+    if isinstance(error, httpx.TimeoutException):
+        return ElToqueTimeoutError(f"the request timed out ({type(error).__name__})")
+    return ElToqueNetworkError(f"the request failed ({type(error).__name__})")
+
+
+def parse_response(
+    config: ClientConfig, status_code: int, headers: Mapping[str, str], body: bytes
+) -> RatesResponse:
+    """Turn a fully read HTTP response into a :class:`RatesResponse` or raise an SDK error."""
+    error = error_for_response(status_code, headers, body, config.api_token)
+    if error is not None:
+        raise error
+    return RatesResponse(
+        data=decode_json(body),
+        status_code=status_code,
+        rate_limit=RateLimitInfo.from_headers(headers),
+    )

eltoque/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

eltoque/exceptions.py

@@ -0,0 +1,77 @@
+"""Public exception hierarchy.
+
+Messages never contain the API token. Response bodies are not included in messages;
+``body_excerpt`` holds a short, sanitized excerpt for diagnostics only.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from eltoque.models import RateLimitInfo
+
+
+class ElToqueError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class ElToqueConfigurationError(ElToqueError):
+    """Invalid client configuration (token, base URL, timeout, retries)."""
+
+
+class ElToqueValidationError(ElToqueError):
+    """Invalid call arguments, detected before any HTTP request is made."""
+
+
+class ElToqueNetworkError(ElToqueError):
+    """The request could not be completed (connection, DNS, TLS, protocol)."""
+
+
+class ElToqueTimeoutError(ElToqueError):
+    """The request timed out."""
+
+
+class ElToqueDecodeError(ElToqueError):
+    """A successful response did not contain valid JSON, or exceeded the size limit."""
+
+
+class ElToqueAPIError(ElToqueError):
+    """The API answered with an unexpected or error HTTP status."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        body_excerpt: str | None = None,
+        rate_limit: RateLimitInfo | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body_excerpt = body_excerpt
+        self.rate_limit = rate_limit
+        if retry_after is None and rate_limit is not None:
+            retry_after = rate_limit.retry_after
+        self.retry_after = retry_after
+
+
+class ElToqueBadRequestError(ElToqueAPIError):
+    """HTTP 400, e.g. a date range of 24 hours or more."""
+
+
+class ElToqueAuthenticationError(ElToqueAPIError):
+    """HTTP 401: the token is wrong or expired."""
+
+
+class ElToqueUnprocessableError(ElToqueAPIError):
+    """HTTP 422: unprocessable entity; check the token."""
+
+
+class ElToqueRateLimitError(ElToqueAPIError):
+    """HTTP 429: the API key exceeded its rate limit. See ``retry_after``."""
+
+
+class ElToqueServerError(ElToqueAPIError):
+    """HTTP 5xx."""

eltoque/models.py

@@ -0,0 +1,78 @@
+"""Response models owned by the SDK.
+
+Nothing in this module describes provider fields: the published OpenAPI document does not
+define the HTTP 200 body, so the payload is exposed exactly as decoded.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+def _parse_int(value: str | None) -> int | None:
+    if value is None:
+        return None
+    text = value.strip()
+    if not text.isascii() or not text.isdigit():
+        return None
+    return int(text)
+
+
+def _parse_seconds(value: str | None) -> float | None:
+    if value is None:
+        return None
+    try:
+        seconds = float(value.strip())
+    except ValueError:
+        return None
+    if not math.isfinite(seconds) or seconds < 0:
+        return None
+    return seconds
+
+
+@dataclass(frozen=True, slots=True)
+class RateLimitInfo:
+    """Rate-limit metadata parsed from response headers.
+
+    Every field is optional: missing or malformed headers yield ``None`` and never raise.
+    ``reset`` is kept as the raw integer sent by the provider; its unit is not documented.
+    """
+
+    limit: int | None = None
+    remaining: int | None = None
+    reset: int | None = None
+    retry_after: float | None = None
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str]) -> RateLimitInfo:
+        """Build an instance from response headers (names are matched case-insensitively)."""
+        lowered = {key.lower(): value for key, value in headers.items()}
+        return cls(
+            limit=_parse_int(lowered.get("x-ratelimit-limit")),
+            remaining=_parse_int(lowered.get("x-ratelimit-remaining")),
+            reset=_parse_int(lowered.get("x-ratelimit-reset")),
+            retry_after=_parse_seconds(lowered.get("retry-after")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RatesResponse:
+    """Envelope around a successful ``GET /v1/trmi`` response.
+
+    ``data`` is the decoded JSON body, untouched: the provider has not published a schema for
+    HTTP 200, so no field names are guaranteed. ``status_code``, ``rate_limit`` and
+    ``received_at`` are SDK metadata, not provider fields.
+
+    Exchange rates are indicative, not official. Source: elTOQUE.
+    """
+
+    data: Any
+    status_code: int = 200
+    rate_limit: RateLimitInfo = field(default_factory=RateLimitInfo)
+    received_at: datetime = field(default_factory=lambda: datetime.now(UTC))

eltoque_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,286 @@
+Metadata-Version: 2.5
+Name: eltoque-python
+Version: 0.1.0
+Summary: Unofficial, typed Python client for the official elTOQUE exchange-rate API.
+Project-URL: Homepage, https://github.com/Alejo2075/eltoque-python
+Project-URL: Source, https://github.com/Alejo2075/eltoque-python
+Project-URL: Issues, https://github.com/Alejo2075/eltoque-python/issues
+Project-URL: Changelog, https://github.com/Alejo2075/eltoque-python/blob/main/CHANGELOG.md
+Project-URL: elTOQUE API docs, https://tasas.eltoque.com/docs/
+Author: eltoque-python contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,async,cuba,eltoque,exchange-rate,httpx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Description-Content-Type: text/markdown
+
+# eltoque-python
+
+**Unofficial Python SDK for elTOQUE exchange-rate data.**
+A modern, typed client for the official elTOQUE exchange-rate API, with sync and async interfaces.
+
+[![PyPI](https://img.shields.io/pypi/v/eltoque-python)](https://pypi.org/project/eltoque-python/)
+[![Python](https://img.shields.io/pypi/pyversions/eltoque-python)](https://pypi.org/project/eltoque-python/)
+[![CI](https://github.com/Alejo2075/eltoque-python/actions/workflows/ci.yml/badge.svg)](https://github.com/Alejo2075/eltoque-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> **Independent project.** `eltoque-python` is community-maintained. It is not developed,
+> sponsored, endorsed or supported by elTOQUE.
+>
+> **Exchange rates are indicative, not official. Source: elTOQUE.
+> Access requires registration and an application-specific API token.**
+
+```python
+import os
+
+from eltoque import ElToqueClient
+
+with ElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"]) as client:
+    response = client.get_latest_rates()
+    print(response.data)  # the provider's JSON, untouched
+```
+
+Leer en español: [docs/quickstart.es.md](docs/quickstart.es.md)
+
+## Why use it?
+
+- **Sync and async** clients with the same methods and behavior.
+- **Typed** public API (`py.typed`, checked with `mypy --strict`).
+- **Safe by default:** HTTPS only, explicit timeouts, no redirects followed (your token is never
+  forwarded to another host), bounded response size, and the token never appears in `repr`,
+  error messages or logs.
+- **Predictable errors:** one exception family, one subclass per documented HTTP status.
+- **Rate-limit aware:** parses `X-RateLimit-*` and `Retry-After`; retries are opt-in and bounded.
+- **Pure Python**, one runtime dependency ([`httpx`](https://www.python-httpx.org/)), works in
+  plain scripts, notebooks, Django, Flask, FastAPI or AWS Lambda.
+- **Tested offline** with mocked HTTP: no token needed to develop or run the test suite.
+
+## Installation
+
+```bash
+pip install eltoque-python
+```
+
+Requires Python 3.11 or newer. To work on the SDK itself, install from a clone with `pip install -e .`.
+
+## Get your API token
+
+The SDK does not grant API access. Each application that integrates the API needs **its own
+token**, requested from elTOQUE:
+
+1. Fill in the official form: <https://tasas-token.eltoque.com/>
+2. Read the [terms of use](https://eltoque.com/api-tasas-de-eltoque-terminos-y-condiciones-de-uso).
+3. Keep the token secret and read it from the environment:
+
+```bash
+export ELTOQUE_API_TOKEN="your-application-token"
+```
+
+Never commit a token, share it with third parties, or ship it in a browser bundle.
+
+## Quickstart
+
+### Latest rates (rolling last 24 hours)
+
+```python
+import os
+
+from eltoque import ElToqueClient
+
+with ElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"]) as client:
+    response = client.get_latest_rates()
+    print(response.data)
+```
+
+### A specific window (shorter than 24 hours)
+
+```python
+import os
+from datetime import datetime
+
+from eltoque import ElToqueClient
+
+with ElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"]) as client:
+    response = client.get_rates(
+        datetime(2022, 10, 27, 0, 0, 0),
+        datetime(2022, 10, 27, 23, 59, 59),
+    )
+    print(response.data)
+```
+
+### Async
+
+```python
+import asyncio
+import os
+
+from eltoque import AsyncElToqueClient
+
+
+async def main() -> None:
+    async with AsyncElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"]) as client:
+        response = await client.get_latest_rates()
+        print(response.data)
+
+
+asyncio.run(main())
+```
+
+### Handling errors
+
+```python
+import os
+
+from eltoque import ElToqueClient, ElToqueError, ElToqueRateLimitError
+
+with ElToqueClient(api_token=os.environ["ELTOQUE_API_TOKEN"], max_retries=2) as client:
+    try:
+        response = client.get_latest_rates()
+    except ElToqueRateLimitError as error:
+        print(f"Rate limited, retry in {error.retry_after} s")
+    except ElToqueError as error:
+        print(f"Request failed: {error}")
+    else:
+        print(response.rate_limit.remaining, "requests left in this window")
+```
+
+## API reference
+
+### Clients
+
+`ElToqueClient` (sync) and `AsyncElToqueClient` (async, `await` every method) share this
+constructor:
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `api_token` | required | Your application token. Printable ASCII, no spaces, no `Bearer ` prefix. |
+| `base_url` | `https://tasas.eltoque.com` | HTTPS only. Plain `http://` is accepted for `localhost`/loopback (tests). |
+| `timeout` | `10 s` (`5 s` connect) | Seconds, or an `httpx.Timeout`. |
+| `max_retries` | `0` | Opt-in retries (max 5). See [Rate limits](#rate-limits-and-retries). |
+| `transport` | `None` | Test seam, e.g. `httpx.MockTransport`. |
+| `http_client` | `None` | Your own `httpx.Client` / `httpx.AsyncClient`. It is never closed by the SDK, and its own timeout applies. |
+
+| Method | Description |
+| --- | --- |
+| `get_latest_rates()` | Rolling last 24 hours, computed by the provider at request time. |
+| `get_rates(date_from, date_to)` | Explicit window, strictly shorter than 24 hours. |
+| `get_rates_for_day(day)` | `day 00:00:00` to `day 23:59:59`. One request. |
+| `close()` / `aclose()` | Release connections. Idempotent. Also called by `with` / `async with`. |
+
+Using a client after it was closed raises `ElToqueError`.
+
+### `RatesResponse`
+
+| Attribute | Description |
+| --- | --- |
+| `data` | The decoded JSON body, **exactly as the provider sent it** (object, list, scalar or `null`). |
+| `status_code` | HTTP status (SDK metadata). |
+| `rate_limit` | `RateLimitInfo` with optional `limit`, `remaining`, `reset`, `retry_after` (SDK metadata). |
+| `received_at` | UTC timestamp of when the SDK received the response (SDK metadata). |
+
+### Exceptions
+
+```text
+ElToqueError
+├── ElToqueConfigurationError   invalid token, base_url, timeout, retries
+├── ElToqueValidationError      invalid arguments, detected before any request
+├── ElToqueNetworkError         connection, DNS, TLS, protocol failures
+├── ElToqueTimeoutError
+├── ElToqueDecodeError          200 response that is not valid JSON, or too large
+└── ElToqueAPIError             has .status_code, .body_excerpt, .rate_limit, .retry_after
+    ├── ElToqueBadRequestError       400
+    ├── ElToqueAuthenticationError   401
+    ├── ElToqueUnprocessableError    422
+    ├── ElToqueRateLimitError        429
+    └── ElToqueServerError           5xx
+```
+
+Other 3xx/4xx statuses raise the base `ElToqueAPIError`. See [docs/errors.md](docs/errors.md).
+
+## Date and time rules
+
+- `date_from` and `date_to` must be **naive** `datetime` objects. Timezone-aware values are
+  rejected, because the API does not document its time zone and the SDK will not guess one.
+- They are sent as `YYYY-MM-DD HH:MM:SS` (microseconds are dropped).
+- `date_from` must be earlier than `date_to`, and the window must be **shorter than 24 hours**,
+  otherwise the API answers HTTP 400. The SDK rejects invalid windows before any request.
+- `get_rates_for_day` is a convenience; it is not guaranteed to be a complete local calendar day.
+
+## Rate limits and retries
+
+By default each API key may make **60 requests/minute and up to 10 requests/second**; your key
+may have different limits. Over the limit the API answers `429` with a `Retry-After` header.
+
+- Retries are **off** (`max_retries=0`). Every retry consumes quota.
+- With `max_retries > 0` the SDK retries only `429`, `502`, `503`, `504` and transport failures,
+  never `400`, `401` or `422`.
+- `Retry-After` is honored. If the server asks for longer than 30 s (or the 60 s total budget),
+  the error is raised instead of waiting.
+- There is no background polling, caching or bulk collection. You decide when to call.
+
+## Known limitations
+
+- Only one operation is documented by the provider: `GET /v1/trmi`. That is all this SDK calls.
+- The provider **does not publish the schema of a successful response**, so `RatesResponse.data`
+  is untyped and no field (currency names, timestamps, ...) is guaranteed. Typed rate models will
+  come only after the schema is validated with authorized access.
+- The time zone of the API is undocumented (see above).
+- Installing this SDK does not give you access to the API; you need your own approved token.
+
+## Supported Python versions
+
+Python 3.11, 3.12, 3.13 and 3.14. No framework is required.
+
+## Development
+
+```bash
+uv sync                      # or: pip install -e . && pip install pytest pytest-asyncio pytest-cov ruff mypy build twine
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv run pytest                # offline, no token needed
+uv run python -m build
+uv run twine check dist/*
+```
+
+Optional live check, only with your own authorized token (never run in CI):
+
+```bash
+ELTOQUE_API_TOKEN=... ELTOQUE_ALLOW_LIVE_TESTS=1 uv run pytest -m integration --no-cov
+```
+
+## Security and legal
+
+- Treat your token like a password. See [docs/security.md](docs/security.md).
+- This project is not affiliated with elTOQUE. When you display rates, name **elTOQUE as the
+  source** and describe them as **reference estimates**, as the
+  [terms of use](https://eltoque.com/api-tasas-de-eltoque-terminos-y-condiciones-de-uso) require.
+  Do not modify the data, share your key, resell the data or mass-extract it.
+- The [MIT license](LICENSE) covers this SDK's source code only. It grants no rights over
+  elTOQUE's API, data, name or trademarks.
+
+## Official resources
+
+- API landing page: <https://tasas.eltoque.com/>
+- Interactive docs: <https://tasas.eltoque.com/docs/>
+- OpenAPI document: <https://tasas.eltoque.com/static/swagger.json>
+- What is and is not verified: [docs/api-contract.md](docs/api-contract.md)
+
+## Community
+
+- Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- Security policy: [SECURITY.md](SECURITY.md)
+- Release notes: [CHANGELOG.md](CHANGELOG.md)

eltoque_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+eltoque/__init__.py,sha256=n8tNGDozKLqvQEBMBFzF_ZEKrpaPhUmveJvi_tk93js,1217
+eltoque/_async_client.py,sha256=w3dlRBLTSTorvlKDknQLFJGUIu_TU-yQRbGGF7XEouk,5129
+eltoque/_client.py,sha256=_1kWhS4t8QgHYovoDH11U8BFFtL_Axx_SuLuotHg8r4,5130
+eltoque/_config.py,sha256=WhomK447d-krKNPEunySQYJGshAkOL8LvlEewE16MEo,4680
+eltoque/_dates.py,sha256=e24dVq4Piy_Up7Our_qkC2H15WCVLBs-WisdF_RnPcs,2307
+eltoque/_retry.py,sha256=lxHigz0SkZx-GJTRVei5-nHh5IPoGRgUhSxJ8o25UrI,2186
+eltoque/_transport.py,sha256=4gzJisbvBnyICy4LPueVE7E0bvnBUNmogpQIPeHhK-I,6122
+eltoque/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+eltoque/exceptions.py,sha256=Wksj29sdxW11_fFemyvNktnUyS3cG51UUDoFTin9964,2149
+eltoque/models.py,sha256=TrN_64EMGI5_rtUXxR0pEvTiZi1U5NxXXqMrHNtUVCY,2526
+eltoque/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+eltoque_python-0.1.0.dist-info/METADATA,sha256=WWLWly5NSNdBeM_AacqkcXBeLrh0Cmjm-W_taGliNOE,11269
+eltoque_python-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+eltoque_python-0.1.0.dist-info/licenses/LICENSE,sha256=FG7YS9H2810eIXz1GzwcjlUisz2-3qcMO3h9vF57gZI,1226
+eltoque_python-0.1.0.dist-info/RECORD,,

eltoque_python-0.1.0.dist-info/WHEEL

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

eltoque_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 eltoque-python contributors
+
+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.
+
+Scope note: this license covers the source code of this repository only. It
+grants no rights over the elTOQUE API, data, name or trademarks.