python-sendparcel 0.1.1__tar.gz → 0.2.0__tar.gz

{python_sendparcel-0.1.1 → python_sendparcel-0.2.0}/PKG-INFO

@@ -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.1.1 → python_sendparcel-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-sendparcel"
-version = "0.1.1"
+version = "0.2.0"
 description = "Framework-agnostic parcel shipping core for Python."
 readme = "README.md"
 license = { text = "MIT" }
@@ -32,32 +32,32 @@ dev = [
 ]
 dummy = []
 django = ["django-sendparcel>=0.1.0"]
-fastapi = ["fastapi-sendparcel>=0.1.0"]
-litestar = ["litestar-sendparcel>=0.1.0"]
+# fastapi = ["fastapi-sendparcel>=0.1.0"]
+# litestar = ["litestar-sendparcel>=0.1.0"]
 inpost = ["python-sendparcel-inpost>=0.1.0"]
 dpdpl = ["python-sendparcel-dpdpl>=0.1.0"]
 cli = ["python-sendparcel-cli>=0.1.0"]
 providers = ["python-sendparcel-inpost>=0.1.0", "python-sendparcel-dpdpl>=0.1.0"]
 frameworks = [
   "django-sendparcel>=0.1.0",
-  "fastapi-sendparcel>=0.1.0",
-  "litestar-sendparcel>=0.1.0",
+  # "fastapi-sendparcel>=0.1.0",
+  # "litestar-sendparcel>=0.1.0",
 ]
 all = [
   "django-sendparcel>=0.1.0",
-  "fastapi-sendparcel>=0.1.0",
-  "litestar-sendparcel>=0.1.0",
+  # "fastapi-sendparcel>=0.1.0",
+  # "litestar-sendparcel>=0.1.0",
   "python-sendparcel-inpost>=0.1.0",
   "python-sendparcel-dpdpl>=0.1.0",
   "python-sendparcel-cli>=0.1.0",
 ]
 
 [project.urls]
-Homepage = "https://github.com/sendparcel/python-sendparcel"
-Documentation = "https://python-sendparcel.readthedocs.io/"
-Repository = "https://github.com/sendparcel/python-sendparcel"
-Changelog = "https://github.com/sendparcel/python-sendparcel/blob/main/CHANGELOG.md"
-"Issue Tracker" = "https://github.com/sendparcel/python-sendparcel/issues"
+Homepage = "https://github.com/python-sendparcel/python-sendparcel"
+# Documentation = "https://python-sendparcel.readthedocs.io/"
+Repository = "https://github.com/python-sendparcel/python-sendparcel"
+Changelog = "https://github.com/python-sendparcel/python-sendparcel/blob/main/CHANGELOG.md"
+"Issue Tracker" = "https://github.com/python-sendparcel/python-sendparcel/issues"
 
 [build-system]
 requires = ["hatchling"]
@@ -82,6 +82,7 @@ ignore = ["N818", "B027"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = ["RUF012"]
+"docs/**" = ["A001"]
 
 [tool.ty.environment]
 python-version = "3.12"
@@ -98,8 +99,6 @@ invalid-return-type = "ignore"
 
 [tool.uv.sources]
 django-sendparcel = { path = "../django-sendparcel", editable = true }
-fastapi-sendparcel = { path = "../fastapi-sendparcel", editable = true }
-litestar-sendparcel = { path = "../litestar-sendparcel", editable = true }
 python-sendparcel-inpost = { path = "../python-sendparcel-inpost", editable = true }
 python-sendparcel-dpdpl = { path = "../python-sendparcel-dpdpl", editable = true }
 python-sendparcel-cli = { path = "../python-sendparcel-cli", editable = true }

{python_sendparcel-0.1.1 → python_sendparcel-0.2.0}/src/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",
 ]

python_sendparcel-0.2.0/src/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

{python_sendparcel-0.1.1 → python_sendparcel-0.2.0}/src/sendparcel/enums.py

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

{python_sendparcel-0.1.1 → python_sendparcel-0.2.0}/src/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__},