click_and_drop_api 3.0.3__tar.gz → 3.0.4__tar.gz

{click_and_drop_api-3.0.3/click_and_drop_api.egg-info → click_and_drop_api-3.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: click_and_drop_api
-Version: 3.0.3
+Version: 3.0.4
 Summary: ChannelShipper & Royal Mail Public API
 Home-page: 
 Author: OpenAPI Generator community

click_and_drop_api-3.0.4/click_and_drop_api/examples/oba_full_workflow.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python
+"""Full OBA workflow: create a cheap domestic order, generate a label,
+apply postage via manifest, and mark the order as despatched.
+
+Steps performed:
+  1. Verify the account is OBA (required for label generation and OBA services)
+  2. Pick the cheapest domestic OBA service
+  3. Create the order (with label generation requested at creation time)
+  4. Save the label PDF to disk
+  5. Manifest eligible orders (applies postage)
+  6. Set the order status to "despatched"
+
+Note: Label generation is only available for OBA customers.
+"""
+
+import os
+import sys
+from datetime import datetime, UTC
+from pathlib import Path
+
+from click_and_drop_api.simple import (
+    ClickAndDrop,
+    CreateOrder,
+    LabelGeneration,
+    RecipientDetails,
+    Address,
+    db,
+)
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+API_KEY = os.environ["API_KEY"]
+REFERENCE = "oba-workflow-{now}".format(now=datetime.now(UTC).strftime("%Y%m%d%H%M%S"))
+WEIGHT_GRAMS = 100
+
+api = ClickAndDrop(API_KEY)
+
+# ---------------------------------------------------------------------------
+# Step 1: verify OBA
+# ---------------------------------------------------------------------------
+
+print("Checking account type…")
+if not api.is_oba():
+    print("ERROR: This account is not OBA. Label generation requires an OBA account.")
+    sys.exit(1)
+print("Account is OBA.")
+
+# ---------------------------------------------------------------------------
+# Step 2: pick cheapest domestic OBA service
+# ---------------------------------------------------------------------------
+
+cheapest = db.filter(is_oba=True, international=False).any_or_none
+if cheapest is None:
+    print("ERROR: No domestic OBA service found in the shipping database.")
+    sys.exit(1)
+
+print(
+    f"Using service: {cheapest.brand} {cheapest.service_code}"
+    f" ({cheapest.delivery_speed}) — £{cheapest.gross}"
+)
+
+# ---------------------------------------------------------------------------
+# Step 3: create the order, requesting a label in the response
+# ---------------------------------------------------------------------------
+
+order = CreateOrder(
+    order_reference=REFERENCE,
+    recipient=RecipientDetails(
+        address=Address(
+            full_name="Nicco Kunzmann",
+            address_line1="1 Test Street",
+            city="London",
+            postcode="SW1A 1AA",
+            country_code="GB",
+        )
+    ),
+    order_date=datetime.now(UTC),
+    subtotal=1.00,
+    shipping_cost_charged=float(cheapest.gross),
+    total=1.00 + float(cheapest.gross),
+    currency_code="GBP",
+    postage_details=cheapest.as_postage_details(),
+    packages=[cheapest.as_package_request(weight_in_grams=WEIGHT_GRAMS)],
+    label=LabelGeneration(
+        include_label_in_response=True,
+        include_cn=False,
+        include_returns_label=False,
+    ),
+)
+
+print(f"Creating order {REFERENCE!r}…")
+response = api.create_order(order)
+
+if response.errors_count or not response.created_orders:
+    print(f"ERROR: Order creation failed: {response.failed_orders}")
+    sys.exit(1)
+
+created = response.created_orders[0]
+order_id = created.order_identifier
+print(f"Order created: id={order_id}, reference={created.order_reference}")
+
+# ---------------------------------------------------------------------------
+# Step 4: save label PDF
+# ---------------------------------------------------------------------------
+
+print("Fetching label…")
+label_pdf = api.get_label(order_id, "postageLabel", include_returns_label=False)
+label_path = Path(__file__).parent / "label.pdf"
+label_path.write_bytes(label_pdf)
+print(f"Label saved to {label_path}")
+
+# ---------------------------------------------------------------------------
+# Step 5: manifest (applies postage)
+# ---------------------------------------------------------------------------
+
+print("Manifesting eligible orders…")
+manifest = api.manifest_orders()
+print(f"Manifest number: {manifest.manifest_number}")
+if manifest.pdf is not None:
+    manifest_path = Path(__file__).parent / "manifest.pdf"
+    manifest_path.write_bytes(manifest.pdf)
+    print(f"Manifest PDF saved to {manifest_path}")
+
+# ---------------------------------------------------------------------------
+# Step 6: mark as despatched
+# ---------------------------------------------------------------------------
+
+print(f"Setting order {order_id} to 'despatched'…")
+update = api.update_orders([order_id], status="despatched")
+
+if update.errors:
+    print(f"WARNING: status update errors: {update.errors}")
+else:
+    print("Order marked as despatched.")
+
+print("Done.")

{click_and_drop_api-3.0.3 → click_and_drop_api-3.0.4}/click_and_drop_api/simple/api.py

@@ -170,5 +170,15 @@ class ClickAndDrop(AbstractClickAndDrop):
             include_cn=include_cn,
         )
 
+    def _set_order_status(
+        self, request: click_and_drop_api.UpdateOrdersStatusRequest
+    ) -> click_and_drop_api.UpdateOrderStatusResponse:
+        return self._orders_api.update_orders_status_async(request)
+
+    def _manifest_orders(
+        self, request: click_and_drop_api.ManifestEligibleOrdersRequest
+    ) -> click_and_drop_api.ManifestOrdersResponse:
+        return self._manifests_api.manifest_eligible_async(request)
+
 
 __all__ = ["ClickAndDrop"]

{click_and_drop_api-3.0.3 → click_and_drop_api-3.0.4}/click_and_drop_api/simple/base.py

@@ -3,7 +3,9 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+import os
 from typing import Literal, Optional, Union
+from click_and_drop_api.simple.compatibility import Self
 
 import click_and_drop_api
 
@@ -12,7 +14,17 @@ from datetime import datetime, timezone
 
 from click_and_drop_api.exceptions import ApiException
 from click_and_drop_api.models.create_order_response import CreateOrderResponse
+from click_and_drop_api.models.manifest_eligible_orders_request import (
+    ManifestEligibleOrdersRequest,
+)
+from click_and_drop_api.models.manifest_orders_response import ManifestOrdersResponse
 from click_and_drop_api.models.order_field_response import OrderFieldResponse
+from click_and_drop_api.models.update_order_status_response import (
+    UpdateOrderStatusResponse,
+)
+from click_and_drop_api.models.update_orders_status_request import (
+    UpdateOrdersStatusRequest,
+)
 from click_and_drop_api.simple import (
     Address,
     CreateOrder,
@@ -22,11 +34,17 @@ from click_and_drop_api.simple import (
 )
 from click_and_drop_api.simple.shipping_test_result import ShippingTestResult
 from click_and_drop_api.simple.addresses import get_address, get_all_country_codes
+from .types import ManifestedOrders, UpdateOrderStatus
 
 
 class AbstractClickAndDrop(ABC):
     """Common interface shared by ClickAndDrop and MockClickAndDrop."""
 
+    @classmethod
+    def from_env(cls, api_env_var: str = "API_KEY") -> Self:
+        api_key = os.environ[api_env_var]
+        return cls(api_key)
+
     max_order_count: int = 100
 
     @property
@@ -52,7 +70,7 @@ class AbstractClickAndDrop(ABC):
         Parameters:
             orders: One or more :class:`~click_and_drop_api.simple.types.CreateOrder` instances.
         Returns:
-            A :class:`~click_and_drop_api.CreateOrdersResponse` instance containing created and failed orders.
+            A :class:`~click_and_drop_api.models.create_orders_response.CreateOrdersResponse` instance containing created and failed orders.
 
         https://api.parcel.royalmail.com/#tag/Orders/operation/CreateOrdersAsync
         """
@@ -223,7 +241,7 @@ class AbstractClickAndDrop(ABC):
                 address for every country.
 
         Returns:
-            :class:`ShippingTestResult` with ``success=True/False`` and a message.
+            :class:`~click_and_drop_api.simple.shipping_test_result.ShippingTestResult` with ``success=True/False`` and a message.
 
         Note:
             This method only seems to work for OBA accounts
@@ -316,6 +334,171 @@ class AbstractClickAndDrop(ABC):
             postage_details=PostageDetails(service_code=service_code),
         )
 
+    def update_order_status(
+        self, updates: list[UpdateOrderStatus]
+    ) -> UpdateOrderStatusResponse:
+        """Set the status of an order.
+
+        Parameters:
+            requests: A list of UpdateOrdersStatusRequest instances.
+
+        Returns:
+            A :class:`~click_and_drop_api.models.set_order_status_resource.SetOrderStatusResource` instance containing the updated order information.
+        """
+        result = UpdateOrderStatusResponse(updated_orders=[], errors=[])
+        for i in range(0, len(updates), self.max_order_count):
+            request = UpdateOrdersStatusRequest(
+                items=updates[i : i + self.max_order_count]
+            )
+            response = self._set_order_status(request)
+            result.updated_orders.extend(response.updated_orders)
+            result.errors.extend(response.errors)
+        return result
+
+    def update_orders(
+        self,
+        order_identifiers: list[Union[str, int]] | str | int,
+        status: Literal["new", "despatchedByOtherCourier", "despatched"] | None = None,
+        tracking_number: str | None = None,
+        despatch_date: datetime | None = None,
+        shipping_carrier: str | None = None,
+        shipping_service: str | None = None,
+    ):
+        """Update the status of multiple orders."""
+        return self.update_order_status(
+            self._get_orders_update_request(
+                order_identifiers,
+                status=status,
+                tracking_number=tracking_number,
+                despatch_date=despatch_date,
+                shipping_carrier=shipping_carrier,
+                shipping_service=shipping_service,
+            )
+        )
+
+    def set_order_status(
+        self,
+        order_identifiers: list[Union[str, int]] | str | int,
+        status: Literal["new", "despatchedByOtherCourier", "despatched"],
+    ) -> UpdateOrderStatusResponse:
+        """Set the status of orders."""
+        return self.update_order_status(
+            self._get_orders_update_request(order_identifiers, status=status)
+        )
+
+    def set_order_tracking_number(
+        self, order_identifiers: list[Union[str, int]] | str | int, tracking_number: str
+    ) -> UpdateOrderStatusResponse:
+        """Set the tracking number of a orders."""
+        return self.update_order_status(
+            self._get_orders_update_request(
+                order_identifiers, tracking_number=tracking_number
+            )
+        )
+
+    def set_order_despatch_date(
+        self,
+        order_identifiers: list[Union[str, int]] | str | int,
+        despatch_date: datetime,
+    ) -> UpdateOrderStatusResponse:
+        """Set the despatch date of a orders."""
+        return self.update_order_status(
+            self._get_orders_update_request(
+                order_identifiers, despatch_date=despatch_date
+            )
+        )
+
+    def set_order_shipping_carrier(
+        self,
+        order_identifiers: list[Union[str, int]] | str | int,
+        shipping_carrier: str,
+    ) -> UpdateOrderStatusResponse:
+        """Set the shipping carrier of a orders."""
+        return self.update_order_status(
+            self._get_orders_update_request(
+                order_identifiers, shipping_carrier=shipping_carrier
+            )
+        )
+
+    def set_order_shipping_service(
+        self,
+        order_identifiers: list[Union[str, int]] | str | int,
+        shipping_service: str,
+    ) -> UpdateOrderStatusResponse:
+        """Set the shipping service of a orders."""
+        return self.update_order_status(
+            self._get_orders_update_request(
+                order_identifiers, shipping_service=shipping_service
+            )
+        )
+
+    def _get_orders_update_request(
+        self,
+        order_identifiers: list[Union[str, int]] | str | int,
+        status: str | None = None,
+        tracking_number: str | None = None,
+        despatch_date: datetime | None = None,
+        shipping_carrier: str | None = None,
+        shipping_service: str | None = None,
+    ) -> list[UpdateOrderStatus]:
+        """Get a list of UpdateOrderStatus for the given order identifiers and attributes."""
+        if not isinstance(order_identifiers, list):
+            order_identifiers = [order_identifiers]
+        result = []
+        for identifier in order_identifiers:
+            order_id = identifier if isinstance(identifier, int) else None
+            order_ref = identifier if isinstance(identifier, str) else None
+            result.append(
+                UpdateOrderStatus(
+                    order_identifier=order_id,
+                    order_reference=order_ref,
+                    status=status,
+                    tracking_number=tracking_number,
+                    despatch_date=despatch_date,
+                    shipping_carrier=shipping_carrier,
+                    shipping_service=shipping_service,
+                )
+            )
+        return result
+
+    @abstractmethod
+    def _set_order_status(
+        self, request: UpdateOrdersStatusRequest
+    ) -> UpdateOrderStatusResponse:
+        """Set the status of an order."""
+
+    @abstractmethod
+    def _manifest_orders(
+        self, request: ManifestEligibleOrdersRequest
+    ) -> ManifestOrdersResponse:
+        """Manifest eligible orders."""
+
+    def manifest_orders(self, carrier_name: str | None = None) -> ManifestedOrders:
+        """Manifest all eligible orders, applying postage.
+
+        Manifests all orders in ``Label Generated`` and ``Despatched`` statuses
+        and returns manifest paperwork where possible.
+
+        Parameters:
+            carrier_name:
+                Required when the account has multiple carriers or postage
+                location numbers. Must match the carrier name configured in the
+                account settings. Pass ``None`` for single-carrier accounts.
+
+        Returns:
+            A :class:`~click_and_drop_api.models.manifest_orders_response.ManifestOrdersResponse`
+            containing the manifest number and an optional base64-encoded PDF.
+
+        https://api.parcel.royalmail.com/#tag/Manifests/operation/ManifestEligibleAsync
+        """
+        response = self._manifest_orders(
+            ManifestEligibleOrdersRequest(carrier_name=carrier_name)
+        )
+        return ManifestedOrders(
+            manifest_number=response.manifest_number,
+            document_pdf=response.document_pdf,
+        )
+
 
 __all__ = [
     "AbstractClickAndDrop",

click_and_drop_api-3.0.4/click_and_drop_api/simple/compatibility.py

@@ -0,0 +1,8 @@
+import sys
+
+if sys.version_info < (3, 11):
+    from typing_extensions import Self
+else:
+    from typing import Self
+
+__all__ = ["Self"]

{click_and_drop_api-3.0.3 → click_and_drop_api-3.0.4}/click_and_drop_api/simple/mock.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import base64
+from importlib.resources import files
 from datetime import datetime, timezone
 from typing import Literal, Optional, Union
 
@@ -26,7 +28,7 @@ class MockClickAndDrop(AbstractClickAndDrop):
         assert response.success_count == 1
     """
 
-    def __init__(self, key: str = _MOCK_KEY):
+    def __init__(self, key: str = _MOCK_KEY, is_oba: bool = True):
         if not isinstance(key, str):
             raise TypeError(f"Expected str, got {key}.")
         key = key.strip()
@@ -35,8 +37,13 @@ class MockClickAndDrop(AbstractClickAndDrop):
         if "".join(key.split()) != key:
             raise ValueError(f"Expected no whitespace in {key!r}.")
         self._key = key
+        self._is_oba = is_oba
         self._orders: dict[int, click_and_drop_api.GetOrderInfoResource] = {}
         self._next_id = 1
+        self._next_manifest_id = 1
+
+    def is_oba(self) -> bool:
+        return self._is_oba
 
     @property
     def key(self) -> str:
@@ -135,7 +142,46 @@ class MockClickAndDrop(AbstractClickAndDrop):
         include_returns_label: Optional[bool] = None,
         include_cn: Optional[bool] = None,
     ) -> bytearray:
-        return bytearray(b"%PDF-1.4 mock label\n")
+        data = (
+            files("click_and_drop_api.examples").joinpath("mock-label.pdf").read_bytes()
+        )
+        return bytearray(data)
+
+    def _manifest_orders(
+        self, request: click_and_drop_api.ManifestEligibleOrdersRequest
+    ) -> click_and_drop_api.ManifestOrdersResponse:
+        manifest_id = self._next_manifest_id
+        self._next_manifest_id += 1
+        data = (
+            files("click_and_drop_api.examples")
+            .joinpath("mock-manifest.pdf")
+            .read_bytes()
+        )
+        return click_and_drop_api.ManifestOrdersResponse(
+            manifest_number=manifest_id,
+            document_pdf=base64.b64encode(data).decode(),
+        )
+
+    def _set_order_status(
+        self, request: click_and_drop_api.UpdateOrdersStatusRequest
+    ) -> click_and_drop_api.UpdateOrderStatusResponse:
+        # For simplicity, this mock does not actually update the orders.
+        # It just returns a successful response for all items in the request.
+        created = []
+        errors = []
+        for item in request.items or []:
+            created.append(
+                click_and_drop_api.UpdatedOrderInfo(
+                    order_identifier=item.order_identifier,
+                    order_reference=item.order_reference,
+                    status=item.status,
+                )
+            )
+
+        return click_and_drop_api.UpdateOrderStatusResponse(
+            updated_orders=created,
+            errors=errors,
+        )
 
 
 __all__ = ["MockClickAndDrop"]

{click_and_drop_api-3.0.3 → click_and_drop_api-3.0.4}/click_and_drop_api/simple/types.py

@@ -1,5 +1,7 @@
 """Renamed types for nicer reading"""
 
+import base64
+
 from click_and_drop_api.models.address_request import AddressRequest as Address
 from click_and_drop_api.models.billing_details_request import (
     BillingDetailsRequest as BillingDetails,
@@ -20,6 +22,7 @@ from click_and_drop_api.models.manifest_details_response import (
 from click_and_drop_api.models.manifest_eligible_orders_request import (
     ManifestEligibleOrdersRequest as ManifestEligibleOrders,
 )
+from click_and_drop_api.models.manifest_orders_response import ManifestOrdersResponse
 from click_and_drop_api.models.postage_details_request import (
     PostageDetailsRequest as PostageDetails,
 )
@@ -47,9 +50,19 @@ from click_and_drop_api.models.update_orders_status_request import (
 )
 
 
+class ManifestedOrders(ManifestOrdersResponse):
+    @property
+    def pdf(self) -> bytearray | None:
+        """Return the PDF content of the manifest as a bytearray, or None if unavailable."""
+        if self.document_pdf is None:
+            return None
+        return bytearray(base64.b64decode(self.document_pdf))
+
+
 __all__ = [
     "CreateOrder",
     "RecipientDetails",
+    "ManifestedOrders",
     "Address",
     "PostageDetails",
     "ShipmentPackage",

{click_and_drop_api-3.0.3 → click_and_drop_api-3.0.4/click_and_drop_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: click_and_drop_api
-Version: 3.0.3
+Version: 3.0.4
 Summary: ChannelShipper & Royal Mail Public API
 Home-page: 
 Author: OpenAPI Generator community

{click_and_drop_api-3.0.3 → click_and_drop_api-3.0.4}/click_and_drop_api.egg-info/SOURCES.txt

@@ -26,6 +26,9 @@ click_and_drop_api/examples/__main__.py
 click_and_drop_api/examples/check_oba.py
 click_and_drop_api/examples/create_order.py
 click_and_drop_api/examples/generate_label.py
+click_and_drop_api/examples/mock-label.pdf
+click_and_drop_api/examples/mock-manifest.pdf
+click_and_drop_api/examples/oba_full_workflow.py
 click_and_drop_api/examples/package_size_and_cost.py
 click_and_drop_api/examples/shipping_countries.py
 click_and_drop_api/examples/view_order.py
@@ -80,6 +83,7 @@ click_and_drop_api/simple/__init__.py
 click_and_drop_api/simple/addresses.py
 click_and_drop_api/simple/api.py
 click_and_drop_api/simple/base.py
+click_and_drop_api/simple/compatibility.py
 click_and_drop_api/simple/errors.py
 click_and_drop_api/simple/mock.py
 click_and_drop_api/simple/shipping_test_result.py
@@ -148,6 +152,8 @@ test/test_manifest_errors_response.py
 test/test_manifest_orders_response.py
 test/test_manifests_api.py
 test/test_mock_api.py
+test/test_mock_api_manifest.py
+test/test_mock_api_update_orders.py
 test/test_oba_parser.py
 test/test_order_error_info.py
 test/test_order_error_response.py

{click_and_drop_api-3.0.3 → click_and_drop_api-3.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "click_and_drop_api"
-version = "3.0.3"
+version = "3.0.4"
 description = "ChannelShipper & Royal Mail Public API"
 authors = [
   {name = "Nicco Kunzmann", email = "niccokunzmann@rambler.ru"},
@@ -73,6 +73,9 @@ cli = [
   "tox",
 ]
 
+[tool.setuptools.package-data]
+"click_and_drop_api.examples" = ["*.pdf"]
+
 [build-system]
 requires = ["setuptools"]
 build-backend = "setuptools.build_meta"

{click_and_drop_api-3.0.3 → click_and_drop_api-3.0.4}/test/test_mock_api.py

@@ -260,6 +260,21 @@ def test_test_shipping_multiple_calls_stay_clean(api):
     assert len(api._orders) == 0
 
 
+# --- is_oba ---
+
+
+def test_is_oba_default_is_true():
+    assert MockClickAndDrop().is_oba() is True
+
+
+def test_is_oba_true():
+    assert MockClickAndDrop(is_oba=True).is_oba() is True
+
+
+def test_is_oba_false():
+    assert MockClickAndDrop(is_oba=False).is_oba() is False
+
+
 # --- format_fields_for_error_message ---
 
 

click_and_drop_api-3.0.4/test/test_mock_api_manifest.py

@@ -0,0 +1,51 @@
+"""Tests for manifest_orders."""
+
+import pytest
+
+from click_and_drop_api.models.manifest_orders_response import ManifestOrdersResponse
+from click_and_drop_api.simple.mock import MockClickAndDrop
+from click_and_drop_api.simple.types import ManifestedOrders
+
+
+@pytest.fixture
+def api() -> MockClickAndDrop:
+    return MockClickAndDrop()
+
+
+def test_manifest_orders_returns_response(api: MockClickAndDrop) -> None:
+    result = api.manifest_orders()
+    assert isinstance(result, ManifestOrdersResponse)
+
+
+def test_manifest_orders_has_manifest_number(api: MockClickAndDrop) -> None:
+    result = api.manifest_orders()
+    assert result.manifest_number is not None
+
+
+def test_manifest_orders_with_carrier_name(api: MockClickAndDrop) -> None:
+    result = api.manifest_orders(carrier_name="Royal Mail")
+    assert isinstance(result, ManifestOrdersResponse)
+
+
+def test_manifest_orders_increments_manifest_number(api: MockClickAndDrop) -> None:
+    r1 = api.manifest_orders()
+    r2 = api.manifest_orders()
+    assert r2.manifest_number != r1.manifest_number
+
+
+# --- .pdf property ---
+
+
+def test_manifest_orders_pdf_returns_bytearray(api: MockClickAndDrop) -> None:
+    result: ManifestedOrders = api.manifest_orders()
+    assert isinstance(result.pdf, bytearray)
+
+
+def test_manifest_orders_pdf_starts_with_pdf_header(api: MockClickAndDrop) -> None:
+    result: ManifestedOrders = api.manifest_orders()
+    assert result.pdf[:4] == bytearray(b"%PDF")
+
+
+def test_manifest_orders_pdf_none_when_no_document() -> None:
+    result = ManifestedOrders(manifest_number=1, document_pdf=None)
+    assert result.pdf is None