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

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @graphql-codegen/python-operations
 
-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 **document-driven** [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) plugin that
+emits **Python operation types**: for each operation in your documents it generates per-operation
+result [pydantic](https://docs.pydantic.dev) `BaseModel` classes (named, nested classes for every
+object selection) plus a `<Operation>Variables` `TypedDict` keyed by the wire (GraphQL) variable
+names. Renamed response keys are pinned with `Field(alias=...)` and a
+`model_config = ConfigDict(populate_by_name=True)`.
+
+It is the operations counterpart to `@graphql-codegen/python` (which emits base schema types),
+analogous to how `typescript-operations` complements `typescript`.
+
+## Example
+
+Schema:
+
+```graphql
+enum Role {
+  ADMIN
+  USER
+}
+type User {
+  id: ID!
+  name: String!
+  role: Role!
+  friends: [User!]!
+}
+type Query {
+  users(role: Role): [User!]!
+}
+```
+
+Operation:
+
+```graphql
+query GetUsers($role: Role) {
+  users(role: $role) {
+    id
+    name
+    role
+    friends {
+      id
+      name
+    }
+  }
+}
+```
+
+Output:
+
+```python
+from typing import Optional, TypedDict
+from pydantic import BaseModel
+
+
+class GetUsersQueryUsersFriends(BaseModel):
+    id: 'str'
+    name: 'str'
+
+
+class GetUsersQueryUsers(BaseModel):
+    id: 'str'
+    name: 'str'
+    role: 'Role'
+    friends: 'list[GetUsersQueryUsersFriends]'
+
+
+class GetUsersQuery(BaseModel):
+    users: 'list[GetUsersQueryUsers]'
+
+
+class GetUsersQueryVariables(TypedDict):
+    role: 'Optional[Role]'
+```
+
+Result types are pydantic `BaseModel` subclasses; the `<Operation>Variables` type stays a
+`TypedDict`. When a response key is renamed (snake_case or a reserved keyword), that attribute is
+pinned with `Field(alias='<wireName>')` and the class gets
+`model_config = ConfigDict(populate_by_name=True)`.
+
+## Config
+
+| Option             | Type                    | Default       | Description                                                                                                                                                                                                                                     |
+| ------------------ | ----------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `namingConvention` | `'keep' \| 'snakeCase'` | `'snakeCase'` | How response keys become result-class attributes. `snakeCase` converts camelCase→snake*case, suffixes reserved keywords with `*`, and pins renamed keys via `Field(alias=...)`. `keep` uses keys verbatim. Variables always keep the wire name. |
+| `baseModel`        | `string`                | `'BaseModel'` | Base class the generated result types extend.                                                                                                                                                                                                   |
+| `runtimeImport`    | `string`                | `'pydantic'`  | Module the base model is imported from (`from {runtimeImport} import {baseModel}`, with `ConfigDict`/`Field` appended when aliases are used).                                                                                                   |
+| `typesImport`      | `string`                | –             | If set, prepend `from {typesImport} import *` so base type names (enums, inputs) resolve at runtime.                                                                                                                                            |
+
+## Behaviour / naming
+
+- Result root type: `<OperationName><OperationType>` (e.g. `GetUsersQuery`).
+- Nested object selections: `<ParentTypeName><PascalCase(responseFieldName)>`.
+- Variables type: `<OperationName><OperationType>Variables`.
+- Field names are `snake_case`; Python reserved keywords get a trailing `_`.
+- Aliases use the alias as the response key; `__typename` becomes `__typename__`.
+- Every annotation is quoted (forward reference), so emit order does not matter.
+
+## Not (yet) supported
+
+Fragment spreads, inline fragments and union member (`... on Type`) selections are not yet
+implemented. Rather than silently omitting their fields (which would produce a result type that
+looks valid but is missing data), the plugin **throws a clear error** at generate time if an
+operation contains one — inline the fields directly into the operation for now. See
+`src/python-helpers.ts` for the duplicated naming helpers (TODO: extract to a shared
+`@graphql-codegen/python-common` package).

package/cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plugin = void 0;
+const tslib_1 = require("tslib");
+const graphql_1 = require("graphql");
+const visitor_js_1 = require("./visitor.js");
+tslib_1.__exportStar(require("./config.js"), exports);
+tslib_1.__exportStar(require("./visitor.js"), exports);
+tslib_1.__exportStar(require("./python-helpers.js"), exports);
+/**
+ * Document-driven plugin: for each GraphQL operation in the provided documents,
+ * emit a per-operation result `TypedDict` (with named nested `TypedDict`s for
+ * every object selection) plus a `<Operation>Variables` `TypedDict`.
+ */
+const plugin = (schema, documents, config) => {
+    const allAst = (0, graphql_1.concatAST)(documents.map(d => d.document).filter(Boolean));
+    const operations = allAst.definitions.filter((def) => def.kind === graphql_1.Kind.OPERATION_DEFINITION);
+    const visitor = new visitor_js_1.PythonOperationsVisitor(schema, config);
+    const definitions = operations.map(op => visitor.generateOperation(op));
+    return {
+        prepend: visitor.getImports(),
+        content: definitions.join('\n\n\n'),
+    };
+};
+exports.plugin = plugin;

package/cjs/package.json

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

package/cjs/python-helpers.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pyFieldName = exports.PYTHON_SCALARS = exports.isValidClassAttr = exports.isReservedField = void 0;
+exports.resultFieldKey = resultFieldKey;
+exports.fieldKey = fieldKey;
+const python_common_1 = require("@graphql-codegen/python-common");
+Object.defineProperty(exports, "isReservedField", { enumerable: true, get: function () { return python_common_1.isReservedField; } });
+Object.defineProperty(exports, "isValidClassAttr", { enumerable: true, get: function () { return python_common_1.isValidClassAttr; } });
+Object.defineProperty(exports, "pyFieldName", { enumerable: true, get: function () { return python_common_1.pythonFieldName; } });
+Object.defineProperty(exports, "PYTHON_SCALARS", { enumerable: true, get: function () { return python_common_1.PYTHON_SCALARS; } });
+/**
+ * Compute the attribute name for a `BaseModel` result class. Under `'snakeCase'`
+ * the key is snake-cased (keywords suffixed with `_`); under `'keep'` the wire
+ * name is used verbatim, but — because `BaseModel` classes cannot use functional
+ * `TypedDict` syntax — a keyword / non-identifier name still falls back to a
+ * trailing `_`.
+ */
+function resultFieldKey(name, convention) {
+    if (convention === 'snakeCase') {
+        return (0, python_common_1.pythonFieldName)(name);
+    }
+    return (0, python_common_1.isValidClassAttr)(name) ? name : `${name}_`;
+}
+/**
+ * Compute the `TypedDict` key for a GraphQL response / variable name under the
+ * given naming convention. Under `'keep'` the raw name is returned verbatim
+ * (functional `TypedDict` syntax handles invalid keys); under `'snakeCase'` the
+ * legacy snake_case + `_`-suffix behavior is applied.
+ */
+function fieldKey(name, convention) {
+    return convention === 'snakeCase' ? (0, python_common_1.pythonFieldName)(name) : name;
+}

package/cjs/visitor.js

@@ -0,0 +1,306 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythonOperationsVisitor = void 0;
+const graphql_1 = require("graphql");
+const visitor_plugin_common_1 = require("@graphql-codegen/visitor-plugin-common");
+const python_helpers_js_1 = require("./python-helpers.js");
+const INDENT = '    ';
+/**
+ * Walks GraphQL `OperationDefinition` nodes against the schema and recursively
+ * emits named, nested Python `TypedDict` classes for every object selection set,
+ * plus a `<Operation>Variables` `TypedDict` for the operation variables.
+ *
+ * Unlike the C-family `SelectionSetToObject`/`DeclarationBlock` approach (which
+ * emits inline anonymous objects), this mirrors the C#/Java strategy: every
+ * nested selection becomes its own named type referenced by its parent.
+ */
+class PythonOperationsVisitor extends visitor_plugin_common_1.BaseVisitor {
+    constructor(schema, rawConfig) {
+        // Our `namingConvention` (`'keep'` | `'snakeCase'`) governs field-KEY naming
+        // only. It must NOT leak into the base visitor's `namingConvention`, which
+        // drives TYPE-name conversion (`convertName` / `pascal`) — those names must
+        // stay PascalCase (e.g. `GetUsersQueryUsers`).
+        super({ ...rawConfig, namingConvention: undefined }, {});
+        this._usesOptional = false;
+        this._usesAny = false;
+        this._usesLiteral = false;
+        this._usesBaseModel = false;
+        this._usesConfigDict = false;
+        this._usesField = false;
+        this._anonymousCount = 0;
+        this._schema = schema;
+        this._typesImport = rawConfig.typesImport;
+        this._namingConvention = (0, visitor_plugin_common_1.getConfigValue)(rawConfig.namingConvention, 'snakeCase');
+        this._baseModel = (0, visitor_plugin_common_1.getConfigValue)(rawConfig.baseModel, 'BaseModel');
+        this._runtimeImport = (0, visitor_plugin_common_1.getConfigValue)(rawConfig.runtimeImport, 'pydantic');
+    }
+    /** PascalCase a name segment without applying any prefix/suffix. */
+    pascal(name) {
+        return this.convertName(name, {
+            useTypesPrefix: false,
+            useTypesSuffix: false,
+        });
+    }
+    get operationRootTypes() {
+        return {
+            query: this._schema.getQueryType(),
+            mutation: this._schema.getMutationType(),
+            subscription: this._schema.getSubscriptionType(),
+        };
+    }
+    // --- Python annotation builders ----------------------------------------
+    /**
+     * Build a Python annotation from a (resolved) GraphQL output type. The
+     * `objectBaseName` is the generated nested type name used when the base type
+     * is an object/interface/union selection.
+     */
+    pyTypeFromGraphQL(type, objectBaseName) {
+        if ((0, graphql_1.isNonNullType)(type)) {
+            return this.innerFromGraphQL(type.ofType, objectBaseName);
+        }
+        this._usesOptional = true;
+        return `Optional[${this.innerFromGraphQL(type, objectBaseName)}]`;
+    }
+    innerFromGraphQL(type, objectBaseName) {
+        if ((0, graphql_1.isListType)(type)) {
+            return `list[${this.pyTypeFromGraphQL(type.ofType, objectBaseName)}]`;
+        }
+        const named = (0, graphql_1.getNamedType)(type);
+        if ((0, graphql_1.isScalarType)(named)) {
+            const mapped = python_helpers_js_1.PYTHON_SCALARS[named.name];
+            if (mapped) {
+                return mapped.output;
+            }
+            this._usesAny = true;
+            return 'Any';
+        }
+        if ((0, graphql_1.isEnumType)(named)) {
+            return named.name;
+        }
+        // object / interface / union selection -> generated nested type name
+        return objectBaseName;
+    }
+    /**
+     * Build a Python annotation from a variable `TypeNode`. Named types resolve
+     * to mapped scalars, or the bare base type name (enums / input objects).
+     */
+    pyTypeFromTypeNode(type) {
+        if (type.kind === graphql_1.Kind.NON_NULL_TYPE) {
+            return this.innerFromTypeNode(type.type);
+        }
+        this._usesOptional = true;
+        return `Optional[${this.innerFromTypeNode(type)}]`;
+    }
+    innerFromTypeNode(type) {
+        if (type.kind === graphql_1.Kind.LIST_TYPE) {
+            return `list[${this.pyTypeFromTypeNode(type.type)}]`;
+        }
+        if (type.kind === graphql_1.Kind.NON_NULL_TYPE) {
+            // Non-null base (e.g. inside a list) — no Optional wrapper.
+            return this.innerFromTypeNode(type.type);
+        }
+        // NamedType
+        const name = type.name.value;
+        const mapped = python_helpers_js_1.PYTHON_SCALARS[name];
+        if (mapped) {
+            return mapped.input;
+        }
+        const schemaType = this._schema.getType(name);
+        if (schemaType && (0, graphql_1.isScalarType)(schemaType)) {
+            this._usesAny = true;
+            return 'Any';
+        }
+        // enum or input object -> bare name (quoted forward ref by caller)
+        return name;
+    }
+    // --- Class builders ----------------------------------------------------
+    /**
+     * Build a variables `TypedDict`. Variable keys are ALWAYS the wire (GraphQL)
+     * name — they are sent to the server as-is. If every key is a valid Python
+     * attribute the readable class syntax is used; otherwise (a key is a keyword /
+     * non-identifier) the functional `TypedDict('Name', { 'key': '...' })` syntax
+     * is emitted so the offending keys remain valid.
+     */
+    buildVariablesClass(name, fields) {
+        if (fields.length === 0) {
+            return `class ${name}(TypedDict):\n${INDENT}pass`;
+        }
+        const needsFunctional = fields.some(f => !(0, python_helpers_js_1.isValidClassAttr)(f.key));
+        if (needsFunctional) {
+            const entries = fields.map(f => `${INDENT}'${f.key}': '${f.annotation}',`);
+            return [`${name} = TypedDict('${name}', {`, ...entries, '})'].join('\n');
+        }
+        const lines = fields.map(f => `${INDENT}${f.key}: '${f.annotation}'`);
+        return [`class ${name}(TypedDict):`, ...lines].join('\n');
+    }
+    /**
+     * Emit the per-class `__init__` that pre-maps wire keys to their escaped
+     * attribute names before delegating to the base model. Only emitted for result
+     * classes that contain keyword fields.
+     */
+    /**
+     * Render a single result field line: `key: 'annotation'`, with a pydantic
+     * `Field(alias=...)` when the Python attribute differs from the wire response
+     * key, and a `None` default for optional fields.
+     */
+    renderResultField(field) {
+        const optional = field.annotation.startsWith('Optional[');
+        let assignment = '';
+        if (field.wire !== undefined && field.key !== field.wire) {
+            this._usesField = true;
+            assignment = optional
+                ? ` = Field(default=None, alias='${field.wire}')`
+                : ` = Field(alias='${field.wire}')`;
+        }
+        else if (optional) {
+            assignment = ' = None';
+        }
+        return `${field.key}: '${field.annotation}'${assignment}`;
+    }
+    /**
+     * Build a result base-model subclass. A field whose Python attribute differs
+     * from the wire key is pinned with `Field(alias=...)`, and a
+     * `model_config = ConfigDict(populate_by_name=True)` line is prepended so such
+     * classes can also be built by attribute name.
+     */
+    buildResultClass(name, fields) {
+        this._usesBaseModel = true;
+        const header = `class ${name}(${this._baseModel}):`;
+        if (fields.length === 0) {
+            return `${header}\n${INDENT}pass`;
+        }
+        const lines = [header];
+        if (fields.some(f => f.wire !== undefined && f.key !== f.wire)) {
+            this._usesConfigDict = true;
+            lines.push(`${INDENT}model_config = ConfigDict(populate_by_name=True)`);
+        }
+        for (const field of fields) {
+            lines.push(`${INDENT}${this.renderResultField(field)}`);
+        }
+        return lines.join('\n');
+    }
+    // --- Selection set walking ---------------------------------------------
+    /**
+     * Emit a `TypedDict` for `selectionSet` (a selection against `parentType`),
+     * named `typeName`. Nested object selections are emitted FIRST (deepest
+     * first) so references resolve top-to-bottom. Returns nothing; classes are
+     * pushed onto `out`.
+     */
+    processSelectionSet(parentType, selectionSet, typeName, out) {
+        var _a, _b, _c, _d;
+        const fields = [];
+        const addField = (responseKey, annotation) => {
+            const key = (0, python_helpers_js_1.resultFieldKey)(responseKey, this._namingConvention);
+            // Record the wire (response) key so a `Field(alias=...)` is emitted when
+            // the Python attribute differs (snake_case conversion or keyword escape).
+            fields.push({ key, annotation, wire: responseKey });
+        };
+        for (const selection of selectionSet.selections) {
+            // Fragments (spread / inline) are not supported yet. Fail loudly instead
+            // of silently omitting their fields, which would otherwise produce a
+            // result type that looks valid but is missing data.
+            if (selection.kind === graphql_1.Kind.FRAGMENT_SPREAD) {
+                throw new Error(`@graphql-codegen/python-operations: fragment spread "...${selection.name.value}" on ` +
+                    `"${parentType.name}" is not supported yet. Inline the fragment's fields directly into ` +
+                    'the operation for now.');
+            }
+            if (selection.kind === graphql_1.Kind.INLINE_FRAGMENT) {
+                const onType = (_b = (_a = selection.typeCondition) === null || _a === void 0 ? void 0 : _a.name.value) !== null && _b !== void 0 ? _b : parentType.name;
+                throw new Error(`@graphql-codegen/python-operations: inline fragment "... on ${onType}" on ` +
+                    `"${parentType.name}" is not supported yet. Union/interface member selections cannot ` +
+                    'be generated; select only common fields for now.');
+            }
+            const fieldNode = selection;
+            const fieldName = fieldNode.name.value;
+            const responseKey = (_d = (_c = fieldNode.alias) === null || _c === void 0 ? void 0 : _c.value) !== null && _d !== void 0 ? _d : fieldName;
+            if (fieldName === '__typename') {
+                // `__typename` selections become a `Literal["ParentType"]` attribute.
+                // pydantic forbids a leading-underscore field name, so the attribute is
+                // `typename__` with `Field(alias='__typename')` pinning the wire key.
+                this._usesLiteral = true;
+                fields.push({
+                    key: 'typename__',
+                    annotation: `Literal["${parentType.name}"]`,
+                    wire: '__typename',
+                });
+                continue;
+            }
+            const fieldDef = parentType.getFields()[fieldName];
+            if (!fieldDef) {
+                // Unknown field (e.g. introspection on a type without it) — skip.
+                continue;
+            }
+            const fieldType = fieldDef.type;
+            const namedType = (0, graphql_1.getNamedType)(fieldType);
+            if (((0, graphql_1.isObjectType)(namedType) || (0, graphql_1.isInterfaceType)(namedType)) && fieldNode.selectionSet) {
+                const nestedName = `${typeName}${this.pascal(responseKey)}`;
+                // Recurse FIRST so deepest types are emitted before this one.
+                this.processSelectionSet(namedType, fieldNode.selectionSet, nestedName, out);
+                addField(responseKey, this.pyTypeFromGraphQL(fieldType, nestedName));
+            }
+            else {
+                // Scalar / enum leaf (or union without object handling).
+                addField(responseKey, this.pyTypeFromGraphQL(fieldType, namedType.name));
+            }
+        }
+        out.push(this.buildResultClass(typeName, fields));
+    }
+    buildVariables(variableDefinitions, variablesTypeName) {
+        const fields = variableDefinitions.map(def => {
+            // Variable keys are ALWAYS the wire name (sent to the server as-is).
+            const name = def.variable.name.value;
+            const annotation = this.pyTypeFromTypeNode(def.type);
+            return { key: name, annotation };
+        });
+        return this.buildVariablesClass(variablesTypeName, fields);
+    }
+    /** Generate all types for a single operation. Returns joined class blocks. */
+    generateOperation(operation) {
+        var _a, _b, _c;
+        const operationType = operation.operation; // 'query' | 'mutation' | 'subscription'
+        const operationTypeName = operationType.charAt(0).toUpperCase() + operationType.slice(1);
+        const operationName = (_b = (_a = operation.name) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : `Anonymous${this._anonymousCount++}`;
+        const baseName = `${this.pascal(operationName)}${operationTypeName}`;
+        const rootType = this.operationRootTypes[operationType];
+        const out = [];
+        if (rootType) {
+            this.processSelectionSet(rootType, operation.selectionSet, baseName, out);
+        }
+        out.push(this.buildVariables((_c = operation.variableDefinitions) !== null && _c !== void 0 ? _c : [], `${baseName}Variables`));
+        return out.join('\n\n\n');
+    }
+    /** Build the `prepend` import lines, emitting only what is referenced. */
+    getImports() {
+        const imports = [];
+        const typingParts = [];
+        if (this._usesOptional) {
+            typingParts.push('Optional');
+        }
+        // Every operation emits at least a variables TypedDict.
+        typingParts.push('TypedDict');
+        if (this._usesLiteral) {
+            typingParts.push('Literal');
+        }
+        if (this._usesAny) {
+            typingParts.push('Any');
+        }
+        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._baseModel];
+            if (this._usesConfigDict) {
+                parts.push('ConfigDict');
+            }
+            if (this._usesField) {
+                parts.push('Field');
+            }
+            imports.push(`from ${this._runtimeImport} import ${parts.join(', ')}`);
+        }
+        if (this._typesImport) {
+            imports.push(`from ${this._typesImport} import *`);
+        }
+        return imports;
+    }
+}
+exports.PythonOperationsVisitor = PythonOperationsVisitor;

package/esm/index.js

@@ -0,0 +1,20 @@
+import { concatAST, Kind } from 'graphql';
+import { PythonOperationsVisitor } from './visitor.js';
+export * from './config.js';
+export * from './visitor.js';
+export * from './python-helpers.js';
+/**
+ * Document-driven plugin: for each GraphQL operation in the provided documents,
+ * emit a per-operation result `TypedDict` (with named nested `TypedDict`s for
+ * every object selection) plus a `<Operation>Variables` `TypedDict`.
+ */
+export const plugin = (schema, documents, config) => {
+    const allAst = concatAST(documents.map(d => d.document).filter(Boolean));
+    const operations = allAst.definitions.filter((def) => def.kind === Kind.OPERATION_DEFINITION);
+    const visitor = new PythonOperationsVisitor(schema, config);
+    const definitions = operations.map(op => visitor.generateOperation(op));
+    return {
+        prepend: visitor.getImports(),
+        content: definitions.join('\n\n\n'),
+    };
+};

package/esm/python-helpers.js

@@ -0,0 +1,24 @@
+import { isReservedField, isValidClassAttr, pythonFieldName as pyFieldName, PYTHON_SCALARS, } from '@graphql-codegen/python-common';
+export { isReservedField, isValidClassAttr, PYTHON_SCALARS, pyFieldName };
+/**
+ * Compute the attribute name for a `BaseModel` result class. Under `'snakeCase'`
+ * the key is snake-cased (keywords suffixed with `_`); under `'keep'` the wire
+ * name is used verbatim, but — because `BaseModel` classes cannot use functional
+ * `TypedDict` syntax — a keyword / non-identifier name still falls back to a
+ * trailing `_`.
+ */
+export function resultFieldKey(name, convention) {
+    if (convention === 'snakeCase') {
+        return pyFieldName(name);
+    }
+    return isValidClassAttr(name) ? name : `${name}_`;
+}
+/**
+ * Compute the `TypedDict` key for a GraphQL response / variable name under the
+ * given naming convention. Under `'keep'` the raw name is returned verbatim
+ * (functional `TypedDict` syntax handles invalid keys); under `'snakeCase'` the
+ * legacy snake_case + `_`-suffix behavior is applied.
+ */
+export function fieldKey(name, convention) {
+    return convention === 'snakeCase' ? pyFieldName(name) : name;
+}

package/esm/visitor.js

@@ -0,0 +1,302 @@
+import { getNamedType, isEnumType, isInterfaceType, isListType, isNonNullType, isObjectType, isScalarType, Kind, } from 'graphql';
+import { BaseVisitor, getConfigValue } from '@graphql-codegen/visitor-plugin-common';
+import { isValidClassAttr, PYTHON_SCALARS, resultFieldKey, } from './python-helpers.js';
+const INDENT = '    ';
+/**
+ * Walks GraphQL `OperationDefinition` nodes against the schema and recursively
+ * emits named, nested Python `TypedDict` classes for every object selection set,
+ * plus a `<Operation>Variables` `TypedDict` for the operation variables.
+ *
+ * Unlike the C-family `SelectionSetToObject`/`DeclarationBlock` approach (which
+ * emits inline anonymous objects), this mirrors the C#/Java strategy: every
+ * nested selection becomes its own named type referenced by its parent.
+ */
+export class PythonOperationsVisitor extends BaseVisitor {
+    constructor(schema, rawConfig) {
+        // Our `namingConvention` (`'keep'` | `'snakeCase'`) governs field-KEY naming
+        // only. It must NOT leak into the base visitor's `namingConvention`, which
+        // drives TYPE-name conversion (`convertName` / `pascal`) — those names must
+        // stay PascalCase (e.g. `GetUsersQueryUsers`).
+        super({ ...rawConfig, namingConvention: undefined }, {});
+        this._usesOptional = false;
+        this._usesAny = false;
+        this._usesLiteral = false;
+        this._usesBaseModel = false;
+        this._usesConfigDict = false;
+        this._usesField = false;
+        this._anonymousCount = 0;
+        this._schema = schema;
+        this._typesImport = rawConfig.typesImport;
+        this._namingConvention = getConfigValue(rawConfig.namingConvention, 'snakeCase');
+        this._baseModel = getConfigValue(rawConfig.baseModel, 'BaseModel');
+        this._runtimeImport = getConfigValue(rawConfig.runtimeImport, 'pydantic');
+    }
+    /** PascalCase a name segment without applying any prefix/suffix. */
+    pascal(name) {
+        return this.convertName(name, {
+            useTypesPrefix: false,
+            useTypesSuffix: false,
+        });
+    }
+    get operationRootTypes() {
+        return {
+            query: this._schema.getQueryType(),
+            mutation: this._schema.getMutationType(),
+            subscription: this._schema.getSubscriptionType(),
+        };
+    }
+    // --- Python annotation builders ----------------------------------------
+    /**
+     * Build a Python annotation from a (resolved) GraphQL output type. The
+     * `objectBaseName` is the generated nested type name used when the base type
+     * is an object/interface/union selection.
+     */
+    pyTypeFromGraphQL(type, objectBaseName) {
+        if (isNonNullType(type)) {
+            return this.innerFromGraphQL(type.ofType, objectBaseName);
+        }
+        this._usesOptional = true;
+        return `Optional[${this.innerFromGraphQL(type, objectBaseName)}]`;
+    }
+    innerFromGraphQL(type, objectBaseName) {
+        if (isListType(type)) {
+            return `list[${this.pyTypeFromGraphQL(type.ofType, objectBaseName)}]`;
+        }
+        const named = getNamedType(type);
+        if (isScalarType(named)) {
+            const mapped = PYTHON_SCALARS[named.name];
+            if (mapped) {
+                return mapped.output;
+            }
+            this._usesAny = true;
+            return 'Any';
+        }
+        if (isEnumType(named)) {
+            return named.name;
+        }
+        // object / interface / union selection -> generated nested type name
+        return objectBaseName;
+    }
+    /**
+     * Build a Python annotation from a variable `TypeNode`. Named types resolve
+     * to mapped scalars, or the bare base type name (enums / input objects).
+     */
+    pyTypeFromTypeNode(type) {
+        if (type.kind === Kind.NON_NULL_TYPE) {
+            return this.innerFromTypeNode(type.type);
+        }
+        this._usesOptional = true;
+        return `Optional[${this.innerFromTypeNode(type)}]`;
+    }
+    innerFromTypeNode(type) {
+        if (type.kind === Kind.LIST_TYPE) {
+            return `list[${this.pyTypeFromTypeNode(type.type)}]`;
+        }
+        if (type.kind === Kind.NON_NULL_TYPE) {
+            // Non-null base (e.g. inside a list) — no Optional wrapper.
+            return this.innerFromTypeNode(type.type);
+        }
+        // NamedType
+        const name = type.name.value;
+        const mapped = PYTHON_SCALARS[name];
+        if (mapped) {
+            return mapped.input;
+        }
+        const schemaType = this._schema.getType(name);
+        if (schemaType && isScalarType(schemaType)) {
+            this._usesAny = true;
+            return 'Any';
+        }
+        // enum or input object -> bare name (quoted forward ref by caller)
+        return name;
+    }
+    // --- Class builders ----------------------------------------------------
+    /**
+     * Build a variables `TypedDict`. Variable keys are ALWAYS the wire (GraphQL)
+     * name — they are sent to the server as-is. If every key is a valid Python
+     * attribute the readable class syntax is used; otherwise (a key is a keyword /
+     * non-identifier) the functional `TypedDict('Name', { 'key': '...' })` syntax
+     * is emitted so the offending keys remain valid.
+     */
+    buildVariablesClass(name, fields) {
+        if (fields.length === 0) {
+            return `class ${name}(TypedDict):\n${INDENT}pass`;
+        }
+        const needsFunctional = fields.some(f => !isValidClassAttr(f.key));
+        if (needsFunctional) {
+            const entries = fields.map(f => `${INDENT}'${f.key}': '${f.annotation}',`);
+            return [`${name} = TypedDict('${name}', {`, ...entries, '})'].join('\n');
+        }
+        const lines = fields.map(f => `${INDENT}${f.key}: '${f.annotation}'`);
+        return [`class ${name}(TypedDict):`, ...lines].join('\n');
+    }
+    /**
+     * Emit the per-class `__init__` that pre-maps wire keys to their escaped
+     * attribute names before delegating to the base model. Only emitted for result
+     * classes that contain keyword fields.
+     */
+    /**
+     * Render a single result field line: `key: 'annotation'`, with a pydantic
+     * `Field(alias=...)` when the Python attribute differs from the wire response
+     * key, and a `None` default for optional fields.
+     */
+    renderResultField(field) {
+        const optional = field.annotation.startsWith('Optional[');
+        let assignment = '';
+        if (field.wire !== undefined && field.key !== field.wire) {
+            this._usesField = true;
+            assignment = optional
+                ? ` = Field(default=None, alias='${field.wire}')`
+                : ` = Field(alias='${field.wire}')`;
+        }
+        else if (optional) {
+            assignment = ' = None';
+        }
+        return `${field.key}: '${field.annotation}'${assignment}`;
+    }
+    /**
+     * Build a result base-model subclass. A field whose Python attribute differs
+     * from the wire key is pinned with `Field(alias=...)`, and a
+     * `model_config = ConfigDict(populate_by_name=True)` line is prepended so such
+     * classes can also be built by attribute name.
+     */
+    buildResultClass(name, fields) {
+        this._usesBaseModel = true;
+        const header = `class ${name}(${this._baseModel}):`;
+        if (fields.length === 0) {
+            return `${header}\n${INDENT}pass`;
+        }
+        const lines = [header];
+        if (fields.some(f => f.wire !== undefined && f.key !== f.wire)) {
+            this._usesConfigDict = true;
+            lines.push(`${INDENT}model_config = ConfigDict(populate_by_name=True)`);
+        }
+        for (const field of fields) {
+            lines.push(`${INDENT}${this.renderResultField(field)}`);
+        }
+        return lines.join('\n');
+    }
+    // --- Selection set walking ---------------------------------------------
+    /**
+     * Emit a `TypedDict` for `selectionSet` (a selection against `parentType`),
+     * named `typeName`. Nested object selections are emitted FIRST (deepest
+     * first) so references resolve top-to-bottom. Returns nothing; classes are
+     * pushed onto `out`.
+     */
+    processSelectionSet(parentType, selectionSet, typeName, out) {
+        var _a, _b, _c, _d;
+        const fields = [];
+        const addField = (responseKey, annotation) => {
+            const key = resultFieldKey(responseKey, this._namingConvention);
+            // Record the wire (response) key so a `Field(alias=...)` is emitted when
+            // the Python attribute differs (snake_case conversion or keyword escape).
+            fields.push({ key, annotation, wire: responseKey });
+        };
+        for (const selection of selectionSet.selections) {
+            // Fragments (spread / inline) are not supported yet. Fail loudly instead
+            // of silently omitting their fields, which would otherwise produce a
+            // result type that looks valid but is missing data.
+            if (selection.kind === Kind.FRAGMENT_SPREAD) {
+                throw new Error(`@graphql-codegen/python-operations: fragment spread "...${selection.name.value}" on ` +
+                    `"${parentType.name}" is not supported yet. Inline the fragment's fields directly into ` +
+                    'the operation for now.');
+            }
+            if (selection.kind === Kind.INLINE_FRAGMENT) {
+                const onType = (_b = (_a = selection.typeCondition) === null || _a === void 0 ? void 0 : _a.name.value) !== null && _b !== void 0 ? _b : parentType.name;
+                throw new Error(`@graphql-codegen/python-operations: inline fragment "... on ${onType}" on ` +
+                    `"${parentType.name}" is not supported yet. Union/interface member selections cannot ` +
+                    'be generated; select only common fields for now.');
+            }
+            const fieldNode = selection;
+            const fieldName = fieldNode.name.value;
+            const responseKey = (_d = (_c = fieldNode.alias) === null || _c === void 0 ? void 0 : _c.value) !== null && _d !== void 0 ? _d : fieldName;
+            if (fieldName === '__typename') {
+                // `__typename` selections become a `Literal["ParentType"]` attribute.
+                // pydantic forbids a leading-underscore field name, so the attribute is
+                // `typename__` with `Field(alias='__typename')` pinning the wire key.
+                this._usesLiteral = true;
+                fields.push({
+                    key: 'typename__',
+                    annotation: `Literal["${parentType.name}"]`,
+                    wire: '__typename',
+                });
+                continue;
+            }
+            const fieldDef = parentType.getFields()[fieldName];
+            if (!fieldDef) {
+                // Unknown field (e.g. introspection on a type without it) — skip.
+                continue;
+            }
+            const fieldType = fieldDef.type;
+            const namedType = getNamedType(fieldType);
+            if ((isObjectType(namedType) || isInterfaceType(namedType)) && fieldNode.selectionSet) {
+                const nestedName = `${typeName}${this.pascal(responseKey)}`;
+                // Recurse FIRST so deepest types are emitted before this one.
+                this.processSelectionSet(namedType, fieldNode.selectionSet, nestedName, out);
+                addField(responseKey, this.pyTypeFromGraphQL(fieldType, nestedName));
+            }
+            else {
+                // Scalar / enum leaf (or union without object handling).
+                addField(responseKey, this.pyTypeFromGraphQL(fieldType, namedType.name));
+            }
+        }
+        out.push(this.buildResultClass(typeName, fields));
+    }
+    buildVariables(variableDefinitions, variablesTypeName) {
+        const fields = variableDefinitions.map(def => {
+            // Variable keys are ALWAYS the wire name (sent to the server as-is).
+            const name = def.variable.name.value;
+            const annotation = this.pyTypeFromTypeNode(def.type);
+            return { key: name, annotation };
+        });
+        return this.buildVariablesClass(variablesTypeName, fields);
+    }
+    /** Generate all types for a single operation. Returns joined class blocks. */
+    generateOperation(operation) {
+        var _a, _b, _c;
+        const operationType = operation.operation; // 'query' | 'mutation' | 'subscription'
+        const operationTypeName = operationType.charAt(0).toUpperCase() + operationType.slice(1);
+        const operationName = (_b = (_a = operation.name) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : `Anonymous${this._anonymousCount++}`;
+        const baseName = `${this.pascal(operationName)}${operationTypeName}`;
+        const rootType = this.operationRootTypes[operationType];
+        const out = [];
+        if (rootType) {
+            this.processSelectionSet(rootType, operation.selectionSet, baseName, out);
+        }
+        out.push(this.buildVariables((_c = operation.variableDefinitions) !== null && _c !== void 0 ? _c : [], `${baseName}Variables`));
+        return out.join('\n\n\n');
+    }
+    /** Build the `prepend` import lines, emitting only what is referenced. */
+    getImports() {
+        const imports = [];
+        const typingParts = [];
+        if (this._usesOptional) {
+            typingParts.push('Optional');
+        }
+        // Every operation emits at least a variables TypedDict.
+        typingParts.push('TypedDict');
+        if (this._usesLiteral) {
+            typingParts.push('Literal');
+        }
+        if (this._usesAny) {
+            typingParts.push('Any');
+        }
+        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._baseModel];
+            if (this._usesConfigDict) {
+                parts.push('ConfigDict');
+            }
+            if (this._usesField) {
+                parts.push('Field');
+            }
+            imports.push(`from ${this._runtimeImport} import ${parts.join(', ')}`);
+        }
+        if (this._typesImport) {
+            imports.push(`from ${this._typesImport} import *`);
+        }
+        return imports;
+    }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@graphql-codegen/python-operations",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2-alpha-20261029093428-bb94591c48dc485d04089639f4ca0f124e339666",
+  "description": "Document-driven GraphQL Code Generator plugin that emits Python operation types (per-operation result + variables).",
+  "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",
+    "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,71 @@
+import { RawDocumentsConfig } from '@graphql-codegen/visitor-plugin-common';
+/**
+ * @description This plugin generates Python operation types (per-operation
+ * result + variables `TypedDict`s) from your GraphQL documents.
+ *
+ * It is document-driven (like `@graphql-codegen/typescript-operations`): it
+ * walks each `OperationDefinition` against the schema and recursively emits
+ * named, nested classes for every object selection set. Operation RESULT types
+ * become [pydantic](https://docs.pydantic.dev) `BaseModel` subclasses with
+ * snake_case attributes (each renamed key pinned via `Field(alias=...)`), while
+ * the `<Operation>Variables` type is a `TypedDict` keyed by the WIRE (GraphQL)
+ * variable name (variables are sent to the server as-is).
+ * Every annotation is quoted so forward / recursive references resolve without
+ * ordering constraints.
+ */
+export interface PythonOperationsPluginConfig extends RawDocumentsConfig {
+    /**
+     * @description Controls how GraphQL response keys (field names / aliases) are
+     * turned into Python `BaseModel` result-class attributes. Variable keys are
+     * unaffected — they always keep the wire (GraphQL) name.
+     *
+     * - `'snakeCase'` (default): keys are converted from camelCase to snake_case
+     *   and Python reserved keywords are suffixed with `_`. Each renamed key is
+     *   pinned with `Field(alias=...)` so pydantic hydrates the original wire key
+     *   onto the attribute.
+     * - `'keep'`: response keys are used verbatim; a keyword / non-identifier key
+     *   falls back to a trailing `_` for just that field.
+     *
+     * @default "snakeCase"
+     */
+    namingConvention?: 'keep' | 'snakeCase';
+    /**
+     * @description The base class that generated operation result types extend.
+     * @default "BaseModel"
+     */
+    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`.
+     * @default "pydantic"
+     */
+    runtimeImport?: string;
+    /**
+     * @description Optional module to star-import base schema type names from.
+     *
+     * Generated field annotations reference base type names (enums, input types)
+     * as quoted forward references, e.g. `role: 'Role'`. By default no import for
+     * those names is emitted (the plugin assumes the base types live in the same
+     * file or are provided elsewhere). If set, the plugin prepends
+     * `from {typesImport} import *` so those names resolve at runtime.
+     *
+     * @exampleMarkdown
+     * ```ts filename="codegen.ts"
+     *  import type { CodegenConfig } from '@graphql-codegen/cli';
+     *
+     *  const config: CodegenConfig = {
+     *    generates: {
+     *      'operations.py': {
+     *        plugins: ['@graphql-codegen/python-operations'],
+     *        config: {
+     *          typesImport: 'my_package.schema_types',
+     *        },
+     *      },
+     *    },
+     *  };
+     *  export default config;
+     * ```
+     */
+    typesImport?: string;
+}

package/typings/config.d.ts

@@ -0,0 +1,71 @@
+import { RawDocumentsConfig } from '@graphql-codegen/visitor-plugin-common';
+/**
+ * @description This plugin generates Python operation types (per-operation
+ * result + variables `TypedDict`s) from your GraphQL documents.
+ *
+ * It is document-driven (like `@graphql-codegen/typescript-operations`): it
+ * walks each `OperationDefinition` against the schema and recursively emits
+ * named, nested classes for every object selection set. Operation RESULT types
+ * become [pydantic](https://docs.pydantic.dev) `BaseModel` subclasses with
+ * snake_case attributes (each renamed key pinned via `Field(alias=...)`), while
+ * the `<Operation>Variables` type is a `TypedDict` keyed by the WIRE (GraphQL)
+ * variable name (variables are sent to the server as-is).
+ * Every annotation is quoted so forward / recursive references resolve without
+ * ordering constraints.
+ */
+export interface PythonOperationsPluginConfig extends RawDocumentsConfig {
+    /**
+     * @description Controls how GraphQL response keys (field names / aliases) are
+     * turned into Python `BaseModel` result-class attributes. Variable keys are
+     * unaffected — they always keep the wire (GraphQL) name.
+     *
+     * - `'snakeCase'` (default): keys are converted from camelCase to snake_case
+     *   and Python reserved keywords are suffixed with `_`. Each renamed key is
+     *   pinned with `Field(alias=...)` so pydantic hydrates the original wire key
+     *   onto the attribute.
+     * - `'keep'`: response keys are used verbatim; a keyword / non-identifier key
+     *   falls back to a trailing `_` for just that field.
+     *
+     * @default "snakeCase"
+     */
+    namingConvention?: 'keep' | 'snakeCase';
+    /**
+     * @description The base class that generated operation result types extend.
+     * @default "BaseModel"
+     */
+    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`.
+     * @default "pydantic"
+     */
+    runtimeImport?: string;
+    /**
+     * @description Optional module to star-import base schema type names from.
+     *
+     * Generated field annotations reference base type names (enums, input types)
+     * as quoted forward references, e.g. `role: 'Role'`. By default no import for
+     * those names is emitted (the plugin assumes the base types live in the same
+     * file or are provided elsewhere). If set, the plugin prepends
+     * `from {typesImport} import *` so those names resolve at runtime.
+     *
+     * @exampleMarkdown
+     * ```ts filename="codegen.ts"
+     *  import type { CodegenConfig } from '@graphql-codegen/cli';
+     *
+     *  const config: CodegenConfig = {
+     *    generates: {
+     *      'operations.py': {
+     *        plugins: ['@graphql-codegen/python-operations'],
+     *        config: {
+     *          typesImport: 'my_package.schema_types',
+     *        },
+     *      },
+     *    },
+     *  };
+     *  export default config;
+     * ```
+     */
+    typesImport?: string;
+}

package/typings/index.d.cts

@@ -0,0 +1,11 @@
+import { PluginFunction, Types } from '@graphql-codegen/plugin-helpers';
+import { PythonOperationsPluginConfig } from './config.cjs';
+export * from './config.cjs';
+export * from './visitor.cjs';
+export * from './python-helpers.cjs';
+/**
+ * Document-driven plugin: for each GraphQL operation in the provided documents,
+ * emit a per-operation result `TypedDict` (with named nested `TypedDict`s for
+ * every object selection) plus a `<Operation>Variables` `TypedDict`.
+ */
+export declare const plugin: PluginFunction<PythonOperationsPluginConfig, Types.ComplexPluginOutput>;

package/typings/index.d.ts

@@ -0,0 +1,11 @@
+import { PluginFunction, Types } from '@graphql-codegen/plugin-helpers';
+import { PythonOperationsPluginConfig } from './config.js';
+export * from './config.js';
+export * from './visitor.js';
+export * from './python-helpers.js';
+/**
+ * Document-driven plugin: for each GraphQL operation in the provided documents,
+ * emit a per-operation result `TypedDict` (with named nested `TypedDict`s for
+ * every object selection) plus a `<Operation>Variables` `TypedDict`.
+ */
+export declare const plugin: PluginFunction<PythonOperationsPluginConfig, Types.ComplexPluginOutput>;

package/typings/python-helpers.d.cts

@@ -0,0 +1,18 @@
+import { isReservedField, isValidClassAttr, pythonFieldName as pyFieldName, PYTHON_SCALARS } from '@graphql-codegen/python-common';
+export { isReservedField, isValidClassAttr, PYTHON_SCALARS, pyFieldName };
+export type PythonNamingConvention = 'keep' | 'snakeCase';
+/**
+ * Compute the attribute name for a `BaseModel` result class. Under `'snakeCase'`
+ * the key is snake-cased (keywords suffixed with `_`); under `'keep'` the wire
+ * name is used verbatim, but — because `BaseModel` classes cannot use functional
+ * `TypedDict` syntax — a keyword / non-identifier name still falls back to a
+ * trailing `_`.
+ */
+export declare function resultFieldKey(name: string, convention: PythonNamingConvention): string;
+/**
+ * Compute the `TypedDict` key for a GraphQL response / variable name under the
+ * given naming convention. Under `'keep'` the raw name is returned verbatim
+ * (functional `TypedDict` syntax handles invalid keys); under `'snakeCase'` the
+ * legacy snake_case + `_`-suffix behavior is applied.
+ */
+export declare function fieldKey(name: string, convention: PythonNamingConvention): string;

package/typings/python-helpers.d.ts

@@ -0,0 +1,18 @@
+import { isReservedField, isValidClassAttr, pythonFieldName as pyFieldName, PYTHON_SCALARS } from '@graphql-codegen/python-common';
+export { isReservedField, isValidClassAttr, PYTHON_SCALARS, pyFieldName };
+export type PythonNamingConvention = 'keep' | 'snakeCase';
+/**
+ * Compute the attribute name for a `BaseModel` result class. Under `'snakeCase'`
+ * the key is snake-cased (keywords suffixed with `_`); under `'keep'` the wire
+ * name is used verbatim, but — because `BaseModel` classes cannot use functional
+ * `TypedDict` syntax — a keyword / non-identifier name still falls back to a
+ * trailing `_`.
+ */
+export declare function resultFieldKey(name: string, convention: PythonNamingConvention): string;
+/**
+ * Compute the `TypedDict` key for a GraphQL response / variable name under the
+ * given naming convention. Under `'keep'` the raw name is returned verbatim
+ * (functional `TypedDict` syntax handles invalid keys); under `'snakeCase'` the
+ * legacy snake_case + `_`-suffix behavior is applied.
+ */
+export declare function fieldKey(name: string, convention: PythonNamingConvention): string;

package/typings/visitor.d.cts

@@ -0,0 +1,81 @@
+import { GraphQLSchema, OperationDefinitionNode } from 'graphql';
+import { BaseVisitor } from '@graphql-codegen/visitor-plugin-common';
+import { PythonOperationsPluginConfig } from './config.cjs';
+/**
+ * Walks GraphQL `OperationDefinition` nodes against the schema and recursively
+ * emits named, nested Python `TypedDict` classes for every object selection set,
+ * plus a `<Operation>Variables` `TypedDict` for the operation variables.
+ *
+ * Unlike the C-family `SelectionSetToObject`/`DeclarationBlock` approach (which
+ * emits inline anonymous objects), this mirrors the C#/Java strategy: every
+ * nested selection becomes its own named type referenced by its parent.
+ */
+export declare class PythonOperationsVisitor extends BaseVisitor<PythonOperationsPluginConfig, any> {
+    private _schema;
+    private _typesImport?;
+    private _namingConvention;
+    private _baseModel;
+    private _runtimeImport;
+    private _usesOptional;
+    private _usesAny;
+    private _usesLiteral;
+    private _usesBaseModel;
+    private _usesConfigDict;
+    private _usesField;
+    private _anonymousCount;
+    constructor(schema: GraphQLSchema, rawConfig: PythonOperationsPluginConfig);
+    /** PascalCase a name segment without applying any prefix/suffix. */
+    private pascal;
+    private get operationRootTypes();
+    /**
+     * Build a Python annotation from a (resolved) GraphQL output type. The
+     * `objectBaseName` is the generated nested type name used when the base type
+     * is an object/interface/union selection.
+     */
+    private pyTypeFromGraphQL;
+    private innerFromGraphQL;
+    /**
+     * Build a Python annotation from a variable `TypeNode`. Named types resolve
+     * to mapped scalars, or the bare base type name (enums / input objects).
+     */
+    private pyTypeFromTypeNode;
+    private innerFromTypeNode;
+    /**
+     * Build a variables `TypedDict`. Variable keys are ALWAYS the wire (GraphQL)
+     * name — they are sent to the server as-is. If every key is a valid Python
+     * attribute the readable class syntax is used; otherwise (a key is a keyword /
+     * non-identifier) the functional `TypedDict('Name', { 'key': '...' })` syntax
+     * is emitted so the offending keys remain valid.
+     */
+    private buildVariablesClass;
+    /**
+     * Emit the per-class `__init__` that pre-maps wire keys to their escaped
+     * attribute names before delegating to the base model. Only emitted for result
+     * classes that contain keyword fields.
+     */
+    /**
+     * Render a single result field line: `key: 'annotation'`, with a pydantic
+     * `Field(alias=...)` when the Python attribute differs from the wire response
+     * key, and a `None` default for optional fields.
+     */
+    private renderResultField;
+    /**
+     * Build a result base-model subclass. A field whose Python attribute differs
+     * from the wire key is pinned with `Field(alias=...)`, and a
+     * `model_config = ConfigDict(populate_by_name=True)` line is prepended so such
+     * classes can also be built by attribute name.
+     */
+    private buildResultClass;
+    /**
+     * Emit a `TypedDict` for `selectionSet` (a selection against `parentType`),
+     * named `typeName`. Nested object selections are emitted FIRST (deepest
+     * first) so references resolve top-to-bottom. Returns nothing; classes are
+     * pushed onto `out`.
+     */
+    private processSelectionSet;
+    private buildVariables;
+    /** Generate all types for a single operation. Returns joined class blocks. */
+    generateOperation(operation: OperationDefinitionNode): string;
+    /** Build the `prepend` import lines, emitting only what is referenced. */
+    getImports(): string[];
+}

package/typings/visitor.d.ts

@@ -0,0 +1,81 @@
+import { GraphQLSchema, OperationDefinitionNode } from 'graphql';
+import { BaseVisitor } from '@graphql-codegen/visitor-plugin-common';
+import { PythonOperationsPluginConfig } from './config.js';
+/**
+ * Walks GraphQL `OperationDefinition` nodes against the schema and recursively
+ * emits named, nested Python `TypedDict` classes for every object selection set,
+ * plus a `<Operation>Variables` `TypedDict` for the operation variables.
+ *
+ * Unlike the C-family `SelectionSetToObject`/`DeclarationBlock` approach (which
+ * emits inline anonymous objects), this mirrors the C#/Java strategy: every
+ * nested selection becomes its own named type referenced by its parent.
+ */
+export declare class PythonOperationsVisitor extends BaseVisitor<PythonOperationsPluginConfig, any> {
+    private _schema;
+    private _typesImport?;
+    private _namingConvention;
+    private _baseModel;
+    private _runtimeImport;
+    private _usesOptional;
+    private _usesAny;
+    private _usesLiteral;
+    private _usesBaseModel;
+    private _usesConfigDict;
+    private _usesField;
+    private _anonymousCount;
+    constructor(schema: GraphQLSchema, rawConfig: PythonOperationsPluginConfig);
+    /** PascalCase a name segment without applying any prefix/suffix. */
+    private pascal;
+    private get operationRootTypes();
+    /**
+     * Build a Python annotation from a (resolved) GraphQL output type. The
+     * `objectBaseName` is the generated nested type name used when the base type
+     * is an object/interface/union selection.
+     */
+    private pyTypeFromGraphQL;
+    private innerFromGraphQL;
+    /**
+     * Build a Python annotation from a variable `TypeNode`. Named types resolve
+     * to mapped scalars, or the bare base type name (enums / input objects).
+     */
+    private pyTypeFromTypeNode;
+    private innerFromTypeNode;
+    /**
+     * Build a variables `TypedDict`. Variable keys are ALWAYS the wire (GraphQL)
+     * name — they are sent to the server as-is. If every key is a valid Python
+     * attribute the readable class syntax is used; otherwise (a key is a keyword /
+     * non-identifier) the functional `TypedDict('Name', { 'key': '...' })` syntax
+     * is emitted so the offending keys remain valid.
+     */
+    private buildVariablesClass;
+    /**
+     * Emit the per-class `__init__` that pre-maps wire keys to their escaped
+     * attribute names before delegating to the base model. Only emitted for result
+     * classes that contain keyword fields.
+     */
+    /**
+     * Render a single result field line: `key: 'annotation'`, with a pydantic
+     * `Field(alias=...)` when the Python attribute differs from the wire response
+     * key, and a `None` default for optional fields.
+     */
+    private renderResultField;
+    /**
+     * Build a result base-model subclass. A field whose Python attribute differs
+     * from the wire key is pinned with `Field(alias=...)`, and a
+     * `model_config = ConfigDict(populate_by_name=True)` line is prepended so such
+     * classes can also be built by attribute name.
+     */
+    private buildResultClass;
+    /**
+     * Emit a `TypedDict` for `selectionSet` (a selection against `parentType`),
+     * named `typeName`. Nested object selections are emitted FIRST (deepest
+     * first) so references resolve top-to-bottom. Returns nothing; classes are
+     * pushed onto `out`.
+     */
+    private processSelectionSet;
+    private buildVariables;
+    /** Generate all types for a single operation. Returns joined class blocks. */
+    generateOperation(operation: OperationDefinitionNode): string;
+    /** Build the `prepend` import lines, emitting only what is referenced. */
+    getImports(): string[];
+}