feat(python): emit response_type so generated calls deserialize into Pydantic models

[rob-archastro]

What changed

The Python backend now emits response_type=Model / list[Model] / hoisted inline BaseModel on every typed operation, in both sync and async resource classes, so generated return annotations are true at runtime (fixes firstlanding#6266; requires ArchAstro/archastro-python#20). One shared classifier (response-type.ts) drives the resource emitter and the contract-tests emitter — assertions and behavior cannot drift, the inline-model naming rule lives in one place, and generation fails loudly if a schema ref appears in a response shape the classifier doesn't deserialize. Contract tests assert concrete classes via type(result).__name__. Also fixes a latent bug the new validation exposed: fields named object shadow the builtin during pydantic's deferred annotation resolution (dict[str, object] silently became dict[str, None]); free-form types now emit typing.Any, with a repro-backed regression test.

sequenceDiagram
    participant S as OpenAPI spec
    participant RT as response-type classifier
    participant RE as resource emitter
    participant CE as contract-tests emitter
    S->>RE: OperationDef
    RE->>RT: pythonResponseTypeExpr(op)
    alt model or list shape
        RT-->>RE: expression like list of RoutinePreset
        RE->>RE: emit request call with response_type
    else ref buried in union or optional
        RT-->>RE: throws, generation fails
    end
    S->>CE: same OperationDef
    CE->>RT: pythonResponseShape(op)
    RT-->>CE: shape verdict
    CE->>CE: emit isinstance and class-name assertions

Loading

classDiagram
    class ResponseTypeModule {
        pythonResponseShape(op) Shape
        pythonResponseTypeExpr(op, inlineName) string
        pythonInlineResponseName(className, opName) string
    }
    class ResourceEmitter {
        emitOperation()
        emitSyncOperation()
    }
    class ContractTestsEmitter {
        emitResultAssertions()
    }
    ResourceEmitter ..> ResponseTypeModule : uses
    ContractTestsEmitter ..> ResponseTypeModule : uses

Loading

Scope: tooling-only (SDK generator); no service code.

Risk: low-medium — output changes are mechanical and were verified by full local regeneration (byte-identical to the committed archastro-python output) plus 1,720 passing contract tests. Merge order matters once: ArchAstro/archastro-python#20 must merge before this version is published to npm, since the regenerate workflow installs @latest.

User impact: none until published + regenerated; then Python SDK responses become typed models.

Testing: 254 generator unit tests (9 new emission tests, 5 contract-assertion tests, shadowing regression, fail-loud throw test).

Follow-ups: version bump + npm publish after merge (release-process owner's call). After publish, running Regenerate SDK on archastro-python should produce a zero diff — a free pipeline verification.

🤖 Generated with Claude Code

[archastro]

✅ Clean PR, @rob-archastro! No blocking findings on 93eb411 — a few nice things I clocked:

• Nice single-source-of-truth move on response-type.ts — one pythonResponseShape drives both the resource emitter's response_type= and the contract-tests emitResultAssertions, so deserialization behavior and assertions can't drift. 🎯
• Smart fail-loud guard: the classifier throws on a ref buried in an undeserialized union/optional shape (response-type.ts containsRef branch) so spec evolution can't silently reintroduce a return annotation the runtime never honors. ✨
• Solid red-green discipline on the object-shadowing fix — the repro test at python.test.ts:208 locks in dict[str, Any] over the dict[str, None] regression before the one-line emitter change. 🙌

---

_{Reply @archastro <verb>: review · do <pattern> · don't <pattern> · forget <slug> · list}