dataceen-client 0.0.1__tar.gz

dataceen_client-0.0.1/.env.example

@@ -0,0 +1,17 @@
+# Copy to .env and fill in real values.
+# Mirrors the C# example's appsettings.json for CandyShopModel.
+
+DATACEEN_TENANT_ID=97dd913c-931e-44cf-96fd-a36270f7a465
+DATACEEN_CLIENT_ID=62e0cda5-a254-4498-b660-e00b98e83225
+DATACEEN_CLIENT_SECRET=replace-me
+
+DATACEEN_DOMAIN=Thomas
+DATACEEN_MODEL=CandyShopModel
+DATACEEN_SCOPE=All
+
+DATACEEN_API_URL=https://api.dataceen.com
+DATACEEN_API_PATH=/graphql
+DATACEEN_API_SCOPE=api://413b24f0-e191-4cf2-839d-3c9c75465ba2/.default
+
+DATACEEN_SUBSCRIPTION_URL=https://subscription.dataceen.com
+DATACEEN_SUBSCRIPTION_SCOPE=api://6982ac36-9f3e-4b60-9f17-6b078fd65ead/.default

dataceen_client-0.0.1/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to `dataceen-client` (Python) are documented here. Format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project loosely follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.1] — 2026-05-01
+
+Initial alpha — feature-parity with C# `DataceenClient` and TypeScript
+`@dataceen/client`, verified against the same model fixtures.
+
+### Added
+
+- **Core runtime** (`dataceen_client.*`)
+  - `DataceenConfig`, `DataceenClientOptions`, `load_config_from_env()`
+  - `DataceenError` — single error type for HTTP, GraphQL, parse, and server-side `ResponseCode != 0`
+  - `DataceenClient.execute_query()` (default retry on transient) and `execute_mutation()` (no retry by default)
+  - `TokenProvider` — Azure AD client-credentials via `msal`, with `force_refresh` simulated by `remove_tokens_for_client()`
+  - `HttpTransport` — `httpx.AsyncClient` POST with 401-refresh + transient retry (408/429/5xx, exponential backoff)
+  - Result `TypedDict`s: `FindResult[T]`, `SearchResult[T]`, `MutationResult`, …
+
+- **Runtime DSL helpers** (`dataceen_client.runtime.*`)
+  - Pure-dict DSL — `filter_to_graphql`, `order_by_to_graphql`, `collect_fields`
+  - `StringOps`, `NumberOps`, `BooleanOps`, `DateOps` — typed comparison-operator dicts
+  - `aggregation_fragment(depth)` — recursive Aggregations result expansion
+  - `do_find` / `do_search` / `do_create` / `do_create_bulk` / `do_update` / `do_update_bulk` / `do_delete` / `do_create_relation` / `do_create_relation_bulk`
+
+- **Codegen** (`tools/codegen/`)
+  - GraphQL introspection fetch + cache (`fetch_schema.py`, `parse_schema.py`)
+  - Per-entity emitters: read TypedDict, Create TypedDict, Update class with `__setattr__` change-tracking, Filter / SearchFilter, Fields, per-entity Client, AllClient
+  - Aggregation emitter — typed `Search<Entity>_aggregation` + `<Entity>AggregationDetails`
+  - CLI: `python -m tools.codegen.src.cli {fetch,emit ROOT,emit-all}` (also installable as `dataceen-codegen`)
+
+- **gRPC subscriptions** (`dataceen_client.subscriptions.*`)
+  - `Subscription` class with typed + low-level handlers, `asyncio.Event`-based cancel
+  - `grpc.aio` async stream open + Bearer-metadata auth
+  - Subscription manager with baseload semantics, exponential reconnect (max 10), synthetic CONNECTION_LOST/RECONNECTED events, slow-handler timing, central exception catch
+  - Pre-compiled proto stubs in `_pb/` (regenerable via `scripts/regenerate_proto.py`)
+
+- **Example app** — `examples/candy_shop/` ports the TS port's `examples/candy-shop/`. Read-only flows always run; create/update/delete gated by `RUN_DESTRUCTIVE=1`.
+
+- **Docs** — `docs/{plan,decisions,progress,dsl-comparison,porting-guide,release}.md`.
+
+### Test coverage
+
+88 unit tests, hermetic (~1.7s). Live-backend integration is opt-in via
+`RUN_INTEGRATION=1` once `.env` is configured.
+
+### Known gaps for v0.1
+
+- No live-backend smoke run yet (needs valid `.env`).
+- No published wheel — `python -m build` produces it locally.
+- Sphinx/MkDocs site not built; docstrings + `docs/*.md` are the source of truth.
+
+[Unreleased]: https://github.com/dataceen/dataceen-client-python/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/dataceen/dataceen-client-python/releases/tag/v0.0.1

dataceen_client-0.0.1/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2026 Dataceen AB.
+
+All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+modification, distribution, or use of this software, via any medium, is
+strictly prohibited without the express written permission of the copyright
+holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

dataceen_client-0.0.1/MANIFEST.in

@@ -0,0 +1,14 @@
+include README.md
+include CHANGELOG.md
+include LICENSE
+include .env.example
+recursive-include docs *.md
+recursive-include protos *.proto
+recursive-include src *.py *.pyi py.typed
+recursive-include tests *.py
+recursive-include tools *.py
+prune .venv
+prune dist
+prune build
+global-exclude __pycache__
+global-exclude *.py[cod]

dataceen_client-0.0.1/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: dataceen-client
+Version: 0.0.1
+Summary: Python client for Dataceen GraphQL + gRPC subscription APIs
+Author: Dataceen
+License: Proprietary
+Project-URL: Source, https://github.com/dataceen/dataceen-client-python
+Project-URL: Issues, https://github.com/dataceen/dataceen-client-python/issues
+Keywords: dataceen,graphql,grpc,client,azure-ad
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: msal>=1.28
+Requires-Dist: grpcio>=1.60
+Requires-Dist: protobuf>=4.25
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+Requires-Dist: grpcio-tools>=1.60; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# dataceen-client (Python)
+
+Python client for the Dataceen GraphQL + gRPC subscription APIs. Parallel to
+the C# (`DataceenClient/`) and TypeScript (`DataceenClientTs/`) reference
+clients — feature-parity verified against the same `Thomas/CandyShopModel/All`
+fixtures.
+
+> **Status:** 0.0.1 alpha. 88 unit tests green. Not yet on PyPI.
+
+## Install
+
+```sh
+python -m venv .venv
+.venv\Scripts\activate            # PowerShell
+pip install -e ".[dev]"
+```
+
+Requires Python 3.11+ (`typing.NotRequired`, generic `TypedDict`).
+
+## Configure
+
+Copy `.env.example` to `.env` at the repo root and fill in real Azure AD
+credentials. The example matches the C# `appsettings.json`'s `AllClient`
+section.
+
+## Quick start
+
+```python
+import asyncio
+from dataceen_client import DataceenClient, load_config_from_env
+from dataceen_client.runtime import do_find
+
+async def main():
+    cfg = load_config_from_env()
+    async with DataceenClient(cfg) as client:
+        result = await do_find(
+            client,
+            "Customer",
+            size=5,
+            filter={"CustomerId": {"like": "cst"}},
+            fields={
+                "_id": True,
+                "CustomerId": True,
+                "CustomerPlacedOrder": {"Order": {"OrderId": True}},
+            },
+            order_by=[{"CustomerId": "Ascending"}],
+        )
+        for item in result["Items"]:
+            print(item)
+
+asyncio.run(main())
+```
+
+After running codegen, replace `do_find(client, "Customer", ...)` with the
+typed `AllClient(client).Customer.find(...)`.
+
+## Subscriptions
+
+```python
+async with DataceenClient(cfg) as client:
+    sub = client.create_subscription(
+        topics=["Customer"],
+        baseload_topics=["Customer"],
+        start_mode="POSITION_BEGINNING",
+        include_complete=True,
+    )
+
+    async def on_customer(evt):
+        if evt.event_type == "BASELOAD_EVENT":
+            ...  # evt.complete is parsed JSON
+        elif evt.event_type == "SUBSCRIPTION_EVENT":
+            ...  # live event
+
+    sub.on("Customer", on_customer)
+    await client.subscribe(sub)   # blocks until sub.cancel()
+```
+
+## Codegen
+
+```sh
+python -m tools.codegen.src.cli fetch          # cache schema.json
+python -m tools.codegen.src.cli emit Customer  # Customer + everything it references
+python -m tools.codegen.src.cli emit-all       # whole model
+```
+
+Output → `src/dataceen_client/generated/` (gitignored). Per entity you get
+typed `TypedDict`s for read/create/filter/fields, a change-tracked `Update`
+class, and an `<Entity>Client` wrapping the runtime helpers; `AllClient`
+aggregates the top-level entities.
+
+Codegen runs from a source checkout — it is intentionally not part of the
+published wheel (only the runtime `dataceen_client` package is shipped).
+
+## Tests
+
+```sh
+pytest                       # 88 unit tests, ~1.7s
+RUN_INTEGRATION=1 pytest     # also run live-backend integration tests (needs .env)
+```
+
+## Example app
+
+End-to-end example against the live backend:
+
+```sh
+python -m examples.candy_shop.find
+python -m examples.candy_shop.search_and_aggregate
+python -m examples.candy_shop.subscriber
+python -m examples.candy_shop.program                    # full read-only orchestrator
+RUN_DESTRUCTIVE=1 python -m examples.candy_shop.program  # also create/update/delete
+```
+
+## Docs
+
+- `docs/plan.md` — phase plan
+- `docs/decisions.md` — decisions and motivation
+- `docs/progress.md` — live status
+- `docs/dsl-comparison.md` — why pure-dict DSL for Python
+- `docs/porting-guide.md` — Python-specific amendments to the canonical guide
+- `docs/release.md` — version-bump and publish runbook
+
+## License
+
+Proprietary — see [LICENSE](LICENSE).

dataceen_client-0.0.1/README.md

@@ -0,0 +1,124 @@
+# dataceen-client (Python)
+
+Python client for the Dataceen GraphQL + gRPC subscription APIs. Parallel to
+the C# (`DataceenClient/`) and TypeScript (`DataceenClientTs/`) reference
+clients — feature-parity verified against the same `Thomas/CandyShopModel/All`
+fixtures.
+
+> **Status:** 0.0.1 alpha. 88 unit tests green. Not yet on PyPI.
+
+## Install
+
+```sh
+python -m venv .venv
+.venv\Scripts\activate            # PowerShell
+pip install -e ".[dev]"
+```
+
+Requires Python 3.11+ (`typing.NotRequired`, generic `TypedDict`).
+
+## Configure
+
+Copy `.env.example` to `.env` at the repo root and fill in real Azure AD
+credentials. The example matches the C# `appsettings.json`'s `AllClient`
+section.
+
+## Quick start
+
+```python
+import asyncio
+from dataceen_client import DataceenClient, load_config_from_env
+from dataceen_client.runtime import do_find
+
+async def main():
+    cfg = load_config_from_env()
+    async with DataceenClient(cfg) as client:
+        result = await do_find(
+            client,
+            "Customer",
+            size=5,
+            filter={"CustomerId": {"like": "cst"}},
+            fields={
+                "_id": True,
+                "CustomerId": True,
+                "CustomerPlacedOrder": {"Order": {"OrderId": True}},
+            },
+            order_by=[{"CustomerId": "Ascending"}],
+        )
+        for item in result["Items"]:
+            print(item)
+
+asyncio.run(main())
+```
+
+After running codegen, replace `do_find(client, "Customer", ...)` with the
+typed `AllClient(client).Customer.find(...)`.
+
+## Subscriptions
+
+```python
+async with DataceenClient(cfg) as client:
+    sub = client.create_subscription(
+        topics=["Customer"],
+        baseload_topics=["Customer"],
+        start_mode="POSITION_BEGINNING",
+        include_complete=True,
+    )
+
+    async def on_customer(evt):
+        if evt.event_type == "BASELOAD_EVENT":
+            ...  # evt.complete is parsed JSON
+        elif evt.event_type == "SUBSCRIPTION_EVENT":
+            ...  # live event
+
+    sub.on("Customer", on_customer)
+    await client.subscribe(sub)   # blocks until sub.cancel()
+```
+
+## Codegen
+
+```sh
+python -m tools.codegen.src.cli fetch          # cache schema.json
+python -m tools.codegen.src.cli emit Customer  # Customer + everything it references
+python -m tools.codegen.src.cli emit-all       # whole model
+```
+
+Output → `src/dataceen_client/generated/` (gitignored). Per entity you get
+typed `TypedDict`s for read/create/filter/fields, a change-tracked `Update`
+class, and an `<Entity>Client` wrapping the runtime helpers; `AllClient`
+aggregates the top-level entities.
+
+Codegen runs from a source checkout — it is intentionally not part of the
+published wheel (only the runtime `dataceen_client` package is shipped).
+
+## Tests
+
+```sh
+pytest                       # 88 unit tests, ~1.7s
+RUN_INTEGRATION=1 pytest     # also run live-backend integration tests (needs .env)
+```
+
+## Example app
+
+End-to-end example against the live backend:
+
+```sh
+python -m examples.candy_shop.find
+python -m examples.candy_shop.search_and_aggregate
+python -m examples.candy_shop.subscriber
+python -m examples.candy_shop.program                    # full read-only orchestrator
+RUN_DESTRUCTIVE=1 python -m examples.candy_shop.program  # also create/update/delete
+```
+
+## Docs
+
+- `docs/plan.md` — phase plan
+- `docs/decisions.md` — decisions and motivation
+- `docs/progress.md` — live status
+- `docs/dsl-comparison.md` — why pure-dict DSL for Python
+- `docs/porting-guide.md` — Python-specific amendments to the canonical guide
+- `docs/release.md` — version-bump and publish runbook
+
+## License
+
+Proprietary — see [LICENSE](LICENSE).

dataceen_client-0.0.1/docs/decisions.md

@@ -0,0 +1,26 @@
+# Beslutade defaults — Python-port
+
+Logg av Python-specifika beslut. Server-imposed beslut (operatorernas casing,
+PascalCase-svar, `like`-semantik etc.) ärvs från
+`DataceenClientTs/docs/porting-guide.md` #19–47 och repeteras inte här.
+
+## 2026-05-01 — Projektstart
+
+| # | Beslut | Motivering |
+|---|---|---|
+| 1 | **Python 3.10+ som minimum** | `X | Y` union-syntax, `dict[str, T]`-generics, `match` om vi behöver. 3.10 är välsupporterat överallt. |
+| 2 | **Async-first API** (`httpx.AsyncClient`, `async def`) | Subscriptions är inneboende async (gRPC stream). Att blanda sync HTTP + async gRPC ger två kodvägar. Sync-wrapper kan adderas senare med `asyncio.run`. |
+| 3 | **`httpx` istället för `requests` + `aiohttp`** | Modern, sync+async i samma paket, native HTTP/2. Default-timeout, AbortController-motsvarighet via `httpx.Timeout`. |
+| 4 | **`msal` för Azure AD** | Officiell Microsoft-SDK, samma autentiseringsflöde som C# och TS. Har inbyggd token-cache. |
+| 5 | **DSL-strategi A (pure dict)** | Se `docs/dsl-comparison.md`. Python's `__getattr__`-proxies ger ingen typsäkerhet och försämrar IDE-stöd; idiomatisk Python är `TypedDict` + `dict`. |
+| 6 | **PascalCase i wire-typer** (`FindResult.Items`, `Customer._id`) | Matchar server-format 1:1. Att konvertera till snake_case skapar friktion vid paritet med C#/TS-dokumentation och GraphQL-strängar. Python-konsumenter får acceptera PascalCase-fält. |
+| 7 | **`pytest` + `pytest-asyncio` + `respx`** | De facto-standard för Python-testning. `respx` för HTTP-mockning matchar Vitest/MSW-rollen i TS-porten. |
+| 8 | **src-layout (`src/dataceen_client/`)** | Standardpraxis för moderna Python-paket; tvingar editable-installs att gå via paket-import istället för repo-rot. |
+| 9 | **`force_refresh` via `app.remove_tokens_for_client()` före re-acquire** | MSAL Python's `acquire_token_for_client` har ingen `skip_cache`-parameter. Cleanest workaround: rensa app-only-cachen före nytt anrop på 401. |
+| 10 | **Result-typer som `TypedDict` (total=False)** | PascalCase-nycklar bevarade. Pydantic kan komma som opt-in senare; `TypedDict` är dependency-free och räcker för read-modeller. |
+
+## Öppna frågor
+
+- Sync-wrapper-API (`DataceenClientSync`)? Beslut tas i fas 6 om exempelappen visar att det behövs.
+- `dataclass` vs `TypedDict` vs `pydantic.BaseModel` för genererade entitet-typer? Tas i fas 3.
+- gRPC-stub-generering: `grpc_tools.protoc` mot `dataceenevent.proto` i build-steg eller checkat in? Tas i fas 4.

dataceen_client-0.0.1/docs/dsl-comparison.md

@@ -0,0 +1,125 @@
+# DSL-jämförelse — Python-port
+
+**Datum:** 2026-05-01
+**Beslut:** Strategi A (pure dict / objekt-literal) — för **alla tre** delar
+(filter, fields, orderBy).
+
+Detta avviker från TS-porten som valde C (hybrid: dict-filter, proxy-fields).
+Motiveringen följer.
+
+---
+
+## Use-case
+
+Hämta 10 kunder vars `CustomerId` matchar `cst` OCH vars status är antingen
+`Active` eller `Premium`. Returnera `_id`, `CustomerId`, `ExternalReference`
+plus nästlad relation `CustomerPlacedOrder -> Order -> OrderId`. Sortera på
+`CustomerId Ascending, ExternalReference Descending`.
+
+```python
+await api.Customer.find(
+    size=10,
+    filter={
+        "and": [
+            {"CustomerId": {"like": "cst"}},
+            {
+                "or": [
+                    {"Status": {"eq": "Active"}},
+                    {"Status": {"eq": "Premium"}},
+                ],
+            },
+        ],
+    },
+    fields={
+        "_id": True,
+        "CustomerId": True,
+        "ExternalReference": True,
+        "CustomerPlacedOrder": {
+            "Order": {"OrderId": True},
+        },
+    },
+    order_by=[
+        {"CustomerId": "Ascending"},
+        {"ExternalReference": "Descending"},
+    ],
+)
+```
+
+---
+
+## Varför inte proxy-lambda för fields (som TS)?
+
+Två separata problem på Python-sidan.
+
+### 1. Typchecker-stöd är sämre
+
+`__getattr__` returnerar `Any` som default. mypy/pyright kan inte härleda
+strukturen `f.CustomerPlacedOrder(lambda r: r.Order(...))` utan att vi skriver
+overloadade `__getattr__`-stubbar per fält per entitet — vilket gör att hela
+"proxy-elegansen" är beroende av codegen som ändå producerar lika mycket TS-typ-kod.
+
+I TS funkar `FieldsProxy<T>` mapped types med konditionella inferens som faktiskt
+ger autocomplete. Pythons typsystem har inga conditional types av motsvarande styrka.
+
+### 2. Statement-as-expression-mönstret är inte idiomatiskt
+
+TS-porten skriver `f._id; f.CustomerId;` som hängande identifiers. Python tillåter
+det syntaktiskt men är ovanligt; rinter och kollegor kommer att fråga "är det
+en bug?". Lambdor på flera rader är dessutom inte tillåtet utan att gå via en
+named function — vilket eliminerar lambda-syntaxens läsbarhetsfördel.
+
+---
+
+## Varför inte builders med method-chaining?
+
+```python
+# Avfärdat
+filter = (FilterBuilder[Customer]()
+          .where("CustomerId").like("cst")
+          .and_(FilterBuilder().where("Status").eq("Active")
+                .or_(FilterBuilder().where("Status").eq("Premium"))))
+```
+
+- Verbose i Python (måste returnera `self` på varje metod).
+- Ger inte bättre typstöd än dict + `TypedDict`.
+- Lägger till en abstraktion som måste serialiseras tillbaka till samma struktur
+  som dict-input ändå producerar.
+
+---
+
+## Vad pure dict ger
+
+- **Typsäkert via `TypedDict`** (genereras i fas 3): `CustomerFilter` är en
+  `TypedDict` per fält → IDE flaggar tryckfel direkt.
+- **Triviell serialisering:** `filter_to_graphql(d)` är ren rekursion över strukturen.
+- **Trivial codegen:** generatorn emit:ar bara typaliasar — inga runtime-byggare per entitet.
+- **Lätt att kopiera mellan språk:** samma struktur fungerar i JSON, vilket är
+  praktiskt vid debug.
+
+---
+
+## Korrelationer mot porting-guide
+
+`DataceenClientTs/docs/porting-guide.md` rekommenderar för Python:
+> Object-literal (dict) for everything. `__getattr__`-proxies are ergonomic
+> but trip static type checkers.
+
+Detta beslut följer rekommendationen.
+
+---
+
+## Konsekvenser för fas 3 (generator)
+
+Per entitet emit:ar generatorn bara *typer* (`TypedDict`):
+
+1. `Customer` (read-model)
+2. `CustomerCreate` (create-input)
+3. `CustomerUpdate` (klass med `__setattr__`-tracking)
+4. `CustomerFilter` (filter-input)
+5. `CustomerSearchFilter` (separat — inkluderar relationer)
+6. `CustomerOrderBy = list[dict[Literal[...field names...], OrderByDirection]]`
+7. `CustomerFields = TypedDict` (rekursivt)
+
+Runtime-helpers (`filter_to_graphql`, `order_by_to_graphql`, `collect_fields`,
+`do_find`, `do_search`, `do_create`, …) delas mellan alla entiteter — skrivs
+en gång i `dataceen_client/runtime/`.

dataceen_client-0.0.1/docs/plan.md

@@ -0,0 +1,143 @@
+# Plan: portera Dataceen-klienten till Python
+
+Parallell-klient-strategi: Python-klienten samexisterar med C#- och TS-klienterna,
+ersätter dem inte. Tredje officiella språkporten efter `DataceenClient/` (C#) och
+`DataceenClientTs/` (TypeScript).
+
+## Förutsättningar (beslutade defaults)
+
+| Fråga | Beslut |
+|---|---|
+| Målversion | Python 3.10+ (typ-syntax `X | Y`, `dict[...]`) |
+| Beroenden | `httpx` (HTTP), `msal` (Azure AD), `grpcio` + `protobuf` (subscriptions, optional) |
+| Async-modell | `asyncio` — primär API är `async def` |
+| Test-ramverk | `pytest` + `pytest-asyncio` + `respx` (HTTP mocking) |
+| Repo-struktur | Eget paket under `C:\Source\Dataceen\DataceenClientPython\` |
+| PyPI-namn | `dataceen-client` (tentativt) |
+| Källlayout | `src/dataceen_client/` (src-layout) |
+| Auth | Client-credentials via `msal.ConfidentialClientApplication` |
+| DSL-strategi | **A — pure dict (objekt-literal)**. Se `docs/dsl-comparison.md`. |
+| Typing | `TypedDict` + Pydantic v2 valbart i framtida fas; v1 levererar `dict`-baserade signaturer |
+
+## Komponentmappning C#/TS → Python
+
+| C# / TS-komponent | Python-motsvarighet | Svårighet |
+|---|---|---|
+| `DataceenClient` (GraphQL över HTTP) | `httpx.AsyncClient` | Lätt |
+| `DataceenClient` subscriptions (gRPC) | `grpcio` (async stub) | Medel |
+| `TokenProvider` (MSAL) | `msal.ConfidentialClientApplication` | Lätt |
+| `FilterBuilder<T>` / object-literal-filter | `dict` med typade `TypedDict`-aliaser | Lätt |
+| `OrderByBuilder<T>` / array | `list[dict[str, Literal["Ascending","Descending"]]]` | Trivialt |
+| `FieldsBuilder<T>` / proxy-lambda | Nested `dict`: `{"_id": True, "Order": {"OrderId": True}}` | Lätt |
+| `CustomerUpdate` med ändringsspårning | Klass med `__setattr__`-hook + `_changed: set[str]` | Medel |
+| `FindResult<T>`, `SearchResult<T>`, `MutationResult` | `TypedDict` (PascalCase för wire-paritet) | Trivialt |
+| Genererad `AllClient` | Codegen i fas 3+ — emit:ar `.py`-moduler från GraphQL-introspection | Stort men rakframt |
+| `EventHandlerList` + typade delegates | `dict[type, list[Callable]]` | Lätt |
+| `PostGraphQLAsync` (retry/auth) | Custom retry-loop runt `httpx` | Lätt |
+
+## Fasplan
+
+Följer samma faser som TS-porten enligt `DataceenClientTs/docs/porting-guide.md`.
+
+### Fas 0 — Spike (1–2 dagar)
+- Token via `msal.ConfidentialClientApplication.acquire_token_for_client`
+- GraphQL POST mot `apiUrl`
+- gRPC subscription-stream mot `subscriptionUrl`
+- Introspection POST → cacha `tools/codegen/cache/schema.json`
+
+### Fas 1 — Kärn-runtime (3–5 dagar) — **denna sessionen**
+Generisk `DataceenClient`-kärna utan typgenerering.
+
+```
+src/dataceen_client/
+  __init__.py
+  config.py              # DataceenConfig dataclass + load_config_from_env()
+  errors.py              # DataceenError
+  types.py               # FindResult, SearchResult, MutationResult (TypedDict)
+  token_provider.py      # TokenProvider (MSAL)
+  http_transport.py      # HttpTransport.post_graphql() — 401-refresh + retry
+  dataceen_client.py     # DataceenClient.execute_query/execute_mutation
+  runtime/
+    filter.py            # filter_to_graphql()
+    order_by.py          # order_by_to_graphql()
+    fields.py            # collect_fields()
+    aggregations.py      # aggregation_fragment(depth)
+    operations.py        # do_find / do_search / do_create / do_update / do_delete
+```
+
+### Fas 2 — DSL-prototyper + beslut (1 dag)
+**Beslut redan taget:** strategi A (pure dict). Python's typcheckare har svårt med
+proxy-attribute-access utan att tappa typsäkerhet. Dict + `TypedDict` är det
+idiomatiska valet. Prototyparbete behövs alltså inte — kort dokumentation i
+`docs/dsl-comparison.md`.
+
+### Fas 3 — Kodgenerator v1 (1–2 veckor)
+Generera typade `.py`-filer per entitet från GraphQL-introspection.
+
+```
+tools/codegen/
+  src/
+    fetch_schema.py
+    parse_schema.py
+    emit_model.py
+    emit_filter.py
+    emit_create.py
+    emit_update.py
+    emit_client.py
+    cli.py
+```
+
+Output i `src/dataceen_client/generated/`.
+
+### Fas 4 — Subscriptions (3–5 dagar)
+gRPC-baserad subscription-klient med baseload-semantik.
+
+```
+src/dataceen_client/subscriptions/
+  __init__.py
+  types.py
+  subscription.py
+  subscription_manager.py
+  grpc_client.py
+```
+
+### Fas 5 — Full modell (3–5 dagar)
+Alla 9 noder + 18 relationer + ~12 sub-entiteter för CandyShopModel. Compound
+mutations (`Create{From}{Rel}{To}`) + aggregations.
+
+### Fas 6 — Exempel-app (3–5 dagar)
+Port av `examples/candy-shop/` från TS:
+
+```
+examples/candy_shop/
+  config.py
+  program.py
+  find.py
+  search_and_aggregate.py
+  subscriber.py
+  create.py / update.py / delete.py
+  handlers/
+```
+
+### Fas 7 — Paketering & release (2–3 dagar)
+- `dataceen-client` på PyPI
+- Sphinx-dokumentation (eller MkDocs)
+- CI: GitHub Actions
+
+## Kritiska beslutpunkter
+
+| # | Beslut | Status |
+|---|---|---|
+| 1 | Parallell eller ersättande klient? | Parallell ✅ |
+| 2 | Sync- eller async-API? | Async-first (`httpx.AsyncClient`); sync-wrapper kan läggas till senare |
+| 3 | DSL-strategi | A (pure dict) ✅ — Python type-checkers fungerar bäst med strukturerad data |
+| 4 | Schemakälla för generator | GraphQL introspection (samma som TS) |
+| 5 | Validering av inputs | Lazy: `dict` skickas direkt; runtime-fel kommer från servern. Pydantic-overlay valbart senare. |
+| 6 | Pydantic-modeller? | Optional opt-in i fas 3 — kan emit:as parallellt med `TypedDict` |
+
+## Referensfiler
+
+- `C:\Source\Dataceen\DataceenClient\` — C#-klienten (kanonisk)
+- `C:\Source\Dataceen\DataceenClientTs\` — TS-klienten (verifierad mot live)
+- `C:\Source\Dataceen\DataceenClientTs\docs\porting-guide.md` — kanonisk porting-guide
+- `C:\Source\Dataceen\DataceenEvent\Protos\dataceenevent.proto` — gRPC-kontrakt