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

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

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: python-sendparcel
-Version: 0.1.1
+Version: 0.2.0
 Summary: Framework-agnostic parcel shipping core for Python.
-Project-URL: Homepage, https://github.com/sendparcel/python-sendparcel
-Project-URL: Documentation, https://python-sendparcel.readthedocs.io/
-Project-URL: Repository, https://github.com/sendparcel/python-sendparcel
-Project-URL: Changelog, https://github.com/sendparcel/python-sendparcel/blob/main/CHANGELOG.md
-Project-URL: Issue Tracker, https://github.com/sendparcel/python-sendparcel/issues
+Project-URL: Homepage, https://github.com/python-sendparcel/python-sendparcel
+Project-URL: Repository, https://github.com/python-sendparcel/python-sendparcel
+Project-URL: Changelog, https://github.com/python-sendparcel/python-sendparcel/blob/main/CHANGELOG.md
+Project-URL: Issue Tracker, https://github.com/python-sendparcel/python-sendparcel/issues
 Author-email: Dominik Kozaczko <dominik@kozaczko.info>
 License: MIT
 License-File: LICENSE
@@ -25,8 +24,6 @@ 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: fastapi-sendparcel>=0.1.0; extra == 'all'
-Requires-Dist: litestar-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'
@@ -45,16 +42,10 @@ Requires-Dist: django-sendparcel>=0.1.0; extra == 'django'
 Provides-Extra: dpdpl
 Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'dpdpl'
 Provides-Extra: dummy
-Provides-Extra: fastapi
-Requires-Dist: fastapi-sendparcel>=0.1.0; extra == 'fastapi'
 Provides-Extra: frameworks
 Requires-Dist: django-sendparcel>=0.1.0; extra == 'frameworks'
-Requires-Dist: fastapi-sendparcel>=0.1.0; extra == 'frameworks'
-Requires-Dist: litestar-sendparcel>=0.1.0; extra == 'frameworks'
 Provides-Extra: inpost
 Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'inpost'
-Provides-Extra: litestar
-Requires-Dist: litestar-sendparcel>=0.1.0; extra == 'litestar'
 Provides-Extra: providers
 Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'providers'
 Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'providers'

python_sendparcel-0.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+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,,

{python_sendparcel-0.1.1.dist-info → python_sendparcel-0.2.0.dist-info}/WHEEL

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

sendparcel/__init__.py

@@ -1,7 +1,8 @@
 """sendparcel core package."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
+from sendparcel.batch import BatchCreateResult, BatchResult, ShipmentBatch
 from sendparcel.enums import ConfirmationMethod, LabelFormat, ShipmentStatus
 from sendparcel.exceptions import (
     CommunicationError,
@@ -13,6 +14,7 @@ from sendparcel.exceptions import (
     ShipmentNotFoundError,
 )
 from sendparcel.flow import ShipmentFlow
+from sendparcel.logging import configure_logging, get_logger
 from sendparcel.provider import (
     BaseProvider,
     CancellableProvider,
@@ -26,10 +28,13 @@ from sendparcel.types import (
     CreateLabelOutcome,
     CreateShipmentOutcome,
     ShipmentUpdateOutcome,
+    ShipmentUpdateResult,
 )
 
 __all__ = [
     "BaseProvider",
+    "BatchCreateResult",
+    "BatchResult",
     "CancellableProvider",
     "CommunicationError",
     "ConfirmationMethod",
@@ -45,10 +50,14 @@ __all__ = [
     "PullStatusProvider",
     "PushCallbackProvider",
     "SendParcelException",
+    "ShipmentBatch",
     "ShipmentFlow",
     "ShipmentNotFoundError",
     "ShipmentStatus",
     "ShipmentUpdateOutcome",
+    "ShipmentUpdateResult",
     "__version__",
+    "configure_logging",
+    "get_logger",
     "registry",
 ]

sendparcel/batch.py

@@ -0,0 +1,303 @@
+"""Batch shipment operations for sendparcel.
+
+Provides batch creation, status fetching, and cancellation of shipments.
+Designed for efficiency when processing multiple shipments at once.
+
+Usage::
+
+    from sendparcel.batch import ShipmentBatch
+
+    batch = ShipmentBatch(repository=repo, config=config)
+    results = await batch.create_shipments(
+        [
+            {
+                "provider_slug": "inpost-courier",
+                "sender_address": {...},
+                "receiver_address": {...},
+                "parcels": [...],
+            },
+            # ... more shipments
+        ]
+    )
+    for result in results:
+        if result.success:
+            print(f"Created {result.shipment.tracking_number}")
+        else:
+            print(f"Failed: {result.error}")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any
+
+from sendparcel.flow import ShipmentFlow
+from sendparcel.logging import get_logger
+from sendparcel.protocols import ShipmentRepository
+from sendparcel.registry import PluginRegistry
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class BatchResult:
+    """Result of a single batch operation."""
+
+    index: int
+    success: bool
+    shipment: Any | None = None
+    error: str | None = None
+    outcome: Any | None = None
+
+
+@dataclass
+class BatchCreateResult:
+    """Result of a batch create operation."""
+
+    total: int
+    successful: int
+    failed: int
+    results: list[BatchResult] = field(default_factory=list)
+
+    @property
+    def success(self) -> bool:
+        """True if all shipments were created successfully."""
+        return self.failed == 0
+
+    @property
+    def summary(self) -> dict[str, Any]:
+        """Return a summary of the batch operation."""
+        return {
+            "total": self.total,
+            "successful": self.successful,
+            "failed": self.failed,
+            "success_rate": (
+                round(self.successful / self.total * 100, 2)
+                if self.total > 0
+                else 0.0
+            ),
+        }
+
+
+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.
+
+    Args:
+        repository: Shipment repository for persisting results.
+        config: Provider configuration.
+        registry: Provider registry (defaults to module-level singleton).
+        max_concurrent: Maximum number of concurrent provider calls
+            (default: 5).
+    """
+
+    def __init__(
+        self,
+        repository: ShipmentRepository,
+        config: dict[str, Any] | None = None,
+        registry: PluginRegistry | None = None,
+        max_concurrent: int = 5,
+    ) -> None:
+        self.repository = repository
+        self.config = config or {}
+        self.registry = registry or PluginRegistry()
+        self.max_concurrent = max_concurrent
+
+    async def create_shipments(
+        self,
+        shipments: list[dict[str, Any]],
+    ) -> BatchCreateResult:
+        """Create multiple shipments in a batch.
+
+        Each shipment dict must contain:
+        - provider_slug: Provider identifier
+        - sender_address: Sender address info
+        - receiver_address: Receiver address info
+        - parcels: List of parcel definitions
+        - Optional: idempotency_key, reference_id, and other kwargs
+
+        Args:
+            shipments: List of shipment dicts to create.
+
+        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)
+
+        results = await asyncio.gather(
+            *(_create_one(i, d) for i, d in enumerate(shipments))
+        )
+
+        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)
+
+        return BatchCreateResult(
+            total=len(shipments),
+            successful=successful,
+            failed=failed,
+            results=results,
+        )
+
+    async def _create_single_shipment(
+        self, index: int, shipment_data: dict[str, Any]
+    ) -> BatchResult:
+        provider_slug = shipment_data.get("provider_slug")
+        if not provider_slug:
+            return BatchResult(
+                index=index,
+                success=False,
+                error="Missing provider_slug",
+            )
+
+        try:
+            self.registry.get_by_slug(provider_slug)
+
+            flow = ShipmentFlow(
+                repository=self.repository,
+                config=self.config,
+                registry=self.registry,
+            )
+
+            outcome = await flow.create_shipment(
+                provider_slug=provider_slug,
+                sender_address=shipment_data["sender_address"],
+                receiver_address=shipment_data["receiver_address"],
+                parcels=shipment_data["parcels"],
+                **{
+                    k: v
+                    for k, v in shipment_data.items()
+                    if k
+                    not in (
+                        "provider_slug",
+                        "sender_address",
+                        "receiver_address",
+                        "parcels",
+                    )
+                },
+            )
+
+            logger.info(
+                "Batch create: shipment %d created successfully "
+                "(provider=%s, tracking=%s)",
+                index,
+                provider_slug,
+                outcome.shipment.tracking_number,
+            )
+
+            return BatchResult(
+                index=index,
+                success=True,
+                shipment=outcome.shipment,
+                outcome=outcome,
+            )
+
+        except Exception as exc:
+            logger.warning(
+                "Batch create: shipment %d failed: %s",
+                index,
+                exc,
+            )
+            return BatchResult(
+                index=index,
+                success=False,
+                error=str(exc),
+            )
+
+    async def fetch_statuses(
+        self,
+        shipment_ids: list[str],
+    ) -> list[BatchResult]:
+        """Fetch statuses for multiple shipments.
+
+        Args:
+            shipment_ids: List of shipment IDs to fetch.
+
+        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))
+        )
+        results.sort(key=lambda r: r.index)
+        return results
+
+    async def cancel_shipments(
+        self,
+        shipment_ids: list[str],
+    ) -> list[BatchResult]:
+        """Cancel multiple shipments.
+
+        Args:
+            shipment_ids: List of shipment IDs to cancel.
+
+        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))
+        )
+        results.sort(key=lambda r: r.index)
+        return results

sendparcel/enums.py

@@ -15,6 +15,7 @@ class ShipmentStatus(StrEnum):
     CANCELLED = "cancelled"
     FAILED = "failed"
     RETURNED = "returned"
+    SUBMITTED = "submitted"
 
 
 class LabelFormat(StrEnum):

sendparcel/flow.py

@@ -21,6 +21,8 @@ from sendparcel.provider import (
     PullStatusProvider,
     PushCallbackProvider,
 )
+from sendparcel.registry import PluginRegistry
+from sendparcel.registry import registry as default_registry
 from sendparcel.types import (
     AddressInfo,
     CreateLabelOutcome,
@@ -40,13 +42,11 @@ class ShipmentFlow:
         repository: ShipmentRepository,
         config: dict[str, Any] | None = None,
         validators: list[Any] | None = None,
-        registry: Any = None,
+        registry: PluginRegistry | None = None,
     ) -> None:
         self.repository = repository
         self.config = config or {}
         self.validators = validators or []
-        from sendparcel.registry import registry as default_registry
-
         self.registry = registry or default_registry
 
     async def create_shipment(
@@ -56,25 +56,98 @@ class ShipmentFlow:
         sender_address: AddressInfo,
         receiver_address: AddressInfo,
         parcels: list[ParcelInfo],
+        idempotency_key: str | None = None,
         **kwargs: Any,
     ) -> CreateShipmentOutcome:
-        """Create a shipment record with explicit address and parcel data."""
+        """Create a shipment record with explicit address and parcel data.
+
+        Uses persistence-enforced idempotency: if a shipment with the same
+        provider + idempotency_key already exists, it is returned without
+        calling the provider again.
+
+        On provider failure:
+        - CommunicationError (timeout, network): marks shipment as
+          ``SUBMITTED`` (ambiguous — provider may have accepted).
+          The caller should reconcile via polling or callback.
+        - Other errors: marks shipment as ``FAILED`` and re-raises.
+
+        The shipment record is never deleted on failure, ensuring that
+        retries and reconciliation always have a record to work with.
 
+        Args:
+            provider_slug: Provider identifier.
+            sender_address: Sender address info.
+            receiver_address: Receiver address info.
+            parcels: List of parcel definitions.
+            idempotency_key: Optional key for retry safety. Stored in the
+                ``reference_id`` field of the shipment record.
+            **kwargs: Passed to the provider (after repo-only fields
+                are stripped).
+
+        Returns:
+            CreateShipmentOutcome with the persisted shipment and
+            optional label payload.
+        """
         self.registry.get_by_slug(provider_slug)
-        shipment = await self.repository.create(
-            provider=provider_slug,
-            status=ShipmentStatus.NEW.value,
-            **kwargs,
-        )
+
+        # Separate repository kwargs from provider kwargs.
+        repo_kwargs: dict[str, Any] = {}
+        for key in ("reference_id",):
+            if key in kwargs:
+                repo_kwargs[key] = kwargs.pop(key)
+
+        # Apply idempotency key to reference_id if provided.
+        if idempotency_key is not None:
+            repo_kwargs.setdefault("reference_id", idempotency_key)
+
+        # Create shipment — use atomic idempotency if key provided.
+        if idempotency_key is not None:
+            (
+                existing,
+                created,
+            ) = await self.repository.create_with_idempotency_key(
+                provider=provider_slug,
+                status=ShipmentStatus.NEW.value,
+                **repo_kwargs,
+            )
+            if existing is not None:
+                return CreateShipmentOutcome(shipment=existing, label=None)
+            if created is None:
+                raise RuntimeError(
+                    "create_with_idempotency_key returned (None, None) "
+                    "— repository contract violated"
+                )
+            shipment = created
+        else:
+            shipment = await self.repository.create(
+                provider=provider_slug,
+                status=ShipmentStatus.NEW.value,
+                **repo_kwargs,
+            )
+
         provider = self._get_provider(shipment)
-        result = await self._call_provider(
-            provider.create_shipment(
-                sender_address=sender_address,
-                receiver_address=receiver_address,
-                parcels=parcels,
-                **kwargs,
+        try:
+            result = await self._call_provider(
+                provider.create_shipment(
+                    sender_address=sender_address,
+                    receiver_address=receiver_address,
+                    parcels=parcels,
+                    **kwargs,
+                )
             )
-        )
+        except CommunicationError:
+            # Ambiguous: provider may have accepted the shipment
+            # (e.g. timeout after acceptance). Mark as SUBMITTED for
+            # reconciliation via polling or callback.
+            transition_shipment(shipment, ShipmentStatus.SUBMITTED)
+            await self.repository.save(shipment)
+            return CreateShipmentOutcome(shipment=shipment, label=None)
+        except Exception:
+            # Non-communication error: mark as FAILED, never delete.
+            transition_shipment(shipment, ShipmentStatus.FAILED)
+            await self.repository.save(shipment)
+            raise
+
         shipment.external_id = str(result.get("external_id", ""))
         shipment.tracking_number = str(result.get("tracking_number", ""))
         transition_shipment(shipment, ShipmentStatus.CREATED)
@@ -98,7 +171,9 @@ class ShipmentFlow:
             )
         label = await self._call_provider(provider.create_label(**kwargs))
         transition_shipment(shipment, ShipmentStatus.LABEL_READY)
-        saved = await self.repository.save(shipment)
+        saved = await self.repository.update_fields(
+            shipment_id=shipment.id, status=shipment.status
+        )
         return CreateLabelOutcome(shipment=saved, label=label)
 
     async def handle_callback(
@@ -155,7 +230,9 @@ class ShipmentFlow:
         )
         if cancelled:
             transition_shipment(shipment, ShipmentStatus.CANCELLED)
-            await self.repository.save(shipment)
+            await self.repository.update_fields(
+                shipment_id=shipment.id, status=shipment.status
+            )
         return bool(cancelled)
 
     def _get_provider(self, shipment: Shipment) -> BaseProvider:
@@ -166,16 +243,29 @@ class ShipmentFlow:
     async def _apply_update(
         self, shipment: Shipment, update: ShipmentUpdateResult
     ) -> Shipment:
+        """Apply a normalized update to a shipment atomically.
+
+        Uses the atomic ``update_fields`` persistence primitive to
+        prevent concurrent read-modify-save races.
+        """
+        fields: dict[str, Any] = {}
         tracking_number = update.get("tracking_number")
         if tracking_number:
-            shipment.tracking_number = str(tracking_number)
+            fields["tracking_number"] = str(tracking_number)
         status = update.get("status")
         if status is not None:
             transition_shipment(shipment, status)
-        return await self.repository.save(shipment)
+            fields["status"] = shipment.status
+        return await self.repository.update_fields(
+            shipment_id=shipment.id, **fields
+        )
 
     async def _call_provider(self, coro: Any) -> Any:
-        """Call a provider coroutine, wrapping non-domain errors."""
+        """Call a provider coroutine, wrapping only network errors.
+
+        Domain errors (ValueError, KeyError, TypeError, etc.) are re-raised
+        as-is so they are distinguishable from communication failures.
+        """
 
         try:
             return await coro
@@ -186,7 +276,18 @@ class ShipmentFlow:
                 str(exc),
                 context={"original_error": type(exc).__name__},
             ) from exc
-        except Exception as exc:
+        except TimeoutError as exc:
+            raise CommunicationError(
+                str(exc),
+                context={"original_error": type(exc).__name__},
+            ) from exc
+        except ExceptionGroup as exc:
+            # Preserve typed inner exceptions: if any inner exception is a
+            # SendParcelException, re-raise it directly. Otherwise wrap the
+            # entire group in a CommunicationError.
+            for e in exc.exceptions:
+                if isinstance(e, SendParcelException):
+                    raise e from exc
             raise CommunicationError(
                 str(exc),
                 context={"original_error": type(exc).__name__},

sendparcel/fsm.py

@@ -6,62 +6,69 @@ from sendparcel.enums import ShipmentStatus
 from sendparcel.exceptions import InvalidTransitionError
 from sendparcel.protocols import Shipment
 
-ALLOWED_STATUS_TRANSITIONS: dict[str, frozenset[str]] = {
-    ShipmentStatus.NEW.value: frozenset(
+ALLOWED_STATUS_TRANSITIONS: dict[ShipmentStatus, frozenset[ShipmentStatus]] = {
+    ShipmentStatus.NEW: frozenset(
         {
-            ShipmentStatus.CREATED.value,
-            ShipmentStatus.CANCELLED.value,
-            ShipmentStatus.FAILED.value,
+            ShipmentStatus.CREATED,
+            ShipmentStatus.CANCELLED,
+            ShipmentStatus.FAILED,
+            ShipmentStatus.SUBMITTED,
         }
     ),
-    ShipmentStatus.CREATED.value: frozenset(
+    ShipmentStatus.CREATED: frozenset(
         {
-            ShipmentStatus.LABEL_READY.value,
-            ShipmentStatus.IN_TRANSIT.value,
-            ShipmentStatus.OUT_FOR_DELIVERY.value,
-            ShipmentStatus.DELIVERED.value,
-            ShipmentStatus.RETURNED.value,
-            ShipmentStatus.CANCELLED.value,
-            ShipmentStatus.FAILED.value,
+            ShipmentStatus.LABEL_READY,
+            ShipmentStatus.IN_TRANSIT,
+            ShipmentStatus.OUT_FOR_DELIVERY,
+            ShipmentStatus.DELIVERED,
+            ShipmentStatus.RETURNED,
+            ShipmentStatus.CANCELLED,
+            ShipmentStatus.FAILED,
         }
     ),
-    ShipmentStatus.LABEL_READY.value: frozenset(
+    ShipmentStatus.LABEL_READY: frozenset(
         {
-            ShipmentStatus.IN_TRANSIT.value,
-            ShipmentStatus.OUT_FOR_DELIVERY.value,
-            ShipmentStatus.DELIVERED.value,
-            ShipmentStatus.RETURNED.value,
-            ShipmentStatus.CANCELLED.value,
-            ShipmentStatus.FAILED.value,
+            ShipmentStatus.IN_TRANSIT,
+            ShipmentStatus.OUT_FOR_DELIVERY,
+            ShipmentStatus.DELIVERED,
+            ShipmentStatus.RETURNED,
+            ShipmentStatus.CANCELLED,
+            ShipmentStatus.FAILED,
         }
     ),
-    ShipmentStatus.IN_TRANSIT.value: frozenset(
+    ShipmentStatus.IN_TRANSIT: frozenset(
         {
-            ShipmentStatus.OUT_FOR_DELIVERY.value,
-            ShipmentStatus.DELIVERED.value,
-            ShipmentStatus.RETURNED.value,
-            ShipmentStatus.FAILED.value,
+            ShipmentStatus.OUT_FOR_DELIVERY,
+            ShipmentStatus.DELIVERED,
+            ShipmentStatus.RETURNED,
+            ShipmentStatus.FAILED,
         }
     ),
-    ShipmentStatus.OUT_FOR_DELIVERY.value: frozenset(
+    ShipmentStatus.OUT_FOR_DELIVERY: frozenset(
         {
-            ShipmentStatus.DELIVERED.value,
-            ShipmentStatus.RETURNED.value,
-            ShipmentStatus.FAILED.value,
+            ShipmentStatus.DELIVERED,
+            ShipmentStatus.RETURNED,
+            ShipmentStatus.FAILED,
+        }
+    ),
+    ShipmentStatus.DELIVERED: frozenset({ShipmentStatus.RETURNED}),
+    ShipmentStatus.CANCELLED: frozenset(),
+    ShipmentStatus.FAILED: frozenset(),
+    ShipmentStatus.RETURNED: frozenset(),
+    ShipmentStatus.SUBMITTED: frozenset(
+        {
+            ShipmentStatus.CREATED,
+            ShipmentStatus.FAILED,
         }
     ),
-    ShipmentStatus.DELIVERED.value: frozenset({ShipmentStatus.RETURNED.value}),
-    ShipmentStatus.CANCELLED.value: frozenset(),
-    ShipmentStatus.FAILED.value: frozenset(),
-    ShipmentStatus.RETURNED.value: frozenset(),
 }
 
 
-def normalize_status(status: str | ShipmentStatus) -> str:
-    """Return a normalized shipment status string."""
+def normalize_status(status: str | ShipmentStatus) -> ShipmentStatus:
+    """Normalise a status to a :class:`ShipmentStatus` enum member."""
 
     try:
-        return ShipmentStatus(status).value
+        return ShipmentStatus(status)
     except ValueError as exc:
         raise InvalidTransitionError(
             f"Unknown shipment status {status!r}"
@@ -89,11 +96,11 @@ def transition_shipment(
     current = normalize_status(shipment.status)
     target = normalize_status(target_status)
     if current == target:
-        shipment.status = target
+        shipment.status = target.value
         return shipment
     if target not in ALLOWED_STATUS_TRANSITIONS[current]:
         raise InvalidTransitionError(
             f"Shipment cannot transition from {current!r} to {target!r}"
         )
-    shipment.status = target
+    shipment.status = target.value
     return shipment

sendparcel/logging.py

@@ -0,0 +1,155 @@
+"""Structured logging for sendparcel.
+
+Provides JSON-formatted logging with consistent fields:
+- timestamp (ISO 8601)
+- level
+- logger name
+- message
+- extra context (module, function, shipment_id, etc.)
+
+Usage::
+
+    from sendparcel.logging import get_logger
+
+    logger = get_logger()
+    logger.info("Shipment created", shipment_id="abc-123", provider="inpost")
+
+In production, the JSON formatter outputs one-line JSON records suitable
+for structured log aggregation (Datadog, CloudWatch, ELK, etc.).
+In development, falls back to human-readable format.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+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.
+
+    Outputs one-line JSON records with consistent fields.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        extra = _format_extra(getattr(record, "extra", None))
+        log_entry: dict[str, Any] = {
+            "timestamp": datetime.now(UTC).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        if extra:
+            log_entry["extra"] = extra
+        if hasattr(record, "exc_info") and record.exc_info:
+            log_entry["exception"] = self.formatException(record.exc_info)
+        return json.dumps(log_entry, default=str)
+
+
+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}"
+        return super().format(record)
+
+
+def configure_logging(
+    level: int = logging.INFO,
+    json_format: bool | None = None,
+) -> None:
+    """Configure structured logging for the sendparcel package.
+
+    Call this once at application startup (e.g. Django ``AppConfig.ready()``,
+    FastAPI lifespan, or a CLI ``__main__.py``) to enable JSON-formatted
+    structured logging for all sendparcel packages.
+
+    Args:
+        level: Logging level (default: INFO).
+        json_format: Force JSON format (True/False). If None, uses
+            JSON when the ``SENDPARCEL_LOG_FORMAT`` environment variable
+            is set to ``"json"``, human-readable otherwise.
+    """
+    if json_format is None:
+        json_format = os.environ.get("SENDPARCEL_LOG_FORMAT") == "json"
+
+    for name in ("sendparcel", "sendparcel_inpost", "sendparcel_django"):
+        logger = logging.getLogger(name)
+        logger.setLevel(level)
+        logger.propagate = False
+
+        # Avoid adding handlers multiple times
+        if logger.handlers:
+            continue
+
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(
+            _JsonFormatter() if json_format else _HumanFormatter()
+        )
+        logger.addHandler(handler)
+
+
+def get_logger(
+    name: str | None = None,
+    *,
+    extra: dict[str, Any] | None = None,
+) -> logging.LoggerAdapter[logging.Logger]:
+    """Get a structured logger for the sendparcel ecosystem.
+
+    Args:
+        name: Logger name. Defaults to the caller's module name.
+        extra: Extra fields to include in every log record.
+
+    Returns:
+        A LoggerAdapter with consistent structured logging.
+
+    Usage::
+
+        logger = get_logger()
+        logger.info("Shipment created", shipment_id="abc-123")
+        logger.error("API failed", exc_info=True)
+    """
+    # Auto-detect caller module if not specified
+    if name is None:
+        import inspect
+
+        frame = inspect.currentframe()
+        if frame is not None:
+            caller = frame.f_back
+            if caller is not None:
+                name = caller.f_globals.get("__name__", __name__)
+
+    logger = logging.getLogger(name)
+    adapter = logging.LoggerAdapter(logger, extra=extra or {})
+    return adapter
+
+
+# NOTE: Logging is NOT configured on import.  Call
+# ``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/protocols.py

@@ -18,9 +18,58 @@ class Shipment(Protocol):
 class ShipmentRepository(Protocol):
     """Persistence abstraction for adapters."""
 
-    async def get_by_id(self, shipment_id: str) -> Shipment: ...
+    def get_by_id_sync(
+        self, shipment_id: str, *, for_update: bool = False
+    ) -> Shipment:
+        """Synchronous fetch — required for transactional helpers."""
+        ...
+
+    async def get_by_id(
+        self, shipment_id: str, *, for_update: bool = False
+    ) -> Shipment: ...
     async def create(self, **kwargs: Any) -> Shipment: ...
     async def save(self, shipment: Shipment) -> Shipment: ...
     async def update_status(
         self, shipment_id: str, status: str, **fields: Any
     ) -> Shipment: ...
+    async def delete(self, shipment_id: str) -> None: ...
+    async def find_by_reference(
+        self, provider: str, reference_id: str
+    ) -> Shipment | None: ...
+    async def create_with_idempotency_key(
+        self,
+        provider: str,
+        status: str,
+        reference_id: str,
+        **kwargs: Any,
+    ) -> tuple[Shipment | None, Shipment | None]:
+        """Atomically check for existing + create if absent.
+
+        Returns:
+            (existing, created) — exactly one is None.
+            If a shipment with this provider + reference_id already
+            exists, returns (existing, None).
+            If no such shipment exists, creates one and returns
+            (None, created).
+        """
+        ...
+
+    async def update_fields(self, shipment_id: str, **fields: Any) -> Shipment:
+        """Atomically update shipment fields by ID.
+
+        This is the atomic persistence primitive for callback and
+        polling flows. Unlike save() which mutates an in-memory
+        object, this performs a single atomic update operation,
+        preventing concurrent read-modify-save races.
+
+        Args:
+            shipment_id: The shipment to update.
+            **fields: Fields to update (e.g. status, tracking_number).
+
+        Returns:
+            The updated shipment object.
+
+        Raises:
+            ShipmentNotFoundError: If no shipment with this ID exists.
+        """
+        ...

sendparcel/registry.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import threading
 from importlib.metadata import entry_points
 
 from sendparcel.exceptions import ProviderNotFoundError
@@ -11,61 +12,92 @@ ENTRY_POINT_GROUP = "sendparcel.providers"
 
 
 class PluginRegistry:
-    """Discover and store provider classes."""
+    """Discover and store provider classes.
+
+    Thread-safe: all public methods and ``_register_provider`` are
+    protected by a ``threading.Lock``.
+    """
 
     def __init__(self) -> None:
         self._providers: dict[str, type[BaseProvider]] = {}
         self._discovered = False
+        self._lock = threading.Lock()
 
     def discover(self) -> None:
-        """Load providers from entry points."""
+        """Load providers from entry points.
 
-        from sendparcel.providers import BUILTIN_PROVIDERS
-
-        for provider_class in BUILTIN_PROVIDERS:
-            self._register_provider(provider_class)
-        for entry_point in entry_points(group=ENTRY_POINT_GROUP):
-            provider_class = entry_point.load()
-            if isinstance(provider_class, type) and issubclass(
-                provider_class, BaseProvider
-            ):
-                self._register_provider(provider_class)
-        self._discovered = True
+        Thread-safe: acquires ``_lock`` before mutating state.
+        Idempotent — subsequent calls are no-ops.
+        """
+        with self._lock:
+            if self._discovered:
+                return
+            self._discover_unlocked()
 
     def register(self, provider_class: type[BaseProvider]) -> None:
-        """Register provider manually."""
+        """Register provider manually.
 
-        self._register_provider(provider_class)
+        Thread-safe.
+        """
+        with self._lock:
+            self._register_provider(provider_class)
 
     def unregister(self, slug: str) -> None:
-        """Unregister provider by slug."""
+        """Unregister provider by slug.
 
-        self._providers.pop(slug, None)
+        Thread-safe.
+        """
+        with self._lock:
+            self._providers.pop(slug, None)
 
     def get_by_slug(self, slug: str) -> type[BaseProvider]:
-        """Get provider class by slug."""
+        """Get provider class by slug.
 
+        Thread-safe.
+        """
         self._ensure_discovered()
-        try:
-            return self._providers[slug]
-        except KeyError as exc:
-            raise ProviderNotFoundError(slug) from exc
+        with self._lock:
+            try:
+                return self._providers[slug]
+            except KeyError as exc:
+                raise ProviderNotFoundError(slug) from exc
 
     def get_choices(self) -> list[tuple[str, str]]:
-        """Get provider slug/display pairs for user-facing selection."""
+        """Get provider slug/display pairs for user-facing selection.
 
+        Thread-safe.
+        """
         self._ensure_discovered()
-        return [
-            (provider.slug, provider.display_name)
-            for provider in self._providers.values()
-            if provider.user_selectable
-        ]
+        with self._lock:
+            return [
+                (provider.slug, provider.display_name)
+                for provider in self._providers.values()
+                if provider.user_selectable
+            ]
 
     def _ensure_discovered(self) -> None:
         if not self._discovered:
             self.discover()
 
+    def _discover_unlocked(self) -> None:
+        """Internal discover — caller must hold ``_lock``."""
+        from sendparcel.providers import BUILTIN_PROVIDERS
+
+        for provider_class in BUILTIN_PROVIDERS:
+            self._register_provider(provider_class)
+        for entry_point in entry_points(group=ENTRY_POINT_GROUP):
+            provider_class = entry_point.load()
+            if isinstance(provider_class, type) and issubclass(
+                provider_class, BaseProvider
+            ):
+                self._register_provider(provider_class)
+        self._discovered = True
+
     def _register_provider(self, provider_class: type[BaseProvider]) -> None:
+        """Register a single provider class.
+
+        Caller must hold ``_lock``.
+        """
         slug = provider_class.slug
         if not isinstance(slug, str) or not slug:
             raise ValueError("Provider classes must declare a non-empty slug")

python_sendparcel-0.1.1.dist-info/RECORD

@@ -1,17 +0,0 @@
-sendparcel/__init__.py,sha256=laO3AFTeFkq_XiqzIvFWMZPblm35Rt51tKteNrNgh9Y,1314
-sendparcel/enums.py,sha256=9tg9eMD5QpHOTNfsedncYQqfkxW_IXVcFfgJL6dCD1o,659
-sendparcel/exceptions.py,sha256=zC5_o9oQfNuOBKaiw5csaHAJmhYsZc3WVbOaoq7s1W0,1437
-sendparcel/flow.py,sha256=gLQuIJXxde_Ta4oseBJvyjCNc80YPq4g1tK4KwnOv90,6940
-sendparcel/fsm.py,sha256=TbKkDNEjqWPDBDdnzvGWEaUtTcEXPJPpcZdSkuqIquI,3147
-sendparcel/protocols.py,sha256=y4TQb0p0z0WO39KCqwiCU0uTi4pXbvgRMbB_LsIPvJ8,689
-sendparcel/provider.py,sha256=6f6Z3hmLNrN2t-pulVAFEPrZnNttX1kmK6ATCnqdZD4,2690
-sendparcel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sendparcel/registry.py,sha256=lVWpNZuXISC2c12GC7fvk-fULHVQ6exFvMqv5ilswg8,2700
-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.1.1.dist-info/METADATA,sha256=-vbQtZxuDuTQeZLa40hfZlqEJefWJAuC-IsnGqt33vc,6888
-python_sendparcel-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_sendparcel-0.1.1.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
-python_sendparcel-0.1.1.dist-info/RECORD,,