python-appie 0.1.0__tar.gz → 0.2.0__tar.gz

{python_appie-0.1.0 → python_appie-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-appie
-Version: 0.1.0
+Version: 0.2.0
 Summary: Unofficial Python client for the Albert Heijn API.
 Project-URL: Homepage, https://github.com/tijnschouten/appie
 Project-URL: Documentation, https://tijnschouten.github.io/appie/
@@ -13,6 +13,7 @@ Requires-Dist: playwright>=1.52.0
 Requires-Dist: pydantic>=2
 Provides-Extra: dev
 Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocs-static-i18n>=1.2; extra == 'dev'
 Requires-Dist: mkdocs>=1.6; extra == 'dev'
 Requires-Dist: pre-commit>=4.0; extra == 'dev'
 Requires-Dist: pyright>=1.1.390; extra == 'dev'
@@ -27,7 +28,7 @@ Description-Content-Type: text/markdown
 
 `python-appie` is an unofficial async Python client for the Albert Heijn API.
 
-Full documentation lives in [`docs/`](/Users/tijnschouten/repos/personal/appie/docs), is built from [`mkdocs.yml`](/Users/tijnschouten/repos/personal/appie/mkdocs.yml), and is intended to be published at [tijnschouten.github.io/appie](https://tijnschouten.github.io/appie/).
+[Full documentation](https://tijnschouten.github.io/appie/) is available in English and Dutch. The source for the docs lives in [`docs/`](/Users/tijnschouten/repos/personal/appie/docs) and is built from [`mkdocs.yml`](/Users/tijnschouten/repos/personal/appie/mkdocs.yml).
 
 Releases are intended to publish to PyPI as `python-appie` from version tags via GitHub Actions.
 
@@ -141,6 +142,9 @@ asyncio.run(main())
 ### Shopping lists
 
 - add an item via `client.lists.add_item(description, quantity=1, product_id=None)`
+- read the current shopping list via `client.lists.get_list()`
+- remove one item via `client.lists.remove_item(item_id)`
+- clear the entire list via `client.lists.clear()`
 - use `MockAHClient` for local development and tests without touching AH
 
 Example:
@@ -153,15 +157,74 @@ from appie import AHClient
 
 async def main() -> None:
     async with AHClient() as client:
-        item = await client.lists.add_item("Halfvolle melk", quantity=2)
-        print(item)
+        await client.lists.add_item("Halfvolle melk", quantity=2)
+        items = await client.lists.get_list()
+        print(items)
 
 
 asyncio.run(main())
 ```
 
-Current limitation:
-shopping-list add is implemented, but `get_list()`, `remove_item()`, and `clear()` still raise `NotImplementedError` until their live API shape is confirmed.
+Note:
+the `ShoppingListItem.id` returned by `get_list()` is an opaque removal key designed for `remove_item(item_id)`. It should be treated as an implementation detail rather than a stable AH server identifier.
+
+### Mocking and downstream tests
+
+- `MockAHClient()` provides an in-memory drop-in client for local development
+- `client.mock.calls` and `client.mock.last_call` capture what your code did
+- `client.mock.next_response(operation, value)` seeds a one-shot result
+- `client.mock.next_error(operation, exc)` seeds a one-shot failure
+- `client.mock.set_scenario(operation, delay_ms=..., error=...)` applies persistent delay/error behavior
+- `appie.pytest_plugin` provides pytest fixtures for downstream packages
+
+Example:
+
+```python
+import asyncio
+
+from appie import MockAHClient
+
+
+async def main() -> None:
+    async with MockAHClient() as client:
+        client.mock.next_response("products.search", [])
+        products = await client.products.search("melk")
+        print(products)
+        print(client.mock.last_call)
+
+
+asyncio.run(main())
+```
+
+Expected outcome:
+
+```text
+[]
+AppieMockCall(operation='products.search', params={'query': 'melk', 'limit': 10}, result=[], error=None)
+```
+
+Pytest plugin example:
+
+```python
+# tests/conftest.py
+pytest_plugins = ["appie.pytest_plugin"]
+```
+
+```python
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_checkout_uses_expected_query(appie_mock):
+    await appie_mock.products.search("melk", limit=3)
+
+    assert appie_mock.mock.last_call is not None
+    assert appie_mock.mock.last_call.params == {"query": "melk", "limit": 3}
+```
+
+Expected outcome:
+- the test runs without touching AH
+- the recorded call proves what your code sent into `python-appie`
 
 ## API overview
 
@@ -169,6 +232,7 @@ shopping-list add is implemented, but `get_list()`, `remove_item()`, and `clear(
 
 - `AHClient()`
 - `MockAHClient()`
+- `MockAHClient().mock`
 - `await client.login()`
 - `await client.graphql(query, variables=None)`
 
@@ -190,6 +254,17 @@ shopping-list add is implemented, but `get_list()`, `remove_item()`, and `clear(
 - `client.lists.remove_item(item_id)`
 - `client.lists.clear()`
 
+### Mock helpers
+
+- `client.mock.calls`
+- `client.mock.last_call`
+- `client.mock.clear_calls()`
+- `client.mock.next_response(operation, value)`
+- `client.mock.next_error(operation, exc)`
+- `client.mock.clear_seeded_responses()`
+- `client.mock.set_scenario(operation, delay_ms=0, error=None)`
+- `client.mock.clear_scenarios()`
+
 ## Development
 
 Run checks locally:
@@ -206,6 +281,6 @@ uv run --extra dev mkdocs build --strict
 
 - This client is unofficial and may break when Albert Heijn changes its backend.
 - Receipt support currently covers in-store POS receipts.
-- Shopping-list support only implements the verified add-item mutation; other operations raise explicit `NotImplementedError` until their GraphQL shape is confirmed.
+- Shopping-list read, add, remove, and clear are implemented against the live main-list endpoint.
 - Receipt summaries do not include line items; call `get_pos_receipt()` for a detailed receipt.
 - Endpoint discovery for this package is inspired by [gwillem/appie-go](https://github.com/gwillem/appie-go).

{python_appie-0.1.0 → python_appie-0.2.0}/README.md

@@ -2,7 +2,7 @@
 
 `python-appie` is an unofficial async Python client for the Albert Heijn API.
 
-Full documentation lives in [`docs/`](/Users/tijnschouten/repos/personal/appie/docs), is built from [`mkdocs.yml`](/Users/tijnschouten/repos/personal/appie/mkdocs.yml), and is intended to be published at [tijnschouten.github.io/appie](https://tijnschouten.github.io/appie/).
+[Full documentation](https://tijnschouten.github.io/appie/) is available in English and Dutch. The source for the docs lives in [`docs/`](/Users/tijnschouten/repos/personal/appie/docs) and is built from [`mkdocs.yml`](/Users/tijnschouten/repos/personal/appie/mkdocs.yml).
 
 Releases are intended to publish to PyPI as `python-appie` from version tags via GitHub Actions.
 
@@ -116,6 +116,9 @@ asyncio.run(main())
 ### Shopping lists
 
 - add an item via `client.lists.add_item(description, quantity=1, product_id=None)`
+- read the current shopping list via `client.lists.get_list()`
+- remove one item via `client.lists.remove_item(item_id)`
+- clear the entire list via `client.lists.clear()`
 - use `MockAHClient` for local development and tests without touching AH
 
 Example:
@@ -128,15 +131,74 @@ from appie import AHClient
 
 async def main() -> None:
     async with AHClient() as client:
-        item = await client.lists.add_item("Halfvolle melk", quantity=2)
-        print(item)
+        await client.lists.add_item("Halfvolle melk", quantity=2)
+        items = await client.lists.get_list()
+        print(items)
 
 
 asyncio.run(main())
 ```
 
-Current limitation:
-shopping-list add is implemented, but `get_list()`, `remove_item()`, and `clear()` still raise `NotImplementedError` until their live API shape is confirmed.
+Note:
+the `ShoppingListItem.id` returned by `get_list()` is an opaque removal key designed for `remove_item(item_id)`. It should be treated as an implementation detail rather than a stable AH server identifier.
+
+### Mocking and downstream tests
+
+- `MockAHClient()` provides an in-memory drop-in client for local development
+- `client.mock.calls` and `client.mock.last_call` capture what your code did
+- `client.mock.next_response(operation, value)` seeds a one-shot result
+- `client.mock.next_error(operation, exc)` seeds a one-shot failure
+- `client.mock.set_scenario(operation, delay_ms=..., error=...)` applies persistent delay/error behavior
+- `appie.pytest_plugin` provides pytest fixtures for downstream packages
+
+Example:
+
+```python
+import asyncio
+
+from appie import MockAHClient
+
+
+async def main() -> None:
+    async with MockAHClient() as client:
+        client.mock.next_response("products.search", [])
+        products = await client.products.search("melk")
+        print(products)
+        print(client.mock.last_call)
+
+
+asyncio.run(main())
+```
+
+Expected outcome:
+
+```text
+[]
+AppieMockCall(operation='products.search', params={'query': 'melk', 'limit': 10}, result=[], error=None)
+```
+
+Pytest plugin example:
+
+```python
+# tests/conftest.py
+pytest_plugins = ["appie.pytest_plugin"]
+```
+
+```python
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_checkout_uses_expected_query(appie_mock):
+    await appie_mock.products.search("melk", limit=3)
+
+    assert appie_mock.mock.last_call is not None
+    assert appie_mock.mock.last_call.params == {"query": "melk", "limit": 3}
+```
+
+Expected outcome:
+- the test runs without touching AH
+- the recorded call proves what your code sent into `python-appie`
 
 ## API overview
 
@@ -144,6 +206,7 @@ shopping-list add is implemented, but `get_list()`, `remove_item()`, and `clear(
 
 - `AHClient()`
 - `MockAHClient()`
+- `MockAHClient().mock`
 - `await client.login()`
 - `await client.graphql(query, variables=None)`
 
@@ -165,6 +228,17 @@ shopping-list add is implemented, but `get_list()`, `remove_item()`, and `clear(
 - `client.lists.remove_item(item_id)`
 - `client.lists.clear()`
 
+### Mock helpers
+
+- `client.mock.calls`
+- `client.mock.last_call`
+- `client.mock.clear_calls()`
+- `client.mock.next_response(operation, value)`
+- `client.mock.next_error(operation, exc)`
+- `client.mock.clear_seeded_responses()`
+- `client.mock.set_scenario(operation, delay_ms=0, error=None)`
+- `client.mock.clear_scenarios()`
+
 ## Development
 
 Run checks locally:
@@ -181,6 +255,6 @@ uv run --extra dev mkdocs build --strict
 
 - This client is unofficial and may break when Albert Heijn changes its backend.
 - Receipt support currently covers in-store POS receipts.
-- Shopping-list support only implements the verified add-item mutation; other operations raise explicit `NotImplementedError` until their GraphQL shape is confirmed.
+- Shopping-list read, add, remove, and clear are implemented against the live main-list endpoint.
 - Receipt summaries do not include line items; call `get_pos_receipt()` for a detailed receipt.
 - Endpoint discovery for this package is inspired by [gwillem/appie-go](https://github.com/gwillem/appie-go).

{python_appie-0.1.0 → python_appie-0.2.0}/docs/authentication.md

@@ -1,5 +1,7 @@
 # Authentication
 
+Language: **English** | [Nederlands](https://tijnschouten.github.io/appie/nl/authentication/)
+
 ## Login flow
 
 The package uses a browser-assisted login flow exposed through `appie-login`.
@@ -19,3 +21,5 @@ Access tokens are refreshed automatically when they are close to expiry. Under n
 
 - This is not an official AH integration.
 - AH may change login requirements at any time.
+
+Read next: [Products](products.md) for product search and product detail examples.

python_appie-0.2.0/docs/authentication.nl.md

@@ -0,0 +1,25 @@
+# Authenticatie
+
+Taal: [English](https://tijnschouten.github.io/appie/authentication/) | **Nederlands**
+
+## Loginflow
+
+De package gebruikt een browser-ondersteunde loginflow via `appie-login`.
+
+De CLI:
+
+- opent een Chrome-venster
+- wacht op de AH-redirect naar `appie://login-exit?code=...`
+- wisselt die code om voor tokens
+- slaat tokens op in `~/.config/appie/tokens.json`
+
+## Token-refresh
+
+Access tokens worden automatisch ververst vlak voor ze verlopen. Normaal gesproken hoef je `appie-login` alleen opnieuw te draaien als de refresh token niet meer geldig is.
+
+## Opmerkingen
+
+- Dit is geen officiële AH-integratie.
+- AH kan de loginvereisten op elk moment aanpassen.
+
+Lees verder: [Producten](products.md) voor productzoeken en productdetails.

python_appie-0.2.0/docs/cli.md

@@ -0,0 +1,20 @@
+# CLI
+
+Language: **English** | [Nederlands](https://tijnschouten.github.io/appie/nl/cli/)
+
+## `appie-login`
+
+Authenticate and store tokens locally:
+
+```bash
+uv run appie-login
+```
+
+The CLI is intended as a one-time or occasional setup step. Day-to-day usage should normally rely on stored tokens and automatic refresh.
+
+Expected outcome:
+- a Chrome window opens for login
+- the CLI captures the redirect code automatically
+- it prints a success message after storing tokens
+
+Read next: [Project History](history.md) for the original project brief and how the implementation evolved.

python_appie-0.2.0/docs/cli.nl.md

@@ -0,0 +1,20 @@
+# CLI
+
+Taal: [English](https://tijnschouten.github.io/appie/cli/) | **Nederlands**
+
+## `appie-login`
+
+Authenticeer en sla tokens lokaal op:
+
+```bash
+uv run appie-login
+```
+
+De CLI is bedoeld als een eenmalige of incidentele setupstap. Daarna hoort normaal gebruik op opgeslagen tokens en automatische refresh te leunen.
+
+Verwacht resultaat:
+- er opent een Chrome-venster voor login
+- de CLI vangt automatisch de redirectcode af
+- na het opslaan van tokens verschijnt een succesmelding
+
+Lees verder: [Projectgeschiedenis](history.md) voor de oorspronkelijke projectbrief en hoe de implementatie is geëvolueerd.

python_appie-0.2.0/docs/development.md

@@ -0,0 +1,44 @@
+# Development
+
+Language: **English** | [Nederlands](https://tijnschouten.github.io/appie/nl/development/)
+
+## Setup
+
+```bash
+uv sync --extra dev
+pre-commit install
+```
+
+Expected outcome:
+- a local virtual environment is created
+- development dependencies are installed
+- git hooks are installed for future commits
+
+## Quality checks
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run pyright
+uv run pytest
+uv run mkdocs build
+```
+
+Expected outcome:
+- formatting is applied cleanly
+- linting passes
+- type checking passes
+- tests pass with coverage
+- docs build successfully
+
+## Pre-commit
+
+This repository uses pre-commit hooks for:
+
+- `ruff format`
+- `ruff check`
+- `pyright`
+- `pytest`
+- `mkdocs build`
+
+Read next: [Home](index.md) to jump back to the documentation overview.

python_appie-0.2.0/docs/development.nl.md

@@ -0,0 +1,44 @@
+# Ontwikkeling
+
+Taal: [English](https://tijnschouten.github.io/appie/development/) | **Nederlands**
+
+## Setup
+
+```bash
+uv sync --extra dev
+pre-commit install
+```
+
+Verwacht resultaat:
+- er wordt een lokale virtual environment gemaakt
+- ontwikkeldependencies worden geïnstalleerd
+- git-hooks worden geïnstalleerd voor volgende commits
+
+## Quality checks
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run pyright
+uv run pytest
+uv run mkdocs build
+```
+
+Verwacht resultaat:
+- formatting wordt schoon toegepast
+- linting slaagt
+- type checking slaagt
+- tests slagen met coverage
+- docs bouwen succesvol
+
+## Pre-commit
+
+Deze repository gebruikt pre-commit hooks voor:
+
+- `ruff format`
+- `ruff check`
+- `pyright`
+- `pytest`
+- `mkdocs build`
+
+Lees verder: [Home](index.md) om terug te gaan naar het documentatieoverzicht.

{python_appie-0.1.0 → python_appie-0.2.0}/docs/getting-started.md

@@ -1,5 +1,7 @@
 # Getting Started
 
+Language: **English** | [Nederlands](https://tijnschouten.github.io/appie/nl/getting-started/)
+
 ## Install
 
 ```bash
@@ -28,6 +30,11 @@ uv run appie-login
 
 This opens Chrome and captures the AH login redirect code automatically. Tokens are stored in `~/.config/appie/tokens.json`.
 
+Expected outcome:
+- a browser window opens for AH login
+- after a successful login, tokens are stored locally
+- later package usage reuses those tokens automatically
+
 ## First request
 
 ```python
@@ -45,3 +52,13 @@ async def main() -> None:
 
 asyncio.run(main())
 ```
+
+Expected outcome:
+
+```text
+Product(id=...)
+Product(id=...)
+Product(id=...)
+```
+
+Read next: [Authentication](authentication.md) for token storage, refresh behavior, and re-login expectations.

python_appie-0.2.0/docs/getting-started.nl.md

@@ -0,0 +1,64 @@
+# Snelstart
+
+Taal: [English](https://tijnschouten.github.io/appie/getting-started/) | **Nederlands**
+
+## Installeren
+
+```bash
+uv add python-appie
+```
+
+Of:
+
+```bash
+pip install python-appie
+```
+
+Voor lokale ontwikkeling in deze repository:
+
+```bash
+uv sync --extra dev
+```
+
+## Inloggen
+
+Voer uit:
+
+```bash
+uv run appie-login
+```
+
+Dit opent Chrome, vangt automatisch de AH-redirectcode af en slaat tokens op in `~/.config/appie/tokens.json`.
+
+Verwacht resultaat:
+- er opent een browservenster voor de AH-login
+- na succesvolle login worden tokens lokaal opgeslagen
+- later hergebruikt de package die tokens automatisch
+
+## Eerste request
+
+```python
+import asyncio
+
+from appie import AHClient
+
+
+async def main() -> None:
+    async with AHClient() as client:
+        products = await client.products.search("melk", limit=3)
+        for product in products:
+            print(product)
+
+
+asyncio.run(main())
+```
+
+Verwacht resultaat:
+
+```text
+Product(id=...)
+Product(id=...)
+Product(id=...)
+```
+
+Lees verder: [Authenticatie](authentication.md) voor tokenopslag, refreshgedrag en opnieuw inloggen.