prestashop-webservice 0.3.0__py3-none-any.whl

prestashop_webservice/__init__.py

@@ -0,0 +1,82 @@
+"""
+PrestaShop Webservice - Python Client for PrestaShop API
+"""
+
+__version__ = "0.3.0"
+__author__ = "Patitas Co."
+
+from prestashop_webservice.address import Address
+from prestashop_webservice.base_model import BaseModel
+from prestashop_webservice.carrier import Carrier
+from prestashop_webservice.client import Client
+from prestashop_webservice.combination import Combination
+from prestashop_webservice.country import Country
+from prestashop_webservice.customer import Customer
+from prestashop_webservice.customer_message import CustomerMessage
+from prestashop_webservice.customer_thread import CustomerThread
+from prestashop_webservice.image_product import ImageProduct
+from prestashop_webservice.models import (
+    AddressData,
+    CarrierData,
+    CombinationData,
+    CountryData,
+    CustomerData,
+    CustomerMessageData,
+    CustomerThreadData,
+    ImageProductData,
+    OrderCarrierData,
+    OrderData,
+    OrderDetailData,
+    OrderHistoryData,
+    OrderStateData,
+    ProductData,
+    StateData,
+)
+from prestashop_webservice.order import Order
+from prestashop_webservice.order_carrier import OrderCarrier
+from prestashop_webservice.order_detail import OrderDetail
+from prestashop_webservice.order_history import OrderHistory
+from prestashop_webservice.order_state import OrderState
+from prestashop_webservice.params import Params, Sort, SortOrder
+from prestashop_webservice.product import Product
+from prestashop_webservice.state import State
+
+__all__ = [
+    "Client",
+    "BaseModel",
+    "Params",
+    "Sort",
+    "SortOrder",
+    # Complex query models
+    "Order",
+    "OrderCarrier",
+    "OrderHistory",
+    "OrderState",
+    "Customer",
+    "Address",
+    "State",
+    "Product",
+    "ImageProduct",
+    "Combination",
+    "Country",
+    "Carrier",
+    "CustomerMessage",
+    "CustomerThread",
+    "OrderDetail",
+    # Data models
+    "OrderData",
+    "CustomerData",
+    "ProductData",
+    "CombinationData",
+    "AddressData",
+    "CountryData",
+    "CarrierData",
+    "OrderCarrierData",
+    "OrderHistoryData",
+    "OrderStateData",
+    "StateData",
+    "ImageProductData",
+    "CustomerMessageData",
+    "CustomerThreadData",
+    "OrderDetailData",
+]

prestashop_webservice/address.py

@@ -0,0 +1,29 @@
+from prestashop_webservice.base_model import BaseModel
+from prestashop_webservice.models import AddressData
+from prestashop_webservice.params import Params
+
+
+class Address(BaseModel):
+    """Complex queries for addresses endpoint."""
+
+    _data_class = AddressData
+
+    def get_by_id(self, address_id: str) -> AddressData:
+        """Get address by ID."""
+        return self._query(f"addresses/{address_id}", None, "address")
+
+    def get_by_customer(self, customer_id: str) -> list[AddressData]:
+        """Get all addresses for a customer."""
+        params = Params(
+            filter={"id_customer": customer_id},
+            display=["id", "id_customer", "address1", "city", "postcode"],
+        )
+        return self._query("addresses", params, "addresses")
+
+    def get_by_postal_code(self, postal_code: str) -> list[AddressData]:
+        """Get addresses by postal code."""
+        params = Params(
+            filter={"postcode": postal_code},
+            display=["id", "address1", "city", "postcode"],
+        )
+        return self._query("addresses", params, "addresses")

prestashop_webservice/base_model.py

@@ -0,0 +1,121 @@
+from dataclasses import fields
+from typing import Any, TypeVar
+
+from prestashop_webservice.client import Client
+from prestashop_webservice.params import Params
+
+T = TypeVar("T")
+
+
+class BaseModel:
+    """Base class for model queries with automatic dataclass conversion."""
+
+    _data_class: type[Any] | None = None
+    _MAX_FILTER_BYTES = 1500
+
+    def __init__(self, client: Client):
+        self.client = client
+
+    @staticmethod
+    def _to_list(result: dict | list) -> list[dict]:
+        """Ensure result is always a list.
+
+        Args:
+            result: Result from API call (dict or list)
+
+        Returns:
+            List of dictionaries
+        """
+        if isinstance(result, dict):
+            return [result] if result else []
+        return result or []
+
+    def _query(self, endpoint: str, params: Params | None = None, response_key: str = "") -> Any:
+        """Override Client._query to return dataclass instances instead of dicts.
+
+        Args:
+            endpoint: API endpoint to query
+            params: Query parameters
+            response_key: Key to extract from JSON response
+
+        Returns:
+            Single dataclass instance or list of dataclass instances
+        """
+
+        if params and params.filter:
+            filter_str = str(params.filter)
+            if len(filter_str.encode("utf-8")) > self._MAX_FILTER_BYTES:
+                filter_chunks = self._split_filter(params)
+                merged_results: list[dict] = []
+                for chunk in filter_chunks:
+                    if not chunk:
+                        continue
+                    chunk_params = Params(
+                        filter=chunk,
+                        display=params.display,
+                        limit=params.limit,
+                        sort=params.sort,
+                        date=params.date,
+                    )
+                    partial = self.client._query(endpoint, chunk_params, response_key)
+                    merged_results.extend(self._to_list(partial))
+
+                result = merged_results
+            else:
+                result = self.client._query(endpoint, params, response_key)
+        else:
+            result = self.client._query(endpoint, params, response_key)
+
+        # If no data_class is set, return raw result
+        if self._data_class is None:
+            return result
+
+        # Convert to list and instantiate dataclasses
+        results = self._to_list(result)
+        instances = []
+        for r in results:
+            # Filter out unknown fields to avoid TypeError
+            if self._data_class:
+                field_names = {f.name for f in fields(self._data_class)}
+                filtered = {k: v for k, v in r.items() if k in field_names}
+                instances.append(self._data_class(**filtered))
+
+        # Return single instance if result was dict, list if it was list
+        if isinstance(result, dict):
+            return instances[0] if instances else None
+        return instances
+
+    def _split_filter(self, params: Params) -> list[dict]:
+        """Split a large filter payload into smaller chunks."""
+        if not params.filter:
+            return []
+
+        # Multiple keys: split dict in half
+        if len(params.filter) > 1:
+            items = list(params.filter.items())
+            mid_index = len(items) // 2
+            return [dict(items[:mid_index]), dict(items[mid_index:])]
+
+        # Single key with huge value: split the value into safe-size chunks
+        key, value = next(iter(params.filter.items()))
+        value_str = str(value)
+        inner = (
+            value_str[1:-1] if value_str.startswith("[") and value_str.endswith("]") else value_str
+        )
+        parts = inner.split("|") if "|" in inner else [inner]
+
+        filter_chunks: list[dict] = []
+        current: list[str] = []
+        for part in parts:
+            candidate = "|".join(current + [part]) if current else part
+            encoded_len = len(f"[{candidate}]".encode())
+            if encoded_len > self._MAX_FILTER_BYTES and current:
+                filter_chunks.append({key: "|".join(current)})
+                current = [part]
+            else:
+                current.append(part)
+
+        if current:
+            filter_chunks.append({key: "|".join(current)})
+
+        return filter_chunks or [params.filter]

prestashop_webservice/carrier.py

@@ -0,0 +1,31 @@
+from typing import cast
+
+from prestashop_webservice.base_model import BaseModel
+from prestashop_webservice.models import CarrierData
+from prestashop_webservice.params import Params
+
+
+class Carrier(BaseModel):
+    """Complex queries for carriers endpoint."""
+
+    _data_class = CarrierData
+
+    def get_by_id(self, carrier_id: str) -> CarrierData:
+        """Get carrier by ID."""
+        return cast(CarrierData, self._query(f"carriers/{carrier_id}", None, "carrier"))
+
+    def get_all(self, limit: int | None = None) -> list[CarrierData]:
+        """Get carriers with optional limit."""
+        params = Params(limit=limit)
+        return cast(list[CarrierData], self._query("carriers", params, "carriers"))
+
+    def get_active(self, limit: int | None = None) -> list[CarrierData]:
+        """Get active carriers only."""
+        params = Params(filter={"active": "1"}, limit=limit)
+        return cast(list[CarrierData], self._query("carriers", params, "carriers"))
+
+    def get_by_reference(self, reference_id: str) -> CarrierData | None:
+        """Get carrier by reference identifier."""
+        params = Params(filter={"id_reference": reference_id}, limit=1)
+        carriers = cast(list[CarrierData], self._query("carriers", params, "carriers"))
+        return carriers[0] if carriers else None

prestashop_webservice/client.py

@@ -0,0 +1,160 @@
+from typing import cast
+
+from cachetools import TTLCache, cached
+from httpx import BasicAuth, Limits, Timeout
+from httpx import Client as HTTPXClient
+
+from prestashop_webservice.config import Config
+from prestashop_webservice.logger import logger
+from prestashop_webservice.params import Params
+
+
+class Client:
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(
+        self,
+        prestashop_base_url: str,
+        prestashop_ws_key: str,
+        max_connections: int = Config.MAX_CONNECTIONS,
+        max_keepalive_connections: int = Config.MAX_KEEPALIVE_CONNECTIONS,
+        keepalive_expiry: float = Config.KEEPALIVE_EXPIRY,
+    ):
+        if getattr(self, "_initialized", False):
+            return
+
+        self.base_url = prestashop_base_url.rstrip("/api")
+        self.client = HTTPXClient(
+            base_url=prestashop_base_url,
+            timeout=Timeout(connect=5.0, read=10.0, write=10.0, pool=5.0),
+            limits=Limits(
+                max_connections=max_connections,
+                max_keepalive_connections=max_keepalive_connections,
+                keepalive_expiry=keepalive_expiry,
+            ),
+            follow_redirects=False,
+            auth=BasicAuth(prestashop_ws_key, ""),
+            params={"output_format": "JSON"},
+        )
+        self._initialized = True
+
+    @cached(cache=TTLCache(maxsize=100, ttl=86400))
+    def query_order(self, params: Params | None = None, order_id: str = "") -> dict:
+        return cast(dict, self._query(f"orders/{order_id}", params, "order"))
+
+    def query_address(self, params: Params | None = None, address_id: str = "") -> dict:
+        return cast(dict, self._query(f"addresses/{address_id}", params, "address"))
+
+    @cached(cache=TTLCache(maxsize=100, ttl=86400))
+    def query_order_carriers(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("order_carriers", params, "order_carriers"))
+
+    @cached(cache=TTLCache(maxsize=200, ttl=86400))
+    def query_customer(self, params: Params | None = None, customer_id: str = "") -> dict:
+        return cast(dict, self._query(f"customers/{customer_id}", params, "customer"))
+
+    @cached(cache=TTLCache(maxsize=100, ttl=86400))
+    def query_customers(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("customers", params, "customers"))
+
+    @cached(cache=TTLCache(maxsize=200, ttl=86400))
+    def query_orders(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("orders", params, "orders"))
+
+    @cached(cache=TTLCache(maxsize=500, ttl=86400))
+    def query_product(self, params: Params | None = None, product_id: str = "") -> dict:
+        return cast(dict, self._query(f"products/{product_id}", params, "product"))
+
+    @cached(cache=TTLCache(maxsize=50, ttl=86400))
+    def query_country(self, params: Params | None = None, country_id: str = "") -> dict:
+        return cast(dict, self._query(f"countries/{country_id}", params, "country"))
+
+    @cached(cache=TTLCache(maxsize=100, ttl=86400))
+    def query_countries(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("countries", params, "countries"))
+
+    @cached(cache=TTLCache(maxsize=100, ttl=86400))
+    def query_addresses(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("addresses", params, "addresses"))
+
+    @cached(cache=TTLCache(maxsize=500, ttl=86400))
+    def query_products(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("products", params, "products"))
+
+    @cached(cache=TTLCache(maxsize=50, ttl=86400))
+    def query_state(self, params: Params | None = None, state_id: str = "") -> dict:
+        return cast(dict, self._query(f"states/{state_id}", params, "state"))
+
+    @cached(cache=TTLCache(maxsize=200, ttl=86400))
+    def query_product_images(
+        self, params: Params | None = None, product_id: str = ""
+    ) -> list[dict]:
+        return cast(list[dict], self._query(f"images/products/{product_id}", params, "image"))
+
+    @cached(cache=TTLCache(maxsize=100, ttl=86400))
+    def query_order_histories(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("order_histories", params, "order_histories"))
+
+    @cached(cache=TTLCache(maxsize=50, ttl=86400))
+    def query_order_state(self, params: Params | None = None, state_id: str = "") -> dict:
+        return cast(dict, self._query(f"order_states/{state_id}", params, "order_state"))
+
+    @cached(cache=TTLCache(maxsize=500, ttl=86400))
+    def query_combination(self, params: Params | None = None, combination_id: str = "") -> dict:
+        return cast(dict, self._query(f"combinations/{combination_id}", params, "combination"))
+
+    @cached(cache=TTLCache(maxsize=500, ttl=86400))
+    def query_combinations(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("combinations", params, "combinations"))
+
+    @cached(cache=TTLCache(maxsize=100, ttl=86400))
+    def query_customer_message(self, params: Params | None = None, message_id: str = "") -> dict:
+        return cast(
+            dict, self._query(f"customer_messages/{message_id}", params, "customer_message")
+        )
+
+    @cached(cache=TTLCache(maxsize=100, ttl=86400))
+    def query_customer_messages(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("customer_messages", params, "customer_messages"))
+
+    @cached(cache=TTLCache(maxsize=500, ttl=86400))
+    def query_order_detail(self, params: Params | None = None, order_detail_id: str = "") -> dict:
+        return cast(dict, self._query(f"order_details/{order_detail_id}", params, "order_detail"))
+
+    @cached(cache=TTLCache(maxsize=500, ttl=86400))
+    def query_order_details(self, params: Params | None = None) -> list[dict]:
+        return cast(list[dict], self._query("order_details", params, "order_details"))
+
+    def post(self, endpoint: str, xml_payload: str) -> dict:
+        logger.debug(f"POSTing to {endpoint}")
+
+        response = self.client.post(
+            f"/{endpoint}",
+            content=xml_payload,
+            headers={"Content-Type": "application/xml"},
+        )
+        response.raise_for_status()
+
+        return response.json() or {}
+
+    def _query(
+        self, endpoint: str, params: Params | None = None, response_key: str = ""
+    ) -> dict | list:
+        logger.debug(f"Requesting {endpoint}")
+
+        response = self.client.get(f"/{endpoint}", params=params.to_dict() if params else None)
+        response.raise_for_status()
+
+        json_response = response.json() or {}
+
+        if response_key:
+            result = json_response.get(response_key, {})
+            return result if result else {}
+
+        return json_response

prestashop_webservice/combination.py

@@ -0,0 +1,29 @@
+from typing import cast
+
+from cachetools import TTLCache, cached
+
+from prestashop_webservice.base_model import BaseModel
+from prestashop_webservice.models import CombinationData
+from prestashop_webservice.params import Params
+
+
+class Combination(BaseModel):
+    """Complex queries for combinations endpoint."""
+
+    _data_class = CombinationData
+
+    @cached(cache=TTLCache(maxsize=1000, ttl=604800))
+    def get_by_id(self, combination_id: str) -> CombinationData:
+        """Get combination by ID."""
+        return cast(
+            CombinationData, self._query(f"combinations/{combination_id}", None, "combination")
+        )
+
+    @cached(cache=TTLCache(maxsize=1000, ttl=604800))
+    def get_by_product(self, product_id: str) -> list[CombinationData]:
+        """Get combinations for a product."""
+        params = Params(
+            filter={"id_product": product_id},
+            display=["id", "id_product", "reference", "ean13", "price", "weight", "default_on"],
+        )
+        return cast(list[CombinationData], self._query("combinations", params, "combinations"))

prestashop_webservice/config.py

@@ -0,0 +1,9 @@
+"""
+Default configuration file for PrestaShop Webservice
+"""
+
+
+class Config:
+    MAX_CONNECTIONS = 2
+    MAX_KEEPALIVE_CONNECTIONS = 2
+    KEEPALIVE_EXPIRY = 10.0

prestashop_webservice/country.py

@@ -0,0 +1,30 @@
+from prestashop_webservice.base_model import BaseModel
+from prestashop_webservice.models import CountryData
+from prestashop_webservice.params import Params
+
+
+class Country(BaseModel):
+    """Complex queries for countries endpoint."""
+
+    _data_class = CountryData
+
+    def get_by_id(self, country_id: str) -> CountryData:
+        """Get country by ID."""
+        return self._query(f"countries/{country_id}", None, "country")
+
+    def get_by_iso_code(self, iso_code: str) -> CountryData | None:
+        """Get country by ISO code."""
+        params = Params(
+            filter={"iso_code": iso_code},
+            display=["id", "iso_code", "name"],
+        )
+        countries = self._query("countries", params, "countries")
+        return countries[0] if countries else None
+
+    def get_active(self) -> list[CountryData]:
+        """Get all active countries."""
+        params = Params(
+            filter={"active": "1"},
+            display=["id", "iso_code", "name", "active"],
+        )
+        return self._query("countries", params, "countries")

prestashop_webservice/customer.py

@@ -0,0 +1,42 @@
+from prestashop_webservice.base_model import BaseModel
+from prestashop_webservice.models import CustomerData
+from prestashop_webservice.params import Params
+
+
+class Customer(BaseModel):
+    """Complex queries for customers endpoint."""
+
+    _data_class = CustomerData
+
+    def get_by_id(self, customer_id: str) -> CustomerData:
+        """Get customer by ID."""
+        return self._query(f"customers/{customer_id}", None, "customer")
+
+    def get_by_email(self, email: str) -> CustomerData | None:
+        """Get customer by email."""
+        email = email.strip().lower()
+        params = Params(
+            filter={"email": email},
+            display=["id", "email", "firstname", "lastname"],
+        )
+        customers = self._query("customers", params, "customers")
+        return customers[0] if customers else None
+
+    def get_active(self, limit: int = 100) -> list[CustomerData]:
+        """Get active customers."""
+        params = Params(
+            filter={"active": "1"},
+            display=["id", "firstname", "lastname", "email", "active"],
+            limit=limit,
+        )
+        return self._query("customers", params, "customers")
+
+    def search_by_name(self, name: str, limit: int = 50) -> list[CustomerData]:
+        """Search customers by firstname or lastname."""
+        params = Params(
+            filter={"firstname": f"%{name}%"},
+            display=["id", "firstname", "lastname", "email"],
+            limit=limit,
+        )
+        result = self._query("customers", params, "customers")
+        return result if result is not None else []

prestashop_webservice/customer_message.py

@@ -0,0 +1,29 @@
+from prestashop_webservice.base_model import BaseModel
+from prestashop_webservice.models import CustomerMessageData
+from prestashop_webservice.params import Params
+
+
+class CustomerMessage(BaseModel):
+    """Complex queries for customer_messages endpoint."""
+
+    _data_class = CustomerMessageData
+
+    def get_by_id(self, message_id: str) -> CustomerMessageData:
+        """Get customer message by ID."""
+        return self._query(f"customer_messages/{message_id}", None, "customer_message")
+
+    def get_by_order(self, order_id: str) -> list[CustomerMessageData]:
+        """Get messages associated with an order (via customer thread potentially, but often queried by order)."""
+        params = Params(
+            filter={"id_order": order_id},
+            display=["id", "message", "id_employee", "private", "date_add"],
+        )
+        return self._query("customer_messages", params, "customer_messages")
+
+    def get_by_thread(self, thread_id: str) -> list[CustomerMessageData]:
+        """Get messages associated with a specific customer thread."""
+        params = Params(
+            filter={"id_customer_thread": thread_id},
+            display=["full"],
+        )
+        return self._query("customer_messages", params, "customer_messages")

prestashop_webservice/customer_thread.py

@@ -0,0 +1,23 @@
+from prestashop_webservice.base_model import BaseModel
+from prestashop_webservice.models import CustomerThreadData
+from prestashop_webservice.params import Params
+
+
+class CustomerThread(BaseModel):
+    """Complex queries for customer_threads endpoint."""
+
+    _data_class = CustomerThreadData
+
+    def get_by_id(self, thread_id: str) -> CustomerThreadData:
+        """Get customer thread by ID."""
+        return self._query(f"customer_threads/{thread_id}", None, "customer_thread")
+
+    def get_by_customer(self, customer_id: str) -> list[CustomerThreadData]:
+        """Get customer threads by customer ID."""
+        params = Params(filter={"id_customer": customer_id}, display=["full"])
+        return self._query("customer_threads", params, "customer_threads")
+
+    def get_by_order(self, order_id: str) -> list[CustomerThreadData]:
+        """Get customer threads by order ID."""
+        params = Params(filter={"id_order": order_id}, display=["full"])
+        return self._query("customer_threads", params, "customer_threads")

prestashop_webservice/image_product.py

@@ -0,0 +1,12 @@
+from prestashop_webservice.base_model import BaseModel
+from prestashop_webservice.models import ImageProductData
+
+
+class ImageProduct(BaseModel):
+    """Complex queries for images/products endpoint."""
+
+    _data_class = ImageProductData
+
+    def get_by_product(self, product_id: str) -> list[ImageProductData]:
+        """Get images for a product."""
+        return self._query(f"images/products/{product_id}", None, "image")

prestashop_webservice/logger.py

@@ -0,0 +1,31 @@
+from loguru import logger
+
+
+def configure_logger():
+    logger.remove()
+
+    # Format
+    console_format = "<green>{time:HH:mm:ss}</green> | " "<level>{level}</level> >> " "{message}"
+
+    # Terminal logging
+    logger.add(
+        lambda msg: print(msg, end=""),
+        level="INFO",
+        format=console_format,
+        colorize=True,
+    )
+
+    # File logging
+    logger.add(
+        "logs/app.log",
+        rotation="10 MB",
+        retention="10 days",
+        level="DEBUG",
+        format="{time:YYYY-MM-DD at HH:mm:ss} | {level} | {message}",
+        compression="zip",
+    )
+
+    return logger
+
+
+configure_logger()