@graphql-codegen/python 0.0.0-stage → 0.0.2-alpha-20261029093428-bb94591c48dc485d04089639f4ca0f124e339666

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/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/cjs/package.json

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

package/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/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/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;
+    }
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@graphql-codegen/python",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2-alpha-20261029093428-bb94591c48dc485d04089639f4ca0f124e339666",
+  "description": "GraphQL Code Generator plugin that emits Python types",
+  "sideEffects": false,
+  "peerDependencies": {
+    "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0"
+  },
+  "dependencies": {
+    "@graphql-codegen/plugin-helpers": "^6.3.0",
+    "@graphql-codegen/python-common": "0.0.2-alpha-20261029093428-bb94591c48dc485d04089639f4ca0f124e339666",
+    "@graphql-codegen/visitor-plugin-common": "^6.3.0",
+    "auto-bind": "~4.0.0",
+    "tslib": "^2.8.1"
+  },
+  "repository": "git@github.com:dotansimha/graphql-code-generator-community.git",
+  "license": "MIT",
+  "engines": {
+    "node": ">= 16.0.0"
+  },
+  "main": "cjs/index.js",
+  "module": "esm/index.js",
+  "typings": "typings/index.d.ts",
+  "typescript": {
+    "definition": "typings/index.d.ts"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./typings/index.d.cts",
+        "default": "./cjs/index.js"
+      },
+      "import": {
+        "types": "./typings/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "default": {
+        "types": "./typings/index.d.ts",
+        "default": "./esm/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  }
 }

package/typings/config.d.cts

@@ -0,0 +1,110 @@
+import { RawTypesConfig } from '@graphql-codegen/visitor-plugin-common';
+/**
+ * @description This plugin generates Python types based on your `GraphQLSchema`.
+ *
+ * It generates idiomatic Python for your entire schema:
+ * - object & interface types become [pydantic](https://docs.pydantic.dev)
+ *   `BaseModel` classes with snake_case attributes; each field whose Python name
+ *   differs from the GraphQL key is pinned with `Field(alias=...)` so pydantic
+ *   hydrates the wire (camelCase) key onto the attribute,
+ * - input types become `TypedDict`s keyed by the WIRE (GraphQL) name — inputs
+ *   are sent to the server as-is, so their keys are never snake-cased,
+ * - enums become `str, Enum` classes,
+ * - scalars are mapped to native Python types.
+ *
+ * By default object / interface field names are converted to snake_case (see
+ * `namingConvention`). Every annotation is quoted so forward / recursive
+ * references resolve without ordering constraints.
+ */
+export interface PythonPluginConfig extends RawTypesConfig {
+    /**
+     * @description The base class that generated object and interface types extend.
+     * @default "BaseModel"
+     *
+     * @exampleMarkdown
+     * ```ts filename="codegen.ts"
+     *  import type { CodegenConfig } from '@graphql-codegen/cli';
+     *
+     *  const config: CodegenConfig = {
+     *    generates: {
+     *      'schema.py': {
+     *        plugins: ['@graphql-codegen/python'],
+     *        config: {
+     *          baseModel: 'BaseModel',
+     *        },
+     *      },
+     *    },
+     *  };
+     *  export default config;
+     * ```
+     */
+    baseModel?: string;
+    /**
+     * @description The module the base model is imported from. Emitted as
+     * `from {runtimeImport} import {baseModel}` (with `ConfigDict` / `Field`
+     * appended when the generated types use aliases). Defaults to `pydantic`; if
+     * you override it, point it at a module that re-exports a pydantic-compatible
+     * `BaseModel`, `ConfigDict`, and `Field`.
+     * @default "pydantic"
+     *
+     * @exampleMarkdown
+     * ```ts filename="codegen.ts"
+     *  import type { CodegenConfig } from '@graphql-codegen/cli';
+     *
+     *  const config: CodegenConfig = {
+     *    generates: {
+     *      'schema.py': {
+     *        plugins: ['@graphql-codegen/python'],
+     *        config: {
+     *          runtimeImport: 'pydantic',
+     *        },
+     *      },
+     *    },
+     *  };
+     *  export default config;
+     * ```
+     */
+    runtimeImport?: string;
+    /**
+     * @description Controls how GraphQL OBJECT / INTERFACE field names are turned
+     * into Python class attributes. Input-type keys are unaffected — they always
+     * keep the wire (GraphQL) name because the runtime forwards the input dict to
+     * the server as-is.
+     *
+     * - `'snakeCase'` (default): field names are converted from camelCase to
+     *   snake_case and Python reserved keywords are suffixed with `_`. This is the
+     *   idiomatic-Python choice; each renamed field is pinned with `Field(alias=...)`
+     *   (e.g. `from` -> `from_` with `alias='from'`) so pydantic hydrates the
+     *   original wire key onto the attribute.
+     * - `'keep'`: object / interface field names are used verbatim; a keyword /
+     *   non-identifier field falls back to a trailing `_` for just that field.
+     *
+     * @default "snakeCase"
+     *
+     * @exampleMarkdown
+     * ```ts filename="codegen.ts"
+     *  import type { CodegenConfig } from '@graphql-codegen/cli';
+     *
+     *  const config: CodegenConfig = {
+     *    generates: {
+     *      'schema.py': {
+     *        plugins: ['@graphql-codegen/python'],
+     *        config: {
+     *          namingConvention: 'snakeCase',
+     *        },
+     *      },
+     *    },
+     *  };
+     *  export default config;
+     * ```
+     */
+    namingConvention?: 'keep' | 'snakeCase';
+    /**
+     * @description Does not add a `__typename` field to the generated types.
+     * For the Python types plugin `__typename` is not emitted by default, so this
+     * option is accepted for parity but has no additional effect unless you opt in
+     * elsewhere.
+     * @default true
+     */
+    skipTypename?: boolean;
+}

package/typings/config.d.ts

@@ -0,0 +1,110 @@
+import { RawTypesConfig } from '@graphql-codegen/visitor-plugin-common';
+/**
+ * @description This plugin generates Python types based on your `GraphQLSchema`.
+ *
+ * It generates idiomatic Python for your entire schema:
+ * - object & interface types become [pydantic](https://docs.pydantic.dev)
+ *   `BaseModel` classes with snake_case attributes; each field whose Python name
+ *   differs from the GraphQL key is pinned with `Field(alias=...)` so pydantic
+ *   hydrates the wire (camelCase) key onto the attribute,
+ * - input types become `TypedDict`s keyed by the WIRE (GraphQL) name — inputs
+ *   are sent to the server as-is, so their keys are never snake-cased,
+ * - enums become `str, Enum` classes,
+ * - scalars are mapped to native Python types.
+ *
+ * By default object / interface field names are converted to snake_case (see
+ * `namingConvention`). Every annotation is quoted so forward / recursive
+ * references resolve without ordering constraints.
+ */
+export interface PythonPluginConfig extends RawTypesConfig {
+    /**
+     * @description The base class that generated object and interface types extend.
+     * @default "BaseModel"
+     *
+     * @exampleMarkdown
+     * ```ts filename="codegen.ts"
+     *  import type { CodegenConfig } from '@graphql-codegen/cli';
+     *
+     *  const config: CodegenConfig = {
+     *    generates: {
+     *      'schema.py': {
+     *        plugins: ['@graphql-codegen/python'],
+     *        config: {
+     *          baseModel: 'BaseModel',
+     *        },
+     *      },
+     *    },
+     *  };
+     *  export default config;
+     * ```
+     */
+    baseModel?: string;
+    /**
+     * @description The module the base model is imported from. Emitted as
+     * `from {runtimeImport} import {baseModel}` (with `ConfigDict` / `Field`
+     * appended when the generated types use aliases). Defaults to `pydantic`; if
+     * you override it, point it at a module that re-exports a pydantic-compatible
+     * `BaseModel`, `ConfigDict`, and `Field`.
+     * @default "pydantic"
+     *
+     * @exampleMarkdown
+     * ```ts filename="codegen.ts"
+     *  import type { CodegenConfig } from '@graphql-codegen/cli';
+     *
+     *  const config: CodegenConfig = {
+     *    generates: {
+     *      'schema.py': {
+     *        plugins: ['@graphql-codegen/python'],
+     *        config: {
+     *          runtimeImport: 'pydantic',
+     *        },
+     *      },
+     *    },
+     *  };
+     *  export default config;
+     * ```
+     */
+    runtimeImport?: string;
+    /**
+     * @description Controls how GraphQL OBJECT / INTERFACE field names are turned
+     * into Python class attributes. Input-type keys are unaffected — they always
+     * keep the wire (GraphQL) name because the runtime forwards the input dict to
+     * the server as-is.
+     *
+     * - `'snakeCase'` (default): field names are converted from camelCase to
+     *   snake_case and Python reserved keywords are suffixed with `_`. This is the
+     *   idiomatic-Python choice; each renamed field is pinned with `Field(alias=...)`
+     *   (e.g. `from` -> `from_` with `alias='from'`) so pydantic hydrates the
+     *   original wire key onto the attribute.
+     * - `'keep'`: object / interface field names are used verbatim; a keyword /
+     *   non-identifier field falls back to a trailing `_` for just that field.
+     *
+     * @default "snakeCase"
+     *
+     * @exampleMarkdown
+     * ```ts filename="codegen.ts"
+     *  import type { CodegenConfig } from '@graphql-codegen/cli';
+     *
+     *  const config: CodegenConfig = {
+     *    generates: {
+     *      'schema.py': {
+     *        plugins: ['@graphql-codegen/python'],
+     *        config: {
+     *          namingConvention: 'snakeCase',
+     *        },
+     *      },
+     *    },
+     *  };
+     *  export default config;
+     * ```
+     */
+    namingConvention?: 'keep' | 'snakeCase';
+    /**
+     * @description Does not add a `__typename` field to the generated types.
+     * For the Python types plugin `__typename` is not emitted by default, so this
+     * option is accepted for parity but has no additional effect unless you opt in
+     * elsewhere.
+     * @default true
+     */
+    skipTypename?: boolean;
+}

package/typings/index.d.cts

@@ -0,0 +1,5 @@
+import { PluginFunction, Types } from '@graphql-codegen/plugin-helpers';
+import { PythonPluginConfig } from './config.cjs';
+export * from './config.cjs';
+export * from './visitor.cjs';
+export declare const plugin: PluginFunction<PythonPluginConfig, Types.ComplexPluginOutput>;

package/typings/index.d.ts

@@ -0,0 +1,5 @@
+import { PluginFunction, Types } from '@graphql-codegen/plugin-helpers';
+import { PythonPluginConfig } from './config.js';
+export * from './config.js';
+export * from './visitor.js';
+export declare const plugin: PluginFunction<PythonPluginConfig, Types.ComplexPluginOutput>;

package/typings/visitor.d.cts

@@ -0,0 +1,96 @@
+import { EnumTypeDefinitionNode, FieldDefinitionNode, GraphQLSchema, InputObjectTypeDefinitionNode, InputValueDefinitionNode, InterfaceTypeDefinitionNode, ListTypeNode, NamedTypeNode, NonNullTypeNode, ObjectTypeDefinitionNode, UnionTypeDefinitionNode } from 'graphql';
+import { PYTHON_SCALARS } from '@graphql-codegen/python-common';
+import { BaseTypesVisitor, ParsedTypesConfig } from '@graphql-codegen/visitor-plugin-common';
+import { PythonPluginConfig } from './config.cjs';
+export { PYTHON_SCALARS };
+export type PythonNamingConvention = 'keep' | 'snakeCase';
+export interface PythonPluginParsedConfig extends ParsedTypesConfig {
+    baseModel: string;
+    runtimeImport: string;
+    pyNamingConvention: PythonNamingConvention;
+}
+export declare class PythonVisitor<TRawConfig extends PythonPluginConfig = PythonPluginConfig, TParsedConfig extends PythonPluginParsedConfig = PythonPluginParsedConfig> extends BaseTypesVisitor<TRawConfig, TParsedConfig> {
+    private _usesEnum;
+    private _usesTypedDict;
+    private _usesBaseModel;
+    private _usesUnion;
+    constructor(schema: GraphQLSchema, pluginConfig: TRawConfig);
+    /** Python has no `export` keyword; disable the C-family export prefix. */
+    protected getExportPrefix(): string;
+    protected _getScalar(name: string, type: 'input' | 'output'): string;
+    NamedType(node: NamedTypeNode, key: any, parent: any, path: any, ancestors: any): string;
+    ListType(node: ListTypeNode, key: any, parent: any, path: any, ancestors: any): string;
+    protected wrapWithListType(str: string): string;
+    NonNullType(node: NonNullTypeNode): string;
+    private snakeFieldName;
+    /**
+     * 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`).
+     */
+    private dictFieldName;
+    /**
+     * 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.
+     */
+    private objectFieldName;
+    FieldDefinition(node: FieldDefinitionNode): string;
+    InputValueDefinition(node: InputValueDefinitionNode): string;
+    private buildClass;
+    /**
+     * 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.
+     */
+    private buildBaseModelClass;
+    /**
+     * 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.
+     */
+    private splitField;
+    /**
+     * 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.
+     */
+    private buildTypedDict;
+    ObjectTypeDefinition(node: ObjectTypeDefinitionNode): string;
+    InterfaceTypeDefinition(node: InterfaceTypeDefinitionNode): string;
+    InputObjectTypeDefinition(node: InputObjectTypeDefinitionNode): string;
+    EnumTypeDefinition(node: EnumTypeDefinitionNode): string;
+    /** Scalars are handled inline via the scalar map; no standalone class. */
+    ScalarTypeDefinition(): string;
+    /**
+     * `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: UnionTypeDefinitionNode, key: string | number | undefined, parent: any): string;
+    /**
+     * Build the `prepend` import lines, emitting only what the generated
+     * `content` actually references.
+     */
+    getImports(content: string): string[];
+}

package/typings/visitor.d.ts

@@ -0,0 +1,96 @@
+import { EnumTypeDefinitionNode, FieldDefinitionNode, GraphQLSchema, InputObjectTypeDefinitionNode, InputValueDefinitionNode, InterfaceTypeDefinitionNode, ListTypeNode, NamedTypeNode, NonNullTypeNode, ObjectTypeDefinitionNode, UnionTypeDefinitionNode } from 'graphql';
+import { PYTHON_SCALARS } from '@graphql-codegen/python-common';
+import { BaseTypesVisitor, ParsedTypesConfig } from '@graphql-codegen/visitor-plugin-common';
+import { PythonPluginConfig } from './config.js';
+export { PYTHON_SCALARS };
+export type PythonNamingConvention = 'keep' | 'snakeCase';
+export interface PythonPluginParsedConfig extends ParsedTypesConfig {
+    baseModel: string;
+    runtimeImport: string;
+    pyNamingConvention: PythonNamingConvention;
+}
+export declare class PythonVisitor<TRawConfig extends PythonPluginConfig = PythonPluginConfig, TParsedConfig extends PythonPluginParsedConfig = PythonPluginParsedConfig> extends BaseTypesVisitor<TRawConfig, TParsedConfig> {
+    private _usesEnum;
+    private _usesTypedDict;
+    private _usesBaseModel;
+    private _usesUnion;
+    constructor(schema: GraphQLSchema, pluginConfig: TRawConfig);
+    /** Python has no `export` keyword; disable the C-family export prefix. */
+    protected getExportPrefix(): string;
+    protected _getScalar(name: string, type: 'input' | 'output'): string;
+    NamedType(node: NamedTypeNode, key: any, parent: any, path: any, ancestors: any): string;
+    ListType(node: ListTypeNode, key: any, parent: any, path: any, ancestors: any): string;
+    protected wrapWithListType(str: string): string;
+    NonNullType(node: NonNullTypeNode): string;
+    private snakeFieldName;
+    /**
+     * 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`).
+     */
+    private dictFieldName;
+    /**
+     * 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.
+     */
+    private objectFieldName;
+    FieldDefinition(node: FieldDefinitionNode): string;
+    InputValueDefinition(node: InputValueDefinitionNode): string;
+    private buildClass;
+    /**
+     * 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.
+     */
+    private buildBaseModelClass;
+    /**
+     * 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.
+     */
+    private splitField;
+    /**
+     * 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.
+     */
+    private buildTypedDict;
+    ObjectTypeDefinition(node: ObjectTypeDefinitionNode): string;
+    InterfaceTypeDefinition(node: InterfaceTypeDefinitionNode): string;
+    InputObjectTypeDefinition(node: InputObjectTypeDefinitionNode): string;
+    EnumTypeDefinition(node: EnumTypeDefinitionNode): string;
+    /** Scalars are handled inline via the scalar map; no standalone class. */
+    ScalarTypeDefinition(): string;
+    /**
+     * `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: UnionTypeDefinitionNode, key: string | number | undefined, parent: any): string;
+    /**
+     * Build the `prepend` import lines, emitting only what the generated
+     * `content` actually references.
+     */
+    getImports(content: string): string[];
+}