python-sendparcel-inpost 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

{python_sendparcel_inpost-0.2.0.dist-info → python_sendparcel_inpost-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-sendparcel-inpost
-Version: 0.2.0
+Version: 0.3.0
 Summary: InPost ShipX provider for python-sendparcel.
 Project-URL: Homepage, https://github.com/python-sendparcel/python-sendparcel-inpost
 Project-URL: Repository, https://github.com/python-sendparcel/python-sendparcel-inpost
@@ -22,7 +22,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: anyio>=4.0
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: python-sendparcel>=0.1.1
+Requires-Dist: python-sendparcel>=0.3.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'

python_sendparcel_inpost-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+sendparcel_inpost/__init__.py,sha256=Tkz5IeAveOLj_1CtR8xKfuon2URY9rst-qsKY66yLqI,548
+sendparcel_inpost/circuit_breaker.py,sha256=RZ6Sry63Jh9y7OdUCdXACxOIIfkgyiGggFG7h34DPCA,4939
+sendparcel_inpost/client.py,sha256=jftpFhvmcQDmpkAm8Bac0tqW5w4IxoC1frB9nso-Mqs,14920
+sendparcel_inpost/exceptions.py,sha256=E79mErjpni41_U9A2Ql2Cw4yAKd82cpguRPwNiamg2Y,2142
+sendparcel_inpost/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sendparcel_inpost/rate_limiter.py,sha256=sct5bYofsdKGLcGrCUXWeciyGIq_yr332kP7oLpTCZE,1870
+sendparcel_inpost/status_mapping.py,sha256=9UDU8XFCWKfKXPyWTV9E_dzgExdZjgZrBkcWUYj2smI,2782
+sendparcel_inpost/types.py,sha256=Pu-OJpC6te4_gY6PLv-Ag0o2IoulYytdr9t0FGf4GIA,1426
+sendparcel_inpost/providers/__init__.py,sha256=akn431q6mekenZV5Y4wjCh2UkLSi2s51umBHZ37orJg,336
+sendparcel_inpost/providers/base.py,sha256=7uQ8e0K0NPHOQ1-JM9XGyc5OzWd3OKUO_Goqm65sL0M,13952
+sendparcel_inpost/providers/courier.py,sha256=gdjZmoBlLTQa73x_JRameJQYCg2F9WhBwt2S-_0r2UU,2592
+sendparcel_inpost/providers/locker.py,sha256=mzn5WvnCi7lLWPoWW7NaHMty-vb4gzFSpgb9ucCHV0o,2867
+python_sendparcel_inpost-0.3.0.dist-info/METADATA,sha256=IRnCMaIs50L-d62gMvbzSd848VITd2JHIeo8_TUqPMM,3446
+python_sendparcel_inpost-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_sendparcel_inpost-0.3.0.dist-info/entry_points.txt,sha256=XuQdmE0LIuIc3TvGPWnYjoB14zXCEof6Q8h1tMp2arE,170
+python_sendparcel_inpost-0.3.0.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
+python_sendparcel_inpost-0.3.0.dist-info/RECORD,,

sendparcel_inpost/__init__.py

@@ -1,9 +1,10 @@
 """InPost ShipX provider for python-sendparcel."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from sendparcel_inpost.client import ShipXClient
 from sendparcel_inpost.exceptions import CircuitBreakerError
+from sendparcel_inpost.providers.base import aclose_transports
 from sendparcel_inpost.providers.courier import InPostCourierProvider
 from sendparcel_inpost.providers.locker import InPostLockerProvider
 
@@ -13,4 +14,5 @@ __all__ = [
     "InPostLockerProvider",
     "ShipXClient",
     "__version__",
+    "aclose_transports",
 ]

sendparcel_inpost/circuit_breaker.py

@@ -0,0 +1,155 @@
+"""Circuit breaker and metrics for external API resilience."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ShipXMetrics:
+    """Collects metrics for a single ShipXClient instance.
+
+    Thread-safe. Use ``snapshot()`` to get a point-in-time view.
+    """
+
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+    _request_count: int = 0
+    _error_count: int = 0
+    _circuit_trip_count: int = 0
+    _retry_count: int = 0
+    _total_latency_ms: float = 0.0
+    _max_latency_ms: float = 0.0
+    _last_error: str | None = None
+    _last_error_at: float | None = None
+    _circuit_state: str = "closed"
+
+    @property
+    def circuit_state(self) -> str:
+        with self._lock:
+            return self._circuit_state
+
+    def set_circuit_state(self, state: str) -> None:
+        with self._lock:
+            self._circuit_state = state
+
+    def record_request(
+        self,
+        latency_ms: float,
+        success: bool,
+        error: str | None = None,
+    ) -> None:
+        with self._lock:
+            self._request_count += 1
+            self._total_latency_ms += latency_ms
+            if latency_ms > self._max_latency_ms:
+                self._max_latency_ms = latency_ms
+            if not success:
+                self._error_count += 1
+                self._last_error = error
+                self._last_error_at = time.time()
+
+    def record_circuit_trip(self) -> None:
+        with self._lock:
+            self._circuit_trip_count += 1
+
+    def record_retry(self) -> None:
+        with self._lock:
+            self._retry_count += 1
+
+    def snapshot(self) -> dict[str, Any]:
+        """Return a point-in-time copy of all metrics."""
+        with self._lock:
+            avg_latency = (
+                self._total_latency_ms / self._request_count
+                if self._request_count > 0
+                else 0.0
+            )
+            return {
+                "request_count": self._request_count,
+                "error_count": self._error_count,
+                "retry_count": self._retry_count,
+                "circuit_trip_count": self._circuit_trip_count,
+                "circuit_state": self._circuit_state,
+                "avg_latency_ms": round(avg_latency, 2),
+                "max_latency_ms": round(self._max_latency_ms, 2),
+                "last_error": self._last_error,
+                "last_error_at": self._last_error_at,
+            }
+
+
+class _CircuitBreaker:
+    """Simple circuit breaker for the ShipX API.
+
+    States:
+    - CLOSED: normal operation, requests pass through
+    - OPEN: circuit tripped, requests fail fast
+    - HALF_OPEN: one probe request allowed after cooldown
+
+    Transitions:
+    - CLOSED → OPEN: after `threshold` consecutive failures
+    - OPEN → HALF_OPEN: after `cooldown` seconds
+    - HALF_OPEN → CLOSED: probe request succeeds
+    - HALF_OPEN → OPEN: probe request fails
+    """
+
+    class State:
+        CLOSED = "closed"
+        OPEN = "open"
+        HALF_OPEN = "half_open"
+
+    def __init__(
+        self,
+        threshold: int = 5,
+        cooldown: float = 30.0,
+    ) -> None:
+        self._threshold = threshold
+        self._cooldown = cooldown
+        self._state = self.State.CLOSED
+        self._failures = 0
+        self._opened_at: float | None = None
+
+    @property
+    def state(self) -> str:
+        """Current circuit state, transitioning OPEN → HALF_OPEN on cooldown."""
+        if self._state == self.State.OPEN and self._opened_at is not None:
+            elapsed = time.monotonic() - self._opened_at
+            if elapsed >= self._cooldown:
+                self._state = self.State.HALF_OPEN
+        return self._state
+
+    @property
+    def failures(self) -> int:
+        return self._failures
+
+    @property
+    def cooldown_remaining(self) -> float:
+        if self._state != self.State.OPEN or self._opened_at is None:
+            return 0.0
+        elapsed = time.monotonic() - self._opened_at
+        return max(0.0, self._cooldown - elapsed)
+
+    def allow_request(self) -> bool:
+        """Check if a request should be allowed through."""
+        current = self.state  # triggers OPEN → HALF_OPEN transition
+        return current != self.State.OPEN
+
+    def record_success(self) -> None:
+        """Record a successful request."""
+        self._failures = 0
+        self._state = self.State.CLOSED
+        self._opened_at = None
+
+    def record_failure(self) -> None:
+        """Record a failed request."""
+        self._failures += 1
+        if self.state == self.State.HALF_OPEN:
+            # Probe failed — reopen circuit
+            self._state = self.State.OPEN
+            self._opened_at = time.monotonic()
+        elif self._failures >= self._threshold:
+            # Threshold reached — open circuit
+            self._state = self.State.OPEN
+            self._opened_at = time.monotonic()

sendparcel_inpost/client.py

@@ -2,99 +2,26 @@
 
 from __future__ import annotations
 
-import asyncio
-import atexit
 import logging
-import threading
 import time
-from dataclasses import dataclass, field
 from types import TracebackType
 from typing import Any, cast
 
+import anyio
 import httpx
 
+from sendparcel_inpost.circuit_breaker import ShipXMetrics, _CircuitBreaker
 from sendparcel_inpost.exceptions import (
     CircuitBreakerError,
     ShipXAPIError,
     ShipXAuthenticationError,
     ShipXValidationError,
 )
+from sendparcel_inpost.rate_limiter import _TokenBucket
 
 logger = logging.getLogger(__name__)
 
 
-@dataclass
-class ShipXMetrics:
-    """Collects metrics for a single ShipXClient instance.
-
-    Thread-safe. Use ``snapshot()`` to get a point-in-time view.
-    """
-
-    _lock: threading.Lock = field(default_factory=threading.Lock)
-    _request_count: int = 0
-    _error_count: int = 0
-    _circuit_trip_count: int = 0
-    _retry_count: int = 0
-    _total_latency_ms: float = 0.0
-    _max_latency_ms: float = 0.0
-    _last_error: str | None = None
-    _last_error_at: float | None = None
-    _circuit_state: str = "closed"
-
-    @property
-    def circuit_state(self) -> str:
-        with self._lock:
-            return self._circuit_state
-
-    def set_circuit_state(self, state: str) -> None:
-        with self._lock:
-            self._circuit_state = state
-
-    def record_request(
-        self,
-        latency_ms: float,
-        success: bool,
-        error: str | None = None,
-    ) -> None:
-        with self._lock:
-            self._request_count += 1
-            self._total_latency_ms += latency_ms
-            if latency_ms > self._max_latency_ms:
-                self._max_latency_ms = latency_ms
-            if not success:
-                self._error_count += 1
-                self._last_error = error
-                self._last_error_at = time.time()
-
-    def record_circuit_trip(self) -> None:
-        with self._lock:
-            self._circuit_trip_count += 1
-
-    def record_retry(self) -> None:
-        with self._lock:
-            self._retry_count += 1
-
-    def snapshot(self) -> dict[str, Any]:
-        """Return a point-in-time copy of all metrics."""
-        with self._lock:
-            avg_latency = (
-                self._total_latency_ms / self._request_count
-                if self._request_count > 0
-                else 0.0
-            )
-            return {
-                "request_count": self._request_count,
-                "error_count": self._error_count,
-                "retry_count": self._retry_count,
-                "circuit_trip_count": self._circuit_trip_count,
-                "circuit_state": self._circuit_state,
-                "avg_latency_ms": round(avg_latency, 2),
-                "max_latency_ms": round(self._max_latency_ms, 2),
-                "last_error": self._last_error,
-                "last_error_at": self._last_error_at,
-            }
-
-
 PRODUCTION_BASE_URL = "https://api-shipx-pl.easypack24.net"
 SANDBOX_BASE_URL = "https://sandbox-api-shipx-pl.easypack24.net"
 
@@ -107,250 +34,6 @@ DEFAULT_CIRCUIT_THRESHOLD = 5  # consecutive failures to open circuit
 DEFAULT_CIRCUIT_COOLDOWN = 30.0  # seconds before allowing probe request
 
 
-class _TokenBucket:
-    """Async token bucket rate limiter.
-
-    Tokens are added at a fixed rate up to a maximum burst size.
-    Each request consumes one token. If no tokens are available,
-    the caller waits until a token is refilled.
-    """
-
-    __slots__ = ("_burst", "_last_refill", "_lock", "_rate", "_tokens")
-
-    def __init__(
-        self,
-        rate: float,
-        burst: int,
-    ) -> None:
-        self._rate = rate
-        self._burst = burst
-        self._tokens = float(burst)
-        self._last_refill: float | None = None
-        self._lock = asyncio.Lock()
-
-    async def acquire(self) -> None:
-        """Acquire a token, waiting if necessary.
-
-        Tokens are refilled based on elapsed wall-clock time up to the
-        burst limit. When no tokens are available the caller waits the
-        exact duration needed for one token to become available — sleep
-        time is NOT counted toward refill to prevent burst above limits.
-        """
-        async with self._lock:
-            now = asyncio.get_event_loop().time()
-            if self._last_refill is None:
-                self._last_refill = now
-            elapsed = now - self._last_refill
-            self._tokens = min(self._burst, self._tokens + elapsed * self._rate)
-            self._last_refill = now
-
-            if self._tokens < 1.0:
-                wait_time = (1.0 - self._tokens) / self._rate
-                await asyncio.sleep(wait_time)
-                # Consume the token and advance last_refill so that
-                # subsequent calls don't double-count the sleep.
-                self._last_refill = asyncio.get_event_loop().time()
-                self._tokens -= 1.0
-            else:
-                self._tokens -= 1.0
-
-
-class _CircuitBreaker:
-    """Simple circuit breaker for the ShipX API.
-
-    States:
-    - CLOSED: normal operation, requests pass through
-    - OPEN: circuit tripped, requests fail fast
-    - HALF_OPEN: one probe request allowed after cooldown
-
-    Transitions:
-    - CLOSED → OPEN: after `threshold` consecutive failures
-    - OPEN → HALF_OPEN: after `cooldown` seconds
-    - HALF_OPEN → CLOSED: probe request succeeds
-    - HALF_OPEN → OPEN: probe request fails
-    """
-
-    class State:
-        CLOSED = "closed"
-        OPEN = "open"
-        HALF_OPEN = "half_open"
-
-    def __init__(
-        self,
-        threshold: int = 5,
-        cooldown: float = 30.0,
-    ) -> None:
-        self._threshold = threshold
-        self._cooldown = cooldown
-        self._state = self.State.CLOSED
-        self._failures = 0
-        self._opened_at: float | None = None
-
-    @property
-    def state(self) -> str:
-        """Current circuit state, transitioning OPEN → HALF_OPEN on cooldown."""
-        if self._state == self.State.OPEN and self._opened_at is not None:
-            elapsed = asyncio.get_event_loop().time() - self._opened_at
-            if elapsed >= self._cooldown:
-                self._state = self.State.HALF_OPEN
-        return self._state
-
-    @property
-    def failures(self) -> int:
-        return self._failures
-
-    @property
-    def cooldown_remaining(self) -> float:
-        if self._state != self.State.OPEN or self._opened_at is None:
-            return 0.0
-        elapsed = asyncio.get_event_loop().time() - self._opened_at
-        return max(0.0, self._cooldown - elapsed)
-
-    def allow_request(self) -> bool:
-        """Check if a request should be allowed through."""
-        current = self.state  # triggers OPEN → HALF_OPEN transition
-        return current != self.State.OPEN
-
-    def record_success(self) -> None:
-        """Record a successful request."""
-        self._failures = 0
-        self._state = self.State.CLOSED
-        self._opened_at = None
-
-    def record_failure(self) -> None:
-        """Record a failed request."""
-        self._failures += 1
-        if self.state == self.State.HALF_OPEN:
-            # Probe failed — reopen circuit
-            self._state = self.State.OPEN
-            self._opened_at = asyncio.get_event_loop().time()
-        elif self._failures >= self._threshold:
-            # Threshold reached — open circuit
-            self._state = self.State.OPEN
-            self._opened_at = asyncio.get_event_loop().time()
-
-
-class _ClientPool:
-    """Thread-safe pool of shared ShipXClient instances.
-
-    Clients are keyed by (token, organization_id, sandbox, base_url,
-    timeout, rate_limit, burst, max_retries, retry_base_delay,
-    circuit_threshold, circuit_cooldown).
-    Multiple providers with the same credentials share a single client.
-    """
-
-    def __init__(self) -> None:
-        self._clients: dict[
-            tuple[
-                str,
-                int,
-                bool,
-                str | None,
-                float,
-                float,
-                int,
-                int,
-                float,
-                int,
-                float,
-            ],
-            ShipXClient,
-        ] = {}
-        self._lock = threading.Lock()
-
-    def get(
-        self,
-        token: str,
-        organization_id: int,
-        *,
-        sandbox: bool = False,
-        base_url: str | None = None,
-        timeout: float = DEFAULT_TIMEOUT,
-        rate_limit: float = DEFAULT_RATE_LIMIT,
-        burst: int = DEFAULT_BURST,
-        max_retries: int = DEFAULT_MAX_RETRIES,
-        retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
-        circuit_threshold: int = DEFAULT_CIRCUIT_THRESHOLD,
-        circuit_cooldown: float = DEFAULT_CIRCUIT_COOLDOWN,
-    ) -> ShipXClient:
-        """Get or create a shared client for the given credentials.
-
-        The pool key includes all parameters that affect client behavior,
-        ensuring that clients with different rate limits, burst sizes,
-        circuit breaker settings, or retry policies are cached separately.
-        """
-        key = (
-            token,
-            organization_id,
-            sandbox,
-            base_url,
-            timeout,
-            rate_limit,
-            burst,
-            max_retries,
-            retry_base_delay,
-            circuit_threshold,
-            circuit_cooldown,
-        )
-        with self._lock:
-            client = self._clients.get(key)
-            if client is None:
-                client = ShipXClient(
-                    token=token,
-                    organization_id=organization_id,
-                    sandbox=sandbox,
-                    base_url=base_url,
-                    timeout=timeout,
-                    rate_limit=rate_limit,
-                    burst=burst,
-                    max_retries=max_retries,
-                    retry_base_delay=retry_base_delay,
-                    circuit_threshold=circuit_threshold,
-                    circuit_cooldown=circuit_cooldown,
-                )
-                self._clients[key] = client
-            return client
-
-    async def close_all(self) -> None:
-        """Close all pooled clients.
-
-        Must be awaited from an async context (e.g. an ``atexit`` hook
-        running via ``anyio.run``, or a Django ASGI shutdown signal).
-        """
-        clients: list[ShipXClient] = []
-        with self._lock:
-            clients = list(self._clients.values())
-            self._clients.clear()
-        await asyncio.gather(
-            *(c.close() for c in clients), return_exceptions=True
-        )
-
-
-# Module-level singleton pool.
-_pool = _ClientPool()
-
-# Shutdown hook — registered at import time so it fires on process exit.
-# Uses anyio.run to create a temporary event loop for cleanup.
-
-
-def _shutdown_pool() -> None:
-    """Clean up pooled HTTP clients on process exit."""
-    import anyio
-
-    try:
-        anyio.run(_pool.close_all)
-    except Exception:
-        logger.warning("Failed to close client pool on shutdown", exc_info=True)
-
-
-atexit.register(_shutdown_pool)
-
-
-def get_client_pool() -> _ClientPool:
-    """Return the module-level client pool singleton."""
-    return _pool
-
-
 class ShipXClient:
     """Async HTTP client for InPost ShipX API.
 
@@ -451,6 +134,7 @@ class ShipXClient:
         """
         start = time.monotonic()
         retries = 0
+        op_name = getattr(coro, "__qualname__", repr(coro))
 
         # Check circuit breaker before attempting any work
         if not self._circuit.allow_request():
@@ -502,11 +186,11 @@ class ShipXClient:
                         "Retry %d/%d for %s after %.1fs: %s",
                         attempt + 1,
                         self._max_retries,
-                        type(coro).__name__,
+                        op_name,
                         delay,
                         exc,
                     )
-                    await asyncio.sleep(delay)
+                    await anyio.sleep(delay)
                 else:
                     latency_ms = (time.monotonic() - start) * 1000
                     self._metrics.record_request(
@@ -515,59 +199,36 @@ class ShipXClient:
                         error=f"{type(exc).__name__}: {exc}",
                     )
                     raise
-            except httpx.HTTPStatusError as exc:
-                if exc.response.status_code >= 500 and idempotent:
-                    last_exc = exc
-                    self._circuit.record_failure()
-                    self._metrics.set_circuit_state(self._circuit.state)
-                    if attempt < self._max_retries:
-                        retries += 1
-                        self._metrics.record_retry()
-                        delay = self._retry_base_delay * (2**attempt)
-                        logger.warning(
-                            "Retry %d/%d for %s after %.1fs: HTTP %d",
-                            attempt + 1,
-                            self._max_retries,
-                            type(coro).__name__,
-                            delay,
-                            exc.response.status_code,
-                        )
-                        await asyncio.sleep(delay)
-                    else:
-                        latency_ms = (time.monotonic() - start) * 1000
-                        self._metrics.record_request(
-                            latency_ms,
-                            success=False,
-                            error=f"HTTP {exc.response.status_code}",
-                        )
-                        raise
-                else:
-                    latency_ms = (time.monotonic() - start) * 1000
-                    self._metrics.record_request(
-                        latency_ms,
-                        success=False,
-                        error=f"HTTP {exc.response.status_code}",
-                    )
-                    raise
             except ShipXAPIError as exc:
-                if exc.status_code >= 500 and idempotent:
+                # 429: the request was rejected before processing, so it
+                # is safe to retry regardless of idempotency. Rate
+                # limiting is not a service failure — don't trip the
+                # circuit. 5xx: retry only idempotent operations.
+                rate_limited = exc.status_code == 429
+                retryable = rate_limited or (
+                    exc.status_code >= 500 and idempotent
+                )
+                if retryable:
                     last_exc = exc
-                    self._circuit.record_failure()
-                    self._metrics.set_circuit_state(self._circuit.state)
+                    if not rate_limited:
+                        self._circuit.record_failure()
+                        self._metrics.set_circuit_state(self._circuit.state)
                     if attempt < self._max_retries:
                         retries += 1
                         self._metrics.record_retry()
                         delay = self._retry_base_delay * (2**attempt)
+                        if rate_limited and exc.retry_after is not None:
+                            delay = exc.retry_after
                         logger.warning(
                             "Retry %d/%d for %s after %.1fs: HTTP %d %s",
                             attempt + 1,
                             self._max_retries,
-                            type(coro).__name__,
+                            op_name,
                             delay,
                             exc.status_code,
                             exc.detail,
                         )
-                        await asyncio.sleep(delay)
+                        await anyio.sleep(delay)
                     else:
                         latency_ms = (time.monotonic() - start) * 1000
                         self._metrics.record_request(
@@ -748,4 +409,17 @@ class ShipXClient:
             status_code=status_code,
             detail=str(detail),
             errors=errors,
+            retry_after=_parse_retry_after(response),
         )
+
+
+def _parse_retry_after(response: httpx.Response) -> float | None:
+    """Parse the Retry-After header as delay seconds, if present."""
+    raw = response.headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        # HTTP-date form — not worth parsing; fall back to backoff.
+        return None

sendparcel_inpost/exceptions.py

@@ -13,10 +13,12 @@ class ShipXAPIError(CommunicationError):
         status_code: int,
         detail: str,
         errors: list[dict[str, Any]] | None = None,
+        retry_after: float | None = None,
     ) -> None:
         self.status_code = status_code
         self.detail = detail
         self.errors = errors or []
+        self.retry_after = retry_after
         super().__init__(
             f"ShipX API error {status_code}: {detail}",
             context={

sendparcel_inpost/providers/base.py

@@ -7,26 +7,31 @@ from __future__ import annotations
 
 import base64
 import ipaddress
+import threading
 from typing import Any, ClassVar
 
 from sendparcel.enums import ConfirmationMethod, LabelFormat
 from sendparcel.exceptions import InvalidCallbackError
 from sendparcel.logging import get_logger
 from sendparcel.protocols import Shipment
-from sendparcel.provider import (
-    BaseProvider,
-    CancellableProvider,
-    LabelProvider,
-    PullStatusProvider,
-    PushCallbackProvider,
-)
+from sendparcel.provider import BaseProvider
 from sendparcel.types import (
     AddressInfo,
+    CallbackContext,
     LabelInfo,
     ShipmentUpdateResult,
 )
 
-from sendparcel_inpost.client import ShipXClient, get_client_pool
+from sendparcel_inpost.client import (
+    DEFAULT_BURST,
+    DEFAULT_CIRCUIT_COOLDOWN,
+    DEFAULT_CIRCUIT_THRESHOLD,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RATE_LIMIT,
+    DEFAULT_RETRY_BASE_DELAY,
+    DEFAULT_TIMEOUT,
+    ShipXClient,
+)
 from sendparcel_inpost.exceptions import (
     ShipXAPIError,
     ShipXAuthenticationError,
@@ -39,13 +44,65 @@ logger = get_logger(__name__)
 _DEFAULT_WEBHOOK_NETWORKS: list[str] = ["91.216.25.0/24"]
 
 
-class InPostBaseProvider(
-    BaseProvider,
-    LabelProvider,
-    PushCallbackProvider,
-    PullStatusProvider,
-    CancellableProvider,
-):
+# Shared clients keyed by client-relevant config. The flow builds a
+# provider (and calls the transport factory) on every operation, so the
+# factory must reuse clients: a fresh httpx.AsyncClient per call would
+# leak connections and reset the circuit breaker, rate limiter, and
+# metrics on each operation.
+_transport_cache: dict[tuple[Any, ...], ShipXClient] = {}
+_transport_cache_lock = threading.Lock()
+
+
+def _client_kwargs(config: dict[str, Any]) -> dict[str, Any]:
+    """Extract ShipXClient constructor kwargs from provider config."""
+    return {
+        "token": config.get("token", ""),
+        "organization_id": config.get("organization_id", 0),
+        "sandbox": config.get("sandbox", False),
+        "base_url": config.get("base_url"),
+        "timeout": config.get("timeout", DEFAULT_TIMEOUT),
+        "rate_limit": config.get("rate_limit", DEFAULT_RATE_LIMIT),
+        "burst": config.get("burst", DEFAULT_BURST),
+        "max_retries": config.get("max_retries", DEFAULT_MAX_RETRIES),
+        "retry_base_delay": config.get(
+            "retry_base_delay", DEFAULT_RETRY_BASE_DELAY
+        ),
+        "circuit_threshold": config.get(
+            "circuit_threshold", DEFAULT_CIRCUIT_THRESHOLD
+        ),
+        "circuit_cooldown": config.get(
+            "circuit_cooldown", DEFAULT_CIRCUIT_COOLDOWN
+        ),
+    }
+
+
+def _build_inpost_transport(**config: Any) -> ShipXClient:
+    """Return the shared ShipXClient for this provider config."""
+    kwargs = _client_kwargs(config)
+    key = tuple(sorted(kwargs.items(), key=lambda kv: kv[0]))
+    with _transport_cache_lock:
+        client = _transport_cache.get(key)
+        if client is None:
+            client = ShipXClient(**kwargs)
+            _transport_cache[key] = client
+        return client
+
+
+async def aclose_transports() -> None:
+    """Close and evict all shared ShipX clients.
+
+    Call during application shutdown to release HTTP connections.
+    Safe to call multiple times; subsequent factory calls create
+    fresh clients.
+    """
+    with _transport_cache_lock:
+        clients = list(_transport_cache.values())
+        _transport_cache.clear()
+    for client in clients:
+        await client.close()
+
+
+class InPostBaseProvider(BaseProvider):
     """Shared implementation for InPost courier and locker providers.
 
     Subclasses must define:
@@ -61,6 +118,7 @@ class InPostBaseProvider(
     supported_countries: ClassVar[list[str]] = ["PL"]
     confirmation_method: ClassVar[ConfirmationMethod] = ConfirmationMethod.PUSH
     user_selectable: ClassVar[bool] = True
+    transport_factory: ClassVar[Any] = staticmethod(_build_inpost_transport)
     config_schema: ClassVar[dict[str, Any]] = {
         "token": {
             "type": "str",
@@ -94,6 +152,48 @@ class InPostBaseProvider(
             "description": "HTTP request timeout in seconds",
             "default": 30.0,
         },
+        "rate_limit": {
+            "type": "float",
+            "required": False,
+            "secret": False,
+            "description": "Max requests per second to the ShipX API",
+            "default": DEFAULT_RATE_LIMIT,
+        },
+        "burst": {
+            "type": "int",
+            "required": False,
+            "secret": False,
+            "description": "Rate limiter burst size",
+            "default": DEFAULT_BURST,
+        },
+        "max_retries": {
+            "type": "int",
+            "required": False,
+            "secret": False,
+            "description": "Max retries for transient failures",
+            "default": DEFAULT_MAX_RETRIES,
+        },
+        "retry_base_delay": {
+            "type": "float",
+            "required": False,
+            "secret": False,
+            "description": "Base delay for exponential backoff (seconds)",
+            "default": DEFAULT_RETRY_BASE_DELAY,
+        },
+        "circuit_threshold": {
+            "type": "int",
+            "required": False,
+            "secret": False,
+            "description": "Consecutive failures before the circuit opens",
+            "default": DEFAULT_CIRCUIT_THRESHOLD,
+        },
+        "circuit_cooldown": {
+            "type": "float",
+            "required": False,
+            "secret": False,
+            "description": "Seconds before the open circuit allows a probe",
+            "default": DEFAULT_CIRCUIT_COOLDOWN,
+        },
         "trusted_networks": {
             "type": "list[str]",
             "required": False,
@@ -116,57 +216,11 @@ class InPostBaseProvider(
         self,
         shipment: Shipment,
         config: dict[str, Any] | None = None,
+        *,
+        transport: Any = None,
     ) -> None:
-        super().__init__(shipment, config)
-        self._validate_config()
-        self._client = self._build_client()
-
-    def _validate_config(self) -> None:
-        """Validate configuration against ``config_schema``.
-
-        Checks that all required fields are present and have the
-        correct type.  Raises ``ValueError`` with a helpful message
-        on the first violation found.
-        """
-        for field_name, spec in self.config_schema.items():
-            if not spec.get("required", False):
-                continue
-            value = self.get_setting(field_name)
-            if value is None or value == "":
-                raise ValueError(
-                    f"InPost provider requires '{field_name}' in config. "
-                    f"Set {field_name!r} in your provider configuration."
-                )
-            expected_type = spec.get("type")
-            if expected_type and value is not None:
-                type_map: dict[str, type | tuple[type, ...]] = {
-                    "str": str,
-                    "int": int,
-                    "float": (int, float),
-                    "bool": bool,
-                    "list[str]": list,
-                }
-                python_type = type_map.get(expected_type)
-                if python_type and not isinstance(value, python_type):
-                    raise TypeError(
-                        f"InPost provider config '{field_name}' must be "
-                        f"{expected_type}, got {type(value).__name__}"
-                    )
-
-    def _build_client(self) -> ShipXClient:
-        """Build a ShipXClient from provider config using the shared pool."""
-        pool = get_client_pool()
-        return pool.get(
-            token=self.get_setting("token", ""),
-            organization_id=self.get_setting("organization_id", 0),
-            sandbox=self.get_setting("sandbox", False),
-            base_url=self.get_setting("base_url"),
-            timeout=self.get_setting("timeout", 30.0),
-        )
-
-    def _get_client(self) -> ShipXClient:
-        """Return the shared ShipXClient instance."""
-        return self._client
+        super().__init__(shipment, config, transport=transport)
+        self._client = transport
 
     def _address_to_peer(self, addr: AddressInfo) -> ShipXPeer:
         """Convert sendparcel AddressInfo to ShipX peer dict."""
@@ -243,23 +297,17 @@ class InPostBaseProvider(
 
     async def verify_callback(
         self,
-        data: dict[str, Any],
-        headers: dict[str, Any],
-        source_ip: str | None = None,
+        ctx: CallbackContext,
         **kwargs: Any,
     ) -> None:
         """Verify InPost webhook by validated source IP.
 
         The provider checks the source IP against the configured
-        ``trusted_networks`` setting.  The IP can be supplied in two
-        ways:
-
-        1. **Direct parameter** (preferred): pass ``source_ip`` directly
-           from the framework layer (e.g. ``request.client.host`` in
-           FastAPI/Litestar or ``request.META['REMOTE_ADDR']`` in Django).
-        2. **Header fallback**: if ``source_ip`` is not provided, the
-           provider falls back to the ``x-validated-source-ip`` header,
-           which the Django view sets from ``REMOTE_ADDR``.
+        ``trusted_networks`` setting.  The IP is read from the
+        ``CallbackContext.source_ip`` field, which the framework
+        layer populates from the actual TCP connection
+        (``request.META['REMOTE_ADDR']`` in Django, ``request.client.host``
+        in FastAPI/Litestar).
 
         Verification can be disabled entirely with
         ``verify_webhook_ip=False`` (useful for local development).
@@ -267,12 +315,11 @@ class InPostBaseProvider(
         if not self.get_setting("verify_webhook_ip", True):
             return
 
-        # Prefer direct parameter; fall back to header for Django compat.
-        ip_str = source_ip or headers.get("x-validated-source-ip", "")
+        ip_str = ctx.source_ip
         if not ip_str:
             raise InvalidCallbackError(
-                "Missing source IP; pass source_ip directly or set "
-                "x-validated-source-ip header"
+                "Missing source IP; ensure the framework layer populates "
+                "CallbackContext.source_ip from the TCP connection"
             )
         await self.validate_source_ip(ip_str)
 
@@ -300,12 +347,11 @@ class InPostBaseProvider(
 
     async def handle_callback(
         self,
-        data: dict[str, Any],
-        headers: dict[str, Any],
+        ctx: CallbackContext,
         **kwargs: Any,
     ) -> ShipmentUpdateResult:
         """Process InPost webhook payload."""
-        payload = data.get("payload", {})
+        payload = ctx.payload.get("payload", {})
         shipx_status = str(payload.get("status", ""))
         tracking_number = str(payload.get("tracking_number", ""))
         update = build_shipment_update(

sendparcel_inpost/providers/courier.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 from typing import Any, ClassVar
 
 from sendparcel.enums import ConfirmationMethod
-from sendparcel.protocols import Shipment
 from sendparcel.types import (
     AddressInfo,
     ParcelInfo,
@@ -27,13 +26,6 @@ class InPostCourierProvider(
     ]
     confirmation_method: ClassVar[ConfirmationMethod] = ConfirmationMethod.PUSH
 
-    def __init__(
-        self,
-        shipment: Shipment,
-        config: dict[str, Any] | None = None,
-    ) -> None:
-        super().__init__(shipment, config)
-
     async def create_shipment(
         self,
         *,

sendparcel_inpost/providers/locker.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 from typing import Any, ClassVar
 
 from sendparcel.enums import ConfirmationMethod
-from sendparcel.protocols import Shipment
 from sendparcel.types import (
     AddressInfo,
     ParcelInfo,
@@ -27,13 +26,6 @@ class InPostLockerProvider(
     ]
     confirmation_method: ClassVar[ConfirmationMethod] = ConfirmationMethod.PUSH
 
-    def __init__(
-        self,
-        shipment: Shipment,
-        config: dict[str, Any] | None = None,
-    ) -> None:
-        super().__init__(shipment, config)
-
     def _parcel_template_from_parcels(self, parcels: list[ParcelInfo]) -> str:
         """Determine locker parcel template from parcels.
 

sendparcel_inpost/rate_limiter.py

@@ -0,0 +1,57 @@
+"""Async token bucket rate limiter."""
+
+from __future__ import annotations
+
+import time
+
+import anyio
+
+
+class _TokenBucket:
+    """Async token bucket rate limiter.
+
+    Tokens are added at a fixed rate up to a maximum burst size.
+    Each request consumes one token. If no tokens are available,
+    the caller waits until a token is refilled.
+
+    Backend-agnostic (anyio): works under both asyncio and trio.
+    """
+
+    __slots__ = ("_burst", "_last_refill", "_lock", "_rate", "_tokens")
+
+    def __init__(
+        self,
+        rate: float,
+        burst: int,
+    ) -> None:
+        self._rate = rate
+        self._burst = burst
+        self._tokens = float(burst)
+        self._last_refill: float | None = None
+        self._lock = anyio.Lock()
+
+    async def acquire(self) -> None:
+        """Acquire a token, waiting if necessary.
+
+        Tokens are refilled based on elapsed wall-clock time up to the
+        burst limit. When no tokens are available the caller waits the
+        exact duration needed for one token to become available — sleep
+        time is NOT counted toward refill to prevent burst above limits.
+        """
+        async with self._lock:
+            now = time.monotonic()
+            if self._last_refill is None:
+                self._last_refill = now
+            elapsed = now - self._last_refill
+            self._tokens = min(self._burst, self._tokens + elapsed * self._rate)
+            self._last_refill = now
+
+            if self._tokens < 1.0:
+                wait_time = (1.0 - self._tokens) / self._rate
+                await anyio.sleep(wait_time)
+                # Consume the token and advance last_refill so that
+                # subsequent calls don't double-count the sleep.
+                self._last_refill = time.monotonic()
+                self._tokens -= 1.0
+            else:
+                self._tokens -= 1.0

sendparcel_inpost/status_mapping.py

@@ -3,34 +3,33 @@
 from sendparcel.enums import ShipmentStatus
 from sendparcel.types import ShipmentUpdateResult
 
-SHIPX_TO_SENDPARCEL_STATUS: dict[str, ShipmentStatus] = {
-    # CREATED
-    "created": ShipmentStatus.CREATED,
+# Non-trivial mappings only: ShipX status strings that don't match the
+# ShipmentStatus enum value. Trivial cases (e.g. "created" → CREATED)
+# are derived from the enum in map_shipx_status().
+_NON_TRIVIAL_STATUS_MAP: dict[str, ShipmentStatus] = {
+    # → CREATED
     "offers_prepared": ShipmentStatus.CREATED,
     "offer_selected": ShipmentStatus.CREATED,
-    # LABEL_READY
+    # → LABEL_READY
     "confirmed": ShipmentStatus.LABEL_READY,
-    # IN_TRANSIT
+    # → IN_TRANSIT
     "dispatched_by_sender": ShipmentStatus.IN_TRANSIT,
     "collected_from_sender": ShipmentStatus.IN_TRANSIT,
     "taken_by_courier": ShipmentStatus.IN_TRANSIT,
     "adopted_at_source_branch": ShipmentStatus.IN_TRANSIT,
     "sent_from_source_branch": ShipmentStatus.IN_TRANSIT,
     "adopted_at_sorting_center": ShipmentStatus.IN_TRANSIT,
-    # OUT_FOR_DELIVERY
-    "out_for_delivery": ShipmentStatus.OUT_FOR_DELIVERY,
+    # → OUT_FOR_DELIVERY
     "ready_to_pickup": ShipmentStatus.OUT_FOR_DELIVERY,
     "pickup_reminder_sent": ShipmentStatus.OUT_FOR_DELIVERY,
     "avizo": ShipmentStatus.OUT_FOR_DELIVERY,
     "stack_in_box_machine": ShipmentStatus.OUT_FOR_DELIVERY,
     "stack_in_customer_service_point": ShipmentStatus.OUT_FOR_DELIVERY,
-    # DELIVERED
-    "delivered": ShipmentStatus.DELIVERED,
-    # CANCELLED
+    # → CANCELLED (ShipX uses US spelling "canceled")
     "canceled": ShipmentStatus.CANCELLED,
-    # RETURNED
+    # → RETURNED
     "returned_to_sender": ShipmentStatus.RETURNED,
-    # FAILED
+    # → FAILED
     "rejected_by_receiver": ShipmentStatus.FAILED,
     "undelivered": ShipmentStatus.FAILED,
     "oversized": ShipmentStatus.FAILED,
@@ -42,9 +41,20 @@ SHIPX_TO_SENDPARCEL_STATUS: dict[str, ShipmentStatus] = {
 def map_shipx_status(shipx_status: str) -> ShipmentStatus | None:
     """Map a ShipX status string to a sendparcel ShipmentStatus.
 
+    Trivial mappings (where the ShipX string matches the enum value) are
+    derived from the ShipmentStatus enum. Non-trivial mappings are looked
+    up in the explicit exceptions dict.
+
     Returns None if the status is not recognized.
     """
-    return SHIPX_TO_SENDPARCEL_STATUS.get(shipx_status)
+    # Check non-trivial mappings first.
+    if shipx_status in _NON_TRIVIAL_STATUS_MAP:
+        return _NON_TRIVIAL_STATUS_MAP[shipx_status]
+    # Try trivial mapping: ShipX status string == enum value.
+    try:
+        return ShipmentStatus(shipx_status)
+    except ValueError:
+        return None
 
 
 def build_shipment_update(

python_sendparcel_inpost-0.2.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-sendparcel_inpost/__init__.py,sha256=iF669tt96Ux4fW-DD2XAIiYEX7_F36gFGxZ9Mui-nzA,460
-sendparcel_inpost/client.py,sha256=wxoCH-7FQc7zdqE2xEXDyBLt-DSdKPHN4s1opTj6YvQ,25607
-sendparcel_inpost/enums.py,sha256=8R0BPxTc_PQdPTjYXMIFlFjNju4X6hL8Xq3EEUe5J94,384
-sendparcel_inpost/exceptions.py,sha256=JRCsLiqLU_u96aVVa5xz9a4MAVBxB6CqR6g_83YyD44,2061
-sendparcel_inpost/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sendparcel_inpost/status_mapping.py,sha256=XPmp-92CUOidLY1EPeL7d0PGDEsqgRAJxK3247y5zWk,2251
-sendparcel_inpost/types.py,sha256=Pu-OJpC6te4_gY6PLv-Ag0o2IoulYytdr9t0FGf4GIA,1426
-sendparcel_inpost/providers/__init__.py,sha256=akn431q6mekenZV5Y4wjCh2UkLSi2s51umBHZ37orJg,336
-sendparcel_inpost/providers/base.py,sha256=dNxSTiE-BrJCCEmTlMVOuriLqpKu1wkMtM8dQspu5C4,12613
-sendparcel_inpost/providers/courier.py,sha256=N-lGvL_6R6wq0nnJUum8wvMwKLjDric8Vv4xODWm5Rg,2799
-sendparcel_inpost/providers/locker.py,sha256=1DG5nPcJGNlJP-ul87U_VBZkvt4VZXKhIws54kYTRe0,3074
-python_sendparcel_inpost-0.2.0.dist-info/METADATA,sha256=XKB409WqD0F3SmgsND_xHd43uy29VUeZ5u9_-WBQGQ0,3446
-python_sendparcel_inpost-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-python_sendparcel_inpost-0.2.0.dist-info/entry_points.txt,sha256=XuQdmE0LIuIc3TvGPWnYjoB14zXCEof6Q8h1tMp2arE,170
-python_sendparcel_inpost-0.2.0.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
-python_sendparcel_inpost-0.2.0.dist-info/RECORD,,

sendparcel_inpost/enums.py

@@ -1,18 +0,0 @@
-"""ShipX-specific enumerations."""
-
-from enum import StrEnum
-
-
-class ShipXService(StrEnum):
-    """ShipX shipment service types."""
-
-    INPOST_LOCKER_STANDARD = "inpost_locker_standard"
-    INPOST_COURIER_STANDARD = "inpost_courier_standard"
-
-
-class ShipXParcelTemplate(StrEnum):
-    """Locker parcel size templates."""
-
-    SMALL = "small"
-    MEDIUM = "medium"
-    LARGE = "large"