python-bestbuy 0.1.0__py3-none-any.whl

bestbuy/clients/__init__.py

@@ -0,0 +1,9 @@
+from .catalog import AsyncCatalogClient, CatalogClient
+from .commerce import AsyncCommerceClient, CommerceClient
+
+__all__ = [
+    "AsyncCatalogClient",
+    "AsyncCommerceClient",
+    "CatalogClient",
+    "CommerceClient",
+]

bestbuy/clients/base.py

@@ -0,0 +1,178 @@
+import abc
+import logging
+from types import TracebackType
+from typing import Any, Dict, List, Type
+
+import httpx
+from pydantic import ValidationError
+
+from ..configs import BaseConfig
+from ..exceptions import ConfigError
+from ..loggers import make_console_logger
+from ..utils import check_for_json_errors, check_for_xml_errors
+
+from ..typing import SyncAsync
+
+
+class BaseClient:
+    config_parser: Type[BaseConfig]
+
+    def __init__(
+        self,
+        client: httpx.Client | httpx.AsyncClient,
+        options: Dict[str, Any] | BaseConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        try:
+            if options is None:
+                options = self.config_parser(**kwargs)
+            elif isinstance(options, dict):
+                options = self.config_parser(**options)
+        except ValidationError as e:
+            errors = []
+            for error in e.errors():
+                field = ".".join(str(loc) for loc in error["loc"])
+                msg = error["msg"]
+                errors.append(f"{field}: {msg}")
+            raise ConfigError(
+                "Configuration validation failed:\n  - " + "\n  - ".join(errors)
+            ) from e
+        self.options = options
+        self.logger = self.options.logger or make_console_logger()
+        self.logger.setLevel(self.options.log_level)
+        self._clients: List[httpx.Client | httpx.AsyncClient] = []
+        self.client = client
+
+    @property
+    def base_url(self):
+        return self.options.base_url
+
+    @property
+    def client(self) -> httpx.Client | httpx.AsyncClient:
+        return self._clients[-1]
+
+    @client.setter
+    def client(self, client: httpx.Client | httpx.AsyncClient) -> None:
+        client.base_url = httpx.URL(self.base_url)
+        client.timeout = httpx.Timeout(timeout=self.options.timeout_ms / 1_000)
+        headers: Dict[str, str] = {"X-API-KEY": self.options.api_key}
+        if self.options.content_type:
+            headers["Content-Type"] = self.options.content_type
+        client.headers = httpx.Headers(headers)
+        self._clients.append(client)
+
+    @abc.abstractmethod
+    def request(self, request: httpx.Request) -> SyncAsync[httpx.Response]:
+        raise NotImplementedError
+
+
+class Client(BaseClient):
+    client: httpx.Client
+
+    def __init__(
+        self,
+        client: httpx.Client | None = None,
+        options: Dict[str, Any] | BaseConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if client is None:
+            client = httpx.Client()
+        super().__init__(client, options, **kwargs)
+
+    def __enter__(self) -> "Client":
+        self.client = httpx.Client()
+        self.client.__enter__()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Type[BaseException],
+        exc_value: BaseException,
+        traceback: TracebackType,
+    ) -> None:
+        self.client.__exit__(exc_type, exc_value, traceback)
+        del self._clients[-1]
+
+    def close(self) -> None:
+        self.client.close()
+
+    def request(self, request: httpx.Request) -> httpx.Response:
+        if self.logger.isEnabledFor(logging.DEBUG):
+            self.logger.debug(
+                f"Request: {request.method} {request.url}\n"
+                f"Headers: {dict(request.headers)}\n"
+                f"Body: {request.content.decode('utf-8') if request.content else None}"
+            )
+        response = self.client.send(request)
+        if self.logger.isEnabledFor(logging.DEBUG):
+            self.logger.debug(
+                f"Response: {response.status_code} {response.reason_phrase}\n"
+                f"Headers: {dict(response.headers)}\n"
+                f"Body: {response.text}"
+            )
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            content_type = e.response.headers.get("content-type", "")
+            if "xml" in content_type:
+                check_for_xml_errors(e.response.text)
+            elif "json" in content_type:
+                check_for_json_errors(e.response.text)
+            raise
+        return response
+
+
+class AsyncClient(BaseClient):
+    client: httpx.AsyncClient
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient | None = None,
+        options: Dict[str, Any] | BaseConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        if client is None:
+            client = httpx.AsyncClient()
+        super().__init__(client, options, **kwargs)
+
+    async def __aenter__(self) -> "AsyncClient":
+        self.client = httpx.AsyncClient()
+        await self.client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Type[BaseException],
+        exc_value: BaseException,
+        traceback: TracebackType,
+    ) -> None:
+        await self.client.__aexit__(exc_type, exc_value, traceback)
+        del self._clients[-1]
+
+    async def aclose(self) -> None:
+        await self.client.aclose()
+
+    async def request(self, request: httpx.Request) -> httpx.Response:
+        if self.logger.isEnabledFor(logging.DEBUG):
+            self.logger.debug(
+                f"Request: {request.method} {request.url}\n"
+                f"Headers: {dict(request.headers)}\n"
+                f"Body: {request.content.decode('utf-8') if request.content else None}"
+            )
+        response = await self.client.send(request)
+        if self.logger.isEnabledFor(logging.DEBUG):
+            self.logger.debug(
+                f"Response: {response.status_code} {response.reason_phrase}\n"
+                f"Headers: {dict(response.headers)}\n"
+                f"Body: {response.text}"
+            )
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            content_type = e.response.headers.get("content-type", "")
+            if "xml" in content_type:
+                check_for_xml_errors(e.response.text)
+            elif "json" in content_type:
+                check_for_json_errors(e.response.text)
+            raise
+        return response

bestbuy/clients/catalog.py

@@ -0,0 +1,64 @@
+from typing import Any, Dict
+
+import httpx
+
+from ..configs import CatalogConfig
+from ..operations.catalog import (
+    AsyncCategoryOperations,
+    AsyncProductOperations,
+    AsyncRecommendationOperations,
+    AsyncStoreOperations,
+    CategoryOperations,
+    ProductOperations,
+    RecommendationOperations,
+    StoreOperations,
+)
+from .base import AsyncClient, Client
+
+
+class CatalogClient(Client):
+    """Synchronous client for the Best Buy Catalog API."""
+
+    config_parser = CatalogConfig
+
+    def __init__(
+        self,
+        client: httpx.Client | None = None,
+        options: Dict[str, Any] | CatalogConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(client, options, **kwargs)
+        self.products = ProductOperations(self)
+        self.categories = CategoryOperations(self)
+        self.recommendations = RecommendationOperations(self)
+        self.stores = StoreOperations(self)
+
+    @property
+    def base_url(self):
+        if self.options.base_url is not None:
+            return self.options.base_url
+        return "https://api.bestbuy.com"
+
+
+class AsyncCatalogClient(AsyncClient):
+    """Asynchronous client for the Best Buy Catalog API."""
+
+    config_parser = CatalogConfig
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient | None = None,
+        options: Dict[str, Any] | CatalogConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(client, options, **kwargs)
+        self.products = AsyncProductOperations(self)
+        self.categories = AsyncCategoryOperations(self)
+        self.recommendations = AsyncRecommendationOperations(self)
+        self.stores = AsyncStoreOperations(self)
+
+    @property
+    def base_url(self):
+        if self.options.base_url is not None:
+            return self.options.base_url
+        return "https://api.bestbuy.com"

bestbuy/clients/commerce.py

@@ -0,0 +1,74 @@
+from typing import Any, Dict
+
+import httpx
+
+from ..configs import CommerceConfig
+from ..operations.commerce import (
+    AsyncAuthOperations,
+    AsyncEncryptionOperations,
+    AsyncFulfillmentOperations,
+    AsyncOrderOperations,
+    AsyncPricingOperations,
+    AuthOperations,
+    EncryptionOperations,
+    FulfillmentOperations,
+    OrderOperations,
+    PricingOperations,
+)
+from .base import AsyncClient, Client
+
+
+class CommerceClient(Client):
+    config_parser = CommerceConfig
+    options: CommerceConfig
+
+    def __init__(
+        self,
+        client: httpx.Client | None = None,
+        options: Dict[str, Any] | CommerceConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(client, options, **kwargs)
+        self.auth = AuthOperations(self)
+        self.fulfillment = FulfillmentOperations(self)
+        self.pricing = PricingOperations(self)
+        self.orders = OrderOperations(self)
+        self.encryption = EncryptionOperations(self)
+
+    @property
+    def base_url(self):
+        if self.options.base_url is not None:
+            return self.options.base_url
+        return (
+            "https://commerce-ssl.sandbox.bestbuy.com"
+            if self.options.sandbox is True
+            else "https://commerce-ssl.bestbuy.com"
+        )
+
+
+class AsyncCommerceClient(AsyncClient):
+    config_parser = CommerceConfig
+    options: CommerceConfig
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient | None = None,
+        options: Dict[str, Any] | CommerceConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(client, options, **kwargs)
+        self.auth = AsyncAuthOperations(self)
+        self.fulfillment = AsyncFulfillmentOperations(self)
+        self.pricing = AsyncPricingOperations(self)
+        self.orders = AsyncOrderOperations(self)
+        self.encryption = AsyncEncryptionOperations(self)
+
+    @property
+    def base_url(self):
+        if self.options.base_url is not None:
+            return self.options.base_url
+        return (
+            "https://commerce-ssl.sandbox.bestbuy.com"
+            if self.options.sandbox is True
+            else "https://commerce-ssl.bestbuy.com"
+        )

bestbuy/configs/__init__.py

@@ -0,0 +1,5 @@
+from .base import BaseConfig
+from .catalog import CatalogConfig
+from .commerce import CommerceConfig
+
+__all__ = ["BaseConfig", "CatalogConfig", "CommerceConfig"]

bestbuy/configs/base.py

@@ -0,0 +1,14 @@
+import logging
+
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseConfig(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    api_key: str
+    base_url: str | None = None
+    content_type: str | None = None
+    log_level: int = logging.WARNING
+    logger: logging.Logger | None = None
+    timeout_ms: int = 60_000

bestbuy/configs/catalog.py

@@ -0,0 +1,6 @@
+from .base import BaseConfig
+
+
+class CatalogConfig(BaseConfig):
+    base_url: str = "https://api.bestbuy.com"
+    content_type: str = "application/json"

bestbuy/configs/commerce.py

@@ -0,0 +1,10 @@
+from .base import BaseConfig
+
+
+class CommerceConfig(BaseConfig):
+    auto_logout: bool = False
+    content_type: str = "application/xml"
+    partner_id: str | None = None
+    password: str | None = None
+    sandbox: bool = True
+    username: str | None = None

bestbuy/exceptions.py

@@ -0,0 +1,59 @@
+"""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))

bestbuy/loggers.py

@@ -0,0 +1,11 @@
+import logging
+from logging import Logger
+
+
+def make_console_logger() -> Logger:
+    logger = logging.getLogger(__package__)
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(logging.BASIC_FORMAT)
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    return logger

bestbuy/models/__init__.py

@@ -0,0 +1,205 @@
+from .catalog import (
+    AccessorySku,
+    BundledProduct,
+    CatalogStore,
+    CatalogStoresResponse,
+    CategoriesResponse,
+    Category,
+    CategoryPathItem,
+    Contract,
+    ContractPrice,
+    ContractTerm,
+    GiftSku,
+    IncludedItem,
+    LanguageOption,
+    MemberSku,
+    Offer,
+    PlaybackFormat,
+    Product,
+    ProductDetail,
+    ProductFeature,
+    ProductImage,
+    ProductList,
+    ProductsResponse,
+    ProductVariant,
+    ProductVariation,
+    RecommendationsContext,
+    RecommendationsMetadata,
+    RecommendationsResponse,
+    RecommendationsResultSet,
+    RecommendationCustomerReviews,
+    RecommendationDescriptions,
+    RecommendationImages,
+    RecommendationLinks,
+    RecommendationNames,
+    RecommendationPrices,
+    RecommendedProduct,
+    RequiredPart,
+    ShippingInfo,
+    ShippingLevelOfService,
+    StoreDetailedHours,
+    StoreService,
+    SubCategory,
+)
+from .commerce import (
+    AddressFulfillment,
+    ApiError,
+    ApiErrorMessage,
+    ApiErrors,
+    AvailabilityQuery,
+    AvailabilityQueryRequest,
+    AvailabilityQueryResponse,
+    BillingAddress,
+    CCTender,
+    Cart,
+    CartTotal,
+    CommerceResponse,
+    CreditCard,
+    DeliveryDateQuery,
+    DeliveryDateQueryItem,
+    DeliveryDateResponse,
+    DeliveryOption,
+    DeliveryOptionsResponse,
+    DeliveryService,
+    DeliveryServicesResponse,
+    EstimateTaxQuery,
+    EstimatedTax,
+    FriendsFamilyDetails,
+    Fulfillment,
+    GuestCCTender,
+    GuestCreditCard,
+    GuestTender,
+    HomeDeliveryFulfillment,
+    IdMapEntry,
+    Link,
+    OrderAddress,
+    OrderItem,
+    OrderList,
+    OrderQueryRequest,
+    OrderResponse,
+    OrderSubmitGuestRequest,
+    OrderSubmitRegisteredRequest,
+    OrderSubmitResponse,
+    OrderStatus,
+    PriceQueryRequest,
+    PriceResponse,
+    ProductServiceRequest,
+    ProductServiceResponse,
+    PublicKeyEncryptionResponse,
+    RegisteredCCTender,
+    RegisteredTender,
+    ShippingAddress,
+    ShippingOption,
+    ShippingOptionsResponse,
+    ShippingQueryRequest,
+    ShippingQueryItem,
+    SimpleError,
+    Store,
+    StoreFulfillment,
+    StoreQuery,
+    StoresResponse,
+    Tender,
+    UnitPrice,
+)
+
+__all__ = [
+    "AccessorySku",
+    "BundledProduct",
+    "CatalogStore",
+    "CatalogStoresResponse",
+    "CategoriesResponse",
+    "Category",
+    "CategoryPathItem",
+    "Contract",
+    "ContractPrice",
+    "ContractTerm",
+    "GiftSku",
+    "IncludedItem",
+    "LanguageOption",
+    "MemberSku",
+    "Offer",
+    "PlaybackFormat",
+    "Product",
+    "ProductDetail",
+    "ProductFeature",
+    "ProductImage",
+    "ProductList",
+    "ProductsResponse",
+    "ProductVariant",
+    "ProductVariation",
+    "RecommendationsContext",
+    "RecommendationsMetadata",
+    "RecommendationsResponse",
+    "RecommendationsResultSet",
+    "RecommendationCustomerReviews",
+    "RecommendationDescriptions",
+    "RecommendationImages",
+    "RecommendationLinks",
+    "RecommendationNames",
+    "RecommendationPrices",
+    "RecommendedProduct",
+    "RequiredPart",
+    "ShippingInfo",
+    "ShippingLevelOfService",
+    "StoreDetailedHours",
+    "StoreService",
+    "SubCategory",
+    "AddressFulfillment",
+    "ApiError",
+    "ApiErrorMessage",
+    "ApiErrors",
+    "AvailabilityQuery",
+    "AvailabilityQueryRequest",
+    "AvailabilityQueryResponse",
+    "BillingAddress",
+    "CCTender",
+    "Cart",
+    "CartTotal",
+    "CommerceResponse",
+    "CreditCard",
+    "DeliveryDateQuery",
+    "DeliveryDateQueryItem",
+    "DeliveryDateResponse",
+    "DeliveryOption",
+    "DeliveryOptionsResponse",
+    "DeliveryService",
+    "DeliveryServicesResponse",
+    "EstimateTaxQuery",
+    "EstimatedTax",
+    "FriendsFamilyDetails",
+    "Fulfillment",
+    "GuestCCTender",
+    "GuestCreditCard",
+    "GuestTender",
+    "HomeDeliveryFulfillment",
+    "IdMapEntry",
+    "Link",
+    "OrderAddress",
+    "OrderItem",
+    "OrderList",
+    "OrderQueryRequest",
+    "OrderResponse",
+    "OrderSubmitGuestRequest",
+    "OrderSubmitRegisteredRequest",
+    "OrderSubmitResponse",
+    "OrderStatus",
+    "PriceQueryRequest",
+    "PriceResponse",
+    "ProductServiceRequest",
+    "ProductServiceResponse",
+    "PublicKeyEncryptionResponse",
+    "RegisteredCCTender",
+    "RegisteredTender",
+    "ShippingAddress",
+    "ShippingOption",
+    "ShippingOptionsResponse",
+    "ShippingQueryRequest",
+    "ShippingQueryItem",
+    "SimpleError",
+    "Store",
+    "StoreFulfillment",
+    "StoreQuery",
+    "StoresResponse",
+    "Tender",
+    "UnitPrice",
+]