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

python_sendparcel-0.2.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: python-sendparcel
+Version: 0.2.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
+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
+Keywords: delivery,logistics,parcel,sendparcel,shipping
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+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'
+Provides-Extra: cli
+Requires-Dist: python-sendparcel-cli>=0.1.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pre-commit-hooks>=6.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+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: ty>=0.0.16; extra == 'dev'
+Provides-Extra: django
+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: frameworks
+Requires-Dist: django-sendparcel>=0.1.0; extra == 'frameworks'
+Provides-Extra: inpost
+Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'inpost'
+Provides-Extra: providers
+Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'providers'
+Requires-Dist: python-sendparcel-inpost>=0.1.0; 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
+> ecosystem is still being cleaned up.
+
+## What it is
+
+- Provider-agnostic shipment orchestration with a single core flow.
+- Explicit shipment metadata persistence: `id`, `status`, `provider`, `external_id`, `tracking_number`.
+- Label payloads are operation results, not persisted shipment fields.
+- One normalized provider update contract for both callbacks and polling.
+- Runtime-checkable `Shipment` and `ShipmentRepository` protocols so adapters can use their own models.
+
+## Core contract
+
+- `ShipmentFlow.create_shipment(...) -> CreateShipmentOutcome`
+- `ShipmentFlow.create_label(...) -> CreateLabelOutcome`
+- `ShipmentFlow.handle_callback(...) -> ShipmentUpdateOutcome`
+- `ShipmentFlow.fetch_and_update_status(...) -> ShipmentUpdateOutcome`
+- `ShipmentFlow.cancel_shipment(...) -> bool`
+
+`CreateShipmentOutcome` and `CreateLabelOutcome` return label payloads when available.
+The shipment object never stores label bytes or a persisted `label_url` in the core contract.
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+from decimal import Decimal
+
+import anyio
+
+from sendparcel import ShipmentFlow
+from sendparcel.types import AddressInfo, ParcelInfo
+
+
+@dataclass
+class MyShipment:
+    id: str
+    status: str = "new"
+    provider: str = ""
+    external_id: str = ""
+    tracking_number: str = ""
+
+
+class InMemoryRepository:
+    def __init__(self) -> None:
+        self._store: dict[str, MyShipment] = {}
+        self._counter = 0
+
+    async def get_by_id(self, shipment_id: str) -> MyShipment:
+        return self._store[shipment_id]
+
+    async def create(self, **kwargs) -> MyShipment:
+        self._counter += 1
+        shipment = MyShipment(
+            id=str(self._counter),
+            status=str(kwargs.get("status", "new")),
+            provider=str(kwargs.get("provider", "")),
+        )
+        self._store[shipment.id] = shipment
+        return shipment
+
+    async def save(self, shipment: MyShipment) -> MyShipment:
+        self._store[shipment.id] = shipment
+        return shipment
+
+
+async def main() -> None:
+    flow = ShipmentFlow(repository=InMemoryRepository())
+
+    created = await flow.create_shipment(
+        "dummy",
+        sender_address=AddressInfo(
+            name="Sender Co.",
+            line1="Marszalkowska 1",
+            city="Warsaw",
+            postal_code="00-001",
+            country_code="PL",
+        ),
+        receiver_address=AddressInfo(
+            name="Jan Kowalski",
+            line1="Dluga 10",
+            city="Gdansk",
+            postal_code="80-001",
+            country_code="PL",
+        ),
+        parcels=[ParcelInfo(weight_kg=Decimal("2.5"))],
+    )
+
+    print(created.shipment.status)
+    print(created.shipment.external_id)
+    print(created.shipment.tracking_number)
+
+    labelled = await flow.create_label(created.shipment)
+    print(labelled.label.get("url"))
+
+
+anyio.run(main)
+```
+
+## Provider model
+
+- `BaseProvider.create_shipment(...)` returns `ShipmentCreateResult`.
+- `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`.
+
+Use `ConfirmationMethod.PUSH` only with `PushCallbackProvider` and
+`ConfirmationMethod.PULL` only with `PullStatusProvider`.
+
+The core owns shipment state transitions. Providers translate carrier responses
+into normalized results.
+
+## Installation
+
+```bash
+pip install python-sendparcel
+```
+
+With `uv`:
+
+```bash
+uv add python-sendparcel
+```
+
+## Extras
+
+- `django`
+- `fastapi`
+- `litestar`
+- `inpost`
+- `dpdpl`
+- `cli`
+- `frameworks`
+- `providers`
+- `all`
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests
+uv run mypy src tests
+```

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.0.dist-info → python_sendparcel-0.2.0.dist-info}/WHEEL

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

sendparcel/__init__.py

@@ -1,29 +1,63 @@
 """sendparcel core package."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
-from sendparcel.enums import ConfirmationMethod, ShipmentStatus
+from sendparcel.batch import BatchCreateResult, BatchResult, ShipmentBatch
+from sendparcel.enums import ConfirmationMethod, LabelFormat, ShipmentStatus
 from sendparcel.exceptions import (
     CommunicationError,
     InvalidCallbackError,
     InvalidTransitionError,
+    ProviderCapabilityError,
+    ProviderNotFoundError,
     SendParcelException,
+    ShipmentNotFoundError,
 )
 from sendparcel.flow import ShipmentFlow
-from sendparcel.provider import BaseProvider
+from sendparcel.logging import configure_logging, get_logger
+from sendparcel.provider import (
+    BaseProvider,
+    CancellableProvider,
+    LabelProvider,
+    PullStatusProvider,
+    PushCallbackProvider,
+)
 from sendparcel.providers.dummy import DummyProvider
 from sendparcel.registry import registry
+from sendparcel.types import (
+    CreateLabelOutcome,
+    CreateShipmentOutcome,
+    ShipmentUpdateOutcome,
+    ShipmentUpdateResult,
+)
 
 __all__ = [
     "BaseProvider",
+    "BatchCreateResult",
+    "BatchResult",
+    "CancellableProvider",
     "CommunicationError",
     "ConfirmationMethod",
+    "CreateLabelOutcome",
+    "CreateShipmentOutcome",
     "DummyProvider",
     "InvalidCallbackError",
     "InvalidTransitionError",
+    "LabelFormat",
+    "LabelProvider",
+    "ProviderCapabilityError",
+    "ProviderNotFoundError",
+    "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,10 +15,21 @@ class ShipmentStatus(StrEnum):
     CANCELLED = "cancelled"
     FAILED = "failed"
     RETURNED = "returned"
+    SUBMITTED = "submitted"
+
+
+class LabelFormat(StrEnum):
+    """Shipping label format."""
+
+    PDF = "PDF"
+    ZPL = "ZPL"
+    PNG = "PNG"
+    EPL = "EPL"
 
 
 class ConfirmationMethod(StrEnum):
     """How the provider confirms shipment status updates."""
 
+    NONE = "NONE"
     PUSH = "PUSH"
     PULL = "PULL"

sendparcel/exceptions.py

@@ -1,10 +1,16 @@
 """Exception hierarchy for sendparcel."""
 
+from __future__ import annotations
+
+from typing import Any
+
 
 class SendParcelException(Exception):
     """Base exception for sendparcel."""
 
-    def __init__(self, message: str = "", context: dict | None = None) -> None:
+    def __init__(
+        self, message: str = "", context: dict[str, Any] | None = None
+    ) -> None:
         super().__init__(message)
         self.context = context or {}
 
@@ -19,3 +25,29 @@ class InvalidCallbackError(SendParcelException):
 
 class InvalidTransitionError(SendParcelException):
     """Invalid shipment state transition requested."""
+
+
+class ShipmentNotFoundError(SendParcelException):
+    """Shipment not found in repository."""
+
+    def __init__(
+        self, shipment_id: str, context: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(f"Shipment {shipment_id} not found", context)
+        self.shipment_id = shipment_id
+
+
+class ProviderNotFoundError(SendParcelException):
+    """Provider slug not found in the registry."""
+
+    def __init__(
+        self, provider_slug: str, context: dict[str, Any] | None = None
+    ) -> None:
+        super().__init__(
+            f"Provider {provider_slug!r} is not registered", context
+        )
+        self.provider_slug = provider_slug
+
+
+class ProviderCapabilityError(SendParcelException):
+    """Provider does not support the requested capability."""