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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-sendparcel
-Version: 0.2.0
+Version: 0.3.0
 Summary: Framework-agnostic parcel shipping core for Python.
 Project-URL: Homepage, https://github.com/python-sendparcel/python-sendparcel
 Project-URL: Repository, https://github.com/python-sendparcel/python-sendparcel
@@ -23,12 +23,13 @@ Requires-Python: >=3.12
 Requires-Dist: anyio>=4.0
 Requires-Dist: httpx>=0.27.0
 Provides-Extra: all
-Requires-Dist: django-sendparcel>=0.1.0; extra == 'all'
-Requires-Dist: python-sendparcel-cli>=0.1.0; extra == 'all'
-Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'all'
-Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'all'
+Requires-Dist: django-sendparcel>=0.3.0; extra == 'all'
+Requires-Dist: python-sendparcel-cli>=0.2.0; extra == 'all'
+Requires-Dist: python-sendparcel-dpdpl>=0.1.1; extra == 'all'
+Requires-Dist: python-sendparcel-inpost>=0.3.0; extra == 'all'
+Requires-Dist: python-sendparcel-orlenpaczka>=0.0.1; extra == 'all'
 Provides-Extra: cli
-Requires-Dist: python-sendparcel-cli>=0.1.0; extra == 'cli'
+Requires-Dist: python-sendparcel-cli>=0.2.0; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: pre-commit-hooks>=6.0.0; extra == 'dev'
 Requires-Dist: pre-commit>=4.0; extra == 'dev'
@@ -36,26 +37,30 @@ Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: trio>=0.27; extra == 'dev'
 Requires-Dist: ty>=0.0.16; extra == 'dev'
 Provides-Extra: django
-Requires-Dist: django-sendparcel>=0.1.0; extra == 'django'
+Requires-Dist: django-sendparcel>=0.3.0; extra == 'django'
 Provides-Extra: dpdpl
-Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'dpdpl'
+Requires-Dist: python-sendparcel-dpdpl>=0.1.1; extra == 'dpdpl'
 Provides-Extra: dummy
 Provides-Extra: frameworks
-Requires-Dist: django-sendparcel>=0.1.0; extra == 'frameworks'
+Requires-Dist: django-sendparcel>=0.3.0; extra == 'frameworks'
 Provides-Extra: inpost
-Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'inpost'
+Requires-Dist: python-sendparcel-inpost>=0.3.0; extra == 'inpost'
+Provides-Extra: orlenpaczka
+Requires-Dist: python-sendparcel-orlenpaczka>=0.0.1; extra == 'orlenpaczka'
 Provides-Extra: providers
-Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'providers'
-Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'providers'
+Requires-Dist: python-sendparcel-dpdpl>=0.1.1; extra == 'providers'
+Requires-Dist: python-sendparcel-inpost>=0.3.0; extra == 'providers'
+Requires-Dist: python-sendparcel-orlenpaczka>=0.0.1; extra == 'providers'
 Description-Content-Type: text/markdown
 
 # python-sendparcel
 
 Framework-agnostic parcel shipping core for Python.
 
-> Alpha notice: `0.1.1` is still unstable. The API can change fast because the
+> Alpha notice: `0.3.0` is still unstable. The API can change fast because the
 > ecosystem is still being cleaned up.
 
 ## What it is
@@ -120,6 +125,12 @@ class InMemoryRepository:
         self._store[shipment.id] = shipment
         return shipment
 
+    async def update_fields(self, shipment_id: str, **fields) -> MyShipment:
+        shipment = self._store[shipment_id]
+        for key, value in fields.items():
+            setattr(shipment, key, value)
+        return shipment
+
 
 async def main() -> None:
     flow = ShipmentFlow(repository=InMemoryRepository())
@@ -156,15 +167,20 @@ anyio.run(main)
 
 ## Provider model
 
-- `BaseProvider.create_shipment(...)` returns `ShipmentCreateResult`.
+All providers subclass `BaseProvider`; capability methods raise
+`ProviderCapabilityError` unless overridden:
+
+- `BaseProvider.create_shipment(...)` returns `ShipmentCreateResult` (required).
 - `BaseProvider.confirmation_method` defaults to `ConfirmationMethod.NONE`.
-- `LabelProvider.create_label(...)` returns `LabelInfo`.
-- `PushCallbackProvider.handle_callback(...)` returns `ShipmentUpdateResult`.
-- `PullStatusProvider.fetch_shipment_status(...)` returns `ShipmentUpdateResult`.
-- `CancellableProvider.cancel_shipment(...)` returns `bool`.
+- `BaseProvider.create_label(...)` returns `LabelInfo`.
+- `BaseProvider.verify_callback(ctx)` / `handle_callback(ctx)` return
+  `None` / `ShipmentUpdateResult`.
+- `BaseProvider.fetch_shipment_status(...)` returns `ShipmentUpdateResult`.
+- `BaseProvider.cancel_shipment(...)` returns `bool`.
 
-Use `ConfirmationMethod.PUSH` only with `PushCallbackProvider` and
-`ConfirmationMethod.PULL` only with `PullStatusProvider`.
+Use `ConfirmationMethod.PUSH` only when the callback methods are overridden
+and `ConfirmationMethod.PULL` only when `fetch_shipment_status` is. See
+`docs/provider-authoring.md` for the full guide.
 
 The core owns shipment state transitions. Providers translate carrier responses
 into normalized results.
@@ -184,10 +200,9 @@ uv add python-sendparcel
 ## Extras
 
 - `django`
-- `fastapi`
-- `litestar`
 - `inpost`
 - `dpdpl`
+- `orlenpaczka`
 - `cli`
 - `frameworks`
 - `providers`
@@ -198,6 +213,8 @@ uv add python-sendparcel
 ```bash
 uv sync --extra dev
 uv run pytest
-uv run ruff check src tests
-uv run mypy src tests
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+uv run mypy src
 ```

python_sendparcel-0.3.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+sendparcel/__init__.py,sha256=OZbB9xNjPbJvnKnaqHv4Ds7-IFc-M8sbjSgkszdNNE8,1521
+sendparcel/batch.py,sha256=4K3PgCOtV2QUNRqH_DuuhqbSYwIiNe-mSk6HKNORsmA,9332
+sendparcel/concurrent.py,sha256=RFkuIjL9XehDqBc2cHXivbzYlJtR_9ZxjAqO5_hxJzY,2082
+sendparcel/enums.py,sha256=e1UM9ka5zWJg4naMCoVeUrIy_PVPPEYHOBh6XiXaW4Q,687
+sendparcel/exceptions.py,sha256=zC5_o9oQfNuOBKaiw5csaHAJmhYsZc3WVbOaoq7s1W0,1437
+sendparcel/factory.py,sha256=VVB8Kz3J-7QI-VjrJsMwKso5SVZf97yZBX5nMbnCMM4,1045
+sendparcel/flow.py,sha256=6NED69FuqrvoVVXMk6P2V1RymLX_4V3-KIm7Ch2aAXk,10360
+sendparcel/fsm.py,sha256=bRkt8tj_mg71Wq8obhhKK6nrQuN2a4Y_YXiL7kYxPDU,3134
+sendparcel/logging.py,sha256=TOetzdKJtl6YIY9Dpq-uxWB-jituOEKx0DpWmGrrBMU,4256
+sendparcel/protocols.py,sha256=7YX2KTOEG5Nje6bzibmIODFiTX7tgqb6I3WYgx9uVS4,2344
+sendparcel/provider.py,sha256=H28ZjvBpHY4C3LBvSm7DYa645300N4k2-X2fvl0epqc,8201
+sendparcel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sendparcel/registry.py,sha256=CCaU7Esd6vS5eVvvv_oLuWEhd9j17Zk3-hEOZl-_7Vk,3790
+sendparcel/types.py,sha256=nNECD7J6WZSlB8-SXnkperAW3d5zmKOM-9l-u9dZ5mk,3042
+sendparcel/providers/__init__.py,sha256=ff82dvrWuPS-UIGF5AoX_fgpcYZaGu2k6q2yrxMZacI,192
+sendparcel/providers/dummy.py,sha256=J_FOzy0NsgKeI3Zxe0vTfPBdVeVSXKGd_zyMWfBL58Q,2836
+python_sendparcel-0.3.0.dist-info/METADATA,sha256=UJGCgut2oKHrg8P6HylzOvU2LeWCLE7l-0aoAoOCEpQ,7175
+python_sendparcel-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_sendparcel-0.3.0.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
+python_sendparcel-0.3.0.dist-info/RECORD,,

sendparcel/__init__.py

@@ -1,6 +1,6 @@
 """sendparcel core package."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from sendparcel.batch import BatchCreateResult, BatchResult, ShipmentBatch
 from sendparcel.enums import ConfirmationMethod, LabelFormat, ShipmentStatus
@@ -13,18 +13,14 @@ from sendparcel.exceptions import (
     SendParcelException,
     ShipmentNotFoundError,
 )
+from sendparcel.factory import create_provider
 from sendparcel.flow import ShipmentFlow
 from sendparcel.logging import configure_logging, get_logger
-from sendparcel.provider import (
-    BaseProvider,
-    CancellableProvider,
-    LabelProvider,
-    PullStatusProvider,
-    PushCallbackProvider,
-)
+from sendparcel.provider import BaseProvider
 from sendparcel.providers.dummy import DummyProvider
 from sendparcel.registry import registry
 from sendparcel.types import (
+    CallbackContext,
     CreateLabelOutcome,
     CreateShipmentOutcome,
     ShipmentUpdateOutcome,
@@ -35,7 +31,7 @@ __all__ = [
     "BaseProvider",
     "BatchCreateResult",
     "BatchResult",
-    "CancellableProvider",
+    "CallbackContext",
     "CommunicationError",
     "ConfirmationMethod",
     "CreateLabelOutcome",
@@ -44,11 +40,8 @@ __all__ = [
     "InvalidCallbackError",
     "InvalidTransitionError",
     "LabelFormat",
-    "LabelProvider",
     "ProviderCapabilityError",
     "ProviderNotFoundError",
-    "PullStatusProvider",
-    "PushCallbackProvider",
     "SendParcelException",
     "ShipmentBatch",
     "ShipmentFlow",
@@ -58,6 +51,7 @@ __all__ = [
     "ShipmentUpdateResult",
     "__version__",
     "configure_logging",
+    "create_provider",
     "get_logger",
     "registry",
 ]

sendparcel/batch.py

@@ -28,14 +28,15 @@ Usage::
 
 from __future__ import annotations
 
-import asyncio
 from dataclasses import dataclass, field
 from typing import Any
 
+from sendparcel.concurrent import ConcurrentExecutor, ConcurrentResult
 from sendparcel.flow import ShipmentFlow
 from sendparcel.logging import get_logger
 from sendparcel.protocols import ShipmentRepository
 from sendparcel.registry import PluginRegistry
+from sendparcel.registry import registry as default_registry
 
 logger = get_logger(__name__)
 
@@ -80,12 +81,25 @@ class BatchCreateResult:
         }
 
 
+def _to_batch_result(res: ConcurrentResult) -> BatchResult:
+    """Convert a ConcurrentResult to a BatchResult."""
+    if res.success:
+        result: BatchResult = res.value
+        return result
+    return BatchResult(
+        index=res.index,
+        success=False,
+        error=res.error,
+    )
+
+
 class ShipmentBatch:
     """Batch shipment operations.
 
     Provides efficient batch creation, status fetching, and cancellation
-    of shipments. All operations are atomic within the batch — if one
-    shipment fails, the others are still processed.
+    of shipments. Operations are independent — if one shipment fails,
+    the others are still processed. There is no cross-shipment
+    transaction or rollback.
 
     Args:
         repository: Shipment repository for persisting results.
@@ -104,8 +118,8 @@ class ShipmentBatch:
     ) -> None:
         self.repository = repository
         self.config = config or {}
-        self.registry = registry or PluginRegistry()
-        self.max_concurrent = max_concurrent
+        self.registry = registry or default_registry
+        self._executor = ConcurrentExecutor(max_concurrent)
 
     async def create_shipments(
         self,
@@ -126,29 +140,23 @@ class ShipmentBatch:
         Returns:
             BatchCreateResult with per-shipment results.
         """
-        semaphore = asyncio.Semaphore(self.max_concurrent)
 
-        async def _create_one(
-            index: int, shipment_data: dict[str, Any]
-        ) -> BatchResult:
-            async with semaphore:
-                return await self._create_single_shipment(index, shipment_data)
+        async def _create_one(data: dict[str, Any], index: int) -> BatchResult:
+            return await self._create_single_shipment(index, data)
 
-        results = await asyncio.gather(
-            *(_create_one(i, d) for i, d in enumerate(shipments))
+        concurrent_results = await self._executor.execute(
+            shipments, _create_one
         )
+        batch_results = [_to_batch_result(r) for r in concurrent_results]
 
-        successful = sum(1 for r in results if r.success)
-        failed = sum(1 for r in results if not r.success)
-
-        # Sort by original index to preserve input order.
-        results.sort(key=lambda r: r.index)
+        successful = sum(1 for r in batch_results if r.success)
+        failed = sum(1 for r in batch_results if not r.success)
 
         return BatchCreateResult(
             total=len(shipments),
             successful=successful,
             failed=failed,
-            results=results,
+            results=batch_results,
         )
 
     async def _create_single_shipment(
@@ -228,36 +236,33 @@ class ShipmentBatch:
         Returns:
             List of BatchResult with per-shipment status updates.
         """
-        semaphore = asyncio.Semaphore(self.max_concurrent)
-
-        async def _fetch_one(index: int, sid: str) -> BatchResult:
-            async with semaphore:
-                try:
-                    shipment = await self.repository.get_by_id(sid)
-                    flow = ShipmentFlow(
-                        repository=self.repository,
-                        config=self.config,
-                        registry=self.registry,
-                    )
-                    outcome = await flow.fetch_and_update_status(shipment)
-                    return BatchResult(
-                        index=index,
-                        success=True,
-                        shipment=outcome.shipment,
-                        outcome=outcome,
-                    )
-                except Exception as exc:
-                    return BatchResult(
-                        index=index,
-                        success=False,
-                        error=str(exc),
-                    )
 
-        results = await asyncio.gather(
-            *(_fetch_one(i, sid) for i, sid in enumerate(shipment_ids))
+        async def _fetch_one(sid: str, index: int) -> BatchResult:
+            try:
+                shipment = await self.repository.get_by_id(sid)
+                flow = ShipmentFlow(
+                    repository=self.repository,
+                    config=self.config,
+                    registry=self.registry,
+                )
+                outcome = await flow.fetch_and_update_status(shipment)
+                return BatchResult(
+                    index=index,
+                    success=True,
+                    shipment=outcome.shipment,
+                    outcome=outcome,
+                )
+            except Exception as exc:
+                return BatchResult(
+                    index=index,
+                    success=False,
+                    error=str(exc),
+                )
+
+        concurrent_results = await self._executor.execute(
+            shipment_ids, _fetch_one
         )
-        results.sort(key=lambda r: r.index)
-        return results
+        return [_to_batch_result(r) for r in concurrent_results]
 
     async def cancel_shipments(
         self,
@@ -271,33 +276,30 @@ class ShipmentBatch:
         Returns:
             List of BatchResult with per-shipment cancellation results.
         """
-        semaphore = asyncio.Semaphore(self.max_concurrent)
-
-        async def _cancel_one(index: int, sid: str) -> BatchResult:
-            async with semaphore:
-                try:
-                    shipment = await self.repository.get_by_id(sid)
-                    flow = ShipmentFlow(
-                        repository=self.repository,
-                        config=self.config,
-                        registry=self.registry,
-                    )
-                    cancelled = await flow.cancel_shipment(shipment)
-                    return BatchResult(
-                        index=index,
-                        success=True,
-                        shipment=shipment,
-                        outcome={"cancelled": cancelled},
-                    )
-                except Exception as exc:
-                    return BatchResult(
-                        index=index,
-                        success=False,
-                        error=str(exc),
-                    )
 
-        results = await asyncio.gather(
-            *(_cancel_one(i, sid) for i, sid in enumerate(shipment_ids))
+        async def _cancel_one(sid: str, index: int) -> BatchResult:
+            try:
+                shipment = await self.repository.get_by_id(sid)
+                flow = ShipmentFlow(
+                    repository=self.repository,
+                    config=self.config,
+                    registry=self.registry,
+                )
+                cancelled = await flow.cancel_shipment(shipment)
+                return BatchResult(
+                    index=index,
+                    success=True,
+                    shipment=shipment,
+                    outcome={"cancelled": cancelled},
+                )
+            except Exception as exc:
+                return BatchResult(
+                    index=index,
+                    success=False,
+                    error=str(exc),
+                )
+
+        concurrent_results = await self._executor.execute(
+            shipment_ids, _cancel_one
         )
-        results.sort(key=lambda r: r.index)
-        return results
+        return [_to_batch_result(r) for r in concurrent_results]

sendparcel/concurrent.py

@@ -0,0 +1,71 @@
+"""Generic concurrent executor with semaphore-based concurrency control."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+import anyio
+
+T = TypeVar("T")
+
+
+@dataclass
+class ConcurrentResult:
+    """Result of a single concurrent operation."""
+
+    index: int
+    success: bool
+    value: Any = None
+    error: str | None = None
+
+
+class ConcurrentExecutor:
+    """Executes async callables with bounded concurrency.
+
+    Backend-agnostic: uses anyio primitives, so it runs under both
+    asyncio and trio.
+    """
+
+    def __init__(self, max_concurrent: int = 5) -> None:
+        self._max_concurrent = max_concurrent
+
+    async def execute(
+        self,
+        items: list[Any],
+        operation: Callable[[Any, int], Coroutine[Any, Any, T]],
+    ) -> list[ConcurrentResult]:
+        """Execute operation on each item with bounded concurrency.
+
+        Args:
+            items: List of items to process.
+            operation: Async callable(item, index) -> result.
+
+        Returns:
+            List of ConcurrentResult in the same order as items.
+        """
+        semaphore = anyio.Semaphore(self._max_concurrent)
+        results: list[ConcurrentResult | None] = [None] * len(items)
+
+        async def _run(index: int, item: Any) -> None:
+            async with semaphore:
+                try:
+                    value = await operation(item, index)
+                    results[index] = ConcurrentResult(
+                        index=index,
+                        success=True,
+                        value=value,
+                    )
+                except Exception as exc:
+                    results[index] = ConcurrentResult(
+                        index=index,
+                        success=False,
+                        error=str(exc),
+                    )
+
+        async with anyio.create_task_group() as tg:
+            for i, item in enumerate(items):
+                tg.start_soon(_run, i, item)
+
+        return [r for r in results if r is not None]

sendparcel/factory.py

@@ -0,0 +1,33 @@
+"""Provider factory — wires providers with their transports."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sendparcel.protocols import Shipment
+from sendparcel.provider import BaseProvider
+
+
+def create_provider(
+    shipment: Shipment,
+    provider_class: type[BaseProvider],
+    config: dict[str, Any],
+) -> BaseProvider:
+    """Wire a provider with its transport from config.
+
+    Uses ``provider_class.transport_factory`` to build the transport.
+    No provider-specific logic — fully generic.
+
+    Args:
+        shipment: The shipment the provider will operate on.
+        provider_class: The provider class to instantiate.
+        config: Provider configuration dict (from framework settings).
+
+    Returns:
+        A provider instance with transport injected.
+    """
+    factory = getattr(provider_class, "transport_factory", None)
+    if factory is not None:
+        transport = factory(**config)
+        return provider_class(shipment, config, transport=transport)
+    return provider_class(shipment, config)

sendparcel/flow.py

@@ -9,29 +9,22 @@ import httpx
 from sendparcel.enums import ShipmentStatus
 from sendparcel.exceptions import (
     CommunicationError,
-    ProviderCapabilityError,
     SendParcelException,
 )
 from sendparcel.fsm import transition_shipment
 from sendparcel.protocols import Shipment, ShipmentRepository
-from sendparcel.provider import (
-    BaseProvider,
-    CancellableProvider,
-    LabelProvider,
-    PullStatusProvider,
-    PushCallbackProvider,
-)
+from sendparcel.provider import BaseProvider
 from sendparcel.registry import PluginRegistry
 from sendparcel.registry import registry as default_registry
 from sendparcel.types import (
     AddressInfo,
+    CallbackContext,
     CreateLabelOutcome,
     CreateShipmentOutcome,
     ParcelInfo,
     ShipmentUpdateOutcome,
     ShipmentUpdateResult,
 )
-from sendparcel.validators import run_validators
 
 
 class ShipmentFlow:
@@ -41,12 +34,10 @@ class ShipmentFlow:
         self,
         repository: ShipmentRepository,
         config: dict[str, Any] | None = None,
-        validators: list[Any] | None = None,
         registry: PluginRegistry | None = None,
     ) -> None:
         self.repository = repository
         self.config = config or {}
-        self.validators = validators or []
         self.registry = registry or default_registry
 
     async def create_shipment(
@@ -92,7 +83,7 @@ class ShipmentFlow:
 
         # Separate repository kwargs from provider kwargs.
         repo_kwargs: dict[str, Any] = {}
-        for key in ("reference_id",):
+        for key in ("reference_id", "order"):
             if key in kwargs:
                 repo_kwargs[key] = kwargs.pop(key)
 
@@ -162,13 +153,7 @@ class ShipmentFlow:
     ) -> CreateLabelOutcome:
         """Create provider label and persist shipment metadata."""
 
-        run_validators({"shipment": shipment}, validators=self.validators)
         provider = self._get_provider(shipment)
-        if not isinstance(provider, LabelProvider):
-            raise ProviderCapabilityError(
-                f"Provider {shipment.provider!r} does not support "
-                "label creation"
-            )
         label = await self._call_provider(provider.create_label(**kwargs))
         transition_shipment(shipment, ShipmentStatus.LABEL_READY)
         saved = await self.repository.update_fields(
@@ -178,25 +163,21 @@ class ShipmentFlow:
 
     async def handle_callback(
         self,
-        shipment: Shipment,
-        data: dict[str, Any],
-        headers: dict[str, Any],
-        **kwargs: Any,
+        ctx: CallbackContext,
+        *,
+        shipment: Shipment | None = None,
     ) -> ShipmentUpdateOutcome:
-        """Verify and apply provider callback."""
+        """Verify and apply provider callback.
 
+        The caller is responsible for loading the shipment (from
+        ``ctx.shipment_id``) and passing it in. If ``shipment`` is not
+        provided, it will be loaded from the repository.
+        """
+        if shipment is None:
+            shipment = await self.repository.get_by_id(ctx.shipment_id)
         provider = self._get_provider(shipment)
-        if not isinstance(provider, PushCallbackProvider):
-            raise ProviderCapabilityError(
-                f"Provider {shipment.provider!r} does not support "
-                "push callbacks"
-            )
-        await self._call_provider(
-            provider.verify_callback(data, headers, **kwargs)
-        )
-        update = await self._call_provider(
-            provider.handle_callback(data, headers, **kwargs)
-        )
+        await self._call_provider(provider.verify_callback(ctx))
+        update = await self._call_provider(provider.handle_callback(ctx))
         normalized_update = update or ShipmentUpdateResult()
         saved = await self._apply_update(shipment, normalized_update)
         return ShipmentUpdateOutcome(shipment=saved, update=normalized_update)
@@ -207,11 +188,6 @@ class ShipmentFlow:
         """Fetch status from provider and persist."""
 
         provider = self._get_provider(shipment)
-        if not isinstance(provider, PullStatusProvider):
-            raise ProviderCapabilityError(
-                f"Provider {shipment.provider!r} does not support "
-                "status polling"
-            )
         update = await self._call_provider(provider.fetch_shipment_status())
         normalized_update = update or ShipmentUpdateResult()
         saved = await self._apply_update(shipment, normalized_update)
@@ -221,10 +197,6 @@ class ShipmentFlow:
         """Cancel shipment via provider and persist state."""
 
         provider = self._get_provider(shipment)
-        if not isinstance(provider, CancellableProvider):
-            raise ProviderCapabilityError(
-                f"Provider {shipment.provider!r} does not support cancellation"
-            )
         cancelled = await self._call_provider(
             provider.cancel_shipment(**kwargs)
         )
@@ -236,9 +208,11 @@ class ShipmentFlow:
         return bool(cancelled)
 
     def _get_provider(self, shipment: Shipment) -> BaseProvider:
+        from sendparcel.factory import create_provider
+
         provider_class = self.registry.get_by_slug(shipment.provider)
         provider_config = self.config.get(shipment.provider, {})
-        return provider_class(shipment, config=provider_config)
+        return create_provider(shipment, provider_class, provider_config)
 
     async def _apply_update(
         self, shipment: Shipment, update: ShipmentUpdateResult

sendparcel/fsm.py

@@ -6,7 +6,7 @@ from sendparcel.enums import ShipmentStatus
 from sendparcel.exceptions import InvalidTransitionError
 from sendparcel.protocols import Shipment
 
-ALLOWED_STATUS_TRANSITIONS: dict[ShipmentStatus, frozenset[ShipmentStatus]] = {
+_ALLOWED_TRANSITIONS: dict[ShipmentStatus, frozenset[ShipmentStatus]] = {
     ShipmentStatus.NEW: frozenset(
         {
             ShipmentStatus.CREATED,
@@ -64,7 +64,7 @@ ALLOWED_STATUS_TRANSITIONS: dict[ShipmentStatus, frozenset[ShipmentStatus]] = {
 }
 
 
-def normalize_status(status: str | ShipmentStatus) -> ShipmentStatus:
+def _normalize(status: str | ShipmentStatus) -> ShipmentStatus:
     """Normalise a status to a :class:`ShipmentStatus` enum member."""
 
     try:
@@ -81,11 +81,11 @@ def can_transition(
 ) -> bool:
     """Check whether a shipment status transition is allowed."""
 
-    current = normalize_status(current_status)
-    target = normalize_status(target_status)
+    current = _normalize(current_status)
+    target = _normalize(target_status)
     if current == target:
         return True
-    return target in ALLOWED_STATUS_TRANSITIONS[current]
+    return target in _ALLOWED_TRANSITIONS[current]
 
 
 def transition_shipment(
@@ -93,12 +93,12 @@ def transition_shipment(
 ) -> Shipment:
     """Apply a validated status transition to a shipment."""
 
-    current = normalize_status(shipment.status)
-    target = normalize_status(target_status)
+    current = _normalize(shipment.status)
+    target = _normalize(target_status)
     if current == target:
         shipment.status = target.value
         return shipment
-    if target not in ALLOWED_STATUS_TRANSITIONS[current]:
+    if target not in _ALLOWED_TRANSITIONS[current]:
         raise InvalidTransitionError(
             f"Shipment cannot transition from {current!r} to {target!r}"
         )

sendparcel/logging.py

@@ -29,19 +29,6 @@ from datetime import UTC, datetime
 from typing import Any
 
 
-def _format_extra(extra: dict[str, Any] | None) -> dict[str, Any]:
-    """Convert extra fields to a serializable dict."""
-    if not extra:
-        return {}
-    result: dict[str, Any] = {}
-    for k, v in extra.items():
-        if isinstance(v, (str, int, float, bool, type(None))):
-            result[k] = v
-        else:
-            result[k] = str(v)
-    return result
-
-
 class _JsonFormatter(logging.Formatter):
     """JSON formatter for structured logging.
 
@@ -49,7 +36,7 @@ class _JsonFormatter(logging.Formatter):
     """
 
     def format(self, record: logging.LogRecord) -> str:
-        extra = _format_extra(getattr(record, "extra", None))
+        extra = getattr(record, "extra", None) or {}
         log_entry: dict[str, Any] = {
             "timestamp": datetime.now(UTC).isoformat(),
             "level": record.levelname,
@@ -67,11 +54,10 @@ class _HumanFormatter(logging.Formatter):
     """Human-readable formatter for development."""
 
     def format(self, record: logging.LogRecord) -> str:
-        extra = _format_extra(getattr(record, "extra", None))
-        extra_str = " ".join(f"{k}={v}" for k, v in extra.items())
-        msg = record.getMessage()
-        if extra_str:
-            msg = f"{msg} {extra_str}"
+        extra = getattr(record, "extra", None) or {}
+        if extra:
+            extra_str = " ".join(f"{k}={v}" for k, v in extra.items())
+            record.msg = f"{record.msg} {extra_str}"
         return super().format(record)
 
 
@@ -149,7 +135,3 @@ def get_logger(
 # ``sendparcel.configure_logging()`` explicitly from your application
 # startup code (e.g. Django ``AppConfig.ready()``) to enable structured
 # logging for the sendparcel packages.
-#
-# Alias for backwards compatibility with any code that imported
-# ``_configure_structured_logging`` directly (pre-0.1.2).
-_configure_structured_logging = configure_logging

sendparcel/provider.py

@@ -1,14 +1,17 @@
-"""Base provider abstraction and capability trait mixins."""
+"""Base provider abstraction."""
 
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from typing import Any, ClassVar
 
 from sendparcel.enums import ConfirmationMethod
+from sendparcel.exceptions import ProviderCapabilityError
 from sendparcel.protocols import Shipment
 from sendparcel.types import (
     AddressInfo,
+    CallbackContext,
     LabelInfo,
     ParcelInfo,
     ShipmentCreateResult,
@@ -17,7 +20,17 @@ from sendparcel.types import (
 
 
 class BaseProvider(ABC):
-    """Base class for parcel delivery providers."""
+    """Base class for parcel delivery providers.
+
+    Capability methods (``create_label``, ``handle_callback``,
+    ``fetch_shipment_status``, ``cancel_shipment``) raise
+    :exc:`ProviderCapabilityError` by default.  Override only the
+    methods the provider supports.
+
+    The flow orchestrator calls capability methods directly — no
+    ``isinstance`` trait checks.  If a provider doesn't support a
+    capability, the default implementation raises.
+    """
 
     slug: ClassVar[str] = ""
     display_name: ClassVar[str] = ""
@@ -26,18 +39,138 @@ class BaseProvider(ABC):
     confirmation_method: ClassVar[ConfirmationMethod] = ConfirmationMethod.NONE
     user_selectable: ClassVar[bool] = True
     config_schema: ClassVar[dict[str, Any]] = {}
+    transport_factory: ClassVar[Callable[..., Any] | None] = None
+    """Callable that builds a transport from config dict.
+    Signature: transport_factory(**config) -> transport.
+    None means the provider doesn't need HTTP transport (e.g. DummyProvider).
+    """
 
     def __init__(
-        self, shipment: Shipment, config: dict[str, Any] | None = None
+        self,
+        shipment: Shipment,
+        config: dict[str, Any] | None = None,
+        *,
+        transport: Any = None,
     ) -> None:
         self.shipment = shipment
         self.config = config or {}
+        self._transport = transport
+        if self.config_schema:
+            self._validate_config()
 
     def get_setting(self, name: str, default: Any = None) -> Any:
         """Read provider setting from config."""
-
         return self.config.get(name, default)
 
+    def _get_client(self) -> Any:
+        """Return the injected transport, or raise if not configured."""
+        if self._transport is None:
+            raise RuntimeError(
+                f"{self.__class__.__name__} requires a transport. "
+                "Use create_provider() to wire the provider."
+            )
+        return self._transport
+
+    def _validate_config(self) -> None:
+        """Validate configuration against config_schema."""
+        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"{self.__class__.__name__} requires "
+                    f"'{field_name}' in config."
+                )
+            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"{self.__class__.__name__} config '{field_name}' "
+                        f"must be {expected_type}, got {type(value).__name__}"
+                    )
+
+    def _address_to_provider(
+        self,
+        addr: AddressInfo,
+        *,
+        field_format: str = "snake",
+    ) -> dict[str, Any]:
+        """Convert AddressInfo to provider-specific address dict.
+
+        field_format: 'snake' (default), 'camel', 'pascal'
+        Subclasses can override _address_format ClassVar to set their default.
+        """
+        fmt = getattr(self, "_address_format", field_format)
+
+        def _convert(key: str) -> str:
+            if fmt == "camel":
+                parts = key.split("_")
+                return parts[0] + "".join(p.capitalize() for p in parts[1:])
+            elif fmt == "pascal":
+                return "".join(p.capitalize() for p in key.split("_"))
+            return key  # snake
+
+        result: dict[str, Any] = {}
+
+        # Map common fields
+        field_mappings = [
+            ("company", "company"),
+            ("first_name", "first_name"),
+            ("last_name", "last_name"),
+            ("name", "name"),
+            ("street", "street"),
+            ("building_number", "building_number"),
+            ("flat_number", "flat_number"),
+            ("line1", "line1"),
+            ("city", "city"),
+            ("country_code", "country_code"),
+            ("postal_code", "postal_code"),
+            ("phone", "phone"),
+            ("email", "email"),
+        ]
+
+        for src, dst in field_mappings:
+            value = addr.get(src)
+            if value:
+                result[_convert(dst)] = value
+
+        return result
+
+    def _parcels_to_provider(
+        self,
+        parcels: list[ParcelInfo],
+    ) -> list[dict[str, Any]]:
+        """Convert ParcelInfo list to provider-specific parcel dicts."""
+        result = []
+        for parcel in parcels:
+            p: dict[str, Any] = {}
+            weight = parcel.get("weight_kg")
+            if weight is not None:
+                p["weight"] = float(weight)
+
+            length = parcel.get("length_cm")
+            width = parcel.get("width_cm")
+            height = parcel.get("height_cm")
+            if length:
+                p["length"] = float(length)
+            if width:
+                p["width"] = float(width)
+            if height:
+                p["height"] = float(height)
+
+            result.append(p)
+
+        return result or [{"weight": 1.0}]
+
     @abstractmethod
     async def create_shipment(
         self,
@@ -49,44 +182,61 @@ class BaseProvider(ABC):
     ) -> ShipmentCreateResult:
         """Create shipment in provider API."""
 
-
-class LabelProvider(ABC):
-    """Trait for providers that support label generation."""
-
-    @abstractmethod
     async def create_label(self, **kwargs: Any) -> LabelInfo:
-        """Create or fetch label payload for a shipment."""
-
-
-class PushCallbackProvider(ABC):
-    """Trait for providers that receive push notifications."""
-
-    @abstractmethod
-    async def verify_callback(
-        self, data: dict[str, Any], headers: dict[str, Any], **kwargs: Any
-    ) -> None:
-        """Verify callback authenticity."""
+        """Create or fetch label payload for a shipment.
+
+        Raises :exc:`ProviderCapabilityError` if the provider does not
+        support label generation.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "label creation"
+        )
+
+    async def verify_callback(self, ctx: CallbackContext) -> None:
+        """Verify callback authenticity.
+
+        Raises :exc:`ProviderCapabilityError` if the provider does not
+        support push callbacks.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "push callbacks"
+        )
 
-    @abstractmethod
     async def handle_callback(
-        self, data: dict[str, Any], headers: dict[str, Any], **kwargs: Any
+        self, ctx: CallbackContext
     ) -> ShipmentUpdateResult:
-        """Normalize callback data into a shipment update payload."""
-
+        """Normalize callback data into a shipment update payload.
 
-class PullStatusProvider(ABC):
-    """Trait for providers that support status polling."""
+        Raises :exc:`ProviderCapabilityError` if the provider does not
+        support push callbacks.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "push callbacks"
+        )
 
-    @abstractmethod
     async def fetch_shipment_status(
         self, **kwargs: Any
     ) -> ShipmentUpdateResult:
-        """Fetch latest shipment update from provider."""
+        """Fetch latest shipment update from provider.
 
+        Raises :exc:`ProviderCapabilityError` if the provider does not
+        support status polling.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "status polling"
+        )
 
-class CancellableProvider(ABC):
-    """Trait for providers that support shipment cancellation."""
-
-    @abstractmethod
     async def cancel_shipment(self, **kwargs: Any) -> bool:
-        """Cancel shipment if provider supports cancellation."""
+        """Cancel shipment if provider supports cancellation.
+
+        Raises :exc:`ProviderCapabilityError` if the provider does not
+        support cancellation.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "cancellation"
+        )

sendparcel/providers/dummy.py

@@ -8,15 +8,10 @@ import anyio
 
 from sendparcel.enums import ConfirmationMethod, LabelFormat
 from sendparcel.exceptions import InvalidCallbackError
-from sendparcel.provider import (
-    BaseProvider,
-    CancellableProvider,
-    LabelProvider,
-    PullStatusProvider,
-    PushCallbackProvider,
-)
+from sendparcel.provider import BaseProvider
 from sendparcel.types import (
     AddressInfo,
+    CallbackContext,
     LabelInfo,
     ParcelInfo,
     ShipmentCreateResult,
@@ -24,13 +19,7 @@ from sendparcel.types import (
 )
 
 
-class DummyProvider(
-    BaseProvider,
-    LabelProvider,
-    PushCallbackProvider,
-    PullStatusProvider,
-    CancellableProvider,
-):
+class DummyProvider(BaseProvider):
     """Reference provider for local, development, and test usage."""
 
     slug: ClassVar[str] = "dummy"
@@ -66,19 +55,17 @@ class DummyProvider(
         await self._simulate_latency()
         return LabelInfo(format=LabelFormat.PDF, url=self._label_url())
 
-    async def verify_callback(
-        self, data: dict[str, Any], headers: dict[str, Any], **kwargs: Any
-    ) -> None:
+    async def verify_callback(self, ctx: CallbackContext) -> None:
         expected = self.get_setting("callback_token", "dummy-token")
-        provided = headers.get("x-dummy-token", "")
+        provided = ctx.headers.get("x-dummy-token", "")
         if provided != expected:
             raise InvalidCallbackError("BAD TOKEN")
 
     async def handle_callback(
-        self, data: dict[str, Any], headers: dict[str, Any], **kwargs: Any
+        self, ctx: CallbackContext
     ) -> ShipmentUpdateResult:
         await self._simulate_latency()
-        status_value = data.get("status")
+        status_value = ctx.payload.get("status")
         if not status_value:
             return ShipmentUpdateResult()
         return ShipmentUpdateResult(status=str(status_value))

sendparcel/registry.py

@@ -62,6 +62,15 @@ class PluginRegistry:
             except KeyError as exc:
                 raise ProviderNotFoundError(slug) from exc
 
+    def slugs(self) -> list[str]:
+        """Get all registered provider slugs.
+
+        Thread-safe.
+        """
+        self._ensure_discovered()
+        with self._lock:
+            return list(self._providers)
+
     def get_choices(self) -> list[tuple[str, str]]:
         """Get provider slug/display pairs for user-facing selection.
 

sendparcel/types.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
+import hashlib
+import json
 from dataclasses import dataclass
 from decimal import Decimal
-from typing import TypedDict
+from typing import Any, TypedDict
 
 from sendparcel.enums import LabelFormat
 from sendparcel.protocols import Shipment
@@ -81,9 +83,6 @@ class ShipmentUpdateResult(TypedDict, total=False):
     tracking_events: list[TrackingEvent]
 
 
-ShipmentStatusResponse = ShipmentUpdateResult
-
-
 @dataclass(frozen=True, slots=True)
 class CreateShipmentOutcome:
     """Flow result for shipment creation."""
@@ -106,3 +105,31 @@ class ShipmentUpdateOutcome:
 
     shipment: Shipment
     update: ShipmentUpdateResult
+
+
+@dataclass(slots=True)
+class CallbackContext:
+    """Everything needed to process a webhook callback.
+
+    Framework layers build this in one place. Core operates on it.
+    The retry store persists this as a single blob.
+
+    The ``dedup_hash`` is computed from the payload alone (not headers
+    or source_ip) so that legitimate re-submissions of the same callback
+    data are deduplicated regardless of transport metadata.
+    """
+
+    shipment_id: str
+    payload: dict[str, Any]
+    headers: dict[str, str]
+    source_ip: str
+    raw_body: bytes
+    provider_slug: str = ""
+
+    @property
+    def dedup_hash(self) -> str:
+        """Deterministic SHA-256 hash of the payload for dedup checks."""
+        raw = json.dumps(self.payload, sort_keys=True, default=str).encode(
+            "utf-8"
+        )
+        return hashlib.sha256(raw).hexdigest()

python_sendparcel-0.2.0.dist-info/RECORD

@@ -1,19 +0,0 @@
-sendparcel/__init__.py,sha256=aHh6hwMkQVrICkswatKnt3Aru-v3kQI0PotD0M3QocQ,1612
-sendparcel/batch.py,sha256=wilO2jPbwlmLowYbhfhNZV17VPX6K_Lf9aHKxWUgbcQ,9400
-sendparcel/enums.py,sha256=e1UM9ka5zWJg4naMCoVeUrIy_PVPPEYHOBh6XiXaW4Q,687
-sendparcel/exceptions.py,sha256=zC5_o9oQfNuOBKaiw5csaHAJmhYsZc3WVbOaoq7s1W0,1437
-sendparcel/flow.py,sha256=REP0i1W2YU09bLVBZWJDUf4mkQ4An4yTZOKMPsfGXL8,11258
-sendparcel/fsm.py,sha256=7Oqccbn2U56htTJLQEidNhZn_0TVtR-js_6OHkTu0zE,3182
-sendparcel/logging.py,sha256=SY7bTtXyPDM-tYCXHRV99YFwK8lHDXpfgB8IN8tOrH0,4843
-sendparcel/protocols.py,sha256=7YX2KTOEG5Nje6bzibmIODFiTX7tgqb6I3WYgx9uVS4,2344
-sendparcel/provider.py,sha256=6f6Z3hmLNrN2t-pulVAFEPrZnNttX1kmK6ATCnqdZD4,2690
-sendparcel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sendparcel/registry.py,sha256=xLDgux5kkp2n5DHfLwOD6mx7yBfMdOyD4QHKUcxJpnw,3575
-sendparcel/types.py,sha256=afPuER1CslkvcTMMogY0EVYrTjUsA36gPxVQguYtIBg,2201
-sendparcel/validators.py,sha256=i_y-edT1hgS_2HeRdARlFaQXiL9sYAzWVsjYPVBqRDc,589
-sendparcel/providers/__init__.py,sha256=ff82dvrWuPS-UIGF5AoX_fgpcYZaGu2k6q2yrxMZacI,192
-sendparcel/providers/dummy.py,sha256=sbXDtPel3DEH_FIN9_gX2xXBLEqZ7Pto3CP_JMcsaEM,3102
-python_sendparcel-0.2.0.dist-info/METADATA,sha256=fozQ4Jz1PhvcQAEnl1zHHb2DTTIXNvhJdKDGjWBPnzE,6429
-python_sendparcel-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-python_sendparcel-0.2.0.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
-python_sendparcel-0.2.0.dist-info/RECORD,,

sendparcel/validators.py

@@ -1,21 +0,0 @@
-"""Pluggable validation system.
-
-Validators are callables that receive a data dict, optionally
-modify it, and return it. Raise an exception to reject.
-"""
-
-from collections.abc import Callable
-from typing import Any
-
-
-def run_validators(
-    data: dict[str, Any], validators: list[Callable[..., Any]] | None = None
-) -> dict[str, Any]:
-    """Run a chain of validators on data.
-
-    Each validator receives the data dict and must return it
-    (possibly modified). Raise an exception to reject.
-    """
-    for validator in validators or []:
-        data = validator(data)
-    return data