@graphql-codegen/python 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @graphql-codegen/python
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A **schema-driven** [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) plugin that
+emits **Python base types** from a `GraphQLSchema`:
+
+- object & interface types → [pydantic](https://docs.pydantic.dev) `BaseModel` classes (snake_case
+  attributes; keys that differ from the GraphQL name are pinned with `Field(alias=...)` +
+  `model_config = ConfigDict(populate_by_name=True)`)
+- input types → `TypedDict`
+- enums → `class X(str, Enum)`
+- scalars → native Python (`ID`/`String` → `str`, `Int` → `int`, `Float` → `float`, `Boolean` →
+  `bool`, custom → `Any`)
+
+It is the base-types counterpart to `@graphql-codegen/python-operations`, analogous to how
+`typescript` underpins `typescript-operations`.
+
+## Config
+
+| Option             | Type                    | Default       | Description                                                                                                                                   |
+| ------------------ | ----------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseModel`        | `string`                | `'BaseModel'` | Base class the generated object/interface types extend.                                                                                       |
+| `runtimeImport`    | `string`                | `'pydantic'`  | Module the base model is imported from (`from {runtimeImport} import {baseModel}`, with `ConfigDict`/`Field` appended when aliases are used). |
+| `namingConvention` | `'keep' \| 'snakeCase'` | `'snakeCase'` | How field names become attributes (`snakeCase` converts and pins renamed keys with `Field(alias=...)`).                                       |

package/dist/README.md

@@ -0,0 +1,23 @@
+# @graphql-codegen/python
+
+A **schema-driven** [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) plugin that
+emits **Python base types** from a `GraphQLSchema`:
+
+- object & interface types → [pydantic](https://docs.pydantic.dev) `BaseModel` classes (snake_case
+  attributes; keys that differ from the GraphQL name are pinned with `Field(alias=...)` +
+  `model_config = ConfigDict(populate_by_name=True)`)
+- input types → `TypedDict`
+- enums → `class X(str, Enum)`
+- scalars → native Python (`ID`/`String` → `str`, `Int` → `int`, `Float` → `float`, `Boolean` →
+  `bool`, custom → `Any`)
+
+It is the base-types counterpart to `@graphql-codegen/python-operations`, analogous to how
+`typescript` underpins `typescript-operations`.
+
+## Config
+
+| Option             | Type                    | Default       | Description                                                                                                                                   |
+| ------------------ | ----------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseModel`        | `string`                | `'BaseModel'` | Base class the generated object/interface types extend.                                                                                       |
+| `runtimeImport`    | `string`                | `'pydantic'`  | Module the base model is imported from (`from {runtimeImport} import {baseModel}`, with `ConfigDict`/`Field` appended when aliases are used). |
+| `namingConvention` | `'keep' \| 'snakeCase'` | `'snakeCase'` | How field names become attributes (`snakeCase` converts and pins renamed keys with `Field(alias=...)`).                                       |

package/dist/cjs/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plugin = void 0;
+const tslib_1 = require("tslib");
+const plugin_helpers_1 = require("@graphql-codegen/plugin-helpers");
+const visitor_js_1 = require("./visitor.js");
+tslib_1.__exportStar(require("./config.js"), exports);
+tslib_1.__exportStar(require("./visitor.js"), exports);
+const plugin = (schema, _documents, config) => {
+    const astNode = (0, plugin_helpers_1.getCachedDocumentNodeFromSchema)(schema);
+    const visitor = new visitor_js_1.PythonVisitor(schema, config);
+    const visitorResult = (0, plugin_helpers_1.oldVisit)(astNode, { leave: visitor });
+    const content = visitorResult.definitions
+        .filter((def) => typeof def === 'string' && def.length > 0)
+        .join('\n\n\n');
+    return {
+        prepend: visitor.getImports(content),
+        content,
+    };
+};
+exports.plugin = plugin;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/visitor.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythonVisitor = exports.PYTHON_SCALARS = void 0;
+const tslib_1 = require("tslib");
+const auto_bind_1 = tslib_1.__importDefault(require("auto-bind"));
+const python_common_1 = require("@graphql-codegen/python-common");
+Object.defineProperty(exports, "PYTHON_SCALARS", { enumerable: true, get: function () { return python_common_1.PYTHON_SCALARS; } });
+const visitor_plugin_common_1 = require("@graphql-codegen/visitor-plugin-common");
+const INDENT = '    ';
+class PythonVisitor extends visitor_plugin_common_1.BaseTypesVisitor {
+    constructor(schema, pluginConfig) {
+        // `namingConvention` here is our own field-naming option (`'keep'` |
+        // `'snakeCase'`) and must NOT leak into the base visitor's `namingConvention`
+        // (which controls TYPE-name conversion via `convertFactory`). Strip it before
+        // calling `super` so type names keep their default (PascalCase) conversion.
+        super(schema, 
+        // Route custom scalars (no explicit mapping) to `Any` instead of `unknown`.
+        {
+            ...pluginConfig,
+            namingConvention: undefined,
+            defaultScalarType: (0, visitor_plugin_common_1.getConfigValue)(pluginConfig.defaultScalarType, 'Any'),
+        }, {
+            baseModel: (0, visitor_plugin_common_1.getConfigValue)(pluginConfig.baseModel, 'BaseModel'),
+            runtimeImport: (0, visitor_plugin_common_1.getConfigValue)(pluginConfig.runtimeImport, 'pydantic'),
+            pyNamingConvention: (0, visitor_plugin_common_1.getConfigValue)(pluginConfig.namingConvention, 'snakeCase'),
+        }, python_common_1.PYTHON_SCALARS);
+        this._usesEnum = false;
+        this._usesTypedDict = false;
+        this._usesBaseModel = false;
+        this._usesUnion = false;
+        (0, auto_bind_1.default)(this);
+    }
+    /** Python has no `export` keyword; disable the C-family export prefix. */
+    getExportPrefix() {
+        return '';
+    }
+    _getScalar(name, type) {
+        const mapped = this.scalars[name];
+        if (mapped) {
+            return mapped[type];
+        }
+        return 'Any';
+    }
+    // --- Nullability / list composition (emit Python instead of TS) ---
+    NamedType(node, key, parent, path, ancestors) {
+        return `Optional[${super.NamedType(node, key, parent, path, ancestors)}]`;
+    }
+    ListType(node, key, parent, path, ancestors) {
+        return `Optional[${super.ListType(node, key, parent, path, ancestors)}]`;
+    }
+    wrapWithListType(str) {
+        return `list[${str}]`;
+    }
+    NonNullType(node) {
+        const baseValue = super.NonNullType(node);
+        if (baseValue.startsWith('Optional[') && baseValue.endsWith(']')) {
+            return baseValue.slice('Optional['.length, -1);
+        }
+        return baseValue;
+    }
+    // --- Field rendering (name: 'annotation') ---
+    snakeFieldName(name) {
+        return (0, python_common_1.pythonFieldName)(name);
+    }
+    /**
+     * Field key for a `TypedDict` (input type). Input types are what the caller
+     * SENDS — the runtime forwards the dict to the server as-is — so they ALWAYS
+     * keep the wire (GraphQL) name regardless of `namingConvention`. If the name
+     * is a keyword / non-identifier the containing `TypedDict` is later emitted
+     * with functional syntax (see `buildTypedDict`).
+     */
+    dictFieldName(name) {
+        return name;
+    }
+    /**
+     * Field key for an object / interface type (a class attribute). Under `'keep'`
+     * a keyword / non-identifier name cannot be a class attribute and BaseModel
+     * cannot use functional `TypedDict` syntax, so we fall back to appending `_`
+     * for just that field.
+     */
+    objectFieldName(name) {
+        if (this.config.pyNamingConvention === 'snakeCase') {
+            return this.snakeFieldName(name);
+        }
+        return (0, python_common_1.isValidClassAttr)(name) ? name : `${name}_`;
+    }
+    FieldDefinition(node) {
+        if (this.config.onlyEnums)
+            return '';
+        const wire = node.name.value;
+        const attr = this.objectFieldName(wire);
+        // The rendered annotation (e.g. `Optional[str]`, `list[User]`). Quoted below
+        // so forward / recursive references resolve without ordering constraints.
+        const annotation = node.type;
+        const optional = annotation.startsWith('Optional[');
+        // When the Python attribute differs from the GraphQL wire key (snake_case
+        // conversion or a keyword escaped with `_`), pin the wire key with a pydantic
+        // `Field(alias=...)` so hydration maps it onto the attribute. Optional fields
+        // also default to `None` so a missing key is allowed.
+        let assignment = '';
+        if (attr !== wire) {
+            assignment = optional
+                ? ` = Field(default=None, alias='${wire}')`
+                : ` = Field(alias='${wire}')`;
+        }
+        else if (optional) {
+            assignment = ' = None';
+        }
+        return `${attr}: '${annotation}'${assignment}`;
+    }
+    InputValueDefinition(node) {
+        if (this.config.onlyEnums)
+            return '';
+        return `${this.dictFieldName(node.name.value)}: '${node.type}'`;
+    }
+    // --- Class / block builder ---
+    buildClass(name, base, fields) {
+        const header = `class ${name}(${base}):`;
+        const body = fields.filter(Boolean);
+        if (body.length === 0) {
+            return `${header}\n${INDENT}pass`;
+        }
+        return [header, ...body.map(f => INDENT + f)].join('\n');
+    }
+    /**
+     * Build a base-model subclass. Fields are class-level annotations; if any field
+     * pins a wire key with `Field(alias=...)`, a
+     * `model_config = ConfigDict(populate_by_name=True)` line is prepended so the
+     * class can be constructed by attribute name as well as by alias.
+     */
+    buildBaseModelClass(name, fields) {
+        const header = `class ${name}(${this.config.baseModel}):`;
+        const body = fields.filter(Boolean);
+        if (body.length === 0) {
+            return `${header}\n${INDENT}pass`;
+        }
+        const lines = [header];
+        if (body.some(f => f.includes('alias='))) {
+            lines.push(`${INDENT}model_config = ConfigDict(populate_by_name=True)`);
+        }
+        lines.push(...body.map(f => INDENT + f));
+        return lines.join('\n');
+    }
+    /**
+     * Split a rendered `key: 'annotation'` field back into its parts. The key is
+     * always a GraphQL Name (no `: '`) and the annotation is always single-quoted,
+     * so splitting on the first `: '` is unambiguous.
+     */
+    splitField(rendered) {
+        const sep = rendered.indexOf(": '");
+        const key = rendered.slice(0, sep);
+        const annotation = rendered.slice(sep + 3, -1);
+        return { key, annotation };
+    }
+    /**
+     * Build a `TypedDict`. If every key is a valid Python attribute, the readable
+     * class syntax is used; otherwise (a key is a keyword / non-identifier under
+     * `'keep'`) the functional `TypedDict('Name', { 'key': 'annotation' })` syntax
+     * is emitted so the offending keys remain valid.
+     */
+    buildTypedDict(name, fields) {
+        const body = fields.filter(Boolean);
+        const parsed = body.map(f => this.splitField(f));
+        const needsFunctional = parsed.some(p => !(0, python_common_1.isValidClassAttr)(p.key));
+        if (!needsFunctional) {
+            return this.buildClass(name, 'TypedDict', body);
+        }
+        const entries = parsed.map(p => `${INDENT}'${p.key}': '${p.annotation}',`);
+        return [`${name} = TypedDict('${name}', {`, ...entries, '})'].join('\n');
+    }
+    ObjectTypeDefinition(node) {
+        if (this.config.onlyOperationTypes || this.config.onlyEnums)
+            return '';
+        if (node.name.value.startsWith('__'))
+            return '';
+        this._usesBaseModel = true;
+        return this.buildBaseModelClass(this.convertName(node), node.fields);
+    }
+    InterfaceTypeDefinition(node) {
+        if (this.config.onlyOperationTypes || this.config.onlyEnums)
+            return '';
+        if (node.name.value.startsWith('__'))
+            return '';
+        this._usesBaseModel = true;
+        return this.buildBaseModelClass(this.convertName(node), node.fields);
+    }
+    InputObjectTypeDefinition(node) {
+        if (this.config.onlyEnums)
+            return '';
+        if (node.name.value.startsWith('__'))
+            return '';
+        this._usesTypedDict = true;
+        // Under `'keep'`, a keyword / non-identifier field key forces functional
+        // `TypedDict` syntax; otherwise readable class syntax is used.
+        return this.buildTypedDict(this.convertName(node), node.fields);
+    }
+    EnumTypeDefinition(node) {
+        var _a;
+        if (node.name.value.startsWith('__'))
+            return '';
+        this._usesEnum = true;
+        const name = this.convertName(node, {
+            useTypesPrefix: this.config.enumPrefix,
+            useTypesSuffix: this.config.enumSuffix,
+        });
+        const members = ((_a = node.values) !== null && _a !== void 0 ? _a : []).map(value => `${INDENT}${value.name.value} = '${value.name.value}'`);
+        const body = members.length > 0 ? members : [`${INDENT}pass`];
+        return [`class ${name}(str, Enum):`, ...body].join('\n');
+    }
+    /** Scalars are handled inline via the scalar map; no standalone class. */
+    ScalarTypeDefinition() {
+        return '';
+    }
+    /**
+     * `union Foo = A | B` -> `Foo = Union['A', 'B']`.
+     *
+     * Must be overridden: `BaseTypesVisitor`'s implementation emits TypeScript
+     * (`export type Foo = A | B;`), and it dereferences the node description
+     * unguarded, so an undocumented union crashes the generator outright. A schema
+     * merely *containing* a union is enough to hit this, even when no operation
+     * selects one.
+     *
+     * Member names come from `parent[key]` — the original, un-visited node — the
+     * same way `typescript`'s visitor reads them. By `leave` time `node.types`
+     * has already been rendered into annotations (`Optional[Foo]`) and would
+     * otherwise be mangled. Members are quoted so a union declared before its
+     * members still resolves, matching how every other annotation in this plugin
+     * is emitted.
+     *
+     * Note this only makes a union *declaration* valid Python. Actually selecting
+     * union members in an operation needs inline-fragment support, which
+     * `python-operations` does not implement yet (it throws).
+     */
+    UnionTypeDefinition(node, key, parent) {
+        var _a;
+        if (this.config.onlyOperationTypes || this.config.onlyEnums)
+            return '';
+        if (node.name.value.startsWith('__'))
+            return '';
+        const originalNode = parent[key];
+        const members = ((_a = originalNode.types) !== null && _a !== void 0 ? _a : []).map(t => `'${this.convertName(t)}'`);
+        // A member-less union is legal to declare but has no inhabitant.
+        if (members.length === 0) {
+            return `${this.convertName(node)} = Any`;
+        }
+        this._usesUnion = true;
+        return `${this.convertName(node)} = Union[${members.join(', ')}]`;
+    }
+    /**
+     * Build the `prepend` import lines, emitting only what the generated
+     * `content` actually references.
+     */
+    getImports(content) {
+        const imports = [];
+        if (this._usesEnum) {
+            imports.push('from enum import Enum');
+        }
+        const typingParts = [];
+        if (content.includes('Optional[')) {
+            typingParts.push('Optional');
+        }
+        if (this._usesTypedDict) {
+            typingParts.push('TypedDict');
+        }
+        if (this._usesUnion) {
+            typingParts.push('Union');
+        }
+        if (/\bAny\b/.test(content)) {
+            typingParts.push('Any');
+        }
+        if (typingParts.length > 0) {
+            imports.push(`from typing import ${typingParts.join(', ')}`);
+        }
+        if (this._usesBaseModel) {
+            // `ConfigDict` / `Field` are pydantic names; emit them from the same module
+            // as the base model, and only when the generated content uses them.
+            const parts = [this.config.baseModel];
+            if (content.includes('ConfigDict(')) {
+                parts.push('ConfigDict');
+            }
+            if (content.includes('Field(')) {
+                parts.push('Field');
+            }
+            imports.push(`from ${this.config.runtimeImport} import ${parts.join(', ')}`);
+        }
+        return imports;
+    }
+}
+exports.PythonVisitor = PythonVisitor;

package/dist/esm/index.js

@@ -0,0 +1,16 @@
+import { getCachedDocumentNodeFromSchema, oldVisit, } from '@graphql-codegen/plugin-helpers';
+import { PythonVisitor } from './visitor.js';
+export * from './config.js';
+export * from './visitor.js';
+export const plugin = (schema, _documents, config) => {
+    const astNode = getCachedDocumentNodeFromSchema(schema);
+    const visitor = new PythonVisitor(schema, config);
+    const visitorResult = oldVisit(astNode, { leave: visitor });
+    const content = visitorResult.definitions
+        .filter((def) => typeof def === 'string' && def.length > 0)
+        .join('\n\n\n');
+    return {
+        prepend: visitor.getImports(content),
+        content,
+    };
+};

package/dist/esm/visitor.js

@@ -0,0 +1,284 @@
+import autoBind from 'auto-bind';
+import { isValidClassAttr, PYTHON_SCALARS, pythonFieldName } from '@graphql-codegen/python-common';
+import { BaseTypesVisitor, getConfigValue, } from '@graphql-codegen/visitor-plugin-common';
+export { PYTHON_SCALARS };
+const INDENT = '    ';
+export class PythonVisitor extends BaseTypesVisitor {
+    constructor(schema, pluginConfig) {
+        // `namingConvention` here is our own field-naming option (`'keep'` |
+        // `'snakeCase'`) and must NOT leak into the base visitor's `namingConvention`
+        // (which controls TYPE-name conversion via `convertFactory`). Strip it before
+        // calling `super` so type names keep their default (PascalCase) conversion.
+        super(schema, 
+        // Route custom scalars (no explicit mapping) to `Any` instead of `unknown`.
+        {
+            ...pluginConfig,
+            namingConvention: undefined,
+            defaultScalarType: getConfigValue(pluginConfig.defaultScalarType, 'Any'),
+        }, {
+            baseModel: getConfigValue(pluginConfig.baseModel, 'BaseModel'),
+            runtimeImport: getConfigValue(pluginConfig.runtimeImport, 'pydantic'),
+            pyNamingConvention: getConfigValue(pluginConfig.namingConvention, 'snakeCase'),
+        }, PYTHON_SCALARS);
+        this._usesEnum = false;
+        this._usesTypedDict = false;
+        this._usesBaseModel = false;
+        this._usesUnion = false;
+        autoBind(this);
+    }
+    /** Python has no `export` keyword; disable the C-family export prefix. */
+    getExportPrefix() {
+        return '';
+    }
+    _getScalar(name, type) {
+        const mapped = this.scalars[name];
+        if (mapped) {
+            return mapped[type];
+        }
+        return 'Any';
+    }
+    // --- Nullability / list composition (emit Python instead of TS) ---
+    NamedType(node, key, parent, path, ancestors) {
+        return `Optional[${super.NamedType(node, key, parent, path, ancestors)}]`;
+    }
+    ListType(node, key, parent, path, ancestors) {
+        return `Optional[${super.ListType(node, key, parent, path, ancestors)}]`;
+    }
+    wrapWithListType(str) {
+        return `list[${str}]`;
+    }
+    NonNullType(node) {
+        const baseValue = super.NonNullType(node);
+        if (baseValue.startsWith('Optional[') && baseValue.endsWith(']')) {
+            return baseValue.slice('Optional['.length, -1);
+        }
+        return baseValue;
+    }
+    // --- Field rendering (name: 'annotation') ---
+    snakeFieldName(name) {
+        return pythonFieldName(name);
+    }
+    /**
+     * Field key for a `TypedDict` (input type). Input types are what the caller
+     * SENDS — the runtime forwards the dict to the server as-is — so they ALWAYS
+     * keep the wire (GraphQL) name regardless of `namingConvention`. If the name
+     * is a keyword / non-identifier the containing `TypedDict` is later emitted
+     * with functional syntax (see `buildTypedDict`).
+     */
+    dictFieldName(name) {
+        return name;
+    }
+    /**
+     * Field key for an object / interface type (a class attribute). Under `'keep'`
+     * a keyword / non-identifier name cannot be a class attribute and BaseModel
+     * cannot use functional `TypedDict` syntax, so we fall back to appending `_`
+     * for just that field.
+     */
+    objectFieldName(name) {
+        if (this.config.pyNamingConvention === 'snakeCase') {
+            return this.snakeFieldName(name);
+        }
+        return isValidClassAttr(name) ? name : `${name}_`;
+    }
+    FieldDefinition(node) {
+        if (this.config.onlyEnums)
+            return '';
+        const wire = node.name.value;
+        const attr = this.objectFieldName(wire);
+        // The rendered annotation (e.g. `Optional[str]`, `list[User]`). Quoted below
+        // so forward / recursive references resolve without ordering constraints.
+        const annotation = node.type;
+        const optional = annotation.startsWith('Optional[');
+        // When the Python attribute differs from the GraphQL wire key (snake_case
+        // conversion or a keyword escaped with `_`), pin the wire key with a pydantic
+        // `Field(alias=...)` so hydration maps it onto the attribute. Optional fields
+        // also default to `None` so a missing key is allowed.
+        let assignment = '';
+        if (attr !== wire) {
+            assignment = optional
+                ? ` = Field(default=None, alias='${wire}')`
+                : ` = Field(alias='${wire}')`;
+        }
+        else if (optional) {
+            assignment = ' = None';
+        }
+        return `${attr}: '${annotation}'${assignment}`;
+    }
+    InputValueDefinition(node) {
+        if (this.config.onlyEnums)
+            return '';
+        return `${this.dictFieldName(node.name.value)}: '${node.type}'`;
+    }
+    // --- Class / block builder ---
+    buildClass(name, base, fields) {
+        const header = `class ${name}(${base}):`;
+        const body = fields.filter(Boolean);
+        if (body.length === 0) {
+            return `${header}\n${INDENT}pass`;
+        }
+        return [header, ...body.map(f => INDENT + f)].join('\n');
+    }
+    /**
+     * Build a base-model subclass. Fields are class-level annotations; if any field
+     * pins a wire key with `Field(alias=...)`, a
+     * `model_config = ConfigDict(populate_by_name=True)` line is prepended so the
+     * class can be constructed by attribute name as well as by alias.
+     */
+    buildBaseModelClass(name, fields) {
+        const header = `class ${name}(${this.config.baseModel}):`;
+        const body = fields.filter(Boolean);
+        if (body.length === 0) {
+            return `${header}\n${INDENT}pass`;
+        }
+        const lines = [header];
+        if (body.some(f => f.includes('alias='))) {
+            lines.push(`${INDENT}model_config = ConfigDict(populate_by_name=True)`);
+        }
+        lines.push(...body.map(f => INDENT + f));
+        return lines.join('\n');
+    }
+    /**
+     * Split a rendered `key: 'annotation'` field back into its parts. The key is
+     * always a GraphQL Name (no `: '`) and the annotation is always single-quoted,
+     * so splitting on the first `: '` is unambiguous.
+     */
+    splitField(rendered) {
+        const sep = rendered.indexOf(": '");
+        const key = rendered.slice(0, sep);
+        const annotation = rendered.slice(sep + 3, -1);
+        return { key, annotation };
+    }
+    /**
+     * Build a `TypedDict`. If every key is a valid Python attribute, the readable
+     * class syntax is used; otherwise (a key is a keyword / non-identifier under
+     * `'keep'`) the functional `TypedDict('Name', { 'key': 'annotation' })` syntax
+     * is emitted so the offending keys remain valid.
+     */
+    buildTypedDict(name, fields) {
+        const body = fields.filter(Boolean);
+        const parsed = body.map(f => this.splitField(f));
+        const needsFunctional = parsed.some(p => !isValidClassAttr(p.key));
+        if (!needsFunctional) {
+            return this.buildClass(name, 'TypedDict', body);
+        }
+        const entries = parsed.map(p => `${INDENT}'${p.key}': '${p.annotation}',`);
+        return [`${name} = TypedDict('${name}', {`, ...entries, '})'].join('\n');
+    }
+    ObjectTypeDefinition(node) {
+        if (this.config.onlyOperationTypes || this.config.onlyEnums)
+            return '';
+        if (node.name.value.startsWith('__'))
+            return '';
+        this._usesBaseModel = true;
+        return this.buildBaseModelClass(this.convertName(node), node.fields);
+    }
+    InterfaceTypeDefinition(node) {
+        if (this.config.onlyOperationTypes || this.config.onlyEnums)
+            return '';
+        if (node.name.value.startsWith('__'))
+            return '';
+        this._usesBaseModel = true;
+        return this.buildBaseModelClass(this.convertName(node), node.fields);
+    }
+    InputObjectTypeDefinition(node) {
+        if (this.config.onlyEnums)
+            return '';
+        if (node.name.value.startsWith('__'))
+            return '';
+        this._usesTypedDict = true;
+        // Under `'keep'`, a keyword / non-identifier field key forces functional
+        // `TypedDict` syntax; otherwise readable class syntax is used.
+        return this.buildTypedDict(this.convertName(node), node.fields);
+    }
+    EnumTypeDefinition(node) {
+        var _a;
+        if (node.name.value.startsWith('__'))
+            return '';
+        this._usesEnum = true;
+        const name = this.convertName(node, {
+            useTypesPrefix: this.config.enumPrefix,
+            useTypesSuffix: this.config.enumSuffix,
+        });
+        const members = ((_a = node.values) !== null && _a !== void 0 ? _a : []).map(value => `${INDENT}${value.name.value} = '${value.name.value}'`);
+        const body = members.length > 0 ? members : [`${INDENT}pass`];
+        return [`class ${name}(str, Enum):`, ...body].join('\n');
+    }
+    /** Scalars are handled inline via the scalar map; no standalone class. */
+    ScalarTypeDefinition() {
+        return '';
+    }
+    /**
+     * `union Foo = A | B` -> `Foo = Union['A', 'B']`.
+     *
+     * Must be overridden: `BaseTypesVisitor`'s implementation emits TypeScript
+     * (`export type Foo = A | B;`), and it dereferences the node description
+     * unguarded, so an undocumented union crashes the generator outright. A schema
+     * merely *containing* a union is enough to hit this, even when no operation
+     * selects one.
+     *
+     * Member names come from `parent[key]` — the original, un-visited node — the
+     * same way `typescript`'s visitor reads them. By `leave` time `node.types`
+     * has already been rendered into annotations (`Optional[Foo]`) and would
+     * otherwise be mangled. Members are quoted so a union declared before its
+     * members still resolves, matching how every other annotation in this plugin
+     * is emitted.
+     *
+     * Note this only makes a union *declaration* valid Python. Actually selecting
+     * union members in an operation needs inline-fragment support, which
+     * `python-operations` does not implement yet (it throws).
+     */
+    UnionTypeDefinition(node, key, parent) {
+        var _a;
+        if (this.config.onlyOperationTypes || this.config.onlyEnums)
+            return '';
+        if (node.name.value.startsWith('__'))
+            return '';
+        const originalNode = parent[key];
+        const members = ((_a = originalNode.types) !== null && _a !== void 0 ? _a : []).map(t => `'${this.convertName(t)}'`);
+        // A member-less union is legal to declare but has no inhabitant.
+        if (members.length === 0) {
+            return `${this.convertName(node)} = Any`;
+        }
+        this._usesUnion = true;
+        return `${this.convertName(node)} = Union[${members.join(', ')}]`;
+    }
+    /**
+     * Build the `prepend` import lines, emitting only what the generated
+     * `content` actually references.
+     */
+    getImports(content) {
+        const imports = [];
+        if (this._usesEnum) {
+            imports.push('from enum import Enum');
+        }
+        const typingParts = [];
+        if (content.includes('Optional[')) {
+            typingParts.push('Optional');
+        }
+        if (this._usesTypedDict) {
+            typingParts.push('TypedDict');
+        }
+        if (this._usesUnion) {
+            typingParts.push('Union');
+        }
+        if (/\bAny\b/.test(content)) {
+            typingParts.push('Any');
+        }
+        if (typingParts.length > 0) {
+            imports.push(`from typing import ${typingParts.join(', ')}`);
+        }
+        if (this._usesBaseModel) {
+            // `ConfigDict` / `Field` are pydantic names; emit them from the same module
+            // as the base model, and only when the generated content uses them.
+            const parts = [this.config.baseModel];
+            if (content.includes('ConfigDict(')) {
+                parts.push('ConfigDict');
+            }
+            if (content.includes('Field(')) {
+                parts.push('Field');
+            }
+            imports.push(`from ${this.config.runtimeImport} import ${parts.join(', ')}`);
+        }
+        return imports;
+    }
+}