Skip to content

Redocly/redocly-cli / packages/client-generator/eject-assets/skills/python-generator

python-generator

Unverified

Design of the ejected Redocly `python` client generator. Read it, and update it, before changing generators/python/.

The python generator — its skill

This file is the DESIGN of your ejected python generator (generators/python/): to change the generator, edit this skill first, then make the code match it — a diff to generators/python/ that has no covering sentence here is incomplete.

What it emits

One self-contained <stem>.py: typed dataclass models, a sync Client and an async AsyncClient, and the embedded runtime. Python ≥ 3.9; the only dependency is httpx (pip install httpx).

Design decisions that must hold

  • The file name is an importable module name. The --output stem follows the TypeScript convention (openapi.client.ts), and openapi.client.py cannot be imported by name — nor can hyphens or a leading digit. The stem is converted with identifierFor(stem, snake), so rebilly-core.client.ts emits rebilly_core_client.py and import rebilly_core_client just works.

  • Models are dataclasses by default, required fields first (a dataclass constraint), optionals Optional[T] = None. Wire names live in a _field_map: ClassVar[Dict[str, str]]; decode/encode is reflective (_decode.py, get_type_hints) — no per-model codecs.

  • The file passes mypy --strict. It lands in the user's own package, so their strictest checker reads it: every function is annotated, the operation table is typed, and a decoded body is cast to the declared return type (decode returns Any).

  • A writeOnly property is optional even when required: requests and responses share one model, and a response never carries it. It is Optional[T] = None, so a response decodes without it and a request still sends it.

  • models: pydantic emits BaseModel classes instead, for the FastAPI-shaped half of the ecosystem that expects them. A wire name becomes Field(alias=…) with populate_by_name=True, so _field_map is not emitted in this mode — the alias is the mapping. Everything else is unchanged: the same class names, the same field names, the same Optional[T] = None, the same enums and union aliases, the same client and runtime. Switching modes must not change a call site.

  • A discriminated union carries its discriminator into the pydantic annotation. The decoder hands a whole object tree to model_validate, so a union nested in a model is resolved by pydantic and never reaches the DISCRIMINATORS table that dataclass mode walks. Pydantic resolves it correctly from Annotated[Union[...], Field(discriminator=…)], which it accepts only when every member types that property as a Literal — and the mapping already pins one value per member, so the members get Literal["cat"]. Such a union registers no table entry: pydantic owns it at every depth, and the Literal makes the decoder's member probe exact. A union whose members never declare the property keeps the plain Union and the table entry, and pydantic then matches nested members its own way — the description is what has to change there.

  • One runtime serves both model modes. _decode.py dispatches on the target: a class with model_validate is validated by pydantic, a dataclass is hydrated reflectively, and encode mirrors that with model_dump(by_alias=True, exclude_none=True, mode="json"). A second runtime variant per mode would double the surface that has to stay in step, and pydantic's ValidationError already subclasses ValueError, so union member probing needs no new except clause.

  • models: pydantic adds a dependency, and the header says so. The default mode keeps httpx as the only requirement; the pydantic header asks for both. A mode that quietly needed a package the file never named would fail at import with nothing to act on.

  • Every parameter is its own argument, so their names share one namespace with the arguments the method declares itself (body, headers, timeout, retry, idempotency_key). Build them with uniqueIdentifiers(..., { taken: … }): OpenAPI lets one operation use a name in two locations (id in the path AND in the query), and a def that declared one name twice is a SyntaxError. The wire name is untouched, so the request is unchanged.

  • Naming: fields/methods snake*case via identifierFor(..., RESERVED_WORDS.python); reserved words get a trailing underscore (class*); +1/-1becomeplus_1/minus_1.

  • Enums are class X(str, Enum) with SCREAMING members; unions are Union[...] aliases, emitted after the classes and the other aliases they name, because a module-level assignment evaluates at import. A DISCRIMINATED union registers its dispatch table in the runtime's DISCRIMINATORS registry (DISCRIMINATORS[Pet] = ("petType", {"cat": Cat, ...})), and decode() routes through it — isinstance narrowing works on decoded members. Undiscriminated unions decode by trying each member in order (the first that hydrates wins — see _decode.py). allOf is flattened via flattenAllOf.

  • Auth keys match the other languages. auth={"apiKey": {...}} is the documented key — the same spelling TypeScript and PHP use, and the same as the scheme kind — with api_key accepted as an alias so a snake_case config keeps working.

  • Errors: errorMode maps to raising ApiError (default) or returning a Result dataclass — the only generator with both modes outside TypeScript.

  • Dates: dateType: Date annotates format: date-time as datetime and date as date; _decode.py parses ISO strings into them and encode() writes isoformat() back. The default (string) keeps the wire shape.

  • Response headers: an operation that DECLARES success-response headers gains a <op>_with_headers() variant (sync and async) returning Envelope[T] — data, headers (coerced to int/bool/str with snake_case keys; absent/unparsable values omitted), and the raw response. Operations without declared headers get no variant, and the base method stays body-only.

  • Servers: when the description declares servers, a Servers class is emitted with one static method per server; server VARIABLES become keyword arguments defaulting to the spec's defaults (Servers.production(organization_id="org_x")), so templated base URLs need no manual string building. The client's baked default stays servers[0] with variable defaults substituted.

  • Stream bodies pass through. For an untyped multipart/form-data operation (isUntypedMultipartBody) or a binary operation (isBinaryContentType), the body argument is Any, and a body that is bytes/bytearray, a str, a file-like object (a callable .read), or an iterator/async iterator of bytes goes to httpx content=, never through json= or to_multipart; a dict body of an untyped multipart operation keeps the to_multipart path. The runtime sets the operation's declared content type only when the caller set none (matched case-insensitively), and never for a multipart body, whose boundary is the caller's. A body that cannot be replayed (a file-like object or iterator, as opposed to bytes or str) is sent in exactly one attempt, whatever the retry policy says. The per-attempt timeout still applies. Both the sync and the async send behave the same. Typed multipart bodies are unaffected: they go straight to to_multipart and never through stream detection, so a model field named read cannot turn one into a raw upload.

  • Parity surface: auth (bearer/basic/apiKey), retries with Retry-After + jittered backoff, timeouts, idempotency keys, middleware, pagination (<op>_pages() / <op>_items() + aiter mirrors), SSE (iter_sse/aiter_sse), multipart.

  • The runtime is hand-written in runtime/*.py in this folder and embedded as strings at prepare time — generator code never builds runtime logic from templates. Under --runtime module the same sources are written as sibling _*.py files instead (package-relative imports become sibling imports; the client star-imports each module).

  • on_settled sees every sent call once. Both send() and send_async() call each middleware's on_settled(context, call) after the last attempt, where call holds the final response or the error, attempts, and duration_ms (from the first attempt to the end of the on_response hooks). A timeout is ApiTimeoutError; a cancelled async call is asyncio.CancelledError. A call that fails in on_request does not reach it. Every hook runs; on a successful call the first hook exception fails the call, and on a failed call the original error wins. SSE streams open outside send(), so they reach no middleware.

  • Telemetry is opt-in at generation time. With client.telemetry: on the generator also writes <module>_telemetry.py (from telemetry/telemetry.py in this folder, embedded at prepare time) beside the client, in both runtime modes, with the generator version baked in. The client file does not change. The module imports nothing from the client; the application passes telemetry(sdk_name=..., sdk_version=..., client=...) in the client's middleware, and the open window is sent at interpreter exit. A timeout of the caller, such as asyncio.wait_for, cancels the task like any cancel, so it counts as aborted; only the client's own timeout counts as timeout.

  • Authored ONLY with the neutral toolkit (Printer, naming, schema, pagination helpers) — the dogfooding guard fails otherwise.

  • It documents itself. With client.docs (or --docs), the docs hook writes <stem>.python.md: the security schemes, then one section per operation with its parameters, body, response type, and behavior notes. The call snippets come from this generator's own sample hook, so the page can only show the syntax of the SDK beside it, and the layout comes from renderReferencePage in the authoring toolkit — reachable from an ejected copy through @redocly/client-generator. Pagination on the page is decided by paginationRuleFor, the same helper this generator resolves pagination with.

The modify loop

  1. Edit this skill: state the new behavior or decision.
  2. Make generators/python/ match it.
  3. Run redocly generate-client and inspect the git diff of the generated output — generated files are never hand-edited.

Newer built-in versions merge in with redocly eject-generator python --update.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall