click_and_drop_api 3.0.2__tar.gz → 3.0.3__tar.gz

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

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

{click_and_drop_api-3.0.2 → click_and_drop_api-3.0.3}/click_and_drop_api/examples/shipping_countries.py

@@ -3,9 +3,14 @@
 
 Uses test_shipping internally: a test order is created and immediately deleted
 for each country, so no real shipments are made.
+
+Arguments:
+
+- service code (optional, defaults to OLP1)
 """
 
 import os
+import sys
 
 from click_and_drop_api.simple import ClickAndDrop
 
@@ -14,7 +19,7 @@ API_KEY = os.environ["API_KEY"]
 api = ClickAndDrop(API_KEY)
 
 PACKAGE_SIZE = "letter"
-SERVICE_CODE = "OLP1"
+SERVICE_CODE = "OLP1" if len(sys.argv) == 1 else sys.argv[1]
 
 countries = api.get_countries_for_shipping(
     package_size=PACKAGE_SIZE,

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

@@ -101,60 +101,23 @@ class ClickAndDrop(AbstractClickAndDrop):
         """The API key in use."""
         return self._key
 
-    def get_orders(
-        self, order_identifiers: Union[list[Union[str, int]], str, int]
+    def _get_orders(
+        self, order_identifiers: Union[list[Union[str, int]]]
     ) -> list[click_and_drop_api.GetOrderInfoResource]:
-        """Get specific orders.
-
-        Parameters:
-            order_identifiers:
-                One or several Order Identifiers or Order References.
-                Order Identifiers are integer numbers.
-                Order References are strings.
-                The maximum number of identifiers is 100.
-
-        Returns:
-            A list of orders
-
-        Raises:
-            click_and_drop_api.exceptions.BadRequestException if an order with the same reference already exists
-
-        https://api.parcel.royalmail.com/#tag/Orders/operation/GetSpecificOrdersAsync
-        """
         return self._orders_api.get_specific_orders_async(
             order_identifiers=order_identifiers_to_string(order_identifiers)
         )
 
-    def delete_orders(
-        self, order_identifiers: Union[list[Union[str, int]], str, int]
+    def _delete_orders(
+        self, order_identifiers: list[Union[str, int]]
     ) -> click_and_drop_api.DeleteOrdersResource:
-        """Delete specific orders.
-
-        Please be aware labels generated on orders which are deleted are no longer valid and must be destroyed.
-        Cancelled label information is automatically shared with Royal Mail Revenue Protection,
-        and should a cancelled label be identified on an item in the Royal Mail Network,
-        you will be charged on your account and an additional handling fee applied.
-
-        Parameters:
-            order_identifiers:
-                One or several Order Identifiers or Order References.
-                Order Identifiers are integer numbers.
-                Order References are strings.
-                The maximum number of identifiers is 100.
-
-        https://api.parcel.royalmail.com/#tag/Orders/operation/DeleteOrdersAsync
-        """
         return self._orders_api.delete_orders_async(
             order_identifiers=order_identifiers_to_string(order_identifiers)
         )
 
-    def create_orders(
+    def _create_orders(
         self, orders: Union[list[CreateOrder], CreateOrder]
     ) -> click_and_drop_api.CreateOrdersResponse:
-        """Create a new order.
-
-        https://api.parcel.royalmail.com/#tag/Orders/operation/CreateOrdersAsync
-        """
         if not isinstance(orders, list):
             orders = [orders]
         request = click_and_drop_api.CreateOrdersRequest(items=orders)

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

@@ -27,6 +27,8 @@ from click_and_drop_api.simple.addresses import get_address, get_all_country_cod
 class AbstractClickAndDrop(ABC):
     """Common interface shared by ClickAndDrop and MockClickAndDrop."""
 
+    max_order_count: int = 100
+
     @property
     @abstractmethod
     def key(self) -> str:
@@ -37,10 +39,35 @@ class AbstractClickAndDrop(ABC):
         """Get the API version."""
 
     @abstractmethod
+    def _create_orders(
+        self, orders: list[CreateOrder]
+    ) -> click_and_drop_api.CreateOrdersResponse:
+        """Create one or more orders."""
+
     def create_orders(
         self, orders: Union[list[CreateOrder], CreateOrder]
     ) -> click_and_drop_api.CreateOrdersResponse:
-        """Create one or more orders."""
+        """Create a new orders.
+
+        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.
+
+        https://api.parcel.royalmail.com/#tag/Orders/operation/CreateOrdersAsync
+        """
+        if isinstance(orders, CreateOrder):
+            orders = [orders]
+        result = click_and_drop_api.CreateOrdersResponse(
+            created_orders=[], failed_orders=[], success_count=0, errors_count=0
+        )
+        for i in range(0, len(orders), self.max_order_count):
+            response = self._create_orders(orders[i : i + self.max_order_count])
+            result.created_orders.extend(response.created_orders)
+            result.failed_orders.extend(response.failed_orders)
+            result.success_count += response.success_count
+            result.errors_count += response.errors_count
+        return result
 
     def create_order(
         self, order: CreateOrder
@@ -49,23 +76,87 @@ class AbstractClickAndDrop(ABC):
         return self.create_orders(order)
 
     @abstractmethod
+    def _get_orders(
+        self, order_identifiers: list[Union[str, int]]
+    ) -> list[click_and_drop_api.GetOrderInfoResource]:
+        """Retrieve orders by identifier or reference."""
+
     def get_orders(
         self, order_identifiers: Union[list[Union[str, int]], str, int]
     ) -> list[click_and_drop_api.GetOrderInfoResource]:
-        """Retrieve orders by identifier or reference."""
+        """Get specific orders.
+
+        Parameters:
+            order_identifiers:
+                One or several Order Identifiers or Order References.
+                Order Identifiers are integer numbers.
+                Order References are strings.
+
+        Returns:
+            A list of orders
+
+        Raises:
+            click_and_drop_api.exceptions.BadRequestException if an order with the same reference already exists
+
+        https://api.parcel.royalmail.com/#tag/Orders/operation/GetSpecificOrdersAsync
+        """
+        if not isinstance(order_identifiers, list):
+            order_identifiers = [order_identifiers]
+        result = []
+        for i in range(0, len(order_identifiers), self.max_order_count):
+            result.extend(
+                self._get_orders(order_identifiers[i : i + self.max_order_count])
+            )
+        return result
 
     def get_order(
         self, order_identifier: Union[str, int]
     ) -> Optional[click_and_drop_api.GetOrderInfoResource]:
-        """Retrieve a single order, or None if not found."""
+        """Retrieve a single order.
+
+        Parameters:
+            order_identifier: Order Identifier (integer) or Order Reference (string).
+
+        Returns:
+            The order if found, else None.
+        """
         orders = self.get_orders(order_identifier)
         return orders[0] if orders else None
 
     @abstractmethod
+    def _delete_orders(
+        self, order_identifiers: list[Union[str, int]]
+    ) -> click_and_drop_api.DeleteOrdersResource:
+        """Delete orders by identifier or reference."""
+
     def delete_orders(
         self, order_identifiers: Union[list[Union[str, int]], str, int]
     ) -> click_and_drop_api.DeleteOrdersResource:
-        """Delete orders by identifier or reference."""
+        """Delete specific orders.
+
+        Please be aware labels generated on orders which are deleted are no longer valid and must be destroyed.
+        Cancelled label information is automatically shared with Royal Mail Revenue Protection,
+        and should a cancelled label be identified on an item in the Royal Mail Network,
+        you will be charged on your account and an additional handling fee applied.
+
+        Parameters:
+            order_identifiers:
+                One or several Order Identifiers or Order References.
+                Order Identifiers are integer numbers.
+                Order References are strings.
+
+        https://api.parcel.royalmail.com/#tag/Orders/operation/DeleteOrdersAsync
+        """
+        if not isinstance(order_identifiers, list):
+            order_identifiers = [order_identifiers]
+        result = click_and_drop_api.DeleteOrdersResource(deleted_orders=[], errors=[])
+        for i in range(0, len(order_identifiers), self.max_order_count):
+            deleted = self._delete_orders(
+                order_identifiers[i : i + self.max_order_count]
+            )
+            result.deleted_orders.extend(deleted.deleted_orders)
+            result.errors.extend(deleted.errors)
+        return result
 
     def delete_order(
         self, order_identifier: Union[str, int]
@@ -101,6 +192,10 @@ class AbstractClickAndDrop(ABC):
         """Get a list of ISO 3166-1 alpha-2 country code strings.
 
         These are the countries that can be shipped with this service.
+
+        Note:
+            This method only seems to work for OBA accounts
+            to limit the countries.
         """
         countries = get_all_country_codes()
         result = self.test_shipping(
@@ -129,6 +224,10 @@ class AbstractClickAndDrop(ABC):
 
         Returns:
             :class:`ShippingTestResult` with ``success=True/False`` and a message.
+
+        Note:
+            This method only seems to work for OBA accounts
+            to limit the countries.
         """
         if not isinstance(address, list):
             address = [address]
@@ -153,35 +252,30 @@ class AbstractClickAndDrop(ABC):
         failed_messages = []
         to_delete = []
         # we can request at max 100 orders at a time
-        for i in range((len(orders) - 1) // 100 + 1):
-            order_subset = orders[i * 100 : (i + 1) * 100]
-            try:
-                response = self.create_orders(order_subset)
-            except ApiException as e:
-                failed_addresses += [get_order_address(order) for order in order_subset]
-                failed_messages += [
-                    f"API error ({e.status} {e.reason}): {e.body or e.data or ''}"
-                ] * len(order_subset)
-                continue
-            except Exception as e:
-                failed_addresses += [get_order_address(order) for order in order_subset]
-                failed_messages += [f"Unexpected error: {e}"] * len(order_subset)
-                continue
-            for co in response.created_orders:
-                successful_addresses.append(get_order_address(co))
-                to_delete.append(co.order_identifier)
-            for fo in response.failed_orders:
-                failed_addresses.append(get_order_address(fo.order))
-                failed_messages.append(
-                    ";".join(
-                        f"Error {e.error_code} in "
-                        f"{self.format_fields_for_error_message(e.fields)}: "
-                        f"{e.error_message}"
-                        for e in fo.errors
-                    )
+        try:
+            response = self.create_orders(orders)
+        except ApiException as e:
+            failed_addresses += [get_order_address(order) for order in orders]
+            failed_messages += [
+                f"API error ({e.status} {e.reason}): {e.body or e.data or ''}"
+            ] * len(orders)
+        except Exception as e:
+            failed_addresses += [get_order_address(order) for order in orders]
+            failed_messages += [f"Unexpected error: {e}"] * len(orders)
+        for co in response.created_orders:
+            successful_addresses.append(get_order_address(co))
+            to_delete.append(co.order_identifier)
+        for fo in response.failed_orders:
+            failed_addresses.append(get_order_address(fo.order))
+            failed_messages.append(
+                ";".join(
+                    f"Error {e.error_code} in "
+                    f"{self.format_fields_for_error_message(e.fields)}: "
+                    f"{e.error_message}"
+                    for e in fo.errors
                 )
-        for i in range((len(to_delete) - 1) // 100 + 1):
-            self.delete_orders(to_delete[i * 100 : (i + 1) * 100])
+            )
+        self.delete_orders(to_delete)
         return ShippingTestResult(
             successful_addresses, failed_addresses, failed_messages
         )

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

@@ -50,12 +50,9 @@ class MockClickAndDrop(AbstractClickAndDrop):
             release_date=datetime.now(timezone.utc),
         )
 
-    def create_orders(
-        self, orders: Union[list[CreateOrder], CreateOrder]
+    def _create_orders(
+        self, orders: list[CreateOrder]
     ) -> click_and_drop_api.CreateOrdersResponse:
-        if not isinstance(orders, list):
-            orders = [orders]
-
         now = datetime.now(timezone.utc)
         created = []
         for order in orders:
@@ -83,12 +80,9 @@ class MockClickAndDrop(AbstractClickAndDrop):
             failed_orders=[],
         )
 
-    def get_orders(
-        self, order_identifiers: Union[list[Union[str, int]], str, int]
+    def _get_orders(
+        self, order_identifiers: list[Union[str, int]]
     ) -> list[click_and_drop_api.GetOrderInfoResource]:
-        if not isinstance(order_identifiers, list):
-            order_identifiers = [order_identifiers]
-
         result = []
         for identifier in order_identifiers:
             if isinstance(identifier, int):
@@ -102,12 +96,9 @@ class MockClickAndDrop(AbstractClickAndDrop):
                         break
         return result
 
-    def delete_orders(
-        self, order_identifiers: Union[list[Union[str, int]], str, int]
+    def _delete_orders(
+        self, order_identifiers: list[Union[str, int]]
     ) -> click_and_drop_api.DeleteOrdersResource:
-        if not isinstance(order_identifiers, list):
-            order_identifiers = [order_identifiers]
-
         deleted = []
         errors = []
         for identifier in order_identifiers:

{click_and_drop_api-3.0.2 → click_and_drop_api-3.0.3}/click_and_drop_api/simple/shipping/package_shipping_option.py

@@ -5,6 +5,8 @@ from dataclasses import dataclass
 from decimal import Decimal as D
 from typing import Literal, Optional
 
+from click_and_drop_api.simple.addresses import get_all_country_codes
+
 from click_and_drop_api.models.dimensions_request import DimensionsRequest
 from click_and_drop_api.models.shipment_package_request import ShipmentPackageRequest
 from click_and_drop_api.simple.types import PostageDetails
@@ -12,6 +14,24 @@ from click_and_drop_api.simple.errors import InvalidWeight, InvalidDimensions
 
 MIN_WEIGHT_IN_GRAMS = 1
 
+# Country codes treated as domestic (national) by Royal Mail.
+NATIONAL_COUNTRY_CODES: frozenset[str] = frozenset({"GB", "GG", "IM", "JE"})
+
+# Country codes excluded from international shipping options.
+NON_INTERNATIONAL_COUNTRY_CODES: frozenset[str] = frozenset(
+    {
+        "GB",
+        "GG",
+        "IM",
+        "JE",  # Royal Mail domestic
+        "GS",  # South Georgia (BFPO)
+        "CC",
+        "NF",  # Australia Post territories
+        "FM",  # USPS territory
+        "PM",  # La Poste (France)
+    }
+)
+
 
 @dataclass
 class PackageShippingOption:
@@ -76,6 +96,26 @@ class PackageShippingOption:
         """Effective weight limit in kilograms."""
         return self.max_weight_g / 1000
 
+    @property
+    def country_codes(self) -> list[str]:
+        """Country codes this option ships to.
+
+        Returns the four national codes (GB, GG, IM, JE) for domestic services,
+        or all other known country codes for international services,
+        excluding those that Royal Mail does not serve.
+
+        If you want to get an updated list of contry codes
+        that the live API accepts, use
+        ``api.get_countries_for_shipping(package_size, service_code)`` instead.
+        """
+        if not self.international:
+            return sorted(NATIONAL_COUNTRY_CODES)
+        return [
+            c
+            for c in get_all_country_codes()
+            if c not in NON_INTERNATIONAL_COUNTRY_CODES
+        ]
+
     # ── Convenience ─────────────────────────────────────────────────────────
 
     @property

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "click_and_drop_api"
-version = "3.0.2"
+version = "3.0.3"
 description = "ChannelShipper & Royal Mail Public API"
 authors = [
   {name = "Nicco Kunzmann", email = "niccokunzmann@rambler.ru"},