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

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

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

{python_sendparcel-0.3.0.dist-info → python_sendparcel-0.3.1.dist-info}/RECORD

@@ -1,20 +1,20 @@
-sendparcel/__init__.py,sha256=OZbB9xNjPbJvnKnaqHv4Ds7-IFc-M8sbjSgkszdNNE8,1521
+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=6NED69FuqrvoVVXMk6P2V1RymLX_4V3-KIm7Ch2aAXk,10360
+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=H28ZjvBpHY4C3LBvSm7DYa645300N4k2-X2fvl0epqc,8201
+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=nNECD7J6WZSlB8-SXnkperAW3d5zmKOM-9l-u9dZ5mk,3042
+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.0.dist-info/METADATA,sha256=UJGCgut2oKHrg8P6HylzOvU2LeWCLE7l-0aoAoOCEpQ,7175
-python_sendparcel-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-python_sendparcel-0.3.0.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
-python_sendparcel-0.3.0.dist-info/RECORD,,
+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

@@ -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",

sendparcel/flow.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Any
 
 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,87 @@ 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)
-        )
-        if cancelled:
+        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,
+                },
+            )
+        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

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"
+        )

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.