@graphql-codegen/python-operations 0.0.0-stage → 0.0.1

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

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@graphql-codegen/python-operations",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Document-driven GraphQL Code Generator plugin that emits Python operation types (per-operation result + variables).",
+  "repository": "git@github.com:dotansimha/graphql-code-generator-community.git",
+  "license": "MIT",
+  "engines": {
+    "node": ">= 16.0.0"
+  },
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/typings/index.d.cts",
+        "default": "./dist/cjs/index.js"
+      },
+      "import": {
+        "types": "./dist/typings/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "default": {
+        "types": "./dist/typings/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typings": "dist/typings/index.d.ts",
+  "scripts": {
+    "lint": "eslint **/*.ts"
+  },
+  "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.1",
+    "@graphql-codegen/visitor-plugin-common": "^6.3.0",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@graphql-codegen/testing": "4.0.5"
+  },
+  "publishConfig": {
+    "directory": "dist",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "typescript": {
+    "definition": "dist/typings/index.d.ts"
+  }
+}

package/src/config.ts

@@ -0,0 +1,72 @@
+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/src/index.ts

@@ -0,0 +1,34 @@
+import { concatAST, GraphQLSchema, Kind, OperationDefinitionNode } from 'graphql';
+import { PluginFunction, Types } from '@graphql-codegen/plugin-helpers';
+import { PythonOperationsPluginConfig } from './config.js';
+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: PluginFunction<PythonOperationsPluginConfig, Types.ComplexPluginOutput> = (
+  schema: GraphQLSchema,
+  documents: Types.DocumentFile[],
+  config: PythonOperationsPluginConfig,
+) => {
+  const allAst = concatAST(documents.map(d => d.document).filter(Boolean) as any);
+
+  const operations = allAst.definitions.filter(
+    (def): def is OperationDefinitionNode => 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/src/python-helpers.ts

@@ -0,0 +1,34 @@
+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 function resultFieldKey(name: string, convention: PythonNamingConvention): string {
+  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: string, convention: PythonNamingConvention): string {
+  return convention === 'snakeCase' ? pyFieldName(name) : name;
+}

package/src/visitor.ts

@@ -0,0 +1,395 @@
+import {
+  getNamedType,
+  GraphQLInterfaceType,
+  GraphQLObjectType,
+  GraphQLOutputType,
+  GraphQLSchema,
+  isEnumType,
+  isInterfaceType,
+  isListType,
+  isNonNullType,
+  isObjectType,
+  isScalarType,
+  Kind,
+  OperationDefinitionNode,
+  SelectionSetNode,
+  TypeNode,
+  VariableDefinitionNode,
+} from 'graphql';
+import { BaseVisitor, getConfigValue } from '@graphql-codegen/visitor-plugin-common';
+import { PythonOperationsPluginConfig } from './config.js';
+import {
+  isValidClassAttr,
+  PYTHON_SCALARS,
+  PythonNamingConvention,
+  resultFieldKey,
+} from './python-helpers.js';
+
+const INDENT = '    ';
+
+/** GraphQL parent object/interface types can carry field definitions. */
+type SelectableType = GraphQLObjectType | GraphQLInterfaceType;
+
+/**
+ * A single class / `TypedDict` entry. `wire` is the response key on the wire and
+ * is set for result fields — when it differs from `key` the field is pinned with
+ * a pydantic `Field(alias=...)`. Variables entries leave it undefined.
+ */
+interface PyField {
+  key: string;
+  annotation: string;
+  wire?: string;
+}
+
+/**
+ * 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<PythonOperationsPluginConfig, any> {
+  private _schema: GraphQLSchema;
+  private _typesImport?: string;
+  private _namingConvention: PythonNamingConvention;
+  private _baseModel: string;
+  private _runtimeImport: string;
+  private _usesOptional = false;
+  private _usesAny = false;
+  private _usesLiteral = false;
+  private _usesBaseModel = false;
+  private _usesConfigDict = false;
+  private _usesField = false;
+  private _anonymousCount = 0;
+
+  constructor(schema: GraphQLSchema, rawConfig: PythonOperationsPluginConfig) {
+    // 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._schema = schema;
+    this._typesImport = rawConfig.typesImport;
+    this._namingConvention = getConfigValue(
+      rawConfig.namingConvention,
+      'snakeCase',
+    ) as PythonNamingConvention;
+    this._baseModel = getConfigValue(rawConfig.baseModel, 'BaseModel') as string;
+    this._runtimeImport = getConfigValue(rawConfig.runtimeImport, 'pydantic') as string;
+  }
+
+  /** PascalCase a name segment without applying any prefix/suffix. */
+  private pascal(name: string): string {
+    return this.convertName(name, {
+      useTypesPrefix: false,
+      useTypesSuffix: false,
+    });
+  }
+
+  private get operationRootTypes(): Record<string, SelectableType | null | undefined> {
+    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.
+   */
+  private pyTypeFromGraphQL(type: GraphQLOutputType, objectBaseName: string): string {
+    if (isNonNullType(type)) {
+      return this.innerFromGraphQL(type.ofType, objectBaseName);
+    }
+    this._usesOptional = true;
+    return `Optional[${this.innerFromGraphQL(type, objectBaseName)}]`;
+  }
+
+  private innerFromGraphQL(type: GraphQLOutputType, objectBaseName: string): string {
+    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).
+   */
+  private pyTypeFromTypeNode(type: TypeNode): string {
+    if (type.kind === Kind.NON_NULL_TYPE) {
+      return this.innerFromTypeNode(type.type);
+    }
+    this._usesOptional = true;
+    return `Optional[${this.innerFromTypeNode(type)}]`;
+  }
+
+  private innerFromTypeNode(type: TypeNode): string {
+    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.
+   */
+  private buildVariablesClass(name: string, fields: PyField[]): string {
+    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.
+   */
+  private renderResultField(field: PyField): string {
+    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.
+   */
+  private buildResultClass(name: string, fields: PyField[]): string {
+    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`.
+   */
+  private processSelectionSet(
+    parentType: SelectableType,
+    selectionSet: SelectionSetNode,
+    typeName: string,
+    out: string[],
+  ): void {
+    const fields: PyField[] = [];
+
+    const addField = (responseKey: string, annotation: string): void => {
+      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 = selection.typeCondition?.name.value ?? 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 = fieldNode.alias?.value ?? 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 as SelectableType,
+          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));
+  }
+
+  private buildVariables(
+    variableDefinitions: readonly VariableDefinitionNode[],
+    variablesTypeName: string,
+  ): string {
+    const fields: PyField[] = 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. */
+  public generateOperation(operation: OperationDefinitionNode): string {
+    const operationType = operation.operation; // 'query' | 'mutation' | 'subscription'
+    const operationTypeName = operationType.charAt(0).toUpperCase() + operationType.slice(1);
+
+    const operationName = operation.name?.value ?? `Anonymous${this._anonymousCount++}`;
+    const baseName = `${this.pascal(operationName)}${operationTypeName}`;
+
+    const rootType = this.operationRootTypes[operationType];
+    const out: string[] = [];
+
+    if (rootType) {
+      this.processSelectionSet(rootType, operation.selectionSet, baseName, out);
+    }
+
+    out.push(this.buildVariables(operation.variableDefinitions ?? [], `${baseName}Variables`));
+
+    return out.join('\n\n\n');
+  }
+
+  /** Build the `prepend` import lines, emitting only what is referenced. */
+  public getImports(): string[] {
+    const imports: string[] = [];
+
+    const typingParts: string[] = [];
+    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;
+  }
+}