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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-sendparcel
-Version: 0.2.0
+Version: 0.3.1
 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.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+sendparcel/__init__.py,sha256=jnFj2CbAJQLE4eeOerlAWgn0ub--fqRdhkscFRvBkfA,1689
+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=ur-GNH9UinrQy2ttErFXzRB4TTh4jdbBP8BlokIKA4A,13328
+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=lXuUevoDVdzqHFry0Mm_lSRgAJF5t6HQ1rj6sL5-_Js,10525
+sendparcel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sendparcel/registry.py,sha256=CCaU7Esd6vS5eVvvv_oLuWEhd9j17Zk3-hEOZl-_7Vk,3790
+sendparcel/types.py,sha256=E96qcbQ6qfpvtA-LRdIzQounYXDWnfMNZJypzJ3dI1g,4855
+sendparcel/providers/__init__.py,sha256=ff82dvrWuPS-UIGF5AoX_fgpcYZaGu2k6q2yrxMZacI,192
+sendparcel/providers/dummy.py,sha256=J_FOzy0NsgKeI3Zxe0vTfPBdVeVSXKGd_zyMWfBL58Q,2836
+python_sendparcel-0.3.1.dist-info/METADATA,sha256=vdcN_KGTpb5PjfoxvcSZXHerCcomZE7WDfS9dMdPXhk,7175
+python_sendparcel-0.3.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_sendparcel-0.3.1.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
+python_sendparcel-0.3.1.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,20 +13,21 @@ 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,
+    CancelOutcome,
+    CancelReason,
     CreateLabelOutcome,
     CreateShipmentOutcome,
+    GeoPoint,
+    PickupPoint,
+    Quote,
     ShipmentUpdateOutcome,
     ShipmentUpdateResult,
 )
@@ -35,20 +36,22 @@ __all__ = [
     "BaseProvider",
     "BatchCreateResult",
     "BatchResult",
-    "CancellableProvider",
+    "CallbackContext",
+    "CancelOutcome",
+    "CancelReason",
     "CommunicationError",
     "ConfirmationMethod",
     "CreateLabelOutcome",
     "CreateShipmentOutcome",
     "DummyProvider",
+    "GeoPoint",
     "InvalidCallbackError",
     "InvalidTransitionError",
     "LabelFormat",
-    "LabelProvider",
+    "PickupPoint",
     "ProviderCapabilityError",
     "ProviderNotFoundError",
-    "PullStatusProvider",
-    "PushCallbackProvider",
+    "Quote",
     "SendParcelException",
     "ShipmentBatch",
     "ShipmentFlow",
@@ -58,6 +61,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)