python-bestbuy 0.2.2__tar.gz → 0.2.3__tar.gz

{python_bestbuy-0.2.2 → python_bestbuy-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-bestbuy
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python client library for Best Buy's Catalog and Commerce APIs
 Project-URL: Homepage, https://github.com/bbify/python-bestbuy
 Project-URL: Repository, https://github.com/bbify/python-bestbuy

python_bestbuy-0.2.3/bestbuy/exceptions/__init__.py

@@ -0,0 +1,123 @@
+"""Custom exceptions for the Best Buy API client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class BestBuyError(Exception):
+    """Base exception for all Best Buy API errors."""
+
+    pass
+
+
+class ConfigError(BestBuyError):
+    """Raised when there's an error with client configuration."""
+
+    pass
+
+
+class AuthenticationError(BestBuyError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class SessionRequiredError(BestBuyError):
+    """Raised when an operation requires an active session but none exists."""
+
+    pass
+
+
+class APIError(BestBuyError):
+    """Raised when the API returns an error.
+
+    Used to handle errors from both Commerce and Catalog APIs.
+
+    Attributes:
+        message: Human-readable error message
+        code: Error code from the API (if available)
+        sku: SKU that caused the error (if available)
+        response_text: Raw response text (XML or JSON)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str | None = None,
+        sku: str | None = None,
+        response_text: str | None = None,
+    ):
+        self.message = message
+        self.code = code
+        self.sku = sku
+        self.response_text = response_text
+
+        # Build error message
+        parts = [message]
+        if code:
+            parts.append(f"Error code: {code}")
+        if sku:
+            parts.append(f"SKU: {sku}")
+
+        super().__init__(" | ".join(parts))
+
+
+# Commerce-specific exceptions
+
+
+@dataclass
+class OrderErrorMessage:
+    """A single message from a commerce order error response.
+
+    Attributes:
+        code: The error code (from the ``item-id`` XML attribute),
+            e.g. ``"INVALID_CID"``, ``"MISSINGPARTNERID"``.
+        text: The human-readable error message.
+    """
+
+    code: str
+    text: str
+
+
+class CommerceOrderError(APIError):
+    """Raised when the Commerce API rejects an order (HTTP 400).
+
+    Contains structured error messages from the
+    ``<order-response><messages>`` element. Multiple messages may be
+    present when several validation errors occur simultaneously.
+
+    Inherits from :class:`APIError` so existing ``except APIError``
+    catch blocks still work. Callers can also catch
+    ``CommerceOrderError`` specifically for structured access to the
+    error messages list.
+
+    Attributes:
+        messages: List of structured error messages with codes.
+    """
+
+    def __init__(
+        self,
+        messages: list[OrderErrorMessage],
+        response_text: str | None = None,
+    ) -> None:
+        self.messages = messages
+        primary = (
+            messages[0]
+            if messages
+            else OrderErrorMessage(code="UNKNOWN", text="Unknown order error")
+        )
+
+        parts = [primary.text]
+        if primary.code:
+            parts.append(f"Error code: {primary.code}")
+        if len(messages) > 1:
+            parts.append(f"{len(messages)} total errors")
+
+        # Initialize APIError fields directly (skip APIError.__init__
+        # to control the str representation)
+        self.message = primary.text
+        self.code = primary.code
+        self.sku = None
+        self.response_text = response_text
+        BestBuyError.__init__(self, " | ".join(parts))

{python_bestbuy-0.2.2 → python_bestbuy-0.2.3}/bestbuy/models/__init__.py

@@ -88,9 +88,11 @@ from .commerce import (
     OrderList,
     OrderQueryRequest,
     OrderResponse,
+    OrderResponseMessage,
     OrderSubmitGuestRequest,
     OrderSubmitRegisteredRequest,
     OrderSubmitResponse,
+    OrderItemStatus,
     OrderStatus,
     PriceQueryRequest,
     PriceResponse,
@@ -201,9 +203,11 @@ __all__ = [
     "OrderList",
     "OrderQueryRequest",
     "OrderResponse",
+    "OrderResponseMessage",
     "OrderSubmitGuestRequest",
     "OrderSubmitRegisteredRequest",
     "OrderSubmitResponse",
+    "OrderItemStatus",
     "OrderStatus",
     "PriceQueryRequest",
     "PriceResponse",

{python_bestbuy-0.2.2 → python_bestbuy-0.2.3}/bestbuy/models/commerce.py

@@ -7,32 +7,75 @@ from pydantic_xml import BaseXmlModel, element, attr, wrapped
 
 
 class OrderStatus(str, Enum):
+    """Overall order status values returned by the Commerce API."""
+
+    CLOSED = "CLOSED"
+    INCOMPLETE = "INCOMPLETE"
+    PAYMENT_COLLECTED = "PAYMENT_COLLECTED"
+    RECEIVED = "RECEIVED"
+    SHIPPED = "SHIPPED"
+    SHIPPING = "SHIPPING"
+    SUBMITTED = "SUBMITTED"
+    WAITING_ACCEPTANCE = "WAITING_ACCEPTANCE"
+
+
+class OrderItemStatus(str, Enum):
+    """Line-item status values for individual items in an order."""
+
+    # Item is waiting to be picked up for return.
     AWAITING_RETURN_PICKUP = "Awaiting Return Pickup"
+    # Your appointment has not been set
     AWAITING_SCHEDULING = "Awaiting Scheduling"
+    # Item is currently backordered and cannot be fulfilled until more
+    # inventory becomes available
     BACKORDERED = "Backordered"
+    # Your item was canceled
     CANCELED = "Canceled"
+    # The process of order through fulfillment is completed/delivered
+    # to the end user
     COMPLETED = "Completed"
+    # Carrier has indicated that your shipment may have been delayed
     DELAYED = "Delayed"
+    # The process of order through fulfillment is completed/delivered
+    # to the end user
     DELIVERED = "Delivered"
+    # Order is in progress — still going through statuses before delivery
     IN_PROGRESS = "In Progress"
-    INCOMPLETE = "Incomplete"
+    # The item has been returned
     ITEM_RETURNED = "Item Returned"
+    # Your order has been received
     ORDER_RECEIVED = "Order Received"
+    # The item is out for delivery
     OUT_FOR_DELIVERY = "Out for Delivery"
+    # The item is out of stock and awaiting more inventory
     OUT_OF_STOCK = "Out of Stock"
+    # Pending cancellation (rarely seen)
     PENDING_CANCELLATION = "Pending Cancellation"
+    # The item was picked up (usually store pickup fulfillment)
     PICKED_UP = "Picked Up"
+    # Item is on pre-order and not yet available for shipping
     PRE_ORDERED = "Pre-Ordered"
+    # Getting the item ready for shipment or delivery
     PREPARING = "Preparing"
+    # The item is ready to be picked up at the store
     READY_TO_PICK_UP = "Ready to Pick Up"
+    # Item is pending a refund
     REFUND_PENDING = "Refund Pending"
+    # Your appointment needs to be rescheduled
     RESCHEDULE_REQUIRED = "Reschedule Required"
+    # The returning item is in transit to the return warehouse
     RETURN_IN_TRANSIT = "Return In Transit"
+    # The item has been received by the return warehouse and is in review
     RETURN_RECEIVED = "Return Received"
+    # Confirmation of a return request
     RETURN_REQUEST_CONFIRMED = "Return Request Confirmed"
+    # Item has been returned
     RETURNED = "Returned"
+    # Item is scheduled for fulfillment
     SCHEDULED = "Scheduled"
+    # Item needs to be scheduled
     SCHEDULING_NEEDED = "Scheduling Needed"
+    # Item has shipped
     SHIPPED = "Shipped"
 
 
@@ -80,13 +123,17 @@ class AvailabilityQueryRequest(BaseXmlModel, tag="availability-query"):
 
 
 class AvailabilityQueryResponse(BaseXmlModel, tag="availability-query"):
-    sku_id: str = attr(name="sku-id")
-    order_code: int = element(tag="order-code")
-    display_message: str = element(tag="display-message")
-    home_delivery_code: int = element(tag="home-delivery-code")
-    home_delivery_message: str = element(tag="home-delivery-message")
-    instore_availability: bool = element(tag="instore-availability")
-    max_quantity: int = element(tag="max-quantity")
+    sku_id: Optional[str] = attr(name="sku-id", default=None)
+    order_code: Optional[int] = element(tag="order-code", default=None)
+    display_message: Optional[str] = element(tag="display-message", default=None)
+    home_delivery_code: Optional[int] = element(tag="home-delivery-code", default=None)
+    home_delivery_message: Optional[str] = element(
+        tag="home-delivery-message", default=None
+    )
+    instore_availability: Optional[bool] = element(
+        tag="instore-availability", default=None
+    )
+    max_quantity: Optional[int] = element(tag="max-quantity", default=None)
     available_for_shipping: Optional[bool] = element(
         tag="available-for-shipping", default=None
     )
@@ -125,8 +172,8 @@ class ShippingOption(BaseXmlModel, tag="option"):
 
 
 class ShippingOptionsResponse(BaseXmlModel, tag="shipping-options"):
-    sku_id: str = attr(name="sku-id")
-    free_shipping: bool = attr(name="free-shipping")
+    sku_id: Optional[str] = attr(name="sku-id", default=None)
+    free_shipping: Optional[bool] = attr(name="free-shipping", default=None)
     options: List[ShippingOption] = element(tag="option", default_factory=list)
 
 
@@ -188,13 +235,17 @@ class ProductServiceRequest(BaseXmlModel, tag="productservice-request"):
 
 
 class AvailabilityQuery(BaseXmlModel, tag="availability-query"):
-    sku_id: str = attr(name="sku-id")
-    order_code: int = element(tag="order-code")
-    display_message: str = element(tag="display-message")
-    home_delivery_code: int = element(tag="home-delivery-code")
-    home_delivery_message: str = element(tag="home-delivery-message")
-    instore_availability: bool = element(tag="instore-availability")
-    max_quantity: int = element(tag="max-quantity")
+    sku_id: Optional[str] = attr(name="sku-id", default=None)
+    order_code: Optional[int] = element(tag="order-code", default=None)
+    display_message: Optional[str] = element(tag="display-message", default=None)
+    home_delivery_code: Optional[int] = element(tag="home-delivery-code", default=None)
+    home_delivery_message: Optional[str] = element(
+        tag="home-delivery-message", default=None
+    )
+    instore_availability: Optional[bool] = element(
+        tag="instore-availability", default=None
+    )
+    max_quantity: Optional[int] = element(tag="max-quantity", default=None)
 
 
 class ProductServiceResponse(BaseXmlModel, tag="productservice-response"):
@@ -239,7 +290,7 @@ class OrderItem(BaseXmlModel, tag="item"):
     cancellable: Optional[bool] = attr(name="cancellable", default=None)
     parent_item: Optional[str] = attr(name="parent-item", default=None)
     type: Optional[str] = attr(name="type", default=None)
-    line_status: Optional[str] = attr(name="line-status", default=None)
+    line_status: Optional[OrderItemStatus] = attr(name="line-status", default=None)
     line_status_message: Optional[str] = attr(name="line-status-message", default=None)
     expected_delivery_date: Optional[str] = attr(
         name="expected-delivery-date", default=None
@@ -557,7 +608,7 @@ class OrderResponse(BaseXmlModel, tag="order", search_mode="unordered"):
     id: Optional[str] = attr(name="id", default=None)
     reviewable: Optional[bool] = attr(name="reviewable", default=None)
     partner_id: Optional[str] = attr(name="partner-id", default=None)
-    status: Optional[OrderStatus] = attr(name="status", default=None)
+    status: Optional[str] = attr(name="status", default=None)
     order_date: Optional[date] = attr(name="order-date", default=None)
     total: Optional[Decimal] = attr(name="total", default=None)
     given_id: Optional[str] = attr(name="given-id", default=None)
@@ -576,6 +627,13 @@ class IdMapEntry(BaseXmlModel, tag="entry"):
     value: str = element(tag="value")
 
 
+class OrderResponseMessage(BaseXmlModel, tag="message"):
+    """A message from an order response (warning/info on success, error on 400)."""
+
+    item_id: Optional[str] = attr(name="item-id", default=None)
+    text: Optional[str] = None
+
+
 class OrderSubmitResponse(BaseXmlModel, tag="order-response"):
     version: str = attr(name="version")
     status: str = attr(name="status")
@@ -583,7 +641,9 @@ class OrderSubmitResponse(BaseXmlModel, tag="order-response"):
     id_map: Optional[List[IdMapEntry]] = wrapped(
         "id-map", element(tag="entry", default_factory=list)
     )
-    messages: Optional[str] = element(tag="messages", default=None)
+    messages: List[OrderResponseMessage] = wrapped(
+        "messages", element(tag="message", default_factory=list)
+    )
 
 
 class PublicKeyEncryptionResponse(BaseXmlModel, tag="publicKeyEncryption"):

{python_bestbuy-0.2.2 → python_bestbuy-0.2.3}/bestbuy/utils/errors.py

@@ -1,7 +1,7 @@
 import json
 from xml.etree import ElementTree as ET
 
-from ..exceptions import APIError
+from ..exceptions import APIError, CommerceOrderError, OrderErrorMessage
 from ..models import ApiError, ApiErrors, SimpleError
 
 
@@ -80,19 +80,35 @@ def check_for_xml_errors(response_text: str | None) -> None:
             except Exception:
                 pass
 
+        # Check for order-response messages format:
+        # <order-response><messages><message item-id="CODE">text</message>
+        elif root.tag == "order-response":
+            messages_elem = root.find("messages")
+            if messages_elem is not None:
+                order_messages = []
+                for msg_elem in messages_elem.findall("message"):
+                    code = msg_elem.get("item-id", "UNKNOWN")
+                    text = msg_elem.text or ""
+                    order_messages.append(OrderErrorMessage(code=code, text=text))
+                if order_messages:
+                    raise CommerceOrderError(
+                        messages=order_messages,
+                        response_text=response_text,
+                    )
+
         # Check for errors embedded in other response types
         else:
             # Look for <error> child elements
             error_elem = root.find(".//error")
             if error_elem is not None:
-                code = error_elem.get("code")
+                error_code = error_elem.get("code")
                 message_elem = error_elem.find("message")
                 if message_elem is not None:
                     message = message_elem.text or "Unknown error"
                     sku = message_elem.get("sku")
                     raise APIError(
                         message=message,
-                        code=code,
+                        code=error_code,
                         sku=sku,
                         response_text=response_text,
                     )

{python_bestbuy-0.2.2 → python_bestbuy-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-bestbuy"
-version = "0.2.2"
+version = "0.2.3"
 description = "Python client library for Best Buy's Catalog and Commerce APIs"
 readme = "README.md"
 license = "MIT"

python_bestbuy-0.2.2/bestbuy/exceptions.py

@@ -1,59 +0,0 @@
-"""Custom exceptions for the Best Buy API client."""
-
-
-class BestBuyError(Exception):
-    """Base exception for all Best Buy API errors."""
-
-    pass
-
-
-class ConfigError(BestBuyError):
-    """Raised when there's an error with client configuration."""
-
-    pass
-
-
-class AuthenticationError(BestBuyError):
-    """Raised when authentication fails."""
-
-    pass
-
-
-class SessionRequiredError(BestBuyError):
-    """Raised when an operation requires an active session but none exists."""
-
-    pass
-
-
-class APIError(BestBuyError):
-    """Raised when the API returns an error.
-
-    Used to handle errors from both Commerce and Catalog APIs.
-
-    Attributes:
-        message: Human-readable error message
-        code: Error code from the API (if available)
-        sku: SKU that caused the error (if available)
-        response_text: Raw response text (XML or JSON)
-    """
-
-    def __init__(
-        self,
-        message: str,
-        code: str | None = None,
-        sku: str | None = None,
-        response_text: str | None = None,
-    ):
-        self.message = message
-        self.code = code
-        self.sku = sku
-        self.response_text = response_text
-
-        # Build error message
-        parts = [message]
-        if code:
-            parts.append(f"Error code: {code}")
-        if sku:
-            parts.append(f"SKU: {sku}")
-
-        super().__init__(" | ".join(parts))