Python First-Class DX Improvements

[hardbyte]

Context

The Python codegen generates production-quality clients — validated against Partly's core-server (284 endpoints, 59K-line generated client, live API authentication). This issue tracks remaining improvements to reach full TypeScript parity.

Completed

• Field descriptions — Field(description="...") propagated from schema
• Typed error returns — ApiResponse[OutputType, ErrorType] in method signatures
• Remove factory classes — direct construction via namespace types
• Remove testing utilities — generate_testing default changed to false
• SemanticSchema-driven codegen — type iteration and ordering via semantic IR
• Extensible PipelineBuilder — backends configure consolidation/naming/stages
• TypeVar collision resolution — _T_ prefix for colliding names
• Typed error deserialization — ApplicationError.typed_error as Pydantic model
• Typed list responses — list[Model] via TypeAdapter (was returning raw dicts)
• Fast JSON parsing — Pydantic's Rust-based validate_json(bytes)
• Compact enum representation — externally-tagged and adjacently-tagged enums use discriminated unions, reducing class count and boilerplate
• Name truncation — long generic class names truncated at 80 chars with hash suffix
• Stuttering removal — SystemSystem → System when module prefix matches type prefix
• Empty docstring removal — omit """Generated data model.""" when no description available
• Field name sanitization — underscore-prefix stripping, serde_name aliasing, keyword escaping
• Compact model_rebuild — single loop instead of N individual try/except blocks
• Externally-tagged serializer fix — r.field_0 instead of incorrect r.value for tuple variant fields

Remaining

1. Flattened generic fields silently dropped (P0 correctness)

When a struct has #[serde(flatten)] on a generic type parameter (e.g. IdentityData<I, D> where data: D is flattened), the Python codegen silently drops the field. This affects 11 generic types and 26 endpoints in core-server (9% of API). TypeScript handles this via intersection types (& NullToEmptyObject<D>); Python needs either monomorphization or a runtime flatten mechanism.

Affected types: IdentityData, InsertOrElse, RemoveOrElse, UpdateOrElse, nomatches::*

2. Reduce namespace bloat

402 namespace classes for core-server. Collapse single-type namespaces.

3. Sync/async runtime deduplication

~500 lines of identical sync/async code in runtime. Could use a shared implementation pattern.