Typed models for PML data (#49)

Author: codesalatdev

.github/workflows/ci.yaml

@@ -35,10 +35,6 @@ jobs:
       run: uv sync
 
     - name: Test with pytest
-      env:
-        USERNAME: ${{ secrets.PICNIC_USERNAME }}
-        PASSWORD: ${{ secrets.PICNIC_PASSWORD }}
-        COUNTRY_CODE: ${{ secrets.PICNIC_COUNTRY_CODE }}
       run: |
         uv run pytest tests/ --cov --cov-report=xml
         

README.md

@@ -4,7 +4,7 @@
 
 **If you want to know why interacting with Picnic is getting harder than ever, check out their blogpost about architectural changes: [https://blog.picnic.nl/adding-write-functionality-to-pages-with-self-service-apis-d09aa7dbc9c0](https://jobs.picnic.app/en/blogs/adding-write-functionality-to-pages-with-self-service-apis)**
 
-Fork of the Unofficial Python wrapper for the [Picnic](https://picnic.app) API. While not all API methods have been implemented yet, you'll find most of what you need to build a working application are available. 
+Fork of the Unofficial Python wrapper for the [Picnic](https://picnic.app) API. While not all API methods have been implemented yet, you'll find most of what you need to build a working application is available.
 
 This library is not affiliated with Picnic and retrieves data from the endpoints of the mobile application. **Use at your own risk.**
 
@@ -53,45 +53,90 @@ except Picnic2FARequired:
 
 After successful verification, the session is authenticated and you can use the API normally. If the code is invalid, `Picnic2FAError` is raised.
 
-## Searching for an article
+## Typed models (2.x)
 
-```python
-picnic.search('coffee')
-```
+As of 2.x the API returns typed [pydantic](https://docs.pydantic.dev) models
+instead of raw dicts. This covers both the "page" endpoints Picnic serves as a
+layout tree of widgets (`search`, `get_article`, `get_category_by_ids`) and the
+domain-JSON endpoints (`get_user`, `get_cart`, `get_delivery_slots`,
+`get_delivery`, `get_deliveries` / `get_current_deliveries`, and the cart-mutation
+methods). Every model exposes `.raw` with the original, untouched payload as an
+escape hatch for data that isn't modelled yet, and `.model_dump()` for a
+plain-dict view.
 
-```python
-[{'items': [{'id': 's1019822', 'name': 'Lavazza Caffè Crema e Aroma Bohnen', 'decorators': [], 'display_price': 1799, 'image_id': 'aecbf7d3b018025ec78daf5a1099b6842a860a2e3faeceec777c13d708ce442c', 'max_count': 99, 'unit_quantity': '1kg', 'sole_article_id': None}, ... ]}]
-```
+A couple of endpoints still return raw dicts: `get_delivery_scenario` and
+`get_delivery_position` (only populated while a delivery is en route, so there is
+no stable shape to model), and `get_article_category` (appears to have been
+removed by Picnic — use `get_article(id, add_category=True)` instead).
 
-## Get article by ID
+If you are upgrading from 1.x, see the [migration notes](#migrating-from-1x-to-20).
+
+## Usage
+
+### Searching for an article
 
 ```python
-picnic.get_article("s1019822")
-```
-```python
-{'name': 'Lavazza Caffè Crema e Aroma Bohnen', 'id': 's1019822'}
+result = picnic.search('coffee')          # -> SearchResult
+result.items[0].name                        # 'Lavazza Caffè Crema e Aroma Bohnen'
+result.items[0].display_price               # 1799  (price shown on the tile, in cents)
+result.items[0].raw                         # original tile payload
 ```
 
-## Get article by GTIN (EAN)
+Search tiles only carry `display_price` (the price shown, in integer cents) — the
+raw payload has no separate `price` key — so read `display_price`.
+
+### Get article by ID
+
 ```python
-picnic.get_article_by_gtin("8000070025400")
-```
+article = picnic.get_article("s1019822")   # -> Article | None
+article.id                                  # 's1019822'
+article.name                                # 'Lavazza Caffè Crema e Aroma Bohnen'
+article.product_name                        # 'Caffè Crema e Aroma Bohnen'
+article.producer                            # 'Lavazza'  (None for unbranded produce)
+article.unit_quantity                       # '1kg'
+article.price_per_unit                      # '€17.99/kg'  (comparative price, may be None)
+article.price                               # 1799  (current price, integer cents)
+article.original_price                      # 2249 when on sale, else None
+article.image_id                            # hero product image id
+article.description                         # product description (markdown)
+article.highlights                          # ['Lange **haltbar**', ...] feature bullets
+article.is_bundle                           # True for multipacks with other pack sizes
+article.bundle_variant_ids                  # ['s1018999', ...] other pack-size article ids
+
+# Optionally resolve the article's category (an extra request):
+article = picnic.get_article("s1019822", add_category=True)
+article.category.name                       # 'Koffiebonen'
+```
+
+### Get article by GTIN (EAN)
+
 ```python
-{'name': 'Lavazza Caffè Crema e Aroma Bohnen', 'id': 's1019822'}
+article = picnic.get_article_by_gtin("8000070025400")  # -> Article | None
+article.name                                # 'Lavazza Caffè Crema e Aroma Bohnen'
 ```
 
-## Check cart
+### Get the user
 
 ```python
-picnic.get_cart()
+user = picnic.get_user()          # -> User
+user.contact_email                  # 'you@example.com'
+user.address.city                   # 'Amsterdam'
+user.total_deliveries               # 25
 ```
 
+### Check cart
+
 ```python
-{'type': 'ORDER', 'id': 'shopping_cart', 'items': [{'type': 'ORDER_LINE', 'id': '1470', 'items': [{'type': 'ORDER_ARTICLE', 'id': 's1019822', 'name': 'Lavazza Caffè Crema e Aroma Bohnen',...
+cart = picnic.get_cart()          # -> Cart
+cart.total_count                    # 3
+cart.total_price                    # 1234  (integer cents)
+cart.items[0].items[0].name         # 'Lavazza Caffè Crema e Aroma Bohnen'
+cart.raw                            # original cart payload
 ```
 
-## Manipulating your cart
-All of these methods will return the shopping cart.
+### Manipulating your cart
+
+All of these methods return the updated `Cart`.
 
 ```python
 # Add product with ID "s1019822" 2x
@@ -104,22 +149,42 @@ picnic.remove_product("s1019822")
 picnic.clear_cart()
 ```
 
-## See upcoming deliveries
+### See upcoming deliveries
 
 ```python
-picnic.get_current_deliveries()
-```
+deliveries = picnic.get_current_deliveries()   # -> list[DeliverySummary]
+deliveries[0].delivery_id
+deliveries[0].status                             # 'CURRENT'
+deliveries[0].slot.window_start                  # '2025-04-29T17:15:00.000+02:00'
 
-```python
-[{'delivery_id': 'XXYYZZ', 'creation_time': '2025-04-28T08:08:41.666+02:00', 'slot': {'slot_id': 'XXYYZZ', 'hub_id': '...
+# Full detail (order lines, articles, payment info) for one delivery:
+delivery = picnic.get_delivery(deliveries[0].delivery_id)   # -> Delivery
+delivery.orders[0].items[0].items[0].name
 ```
 
-## See available delivery slots
+### See available delivery slots
 
 ```python
-picnic.get_delivery_slots()
-```
-
-```python
-{'delivery_slots': [{'slot_id': 'XXYYZZ', 'hub_id': 'YYY', 'fc_id': 'FCX', 'window_start': '2025-04-29T17:15:00.000+02:00', 'window_end': '2025-04-29T19:15:00.000+02:00'...
-```
+slots = picnic.get_delivery_slots()   # -> DeliverySlots
+slots.delivery_slots[0].window_start    # '2025-04-29T17:15:00.000+02:00'
+slots.selected_slot.slot_id
+```
+
+## Migrating from 1.x to 2.0
+
+- `search()` now returns a `SearchResult` (`.items` is a list of `SearchResultItem`)
+  instead of `[{"items": [...]}]`.
+- `get_article()` / `get_article_by_gtin()` now return an `Article` (or `None`)
+  instead of a `dict`; use `.id` / `.name` / `.category` instead of key access.
+- `get_category_by_ids()` now returns a `Category` instead of a `dict`.
+- Missing/unexpected PML nodes now raise `PicnicParseError` (from
+  `python_picnic_api2`) instead of a bare `KeyError`.
+- The domain-JSON methods now return typed models instead of raw dicts:
+  `get_user()` → `User`, `get_cart()` / `add_product()` / `remove_product()` /
+  `clear_cart()` → `Cart`, `get_delivery_slots()` → `DeliverySlots`,
+  `get_delivery()` → `Delivery`, and `get_deliveries()` /
+  `get_current_deliveries()` → `list[DeliverySummary]`. Use attribute access
+  (`cart.items`, `user.contact_email`) instead of `["items"]` / `["contact_email"]`.
+- `get_delivery_scenario()`, `get_delivery_position()` and `get_article_category()`
+  still return raw dicts (see [Typed models](#typed-models-2x)).
+- Any field you need that isn't modelled yet is available on `model.raw`.

README.rst

@@ -10,6 +10,7 @@
       in {
         devShell = pkgs.mkShell { buildInputs = with pkgs; [
           python313Packages.requests
+          python313Packages.pydantic
           python313Packages.python-lsp-ruff
           python313Packages.ruff
           python313Packages.typing-extensions