python-sendparcel 0.3.0__tar.gz → 0.3.2__tar.gz

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.2 (2026-07-09)
+
+- `DummyProvider.cancel_shipment` returns a structured `CancelOutcome`
+  (configurable via `cancel_success` / `cancel_reason` settings) instead of a
+  bare bool — aligning core's own provider with the 0.3.1 cancel trait that
+  `ShipmentFlow.cancel_shipment` already requires.
+- `ShipmentFlow`: typed returns for `cancel_shipment` / `search_points`
+  (mypy no-any-return).
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/),

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-sendparcel
-Version: 0.3.0
+Version: 0.3.2
 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

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-sendparcel"
-version = "0.3.0"
+version = "0.3.2"
 description = "Framework-agnostic parcel shipping core for Python."
 readme = "README.md"
 license = { text = "MIT" }

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/src/sendparcel/__init__.py

@@ -21,8 +21,13 @@ 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,
 )
@@ -32,16 +37,21 @@ __all__ = [
     "BatchCreateResult",
     "BatchResult",
     "CallbackContext",
+    "CancelOutcome",
+    "CancelReason",
     "CommunicationError",
     "ConfirmationMethod",
     "CreateLabelOutcome",
     "CreateShipmentOutcome",
     "DummyProvider",
+    "GeoPoint",
     "InvalidCallbackError",
     "InvalidTransitionError",
     "LabelFormat",
+    "PickupPoint",
     "ProviderCapabilityError",
     "ProviderNotFoundError",
+    "Quote",
     "SendParcelException",
     "ShipmentBatch",
     "ShipmentFlow",

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/src/sendparcel/flow.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from typing import Any
+from dataclasses import dataclass
+from typing import Any, cast
 
 import httpx
 
@@ -19,14 +20,30 @@ from sendparcel.registry import registry as default_registry
 from sendparcel.types import (
     AddressInfo,
     CallbackContext,
+    CancelOutcome,
+    CancelReason,
     CreateLabelOutcome,
     CreateShipmentOutcome,
+    GeoPoint,
     ParcelInfo,
+    PickupPoint,
     ShipmentUpdateOutcome,
     ShipmentUpdateResult,
 )
 
 
+@dataclass(slots=True)
+class _PointSearchShipment:
+    """Placeholder satisfying the Shipment protocol for provider calls
+    that do not operate on a specific shipment (e.g. point search)."""
+
+    provider: str
+    id: str = ""
+    status: str = "new"
+    external_id: str = ""
+    tracking_number: str = ""
+
+
 class ShipmentFlow:
     """Framework-agnostic shipment orchestration."""
 
@@ -193,19 +210,93 @@ class ShipmentFlow:
         saved = await self._apply_update(shipment, normalized_update)
         return ShipmentUpdateOutcome(shipment=saved, update=normalized_update)
 
-    async def cancel_shipment(self, shipment: Shipment, **kwargs: Any) -> bool:
-        """Cancel shipment via provider and persist state."""
-
+    async def cancel_shipment(
+        self, shipment: Shipment, **kwargs: Any
+    ) -> CancelOutcome:
+        """Cancel shipment via provider and persist state.
+
+        Returns a structured :class:`CancelOutcome` so callers can
+        distinguish permanent denies from retryable failures.
+
+        - ``CANCELLED`` / ``ALREADY_CANCELLED`` → transitions shipment to
+          ``CANCELLED``.
+        - ``REFUSED_IN_TRANSIT`` / ``NOT_CANCELLABLE`` → leaves shipment
+          in current state (caller decides UX).
+        - ``TRANSIENT_ERROR`` → raises ``CommunicationError`` (retryable),
+          no state change.
+        - ``AUTH_ERROR`` → re-raises provider auth error.
+        """
         provider = self._get_provider(shipment)
-        cancelled = await self._call_provider(
-            provider.cancel_shipment(**kwargs)
+        outcome = cast(
+            "CancelOutcome",
+            await self._call_provider(provider.cancel_shipment(**kwargs)),
         )
-        if cancelled:
+        if outcome.get("reason") == CancelReason.TRANSIENT_ERROR:
+            raise CommunicationError(
+                outcome.get("detail") or "Cancel failed with transient error",
+                context={
+                    "provider_status_code": outcome.get("provider_status_code"),
+                    "reason": CancelReason.TRANSIENT_ERROR,
+                },
+            )
+        if outcome.get("cancelled"):
             transition_shipment(shipment, ShipmentStatus.CANCELLED)
             await self.repository.update_fields(
                 shipment_id=shipment.id, status=shipment.status
             )
-        return bool(cancelled)
+        return outcome
+
+    async def search_points(
+        self,
+        provider_slug: str,
+        *,
+        query: str | None = None,
+        near: GeoPoint | None = None,
+        radius_m: int | None = None,
+        point_type: str | None = None,
+        limit: int = 20,
+        **kwargs: Any,
+    ) -> list[PickupPoint]:
+        """Search carrier pickup points via the registered provider.
+
+        Convenience method that delegates to the provider's
+        ``search_points`` capability. Raises
+        ``ProviderCapabilityError`` if the provider does not support
+        point search.
+
+        Args:
+            provider_slug: Provider identifier.
+            query: Free-text search (city, address, or point code).
+            near: :class:`GeoPoint` for proximity search.
+            radius_m: Search radius in metres when ``near`` is given.
+            point_type: Provider taxonomy filter.
+            limit: Maximum number of results.
+
+        Returns:
+            List of :class:`PickupPoint` results.
+        """
+        provider_class = self.registry.get_by_slug(provider_slug)
+        provider_config = self.config.get(provider_slug, {})
+        from sendparcel.factory import create_provider
+
+        provider = create_provider(
+            _PointSearchShipment(provider=provider_slug),
+            provider_class,
+            provider_config,
+        )
+        return cast(
+            "list[PickupPoint]",
+            await self._call_provider(
+                provider.search_points(
+                    query=query,
+                    near=near,
+                    radius_m=radius_m,
+                    point_type=point_type,
+                    limit=limit,
+                    **kwargs,
+                )
+            ),
+        )
 
     def _get_provider(self, shipment: Shipment) -> BaseProvider:
         from sendparcel.factory import create_provider

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/src/sendparcel/provider.py

@@ -12,8 +12,12 @@ from sendparcel.protocols import Shipment
 from sendparcel.types import (
     AddressInfo,
     CallbackContext,
+    CancelOutcome,
+    GeoPoint,
     LabelInfo,
     ParcelInfo,
+    PickupPoint,
+    Quote,
     ShipmentCreateResult,
     ShipmentUpdateResult,
 )
@@ -230,9 +234,13 @@ class BaseProvider(ABC):
             "status polling"
         )
 
-    async def cancel_shipment(self, **kwargs: Any) -> bool:
+    async def cancel_shipment(self, **kwargs: Any) -> CancelOutcome:
         """Cancel shipment if provider supports cancellation.
 
+        Returns a structured :class:`CancelOutcome` so callers can
+        distinguish permanent denies (REFUSED_IN_TRANSIT, NOT_CANCELLABLE)
+        from retryable failures (TRANSIENT_ERROR).
+
         Raises :exc:`ProviderCapabilityError` if the provider does not
         support cancellation.
         """
@@ -240,3 +248,63 @@ class BaseProvider(ABC):
             f"Provider {self.__class__.__name__!r} does not support "
             "cancellation"
         )
+
+    async def search_points(
+        self,
+        *,
+        query: str | None = None,
+        near: GeoPoint | None = None,
+        radius_m: int | None = None,
+        point_type: str | None = None,
+        limit: int = 20,
+        **kwargs: Any,
+    ) -> list[PickupPoint]:
+        """Search carrier pickup points (lockers, parcel shops, etc.).
+
+        Args:
+            query: Free-text search (city, address, or point code).
+            near: :class:`GeoPoint` for proximity search.
+            radius_m: Search radius in metres when ``near`` is given.
+            point_type: Provider taxonomy filter (e.g. "parcel_locker").
+            limit: Maximum number of results to return.
+
+        Returns:
+            List of :class:`PickupPoint` results, ordered by distance
+            when ``near`` is given, else by relevance/name.
+
+        Raises:
+            ProviderCapabilityError: If the provider does not support
+                point search.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "pickup point search"
+        )
+
+    async def get_quote(
+        self,
+        *,
+        service: str,
+        parcels: list[ParcelInfo],
+        sender_address: AddressInfo | None = None,
+        receiver_address: AddressInfo | None = None,
+        **kwargs: Any,
+    ) -> Quote:
+        """Get a shipping rate quote for a service/route combination.
+
+        Args:
+            service: Service slug (e.g. "parcel_locker_31_0").
+            parcels: List of parcel definitions.
+            sender_address: Optional sender address.
+            receiver_address: Optional receiver address.
+
+        Returns:
+            :class:`Quote` with carrier cost as ``Decimal``.
+
+        Raises:
+            ProviderCapabilityError: If the provider does not support
+                rate lookup (callers should fall back to static pricing).
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support rate lookup"
+        )

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/src/sendparcel/providers/dummy.py

@@ -12,6 +12,8 @@ from sendparcel.provider import BaseProvider
 from sendparcel.types import (
     AddressInfo,
     CallbackContext,
+    CancelOutcome,
+    CancelReason,
     LabelInfo,
     ParcelInfo,
     ShipmentCreateResult,
@@ -78,6 +80,23 @@ class DummyProvider(BaseProvider):
             status=self.get_setting("status_override", self.shipment.status)
         )
 
-    async def cancel_shipment(self, **kwargs: Any) -> bool:
+    async def cancel_shipment(self, **kwargs: Any) -> CancelOutcome:
+        """Cancel with a configurable structured outcome.
+
+        Settings: ``cancel_success`` (bool, default True) and
+        ``cancel_reason`` (a :class:`CancelReason` value used when the
+        cancel is configured to fail; defaults to ``not_cancellable``).
+        """
         await self._simulate_latency()
-        return bool(self.get_setting("cancel_success", True))
+        if bool(self.get_setting("cancel_success", True)):
+            return CancelOutcome(
+                cancelled=True, reason=CancelReason.CANCELLED, retryable=False
+            )
+        reason = CancelReason(
+            self.get_setting("cancel_reason", CancelReason.NOT_CANCELLABLE)
+        )
+        return CancelOutcome(
+            cancelled=False,
+            reason=reason,
+            retryable=reason == CancelReason.TRANSIENT_ERROR,
+        )

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/src/sendparcel/types.py

@@ -5,7 +5,9 @@ from __future__ import annotations
 import hashlib
 import json
 from dataclasses import dataclass
+from datetime import datetime
 from decimal import Decimal
+from enum import StrEnum
 from typing import Any, TypedDict
 
 from sendparcel.enums import LabelFormat
@@ -107,6 +109,81 @@ class ShipmentUpdateOutcome:
     update: ShipmentUpdateResult
 
 
+class CancelReason(StrEnum):
+    """Reason for a cancel_shipment outcome."""
+
+    CANCELLED = "cancelled"
+    ALREADY_CANCELLED = "already_cancelled"
+    REFUSED_IN_TRANSIT = "refused_in_transit"
+    NOT_CANCELLABLE = "not_cancellable"
+    TRANSIENT_ERROR = "transient_error"
+    AUTH_ERROR = "auth_error"
+
+
+class _CancelOutcomeRequired(TypedDict):
+    cancelled: bool
+    reason: CancelReason
+    retryable: bool
+
+
+class CancelOutcome(_CancelOutcomeRequired, total=False):
+    """Structured result from cancel_shipment.
+
+    Replaces the bare bool return so callers can distinguish permanent
+    denies (REFUSED_IN_TRANSIT, NOT_CANCELLABLE) from retryable failures
+    (TRANSIENT_ERROR).
+    """
+
+    provider_status_code: int | None
+    detail: str | None
+
+
+class GeoPoint(TypedDict):
+    """Geographic coordinate pair."""
+
+    lat: float
+    lng: float
+
+
+class _PickupPointRequired(TypedDict):
+    code: str
+    name: str
+    provider_slug: str
+    address: str
+
+
+class PickupPoint(_PickupPointRequired, total=False):
+    """Carrier pickup point (locker, parcel shop, etc.).
+
+    ``code`` is the machine id used as ``target_point`` in
+    ``create_shipment``, so a searched point is directly usable
+    without translation.
+    """
+
+    location: GeoPoint | None
+    opening_hours: str | None
+    point_type: str | None
+    raw: dict[str, Any] | None
+
+
+class _QuoteRequired(TypedDict):
+    provider_slug: str
+    service: str
+    amount: Decimal
+    currency: str
+
+
+class Quote(_QuoteRequired, total=False):
+    """Shipping rate quote from a carrier.
+
+    ``amount`` is the carrier cost in the provider's currency.
+    Use ``Decimal`` — never ``float`` — for monetary values.
+    """
+
+    valid_until: datetime | None
+    raw: dict[str, Any] | None
+
+
 @dataclass(slots=True)
 class CallbackContext:
     """Everything needed to process a webhook callback.

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/tests/test_batch.py

@@ -15,6 +15,8 @@ from sendparcel.registry import PluginRegistry
 from sendparcel.types import (
     AddressInfo,
     CallbackContext,
+    CancelOutcome,
+    CancelReason,
     ParcelInfo,
     ShipmentCreateResult,
     ShipmentUpdateResult,
@@ -168,8 +170,14 @@ class DummyProvider(BaseProvider):
     ) -> ShipmentUpdateResult:
         return {"status": ShipmentStatus.CREATED}
 
-    async def cancel_shipment(self, **kwargs: Any) -> bool:
-        return True
+    async def cancel_shipment(self, **kwargs: Any) -> CancelOutcome:
+        return CancelOutcome(
+            cancelled=True,
+            reason=CancelReason.CANCELLED,
+            retryable=False,
+            provider_status_code=200,
+            detail=None,
+        )
 
 
 @pytest.fixture

{python_sendparcel-0.3.0 → python_sendparcel-0.3.2}/tests/test_builtin_dummy_provider.py

@@ -8,7 +8,12 @@ import pytest
 from sendparcel.enums import ConfirmationMethod
 from sendparcel.exceptions import InvalidCallbackError
 from sendparcel.providers.dummy import DummyProvider
-from sendparcel.types import AddressInfo, CallbackContext, ParcelInfo
+from sendparcel.types import (
+    AddressInfo,
+    CallbackContext,
+    CancelReason,
+    ParcelInfo,
+)
 
 _SENDER = AddressInfo(
     name="Test Sender",
@@ -166,19 +171,38 @@ class TestFetchShipmentStatus:
 
 class TestCancelShipment:
     @pytest.mark.asyncio
-    async def test_cancel_returns_true_by_default(self) -> None:
+    async def test_cancel_returns_outcome_by_default(self) -> None:
         provider = DummyProvider(DummyShipment(), config={})
 
-        result = await provider.cancel_shipment()
+        outcome = await provider.cancel_shipment()
 
-        assert result is True
+        assert outcome["cancelled"] is True
+        assert outcome["reason"] == CancelReason.CANCELLED
+        assert outcome["retryable"] is False
 
     @pytest.mark.asyncio
-    async def test_cancel_can_be_configured_to_fail(self) -> None:
+    async def test_cancel_can_be_configured_to_refuse(self) -> None:
         provider = DummyProvider(
             DummyShipment(), config={"cancel_success": False}
         )
 
-        result = await provider.cancel_shipment()
+        outcome = await provider.cancel_shipment()
+
+        assert outcome["cancelled"] is False
+        assert outcome["reason"] == CancelReason.NOT_CANCELLABLE
+        assert outcome["retryable"] is False
+
+    @pytest.mark.asyncio
+    async def test_cancel_reason_is_configurable(self) -> None:
+        provider = DummyProvider(
+            DummyShipment(),
+            config={
+                "cancel_success": False,
+                "cancel_reason": "refused_in_transit",
+            },
+        )
+
+        outcome = await provider.cancel_shipment()
 
-        assert result is False
+        assert outcome["cancelled"] is False
+        assert outcome["reason"] == CancelReason.REFUSED_IN_TRANSIT