Python target

Use the Python target for services, data tooling, or scripts that need generated model surfaces with load/save helpers.

emit-targets:
  - type: Python
    output-dir: "generated/python"
    test-dir: "generated/python/tests"
    import-path: "fixtures"
    protocol-scaffolds: "compile-only"
    native-serialization: "none"
    outputs:
      - kind: server
        provider: fastapi
      - kind: server
        provider: starlette
      - kind: consumer
        provider: httpx

Option	Why it matters
output-dir	Where generated Python modules are written.
test-dir	Where generated Python tests are written.
import-path	Module path used by generated tests.
protocol-scaffolds	Emits compile-only test scaffolds for generated protocols.
native-serialization	"none" keeps dataclass output. "pydantic" emits Pydantic v2 BaseModel types.
outputs	Optional generated surfaces. server:fastapi and server:starlette emit HTTP route factories; consumer:httpx emits contract clients backed by an injected async transport.

Generated Python surfaces include model surfaces, loader/saver helpers, JSON/YAML helpers, import-pruned output, and tests.

native-serialization: "pydantic" is opt-in and requires Pydantic v2 in the consuming Python environment. Typra still treats generated load() and save() as the authoritative contract surface: the Pydantic model_validate(), model_validate_json(), model_dump(), and model_dump_json() helpers delegate to those methods rather than introducing a second loader or serializer with different semantics. model_validate_strings() hard-fails because Pydantic’s string-coercing validation would not preserve Typra’s loader contract.

Typical usage shape

import json

from fixtures import FixtureRoot

root = FixtureRoot.load(json.loads(json_text))
saved = root.to_json()

Python models expose instance to_json() and to_yaml() helpers plus the static load() and instance save() methods. There is no from_json; parse the text yourself (for example with json.loads) and pass the parsed value to load().

Review generated tests for the exact helper names emitted by your selected contract and target options.

HTTP transport projections

outputs can request Python HTTP server and consumer surfaces from TypeSpec HTTP metadata:

outputs:
  - kind: server
    provider: fastapi
  - kind: server
    provider: starlette
  - kind: consumer
    provider: httpx

FastAPI and Starlette outputs emit route factories, AUTH_REQUIREMENTS metadata, and transport vector tests. The route factories bind path/query/header/cookie/body values, load request bodies through generated model helpers, call a handwritten handler protocol, and save model responses with the declared success status.

The httpx consumer output emits clients backed by an injected async transport. Generated methods serialize the TypeSpec HTTP request shape, include cookie bindings and auth requirements as metadata, require a declared success status before hydrating a response body, and raise TypraHttpxResponseError with the original status/body for non-matching or non-2xx responses. Typra does not attach credentials, manage cookie jars, retry requests, or enforce provider identity policy; those runtime behaviors stay in the host transport and server middleware.