salestax-python 0.1.0__py3-none-any.whl

salestax/__init__.py

@@ -0,0 +1,61 @@
+"""Official Python SDK for the Sales Tax Calculator API.
+
+Real-time sales tax for 70+ countries, 51 US jurisdictions, and 13 Canadian
+provinces. Batch up to 100 transactions per call.
+
+Docs: https://salestaxcalculatorapi.com/docs
+"""
+
+from __future__ import annotations
+
+from ._config import ClientOptions, RetryPolicy
+from ._version import __version__
+from .client import AsyncSalesTaxClient, SalesTaxClient
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    ConflictError,
+    ConnectionError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    SalesTaxError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+from .models import (
+    BatchResult,
+    CalculateTaxParams,
+    Jurisdiction,
+    JurisdictionQuery,
+    TaxBreakdownEntry,
+    TaxCalculation,
+    TaxRate,
+)
+
+__all__ = [
+    "ApiError",
+    "AsyncSalesTaxClient",
+    "AuthenticationError",
+    "BatchResult",
+    "CalculateTaxParams",
+    "ClientOptions",
+    "ConflictError",
+    "ConnectionError",
+    "Jurisdiction",
+    "JurisdictionQuery",
+    "NotFoundError",
+    "PermissionError",
+    "RateLimitError",
+    "RetryPolicy",
+    "SalesTaxClient",
+    "SalesTaxError",
+    "ServerError",
+    "TaxBreakdownEntry",
+    "TaxCalculation",
+    "TaxRate",
+    "TimeoutError",
+    "ValidationError",
+    "__version__",
+]

salestax/_config.py

@@ -0,0 +1,53 @@
+"""Configuration and defaults for the SDK."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+
+DEFAULT_BASE_URL = "https://api.salestaxcalculatorapi.com/v1"
+DEFAULT_TIMEOUT_MS = 30_000
+MAX_BATCH_SIZE = 100
+ENV_API_KEY = "SALESTAX_API_KEY"
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Retry behavior for transient failures.
+
+    Attributes:
+        max_retries: Number of retries *after* the initial attempt.
+        initial_delay_ms: Base delay for the first retry.
+        max_delay_ms: Ceiling for any single delay.
+        backoff_factor: Exponential multiplier applied per attempt.
+        jitter: Apply full jitter to each computed delay.
+    """
+
+    max_retries: int = 2
+    initial_delay_ms: int = 250
+    max_delay_ms: int = 8_000
+    backoff_factor: float = 2.0
+    jitter: bool = True
+
+
+@dataclass(frozen=True)
+class ClientOptions:
+    """Immutable options container. Prefer passing keyword args to the client."""
+
+    api_key: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+    timeout_ms: int = DEFAULT_TIMEOUT_MS
+    retry: RetryPolicy = field(default_factory=RetryPolicy)
+    default_headers: dict[str, str] = field(default_factory=dict)
+    chunk_batch: bool = False
+
+    def resolved_api_key(self) -> str:
+        key = self.api_key or os.environ.get(ENV_API_KEY)
+        if not key:
+            raise ValueError(
+                f"Missing API key. Pass api_key=... or set the {ENV_API_KEY} environment variable."
+            )
+        return key
+
+    def with_overrides(self, **kwargs: object) -> ClientOptions:
+        return replace(self, **kwargs)  # type: ignore[arg-type]

salestax/_transport/__init__.py

@@ -0,0 +1,18 @@
+from .http_client import AsyncHttpClient, HttpClient
+from .retry import compute_delay_ms, parse_retry_after
+from .types import AsyncTransport, Hooks, RequestOptions, SyncTransport
+from .urllib_transport import UrllibTransport
+from .user_agent import build_user_agent
+
+__all__ = [
+    "AsyncHttpClient",
+    "AsyncTransport",
+    "Hooks",
+    "HttpClient",
+    "RequestOptions",
+    "SyncTransport",
+    "UrllibTransport",
+    "build_user_agent",
+    "compute_delay_ms",
+    "parse_retry_after",
+]

salestax/_transport/http_client.py

@@ -0,0 +1,287 @@
+"""High-level HTTP clients (sync + async).
+
+Owns the full request lifecycle:
+
+1. Serialize body / build headers (auth, UA, idempotency).
+2. Delegate to the transport.
+3. Retry on retryable failures with backoff + jitter, honoring ``Retry-After``.
+4. Map non-2xx responses to typed errors.
+5. Fire lifecycle hooks.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from collections.abc import Mapping
+from typing import Any, TypeVar
+
+from .._config import ClientOptions, RetryPolicy
+from ..errors import SalesTaxError, error_from_response
+from .retry import compute_delay_ms, parse_retry_after
+from .types import AsyncTransport, Hooks, RequestOptions, SyncTransport
+from .urllib_transport import UrllibTransport
+from .user_agent import build_user_agent
+
+T = TypeVar("T")
+
+_JSON_DECODE_ERRORS = (json.JSONDecodeError, UnicodeDecodeError, ValueError)
+
+
+# -- Shared helpers ---------------------------------------------------------
+
+
+def _build_headers(
+    api_key: str,
+    options: ClientOptions,
+    request_options: RequestOptions | None,
+) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": build_user_agent(),
+    }
+    headers.update(options.default_headers)
+    if request_options and request_options.headers:
+        headers.update(request_options.headers)
+    if request_options and request_options.idempotency_key:
+        headers["Idempotency-Key"] = request_options.idempotency_key
+    return headers
+
+
+def _extract_request_id(headers: Mapping[str, str]) -> str | None:
+    for key in ("x-request-id", "request-id", "X-Request-Id"):
+        if key in headers:
+            return headers[key]
+    return None
+
+
+def _decode_json(raw: bytes) -> Mapping[str, Any]:
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except _JSON_DECODE_ERRORS:
+        return {}
+    return parsed if isinstance(parsed, Mapping) else {}
+
+
+def _should_retry(
+    err: SalesTaxError,
+    attempt: int,
+    policy: RetryPolicy,
+    request_options: RequestOptions | None,
+) -> bool:
+    if request_options and request_options.retryable is False:
+        return False
+    if not err.retryable:
+        return False
+    return attempt < policy.max_retries
+
+
+# -- Sync client ------------------------------------------------------------
+
+
+class HttpClient:
+    """Synchronous HTTP client with retry and typed error mapping."""
+
+    def __init__(
+        self,
+        options: ClientOptions,
+        *,
+        transport: SyncTransport | None = None,
+        hooks: Hooks | None = None,
+    ) -> None:
+        self._options = options
+        self._api_key = options.resolved_api_key()
+        self._base_url = options.base_url.rstrip("/")
+        self._timeout_s = options.timeout_ms / 1000.0
+        self._retry = options.retry
+        self._transport: SyncTransport = transport or UrllibTransport()
+        self._hooks = hooks or Hooks()
+
+    def send(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Mapping[str, Any] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        headers = _build_headers(self._api_key, self._options, options)
+        encoded = json.dumps(body).encode("utf-8") if body is not None else None
+
+        attempt = 0
+        last_error: SalesTaxError | None = None
+
+        while attempt <= self._retry.max_retries:
+            started = time.monotonic()
+            self._hooks.fire("on_request", {"method": method, "url": url, "attempt": attempt})
+            try:
+                status, resp_headers, raw = self._transport.request(
+                    method,
+                    url,
+                    headers=headers,
+                    body=encoded,
+                    timeout_s=self._timeout_s,
+                )
+            except SalesTaxError as exc:
+                last_error = exc
+                if not _should_retry(exc, attempt, self._retry, options):
+                    raise
+                delay = compute_delay_ms(attempt, self._retry)
+                self._hooks.fire(
+                    "on_retry", {"attempt": attempt + 1, "delay_ms": delay, "error": exc}
+                )
+                time.sleep(delay / 1000.0)
+                attempt += 1
+                continue
+
+            request_id = _extract_request_id(resp_headers)
+            self._hooks.fire(
+                "on_response",
+                {
+                    "status": status,
+                    "url": url,
+                    "duration_ms": int((time.monotonic() - started) * 1000),
+                    "request_id": request_id,
+                },
+            )
+
+            if 200 <= status < 300:
+                return _decode_json(raw)
+
+            parsed = _decode_json(raw)
+            err = error_from_response(
+                status,
+                parsed,
+                request_id=request_id,
+                retry_after_ms=parse_retry_after(resp_headers.get("retry-after")),
+            )
+            last_error = err
+
+            if not _should_retry(err, attempt, self._retry, options):
+                raise err
+
+            retry_after = getattr(err, "retry_after_ms", None)
+            delay = compute_delay_ms(attempt, self._retry, retry_after_ms=retry_after)
+            self._hooks.fire("on_retry", {"attempt": attempt + 1, "delay_ms": delay, "error": err})
+            time.sleep(delay / 1000.0)
+            attempt += 1
+
+        assert last_error is not None
+        raise last_error
+
+    def close(self) -> None:
+        """Release transport resources. No-op for the default transport."""
+
+
+# -- Async client -----------------------------------------------------------
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client with retry and typed error mapping."""
+
+    def __init__(
+        self,
+        options: ClientOptions,
+        *,
+        transport: AsyncTransport | None = None,
+        hooks: Hooks | None = None,
+    ) -> None:
+        self._options = options
+        self._api_key = options.resolved_api_key()
+        self._base_url = options.base_url.rstrip("/")
+        self._timeout_s = options.timeout_ms / 1000.0
+        self._retry = options.retry
+        if transport is None:
+            from .httpx_transport import HttpxAsyncTransport
+
+            transport = HttpxAsyncTransport()
+        self._transport: AsyncTransport = transport
+        self._hooks = hooks or Hooks()
+
+    async def send(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Mapping[str, Any] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        headers = _build_headers(self._api_key, self._options, options)
+        encoded = json.dumps(body).encode("utf-8") if body is not None else None
+
+        attempt = 0
+        last_error: SalesTaxError | None = None
+
+        while attempt <= self._retry.max_retries:
+            started = time.monotonic()
+            self._hooks.fire("on_request", {"method": method, "url": url, "attempt": attempt})
+            try:
+                status, resp_headers, raw = await self._transport.request(
+                    method,
+                    url,
+                    headers=headers,
+                    body=encoded,
+                    timeout_s=self._timeout_s,
+                )
+            except SalesTaxError as exc:
+                last_error = exc
+                if not _should_retry(exc, attempt, self._retry, options):
+                    raise
+                delay = compute_delay_ms(attempt, self._retry)
+                self._hooks.fire(
+                    "on_retry", {"attempt": attempt + 1, "delay_ms": delay, "error": exc}
+                )
+                await asyncio.sleep(delay / 1000.0)
+                attempt += 1
+                continue
+
+            request_id = _extract_request_id(resp_headers)
+            self._hooks.fire(
+                "on_response",
+                {
+                    "status": status,
+                    "url": url,
+                    "duration_ms": int((time.monotonic() - started) * 1000),
+                    "request_id": request_id,
+                },
+            )
+
+            if 200 <= status < 300:
+                return _decode_json(raw)
+
+            parsed = _decode_json(raw)
+            err = error_from_response(
+                status,
+                parsed,
+                request_id=request_id,
+                retry_after_ms=parse_retry_after(resp_headers.get("retry-after")),
+            )
+            last_error = err
+
+            if not _should_retry(err, attempt, self._retry, options):
+                raise err
+
+            retry_after = getattr(err, "retry_after_ms", None)
+            delay = compute_delay_ms(attempt, self._retry, retry_after_ms=retry_after)
+            self._hooks.fire("on_retry", {"attempt": attempt + 1, "delay_ms": delay, "error": err})
+            await asyncio.sleep(delay / 1000.0)
+            attempt += 1
+
+        assert last_error is not None
+        raise last_error
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncHttpClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

salestax/_transport/httpx_transport.py

@@ -0,0 +1,54 @@
+"""Optional async transport backed by httpx.
+
+Only imported when the user calls :class:`AsyncSalesTaxClient` or passes an
+instance explicitly. Installing the ``[async]`` extra is required.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ..errors import ConnectionError, TimeoutError
+
+try:
+    import httpx
+except ImportError as exc:  # pragma: no cover - import-guard
+    raise ImportError(
+        "The async client requires httpx. Install with: pip install salestax-python[async]"
+    ) from exc
+
+
+class HttpxAsyncTransport:
+    """httpx.AsyncClient-backed transport. One connection pool per instance."""
+
+    def __init__(self) -> None:
+        self._client = httpx.AsyncClient()
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        timeout_s: float,
+    ) -> tuple[int, Mapping[str, str], bytes]:
+        try:
+            resp = await self._client.request(
+                method, url, headers=dict(headers), content=body, timeout=timeout_s
+            )
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(int(timeout_s * 1000)) from exc
+        except httpx.TransportError as exc:
+            raise ConnectionError(str(exc)) from exc
+
+        return resp.status_code, dict(resp.headers), resp.content
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> HttpxAsyncTransport:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

salestax/_transport/retry.py

@@ -0,0 +1,49 @@
+"""Backoff computation and ``Retry-After`` parsing."""
+
+from __future__ import annotations
+
+import random
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+
+from .._config import RetryPolicy
+
+
+def compute_delay_ms(
+    attempt: int,
+    policy: RetryPolicy,
+    *,
+    retry_after_ms: int | None = None,
+) -> int:
+    """Return the delay in milliseconds before retry ``attempt`` (0-indexed)."""
+    if retry_after_ms is not None:
+        return max(0, retry_after_ms)
+
+    exponential = policy.initial_delay_ms * (policy.backoff_factor**attempt)
+    capped = min(exponential, policy.max_delay_ms)
+    if policy.jitter:
+        return int(random.random() * capped)
+    return int(capped)
+
+
+def parse_retry_after(value: str | None) -> int | None:
+    """Parse a ``Retry-After`` header into milliseconds.
+
+    Supports both the delay-seconds and HTTP-date forms per RFC 7231.
+    Returns ``None`` when the header is absent or unparseable.
+    """
+    if not value:
+        return None
+    value = value.strip()
+    if value.isdigit():
+        return int(value) * 1000
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when is None:
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    delta_ms = int((when - datetime.now(timezone.utc)).total_seconds() * 1000)
+    return max(0, delta_ms)

salestax/_transport/types.py

@@ -0,0 +1,91 @@
+"""Transport-layer contracts: request options, hooks, transport protocol."""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from ..errors import SalesTaxError
+
+# -- Request options --------------------------------------------------------
+
+
+@dataclass
+class RequestOptions:
+    """Per-request overrides."""
+
+    idempotency_key: str | None = None
+    headers: dict[str, str] | None = None
+    retryable: bool = True
+
+
+# -- Hooks ------------------------------------------------------------------
+
+
+@dataclass
+class Hooks:
+    """Lifecycle callbacks. All are optional and called synchronously.
+
+    Exceptions raised inside hooks are swallowed so a buggy hook cannot
+    break request flow.
+    """
+
+    on_request: Callable[[dict[str, Any]], None] | None = None
+    on_response: Callable[[dict[str, Any]], None] | None = None
+    on_retry: Callable[[dict[str, Any]], None] | None = None
+
+    def fire(self, name: str, info: Mapping[str, Any]) -> None:
+        cb = getattr(self, name, None)
+        if cb is None:
+            return
+        with contextlib.suppress(Exception):
+            cb(dict(info))
+
+
+# -- Transport protocol -----------------------------------------------------
+
+
+class SyncTransport(Protocol):
+    """Minimal synchronous transport contract.
+
+    Implementations take a fully-prepared request and return a tuple of
+    ``(status_code, response_headers, raw_body_bytes)``. They must not
+    raise for non-2xx responses — only for genuine network failures.
+    """
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        timeout_s: float,
+    ) -> tuple[int, Mapping[str, str], bytes]: ...
+
+
+class AsyncTransport(Protocol):
+    """Minimal asynchronous transport contract. Mirror of :class:`SyncTransport`."""
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        timeout_s: float,
+    ) -> tuple[int, Mapping[str, str], bytes]: ...
+
+    async def aclose(self) -> None: ...
+
+
+__all__ = [
+    "AsyncTransport",
+    "Hooks",
+    "RequestOptions",
+    "SalesTaxError",
+    "SyncTransport",
+]

salestax/_transport/urllib_transport.py

@@ -0,0 +1,55 @@
+"""Default synchronous transport — stdlib only, zero dependencies."""
+
+from __future__ import annotations
+
+import builtins
+import socket
+import ssl
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+
+from ..errors import ConnectionError, TimeoutError
+
+
+class UrllibTransport:
+    """Stdlib-backed synchronous HTTP transport.
+
+    Only raises :class:`ConnectionError` and :class:`TimeoutError`.
+    HTTP status codes are returned to the caller as data, never raised.
+    """
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        timeout_s: float,
+    ) -> tuple[int, Mapping[str, str], bytes]:
+        req = urllib.request.Request(url, data=body, method=method)
+        for key, value in headers.items():
+            req.add_header(key, value)
+
+        # Order matters:
+        #   HTTPError   is a subclass of URLError and OSError
+        #   URLError    is a subclass of OSError
+        #   TimeoutError/socket.timeout is a subclass of OSError
+        # Catch the most specific first.
+        try:
+            with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+                return resp.status, dict(resp.headers.items()), resp.read()
+        except urllib.error.HTTPError as exc:
+            # HTTP errors still carry a response body we want to surface.
+            raw = exc.read()
+            return exc.code, dict(exc.headers.items()) if exc.headers else {}, raw
+        except urllib.error.URLError as exc:
+            reason = getattr(exc, "reason", exc)
+            if isinstance(reason, (socket.timeout, builtins.TimeoutError)):
+                raise TimeoutError(int(timeout_s * 1000)) from exc
+            raise ConnectionError(str(reason)) from exc
+        except (socket.timeout, builtins.TimeoutError) as exc:
+            raise TimeoutError(int(timeout_s * 1000)) from exc
+        except (ssl.SSLError, OSError) as exc:
+            raise ConnectionError(str(exc)) from exc

salestax/_transport/user_agent.py

@@ -0,0 +1,15 @@
+"""User-Agent construction."""
+
+from __future__ import annotations
+
+import platform
+import sys
+
+from .._version import __version__
+
+
+def build_user_agent() -> str:
+    """Return a stable, informative User-Agent string."""
+    py = f"python/{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    os_info = f"{platform.system().lower()}/{platform.release()}"
+    return f"salestax-python/{__version__} ({py}; {os_info})"

salestax/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the SDK version."""
+
+__version__ = "0.1.0"