Merge FR-008 §2.3 — Python router_generator (FastAPI APIRouter)

NEW generator emits <entity_snake>_router.py per entity with source.rdb @kind=table:
- FastAPI APIRouter with prefix /api/<entity-plural>
- 5 verbs (GET list, GET by id, POST 201, PATCH+PUT, DELETE 204) matching
  the cross-port API contract
- ?limit=N&offset=N pagination (defaults 50/0)
- ?sort=<field>:asc|desc with module-level _SORT_ALLOWLIST + 400 envelope
- ?withCount=1 returns {"rows": ..., "total": N}; default returns bare list
- 404 envelope: {"error": "not_found"}
- Repository Protocol interface (consumer overrides via Depends + app.dependency_overrides)

Skip @kind=view (read-only) + @kind=storedProc (separate shape).

Deferred to KNOWN_GAPS.md: filter operators, int-PK assumption, dto=dict[str,Any]
(cross-file import threading needs per-target output-dir infrastructure Python
codegen doesn't have yet — DTO Protocol shape preserved).

5 new tests; codegen suite 29→34. Mypy strict-mode clean across all 21
codegen files + new test file. Generated output compiles cleanly under
Python 3.11+. Full Python suite green (modulo 1 pre-existing unrelated
doc-common-attrs failure).

Docs: api-contract.md Python row now shows "shipped"; ports/python.md
gains router-generator section + universal client (React/Angular) hookup note.

All 5 ports (TS / Java / Kotlin / C# / Python) now ship REST route codegen
conforming to the cross-port API contract. FR-008 §2.6 (cross-port
conformance corpus) is next.

Author: dmealing

docs/features/api-contract.md

@@ -170,7 +170,7 @@ retryable / log-only.
 | C# | shipped — `MetaObjects.Codegen` `RoutesGenerator` → ASP.NET Minimal API | `MapGet` / `MapPost` / `MapPut` / `MapDelete` mounted under `apiPrefix`; full CRUD. |
 | Java | shipped — `metaobjects-codegen-spring` `SpringControllerGenerator` + `SpringDtoGenerator` + `SpringRepositoryGenerator` → Spring `@RestController` (Spring Boot 3.x / Spring Web MVC) | One controller per writable entity (`source.rdb @kind="table"`); 5 CRUD endpoints (GET list / GET by id / POST / PATCH + PUT / DELETE); `?sort`, `?limit/?offset`, `?withCount=1` envelope, 404 + 400 envelopes per the contract. Java 21 record DTOs for request/response; a stubbed `<Entity>Repository` interface the consumer implements against their persistence layer (JPA / jOOQ / JDBC). Filter operators (`eq/ne/...`) deferred — see the module's `KNOWN_GAPS.md`. |
 | Kotlin | shipped — `metaobjects-codegen-kotlin` `KotlinSpringControllerGenerator` → Spring `@RestController` | One controller per writable entity (`source.rdb @kind="table"`); 5 CRUD endpoints (GET list / GET by id / POST / PATCH+PUT / DELETE); `?sort`, `?limit/?offset`, `?withCount=1` envelope, 404 + 400 envelopes per the contract. Filter operators (`eq/ne/...`) deferred. |
-| Python | planned | Hand-write a FastAPI router matching the URL grammar. Entity-model codegen ships; persistence + migration in progress. |
+| Python | shipped — `metaobjects.codegen.generators.router_generator` → FastAPI `APIRouter` | One router per writable entity (`source.rdb @kind="table"`); 5 CRUD endpoints (GET list / GET by id / POST / PATCH+PUT / DELETE); `?sort`, `?limit/?offset`, `?withCount=1` envelope, 404 + 400 envelopes per the contract. Consumer wires the repository via FastAPI `app.dependency_overrides`; the generator emits a `Protocol` interface so the persistence layer (SQLAlchemy / asyncpg / etc.) is the consumer's choice. Filter operators (`eq/ne/...`) deferred — see the module's `KNOWN_GAPS.md`. |
 
 ## Hand-writing a conforming controller
 

docs/ports/python.md

@@ -73,6 +73,62 @@ class Author:
     bio: Optional[str] = None
 ```
 
+The router generator emits one FastAPI `APIRouter` per writable entity
+(`source.rdb` with `@kind="table"`):
+
+```python
+# generated/acme/blog/author_router.py (excerpt)
+router = APIRouter(prefix="/api/authors", tags=["authors"])
+
+class AuthorRepository(Protocol):
+    def list(self, limit: int, offset: int, sort: _SortClause | None) -> list[Any]: ...
+    def count(self) -> int: ...
+    def find_by_id(self, id: int) -> Any | None: ...
+    def create(self, dto: Any) -> Any: ...
+    def update(self, id: int, dto: Any) -> Any | None: ...
+    def delete(self, id: int) -> bool: ...
+
+def get_repository() -> AuthorRepository:
+    raise NotImplementedError("Override get_repository via FastAPI dependency_overrides")
+
+@router.get("")  # list with ?limit / ?offset / ?sort / ?withCount=1
+@router.get("/{author_id}")
+@router.post("", status_code=status.HTTP_201_CREATED)
+@router.patch("/{author_id}")
+@router.put("/{author_id}")
+@router.delete("/{author_id}", status_code=status.HTTP_204_NO_CONTENT)
+```
+
+The router conforms to the cross-port API contract
+([`docs/features/api-contract.md`](../features/api-contract.md)):
+`?withCount=1` returns `{"rows", "total"}`; `?sort=field:asc|desc` uses
+a static per-entity allowlist (HTTP 400 envelope on unknown field); 404
+envelope is `{"error": "not_found"}`. Filter operators
+(`eq` / `ne` / ...) are a known gap — see
+[`server/python/src/metaobjects/codegen/KNOWN_GAPS.md`](../../server/python/src/metaobjects/codegen/KNOWN_GAPS.md).
+
+Wire the router into your consumer FastAPI app:
+
+```python
+from fastapi import FastAPI
+from acme.blog.author_router import router as author_router, get_repository
+from my_app.persistence import SqlAlchemyAuthorRepository
+
+app = FastAPI()
+app.include_router(author_router)
+app.dependency_overrides[get_repository] = lambda: SqlAlchemyAuthorRepository(session)
+```
+
+### Universal browser-client hookup (React / Angular 18)
+
+The router conforms to the same URL grammar as every other backend port,
+so the universal browser client — React/TanStack today, Angular 18 once
+FR-008 §2.5 lands — works against a FastAPI backend with no FastAPI-
+specific client code. The same generated TanStack hooks (or Angular
+services) that talk to a TS Fastify, Java Spring, Kotlin Ktor, or C#
+ASP.NET backend will talk to this FastAPI router; the only consumer
+wiring is the `EntityFetcher` base URL + auth.
+
 ## Use
 
 The loader API is symmetric with the other ports — `from_directory` /

server/python/src/metaobjects/codegen/KNOWN_GAPS.md

@@ -0,0 +1,72 @@
+# Python codegen — known gaps
+
+This document tracks deliberate Day-1 deferrals in the Python codegen
+(`metaobjects.codegen.generators`).
+
+## Filter operators (`eq` / `ne` / `gt` / `gte` / `lt` / `lte` / `in` / `like` / `isNull`)
+
+**Status:** deferred (`router_generator` only). Matches the Java / Kotlin / C#
+Day-1 deferral pattern.
+
+The cross-port REST API contract
+([`docs/features/api-contract.md`](../../../../../docs/features/api-contract.md))
+describes a bracketed query-string grammar (`filter[<field>][<op>]=<value>`)
+with eight operators, gated per field subtype. The TypeScript reference
+port ships full support via `parseFilterParams` in
+`@metaobjectsdev/runtime-ts/drizzle-fastify`.
+
+The Python `router_generator` does **not** parse this grammar at the
+router layer in Day 1. Only `sort`, `limit`, `offset`, and `withCount`
+are honoured. A request containing `filter[...]=...` parameters is
+currently silently ignored by the generated router. Consumers that need
+filter support today must add their own query-string handling via a
+FastAPI dependency that reads `request.query_params` and pass through to
+the repository.
+
+**When it ships:** a future `filter_allowlist_generator` will emit a
+static `<Entity>FilterAllowlist` per entity (mirroring TS Project D +
+the cross-port allowlist shape), and the generated `list_*()` handler
+will delegate to a `parse_filter_qs(qs, allowlist)` helper that returns
+either a Pydantic-validated filter object or a typed query-builder
+expression for the repository to apply.
+
+## Single-field, `int`-typed primary keys only
+
+**Status:** assumption baked into Day 1.
+
+The generated router assumes the entity's primary key is a single field
+of type `int` (the canonical `BaseEntity` convention across the shared
+corpus). The path-parameter type is hard-coded to `int` (e.g.
+`def get_author(author_id: int, ...)`); the `find_by_id` / `update` /
+`delete` repository methods take `id: int`.
+
+Composite PKs would require a URL grammar for composite ids
+(`/api/<entity>/{id_a}_{id_b}` or similar) that the cross-port contract
+has not yet specified. Entities with non-`int` single-field PKs (e.g.
+`UUID`) still generate, but the `: int` typing in the generated code
+will need a hand-edit until typed-PK threading lands in the generator.
+
+**Why deferred:** non-`int` PKs are uncommon and composite PKs are
+rarer still. Adding generic PK-type threading to the generator is a
+non-trivial spec change that should be discussed at the cross-port
+contract level first.
+
+## DTO equals `dict[str, Any]` (no separate request / response Pydantic models)
+
+**Status:** intentional Day-1 simplification.
+
+The generated router takes `dto: dict[str, Any]` for `POST` / `PATCH` /
+`PUT` request bodies and returns `Any` for responses. The repository
+`Protocol` likewise uses `Any` for the row type.
+
+This keeps the router module decoupled from sibling generated files
+(the entity-model generator emits one `@dataclass`/Pydantic model per
+entity in a separate file — wiring router→entity-model would require
+the path-resolution and import-base machinery that is not yet on the
+Python codegen surface). Consumers wanting strong typing can hand-edit
+the generated router to import their preferred entity shape.
+
+**When it ships:** once the Python codegen grows per-target output
+directories (mirroring the TS `targets` registry — see
+`@metaobjectsdev/cli` README), the router generator will emit
+`from .<snake>_entity import <Entity>` and use the entity type throughout.