python-picnic-api2 1.3.3__py3-none-any.whl → 2.0.0__py3-none-any.whl

python_picnic_api2/__init__.py

@@ -1,7 +1,50 @@
 from .client import PicnicAPI
-from .session import Picnic2FAError, Picnic2FARequired
+from .exceptions import PicnicParseError
+from .models import (
+    Address,
+    Article,
+    Cart,
+    Category,
+    Delivery,
+    DeliverySlots,
+    DeliverySummary,
+    HouseholdDetails,
+    Order,
+    OrderArticle,
+    OrderLine,
+    PicnicModel,
+    SearchResult,
+    SearchResultItem,
+    Slot,
+    Subscription,
+    User,
+)
+from .session import Picnic2FAError, Picnic2FARequired, PicnicAuthError
 
-__all__ = ["PicnicAPI", "Picnic2FAError", "Picnic2FARequired"]
+__all__ = [
+    "PicnicAPI",
+    "PicnicAuthError",
+    "Picnic2FAError",
+    "Picnic2FARequired",
+    "PicnicParseError",
+    "PicnicModel",
+    "Article",
+    "Category",
+    "SearchResult",
+    "SearchResultItem",
+    "User",
+    "Address",
+    "Subscription",
+    "HouseholdDetails",
+    "Cart",
+    "DeliverySlots",
+    "Delivery",
+    "DeliverySummary",
+    "Slot",
+    "Order",
+    "OrderLine",
+    "OrderArticle",
+]
 __title__ = "python-picnic-api"
-__version__ = "1.1.0"
+__version__ = "2.0.0"
 __author__ = "Mike Brink"

python_picnic_api2/client.py

@@ -1,14 +1,20 @@
-import re
 from hashlib import md5
 from urllib.parse import quote
 
 import typing_extensions
 
-from .helper import (
-    _extract_search_results,
-    _tree_generator,
-    _url_generator,
-    find_nodes_by_content,
+from .exceptions import PicnicParseError
+from .helper import _url_generator
+from .models import (
+    Article,
+    Cart,
+    Category,
+    Delivery,
+    DeliverySlots,
+    DeliverySummary,
+    SearchResult,
+    User,
+    pml,
 )
 from .session import (
     Picnic2FAError,
@@ -18,7 +24,6 @@ from .session import (
 )
 
 DEFAULT_URL = "https://storefront-prod.{}.picnicinternational.com/api/{}"
-GLOBAL_GATEWAY_URL = "https://gateway-prod.global.picnicinternational.com"
 DEFAULT_COUNTRY_CODE = "NL"
 DEFAULT_API_VERSION = "15"
 _HEADERS = {
@@ -46,13 +51,6 @@ class PicnicAPI:
         if not self.session.authenticated and username and password:
             self.login(username, password)
 
-        self.high_level_categories = None
-
-    def initialize_high_level_categories(self):
-        """Initialize high-level categories once to avoid multiple requests."""
-        if not self.high_level_categories:
-            self.high_level_categories = self.get_categories(depth=1)
-
     def _get(self, path: str, add_picnic_headers=False):
         url = self._base_url + path
 
@@ -86,7 +84,7 @@ class PicnicAPI:
         if not isinstance(response, dict):
             return False
 
-        error_code = response.setdefault("error", {}).get("code")
+        error_code = response.get("error", {}).get("code")
         return error_code == "AUTH_ERROR" or error_code == "AUTH_INVALID_CRED"
 
     @staticmethod
@@ -94,8 +92,8 @@ class PicnicAPI:
         if not isinstance(response, dict):
             return False
 
-        error_code = response.get("error", {}).get("code")
-        return error_code == "TWO_FACTOR_AUTHENTICATION_REQUIRED"
+        return "second_factor_authentication_required" in response \
+        and response["second_factor_authentication_required"] is True
 
     def login(self, username: str, password: str):
         path = "/user/login"
@@ -169,85 +167,82 @@ class PicnicAPI:
     def logged_in(self):
         return self.session.authenticated
 
-    def get_user(self):
-        return self._get("/user")
+    def get_user(self) -> User:
+        return User.from_api(self._get("/user"))
 
-    def search(self, term: str):
+    def search(self, term: str) -> SearchResult:
         path = f"/pages/search-page-results?search_term={quote(term)}"
         raw_results = self._get(path, add_picnic_headers=True)
-        return _extract_search_results(raw_results)
+        return SearchResult.from_page(raw_results)
 
-    def get_cart(self):
-        return self._get("/cart")
+    def get_cart(self) -> Cart:
+        return Cart.from_api(self._get("/cart"))
 
-    def get_article(self, article_id: str, add_category=False):
+    def get_article(self, article_id: str, add_category=False) -> Article | None:
         path = f"/pages/product-details-page-root?id={article_id}" + \
             "&show_category_action=true"
         data = self._get(path, add_picnic_headers=True)
-        article_details = []
 
-        root_container = find_nodes_by_content(
-            data, {"id": "product-details-page-root-main-container"}, max_nodes=1)
-        if len(root_container) == 0:
+        article = Article.from_page(data, article_id)
+        if article is None:
             return None
 
-        article_details = root_container[0]["pml"]["component"]["children"]
-
-        if len(article_details) == 0:
-            return None
-
-        article = {}
         if add_category:
-            cat_node = find_nodes_by_content(
-                data, {"id": "category-button"}, max_nodes=1)
-            if len(cat_node) == 0:
-                raise KeyError(
-                    f"Could not extract category from article with id {article_id}")
-            category_regex = re.compile(
-                "app\\.picnic:\\/\\/categories\\/(\\d+)\\/l2\\/(\\d+)\\/l3\\/(\\d+)")
-            cat_ids = category_regex.match(
-                cat_node[0]["pml"]["component"]["onPress"]["target"]).groups()
-            article["category"] = self.get_category_by_ids(
-                int(cat_ids[1]), int(cat_ids[2]))
-
-        color_regex = re.compile(r"#\(#\d{6}\)")
-        producer = re.sub(color_regex, "", str(
-            article_details[1].get("markdown", "")))
-        article_name = re.sub(color_regex, "", str(
-            article_details[0]["markdown"]))
-
-        article["name"] = f"{producer} {article_name}"
-        article["id"] = article_id
+            cat_ids = Article.category_ids_from_page(data)
+            if cat_ids is None:
+                raise PicnicParseError(
+                    f"Could not extract category from article with id {article_id}",
+                    endpoint="product-details-page-root",
+                )
+            _, l2_id, l3_id = cat_ids
+            article.category = self.get_category_by_ids(l2_id, l3_id)
 
         return article
 
     def get_article_category(self, article_id: str):
+        """Return the raw category payload for an article.
+
+        Not modelled: this endpoint appears to have been removed by Picnic (it
+        returns an error object, like ``get_categories``). Kept for backwards
+        compatibility; returns the raw dict. Use ``get_article(id,
+        add_category=True)`` to resolve an article's category instead.
+        """
         path = "/articles/" + article_id + "/category"
         return self._get(path)
 
-    def add_product(self, product_id: str, count: int = 1):
+    def add_product(self, product_id: str, count: int = 1) -> Cart:
         data = {"product_id": product_id, "count": count}
-        return self._post("/cart/add_product", data)
+        return Cart.from_api(self._post("/cart/add_product", data))
 
-    def remove_product(self, product_id: str, count: int = 1):
+    def remove_product(self, product_id: str, count: int = 1) -> Cart:
         data = {"product_id": product_id, "count": count}
-        return self._post("/cart/remove_product", data)
+        return Cart.from_api(self._post("/cart/remove_product", data))
 
-    def clear_cart(self):
-        return self._post("/cart/clear")
+    def clear_cart(self) -> Cart:
+        return Cart.from_api(self._post("/cart/clear"))
 
-    def get_delivery_slots(self):
-        return self._get("/cart/delivery_slots")
+    def get_delivery_slots(self) -> DeliverySlots:
+        return DeliverySlots.from_api(self._get("/cart/delivery_slots"))
 
-    def get_delivery(self, delivery_id: str):
+    def get_delivery(self, delivery_id: str) -> Delivery:
         path = "/deliveries/" + delivery_id
-        return self._get(path)
+        return Delivery.from_api(self._get(path))
 
     def get_delivery_scenario(self, delivery_id: str):
+        """Return the raw driving-scenario payload for a delivery.
+
+        Not modelled: it is only populated while a delivery is en route, so
+        there is no stable sample to build a model against. Returns the raw dict.
+        """
         path = "/deliveries/" + delivery_id + "/scenario"
         return self._get(path, add_picnic_headers=True)
 
     def get_delivery_position(self, delivery_id: str):
+        """Return the raw driver-position payload for a delivery.
+
+        Not modelled: only populated while a delivery is en route (otherwise
+        empty). Returns the raw dict.
+        """
         path = "/deliveries/" + delivery_id + "/position"
         return self._get(path, add_picnic_headers=True)
 
@@ -258,33 +253,36 @@ class PicnicAPI:
         You can ignore this warning if you do not pass the 'summary' argument to
         this function."""
     )
-    def get_deliveries(self, summary: bool = True, data: list = None):
+    def get_deliveries(
+        self, summary: bool = True, data: list = None
+    ) -> list[DeliverySummary]:
         data = [] if data is None else data
         if not summary:
             raise NotImplementedError()
-        return self._post("/deliveries/summary", data=data)
+        raw = self._post("/deliveries/summary", data=data)
+        return [DeliverySummary.from_api(item) for item in raw]
 
-    def get_current_deliveries(self):
+    def get_current_deliveries(self) -> list[DeliverySummary]:
         return self.get_deliveries(data=["CURRENT"])
 
     def get_categories(self, depth: int = 0):
         raise NotImplementedError("This endpoint has been removed by picnic\
         and is no longer functional.")
 
-    def get_category_by_ids(self, l2_id: int, l3_id: int):
+    def get_category_by_ids(self, l2_id: int, l3_id: int) -> Category:
         path = "/pages/L2-category-page-root" + \
             f"?category_id={l2_id}&l3_category_id={l3_id}"
         data = self._get(path, add_picnic_headers=True)
-        nodes = find_nodes_by_content(
-            data, {"id": f"vertical-article-tiles-sub-header-{l3_id}"}, max_nodes=1)
-        if len(nodes) == 0:
-            raise KeyError("Could not find category with specified IDs")
-        return {"l2_id": l2_id, "l3_id": l3_id,
-                "name": nodes[0]["pml"]["component"]["accessibilityLabel"]}
-
-    def print_categories(self, depth: int = 0):
-        tree = "\n".join(_tree_generator(self.get_categories(depth=depth)))
-        print(tree)
+        node = pml.find(
+            data, id=f"vertical-article-tiles-sub-header-{l3_id}")
+        if node is None:
+            raise PicnicParseError(
+                "Could not find category with specified IDs",
+                endpoint="L2-category-page-root",
+            )
+        return Category(
+            l2_id=l2_id, l3_id=l3_id,
+            name=pml.accessibility_label(node), raw=data)
 
     def get_article_by_gtin(self, etan: str, maxRedirects: int = 5):
         # Finds the article ID for a gtin/ean (barcode).

python_picnic_api2/exceptions.py

@@ -0,0 +1,32 @@
+"""Exceptions raised by the Picnic API client.
+
+Authentication-related exceptions live in :mod:`python_picnic_api2.session` for
+historical reasons and are re-exported here so that all public exceptions can be
+imported from a single place.
+"""
+
+from .session import Picnic2FAError, Picnic2FARequired, PicnicAuthError
+
+
+class PicnicParseError(Exception):
+    """Raised when a Picnic PML ("layout") response cannot be parsed into a model.
+
+    The Picnic ``/pages/*`` endpoints return a UI layout tree of widgets that
+    varies by country and A/B test. When an expected node or field is missing
+    this is raised instead of a bare ``KeyError`` so callers get a clear,
+    actionable message about what was being looked for.
+    """
+
+    def __init__(self, message: str, *, endpoint: str | None = None):
+        if endpoint:
+            message = f"{message} (endpoint: {endpoint})"
+        super().__init__(message)
+        self.endpoint = endpoint
+
+
+__all__ = [
+    "PicnicParseError",
+    "PicnicAuthError",
+    "Picnic2FARequired",
+    "Picnic2FAError",
+]

python_picnic_api2/helper.py

@@ -1,73 +1,15 @@
-import json
 import logging
-import re
-
-# prefix components:
-space = "    "
-branch = "│   "
-# pointers:
-tee = "├── "
-last = "└── "
 
 LOGGER = logging.getLogger(__name__)
 
 IMAGE_SIZES = ["small", "medium", "regular", "large", "extra-large"]
 IMAGE_BASE_URL = "https://storefront-prod.nl.picnicinternational.com/static/images"
 
-SOLE_ARTICLE_ID_PATTERN = re.compile(r'"sole_article_id":"(\w+)"')
-
-
-def _tree_generator(response: list, prefix: str = ""):
-    """A recursive tree generator,
-    will yield a visual tree structure line by line
-    with each line prefixed by the same characters
-    """
-    # response each get pointers that are ├── with a final └── :
-    pointers = [tee] * (len(response) - 1) + [last]
-    for pointer, item in zip(pointers, response, strict=False):
-        if "name" in item:  # print the item
-            pre = ""
-            if "unit_quantity" in item:
-                pre = f"{item['unit_quantity']} "
-            after = ""
-            if "display_price" in item:
-                after = f" €{int(item['display_price']) / 100.0:.2f}"
-
-            yield prefix + pointer + pre + item["name"] + after
-        if "items" in item:  # extend the prefix and recurse:
-            extension = branch if pointer == tee else space
-            # i.e. space because last, └── , above so no more |
-            yield from _tree_generator(item["items"], prefix=prefix + extension)
-
 
 def _url_generator(url: str, country_code: str, api_version: str):
     return url.format(country_code.lower(), api_version)
 
 
-def _get_category_id_from_link(category_link: str) -> str | None:
-    pattern = r"categories/(\d+)"
-    first_number = re.search(pattern, category_link)
-    if first_number:
-        result = str(first_number.group(1))
-        return result
-    else:
-        return None
-
-
-def _get_category_name(category_link: str, categories: list) -> str | None:
-    category_id = _get_category_id_from_link(category_link)
-    if category_id:
-        category = next(
-            (item for item in categories if item["id"] == category_id), None
-        )
-        if category:
-            return category["name"]
-        else:
-            return None
-    else:
-        return None
-
-
 def get_recipe_image(id: str, size="regular"):
     sizes = IMAGE_SIZES + ["1250x1250"]
     assert size in sizes, "size must be one of: " + ", ".join(sizes)
@@ -83,68 +25,3 @@ def get_image(id: str, size="regular", suffix="webp"):
 
     assert size in sizes, "size must be one of: " + ", ".join(sizes)
     return f"{IMAGE_BASE_URL}/{id}/{size}.{suffix}"
-
-
-def find_nodes_by_content(node, filter, max_nodes: int = 10):
-    nodes = []
-
-    if len(nodes) >= 10:
-        return nodes
-
-    def is_dict_included(node_dict, filter_dict):
-        for k, v in filter_dict.items():
-            if k not in node_dict:
-                return False
-            if isinstance(v, dict) and isinstance(node_dict[k], dict):
-                if not is_dict_included(node_dict[k], v):
-                    return False
-            elif node_dict[k] != v and v is not None:
-                return False
-        return True
-
-    if is_dict_included(node, filter):
-        nodes.append(node)
-
-    if isinstance(node, dict):
-        for _, v in node.items():
-            if isinstance(v, dict):
-                nodes.extend(find_nodes_by_content(v, filter, max_nodes))
-                continue
-            if isinstance(v, list):
-                for item in v:
-                    if isinstance(v, dict | list):
-                        nodes.extend(find_nodes_by_content(
-                            item, filter, max_nodes))
-                        continue
-
-    return nodes
-
-
-def _extract_search_results(raw_results, max_items: int = 10):
-    """Extract search results from the nested dictionary structure returned by
-    Picnic search. Number of max items can be defined to reduce excessive nested
-    search"""
-
-    LOGGER.debug(f"Extracting search results from {raw_results}")
-
-    body = raw_results.get("body", {})
-    nodes = find_nodes_by_content(body.get("child", {}), {
-        "type": "SELLING_UNIT_TILE", "sellingUnit": {}})
-
-    search_results = []
-    for node in nodes:
-        selling_unit = node["sellingUnit"]
-        sole_article_ids = SOLE_ARTICLE_ID_PATTERN.findall(
-            json.dumps(node))
-        sole_article_id = sole_article_ids[0] if sole_article_ids else None
-        result_entry = {
-            **selling_unit,
-            "sole_article_id": sole_article_id,
-        }
-        LOGGER.debug(f"Found article {result_entry}")
-        search_results.append(result_entry)
-
-    LOGGER.debug(
-        f"Found {len(search_results)}/{max_items} products after extraction")
-
-    return [{"items": search_results}]

python_picnic_api2/models/__init__.py

@@ -0,0 +1,45 @@
+"""Typed data models for Picnic API responses."""
+
+from .article import Article
+from .base import PicnicModel
+from .cart import Cart
+from .category import Category
+from .common import (
+    Decorator,
+    Eta,
+    Order,
+    OrderArticle,
+    OrderLine,
+    SelectedSlot,
+    Slot,
+    TransactionInfo,
+)
+from .delivery import Delivery, DeliverySlots, DeliverySummary
+from .search import SearchResult, SearchResultItem
+from .user import Address, HouseholdDetails, Subscription, User
+
+__all__ = [
+    "PicnicModel",
+    "Article",
+    "Category",
+    "SearchResult",
+    "SearchResultItem",
+    # Domain-JSON models
+    "User",
+    "Address",
+    "Subscription",
+    "HouseholdDetails",
+    "Cart",
+    "DeliverySlots",
+    "Delivery",
+    "DeliverySummary",
+    # Shared building blocks
+    "Slot",
+    "SelectedSlot",
+    "Eta",
+    "TransactionInfo",
+    "Order",
+    "OrderLine",
+    "OrderArticle",
+    "Decorator",
+]