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

sendparcel/flow.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Any
 
 import httpx
@@ -9,29 +10,38 @@ import httpx
 from sendparcel.enums import ShipmentStatus
 from sendparcel.exceptions import (
     CommunicationError,
-    ProviderCapabilityError,
     SendParcelException,
 )
 from sendparcel.fsm import transition_shipment
 from sendparcel.protocols import Shipment, ShipmentRepository
-from sendparcel.provider import (
-    BaseProvider,
-    CancellableProvider,
-    LabelProvider,
-    PullStatusProvider,
-    PushCallbackProvider,
-)
+from sendparcel.provider import BaseProvider
 from sendparcel.registry import PluginRegistry
 from sendparcel.registry import registry as default_registry
 from sendparcel.types import (
     AddressInfo,
+    CallbackContext,
+    CancelOutcome,
+    CancelReason,
     CreateLabelOutcome,
     CreateShipmentOutcome,
+    GeoPoint,
     ParcelInfo,
+    PickupPoint,
     ShipmentUpdateOutcome,
     ShipmentUpdateResult,
 )
-from sendparcel.validators import run_validators
+
+
+@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:
@@ -41,12 +51,10 @@ class ShipmentFlow:
         self,
         repository: ShipmentRepository,
         config: dict[str, Any] | None = None,
-        validators: list[Any] | None = None,
         registry: PluginRegistry | None = None,
     ) -> None:
         self.repository = repository
         self.config = config or {}
-        self.validators = validators or []
         self.registry = registry or default_registry
 
     async def create_shipment(
@@ -92,7 +100,7 @@ class ShipmentFlow:
 
         # Separate repository kwargs from provider kwargs.
         repo_kwargs: dict[str, Any] = {}
-        for key in ("reference_id",):
+        for key in ("reference_id", "order"):
             if key in kwargs:
                 repo_kwargs[key] = kwargs.pop(key)
 
@@ -162,13 +170,7 @@ class ShipmentFlow:
     ) -> CreateLabelOutcome:
         """Create provider label and persist shipment metadata."""
 
-        run_validators({"shipment": shipment}, validators=self.validators)
         provider = self._get_provider(shipment)
-        if not isinstance(provider, LabelProvider):
-            raise ProviderCapabilityError(
-                f"Provider {shipment.provider!r} does not support "
-                "label creation"
-            )
         label = await self._call_provider(provider.create_label(**kwargs))
         transition_shipment(shipment, ShipmentStatus.LABEL_READY)
         saved = await self.repository.update_fields(
@@ -178,25 +180,21 @@ class ShipmentFlow:
 
     async def handle_callback(
         self,
-        shipment: Shipment,
-        data: dict[str, Any],
-        headers: dict[str, Any],
-        **kwargs: Any,
+        ctx: CallbackContext,
+        *,
+        shipment: Shipment | None = None,
     ) -> ShipmentUpdateOutcome:
-        """Verify and apply provider callback."""
+        """Verify and apply provider callback.
 
+        The caller is responsible for loading the shipment (from
+        ``ctx.shipment_id``) and passing it in. If ``shipment`` is not
+        provided, it will be loaded from the repository.
+        """
+        if shipment is None:
+            shipment = await self.repository.get_by_id(ctx.shipment_id)
         provider = self._get_provider(shipment)
-        if not isinstance(provider, PushCallbackProvider):
-            raise ProviderCapabilityError(
-                f"Provider {shipment.provider!r} does not support "
-                "push callbacks"
-            )
-        await self._call_provider(
-            provider.verify_callback(data, headers, **kwargs)
-        )
-        update = await self._call_provider(
-            provider.handle_callback(data, headers, **kwargs)
-        )
+        await self._call_provider(provider.verify_callback(ctx))
+        update = await self._call_provider(provider.handle_callback(ctx))
         normalized_update = update or ShipmentUpdateResult()
         saved = await self._apply_update(shipment, normalized_update)
         return ShipmentUpdateOutcome(shipment=saved, update=normalized_update)
@@ -207,38 +205,99 @@ class ShipmentFlow:
         """Fetch status from provider and persist."""
 
         provider = self._get_provider(shipment)
-        if not isinstance(provider, PullStatusProvider):
-            raise ProviderCapabilityError(
-                f"Provider {shipment.provider!r} does not support "
-                "status polling"
-            )
         update = await self._call_provider(provider.fetch_shipment_status())
         normalized_update = update or ShipmentUpdateResult()
         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)
-        if not isinstance(provider, CancellableProvider):
-            raise ProviderCapabilityError(
-                f"Provider {shipment.provider!r} does not support cancellation"
+        outcome = await self._call_provider(provider.cancel_shipment(**kwargs))
+        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,
+                },
             )
-        cancelled = await self._call_provider(
-            provider.cancel_shipment(**kwargs)
-        )
-        if cancelled:
+        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 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
+
         provider_class = self.registry.get_by_slug(shipment.provider)
         provider_config = self.config.get(shipment.provider, {})
-        return provider_class(shipment, config=provider_config)
+        return create_provider(shipment, provider_class, provider_config)
 
     async def _apply_update(
         self, shipment: Shipment, update: ShipmentUpdateResult

sendparcel/fsm.py

@@ -6,7 +6,7 @@ from sendparcel.enums import ShipmentStatus
 from sendparcel.exceptions import InvalidTransitionError
 from sendparcel.protocols import Shipment
 
-ALLOWED_STATUS_TRANSITIONS: dict[ShipmentStatus, frozenset[ShipmentStatus]] = {
+_ALLOWED_TRANSITIONS: dict[ShipmentStatus, frozenset[ShipmentStatus]] = {
     ShipmentStatus.NEW: frozenset(
         {
             ShipmentStatus.CREATED,
@@ -64,7 +64,7 @@ ALLOWED_STATUS_TRANSITIONS: dict[ShipmentStatus, frozenset[ShipmentStatus]] = {
 }
 
 
-def normalize_status(status: str | ShipmentStatus) -> ShipmentStatus:
+def _normalize(status: str | ShipmentStatus) -> ShipmentStatus:
     """Normalise a status to a :class:`ShipmentStatus` enum member."""
 
     try:
@@ -81,11 +81,11 @@ def can_transition(
 ) -> bool:
     """Check whether a shipment status transition is allowed."""
 
-    current = normalize_status(current_status)
-    target = normalize_status(target_status)
+    current = _normalize(current_status)
+    target = _normalize(target_status)
     if current == target:
         return True
-    return target in ALLOWED_STATUS_TRANSITIONS[current]
+    return target in _ALLOWED_TRANSITIONS[current]
 
 
 def transition_shipment(
@@ -93,12 +93,12 @@ def transition_shipment(
 ) -> Shipment:
     """Apply a validated status transition to a shipment."""
 
-    current = normalize_status(shipment.status)
-    target = normalize_status(target_status)
+    current = _normalize(shipment.status)
+    target = _normalize(target_status)
     if current == target:
         shipment.status = target.value
         return shipment
-    if target not in ALLOWED_STATUS_TRANSITIONS[current]:
+    if target not in _ALLOWED_TRANSITIONS[current]:
         raise InvalidTransitionError(
             f"Shipment cannot transition from {current!r} to {target!r}"
         )

sendparcel/logging.py

@@ -29,19 +29,6 @@ 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.
 
@@ -49,7 +36,7 @@ class _JsonFormatter(logging.Formatter):
     """
 
     def format(self, record: logging.LogRecord) -> str:
-        extra = _format_extra(getattr(record, "extra", None))
+        extra = getattr(record, "extra", None) or {}
         log_entry: dict[str, Any] = {
             "timestamp": datetime.now(UTC).isoformat(),
             "level": record.levelname,
@@ -67,11 +54,10 @@ 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}"
+        extra = getattr(record, "extra", None) or {}
+        if extra:
+            extra_str = " ".join(f"{k}={v}" for k, v in extra.items())
+            record.msg = f"{record.msg} {extra_str}"
         return super().format(record)
 
 
@@ -149,7 +135,3 @@ def get_logger(
 # ``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/provider.py

@@ -1,23 +1,40 @@
-"""Base provider abstraction and capability trait mixins."""
+"""Base provider abstraction."""
 
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from typing import Any, ClassVar
 
 from sendparcel.enums import ConfirmationMethod
+from sendparcel.exceptions import ProviderCapabilityError
 from sendparcel.protocols import Shipment
 from sendparcel.types import (
     AddressInfo,
+    CallbackContext,
+    CancelOutcome,
+    GeoPoint,
     LabelInfo,
     ParcelInfo,
+    PickupPoint,
+    Quote,
     ShipmentCreateResult,
     ShipmentUpdateResult,
 )
 
 
 class BaseProvider(ABC):
-    """Base class for parcel delivery providers."""
+    """Base class for parcel delivery providers.
+
+    Capability methods (``create_label``, ``handle_callback``,
+    ``fetch_shipment_status``, ``cancel_shipment``) raise
+    :exc:`ProviderCapabilityError` by default.  Override only the
+    methods the provider supports.
+
+    The flow orchestrator calls capability methods directly — no
+    ``isinstance`` trait checks.  If a provider doesn't support a
+    capability, the default implementation raises.
+    """
 
     slug: ClassVar[str] = ""
     display_name: ClassVar[str] = ""
@@ -26,18 +43,138 @@ class BaseProvider(ABC):
     confirmation_method: ClassVar[ConfirmationMethod] = ConfirmationMethod.NONE
     user_selectable: ClassVar[bool] = True
     config_schema: ClassVar[dict[str, Any]] = {}
+    transport_factory: ClassVar[Callable[..., Any] | None] = None
+    """Callable that builds a transport from config dict.
+    Signature: transport_factory(**config) -> transport.
+    None means the provider doesn't need HTTP transport (e.g. DummyProvider).
+    """
 
     def __init__(
-        self, shipment: Shipment, config: dict[str, Any] | None = None
+        self,
+        shipment: Shipment,
+        config: dict[str, Any] | None = None,
+        *,
+        transport: Any = None,
     ) -> None:
         self.shipment = shipment
         self.config = config or {}
+        self._transport = transport
+        if self.config_schema:
+            self._validate_config()
 
     def get_setting(self, name: str, default: Any = None) -> Any:
         """Read provider setting from config."""
-
         return self.config.get(name, default)
 
+    def _get_client(self) -> Any:
+        """Return the injected transport, or raise if not configured."""
+        if self._transport is None:
+            raise RuntimeError(
+                f"{self.__class__.__name__} requires a transport. "
+                "Use create_provider() to wire the provider."
+            )
+        return self._transport
+
+    def _validate_config(self) -> None:
+        """Validate configuration against config_schema."""
+        for field_name, spec in self.config_schema.items():
+            if not spec.get("required", False):
+                continue
+            value = self.get_setting(field_name)
+            if value is None or value == "":
+                raise ValueError(
+                    f"{self.__class__.__name__} requires "
+                    f"'{field_name}' in config."
+                )
+            expected_type = spec.get("type")
+            if expected_type and value is not None:
+                type_map: dict[str, type | tuple[type, ...]] = {
+                    "str": str,
+                    "int": int,
+                    "float": (int, float),
+                    "bool": bool,
+                    "list[str]": list,
+                }
+                python_type = type_map.get(expected_type)
+                if python_type and not isinstance(value, python_type):
+                    raise TypeError(
+                        f"{self.__class__.__name__} config '{field_name}' "
+                        f"must be {expected_type}, got {type(value).__name__}"
+                    )
+
+    def _address_to_provider(
+        self,
+        addr: AddressInfo,
+        *,
+        field_format: str = "snake",
+    ) -> dict[str, Any]:
+        """Convert AddressInfo to provider-specific address dict.
+
+        field_format: 'snake' (default), 'camel', 'pascal'
+        Subclasses can override _address_format ClassVar to set their default.
+        """
+        fmt = getattr(self, "_address_format", field_format)
+
+        def _convert(key: str) -> str:
+            if fmt == "camel":
+                parts = key.split("_")
+                return parts[0] + "".join(p.capitalize() for p in parts[1:])
+            elif fmt == "pascal":
+                return "".join(p.capitalize() for p in key.split("_"))
+            return key  # snake
+
+        result: dict[str, Any] = {}
+
+        # Map common fields
+        field_mappings = [
+            ("company", "company"),
+            ("first_name", "first_name"),
+            ("last_name", "last_name"),
+            ("name", "name"),
+            ("street", "street"),
+            ("building_number", "building_number"),
+            ("flat_number", "flat_number"),
+            ("line1", "line1"),
+            ("city", "city"),
+            ("country_code", "country_code"),
+            ("postal_code", "postal_code"),
+            ("phone", "phone"),
+            ("email", "email"),
+        ]
+
+        for src, dst in field_mappings:
+            value = addr.get(src)
+            if value:
+                result[_convert(dst)] = value
+
+        return result
+
+    def _parcels_to_provider(
+        self,
+        parcels: list[ParcelInfo],
+    ) -> list[dict[str, Any]]:
+        """Convert ParcelInfo list to provider-specific parcel dicts."""
+        result = []
+        for parcel in parcels:
+            p: dict[str, Any] = {}
+            weight = parcel.get("weight_kg")
+            if weight is not None:
+                p["weight"] = float(weight)
+
+            length = parcel.get("length_cm")
+            width = parcel.get("width_cm")
+            height = parcel.get("height_cm")
+            if length:
+                p["length"] = float(length)
+            if width:
+                p["width"] = float(width)
+            if height:
+                p["height"] = float(height)
+
+            result.append(p)
+
+        return result or [{"weight": 1.0}]
+
     @abstractmethod
     async def create_shipment(
         self,
@@ -49,44 +186,125 @@ class BaseProvider(ABC):
     ) -> ShipmentCreateResult:
         """Create shipment in provider API."""
 
-
-class LabelProvider(ABC):
-    """Trait for providers that support label generation."""
-
-    @abstractmethod
     async def create_label(self, **kwargs: Any) -> LabelInfo:
-        """Create or fetch label payload for a shipment."""
+        """Create or fetch label payload for a shipment.
 
+        Raises :exc:`ProviderCapabilityError` if the provider does not
+        support label generation.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "label creation"
+        )
 
-class PushCallbackProvider(ABC):
-    """Trait for providers that receive push notifications."""
+    async def verify_callback(self, ctx: CallbackContext) -> None:
+        """Verify callback authenticity.
 
-    @abstractmethod
-    async def verify_callback(
-        self, data: dict[str, Any], headers: dict[str, Any], **kwargs: Any
-    ) -> None:
-        """Verify callback authenticity."""
+        Raises :exc:`ProviderCapabilityError` if the provider does not
+        support push callbacks.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "push callbacks"
+        )
 
-    @abstractmethod
     async def handle_callback(
-        self, data: dict[str, Any], headers: dict[str, Any], **kwargs: Any
+        self, ctx: CallbackContext
     ) -> ShipmentUpdateResult:
-        """Normalize callback data into a shipment update payload."""
-
+        """Normalize callback data into a shipment update payload.
 
-class PullStatusProvider(ABC):
-    """Trait for providers that support status polling."""
+        Raises :exc:`ProviderCapabilityError` if the provider does not
+        support push callbacks.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "push callbacks"
+        )
 
-    @abstractmethod
     async def fetch_shipment_status(
         self, **kwargs: Any
     ) -> ShipmentUpdateResult:
-        """Fetch latest shipment update from provider."""
+        """Fetch latest shipment update from provider.
 
+        Raises :exc:`ProviderCapabilityError` if the provider does not
+        support status polling.
+        """
+        raise ProviderCapabilityError(
+            f"Provider {self.__class__.__name__!r} does not support "
+            "status polling"
+        )
 
-class CancellableProvider(ABC):
-    """Trait for providers that support shipment cancellation."""
+    async def cancel_shipment(self, **kwargs: Any) -> CancelOutcome:
+        """Cancel shipment if provider supports cancellation.
 
-    @abstractmethod
-    async def cancel_shipment(self, **kwargs: Any) -> bool:
-        """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.
+        """
+        raise ProviderCapabilityError(
+            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"
+        )