@typra/emitter 0.2.0

package/dist/src/languages/python/emitter.js

@@ -0,0 +1,856 @@
+/**
+ * Python code emitter — Declaration IR → Python source code.
+ *
+ * Replaces `file.py.njk` + `_macros.njk` (~619 lines of Nunjucks templates)
+ * with a typed TypeScript function that walks the FileDecl tree.
+ *
+ * The emitter produces correctly-formatted Python 3.11+ code using modern
+ * `X | None` union syntax. Output should be byte-identical to the template
+ * output after ruff+black formatting.
+ *
+ * Structural blocks emitted (in order):
+ *   1. Header comment (auto-generated warning)
+ *   2. Imports (abc, dataclasses, typing, context, local types)
+ *   3. For each type in the file:
+ *      a. @dataclass class definition with docstring
+ *      b. _shorthand_property ClassVar
+ *      c. Field declarations with type annotations + defaults
+ *      d. load() static method
+ *      e. Collection helpers (load_X / save_X)
+ *      f. Polymorphic dispatch (load_<discriminator>)
+ *      g. save() instance method
+ *      h. to_yaml() and to_json() methods
+ *      i. Factory classmethods
+ *      j. Method stubs (as comments)
+ */
+import { toSnakeCase } from "../../ir/utilities.js";
+/**
+ * Type mapping from TypeSpec scalar types to Python types.
+ */
+const TYPE_MAP = {
+    "string": "str",
+    "number": "float",
+    "array": "list",
+    "object": "dict",
+    "boolean": "bool",
+    "int64": "int",
+    "int32": "int",
+    "float64": "float",
+    "float32": "float",
+    "integer": "int",
+    "float": "float",
+    "numeric": "float",
+    "any": "Any",
+    "dictionary": "dict[str, Any]",
+};
+function paramType(typeStr) {
+    if (typeStr === "string")
+        return "str";
+    if (typeStr === "boolean")
+        return "bool";
+    if (typeStr === "integer" || typeStr === "int32" || typeStr === "int64")
+        return "int";
+    if (typeStr === "float" || typeStr === "float64" || typeStr === "float32")
+        return "float";
+    return "Any";
+}
+function returnType(typeStr) {
+    if (typeStr === "string")
+        return "str";
+    if (typeStr === "boolean")
+        return "bool";
+    if (typeStr === "integer" || typeStr === "int32" || typeStr === "int64")
+        return "int";
+    if (typeStr === "float" || typeStr === "float64" || typeStr === "float32")
+        return "float";
+    return typeStr;
+}
+// ============================================================================
+// Main entry point
+// ============================================================================
+/**
+ * Emit a complete Python file from a FileDecl.
+ */
+export function emitPythonFile(decl, visitor, group = "") {
+    const lines = [];
+    // 1. Header
+    lines.push("##########################################");
+    lines.push("# WARNING: This is an auto-generated file.");
+    lines.push("# DO NOT EDIT THIS FILE DIRECTLY");
+    lines.push("# ANY EDITS WILL BE LOST");
+    lines.push("##########################################");
+    lines.push("");
+    // 2. Imports — sorted alphabetically as ruff/isort would
+    // Collect all import lines, then sort them
+    const stdlibImports = [];
+    const localImports = [];
+    const hasProtocol = decl.types.some(t => t.isProtocol);
+    const hasNonProtocol = decl.types.some(t => !t.isProtocol);
+    const hasMethodHelpers = decl.types.some(t => !t.isProtocol && t.methods.length > 0);
+    if (decl.containsAbstract) {
+        stdlibImports.push("from abc import ABC");
+    }
+    if (hasNonProtocol) {
+        stdlibImports.push("from dataclasses import dataclass, field");
+    }
+    const typingImports = ["Any"];
+    if (hasNonProtocol)
+        typingImports.push("ClassVar");
+    if (decl.enums.length > 0)
+        typingImports.push("Literal");
+    if (hasProtocol || hasMethodHelpers)
+        typingImports.push("Protocol", "runtime_checkable");
+    typingImports.sort();
+    stdlibImports.push(`from typing import ${typingImports.join(", ")}`);
+    // Context import — go up one level when inside a group subfolder
+    if (hasNonProtocol) {
+        const ctxPrefix = group ? ".." : ".";
+        localImports.push(`from ${ctxPrefix}_context import LoadContext, SaveContext`);
+    }
+    // Cross-group and same-group type imports
+    for (const imp of decl.imports) {
+        if (imp.group === group) {
+            // Same group (or both root): relative sibling import
+            localImports.push(`from ._${imp.module} import ${imp.names.join(", ")}`);
+        }
+        else if (imp.group) {
+            // Different non-empty group: go up to model root, then into the group subfolder
+            localImports.push(`from ..${imp.group}._${imp.module} import ${imp.names.join(", ")}`);
+        }
+        else {
+            // Imported module is at model root (no group): go up one level
+            localImports.push(`from .._${imp.module} import ${imp.names.join(", ")}`);
+        }
+    }
+    localImports.sort();
+    for (const line of stdlibImports) {
+        lines.push(line);
+    }
+    lines.push("");
+    for (const line of localImports) {
+        lines.push(line);
+    }
+    // 2.5. Enum type aliases
+    if (decl.enums.length > 0) {
+        lines.push("");
+        for (const enumDef of decl.enums) {
+            const values = enumDef.values.map(v => `"${v}"`).join(", ");
+            if (enumDef.isOpen) {
+                // Open enum — Literal values or any str
+                lines.push(`${enumDef.name} = Literal[${values}] | str`);
+            }
+            else {
+                lines.push(`${enumDef.name} = Literal[${values}]`);
+            }
+        }
+    }
+    // 3. Emit each type
+    for (const type of decl.types) {
+        lines.push("");
+        lines.push("");
+        emitType(type, lines, visitor);
+    }
+    return lines.join("\n") + "\n";
+}
+// ============================================================================
+// Type emission
+// ============================================================================
+function emitType(type, lines, visitor) {
+    const name = type.typeName.name;
+    // Protocol types → emit as Protocol class with method signatures
+    if (type.isProtocol) {
+        emitProtocolClass(type, lines);
+        return;
+    }
+    // Class definition
+    lines.push("@dataclass");
+    const bases = [];
+    if (type.base)
+        bases.push(type.base.name);
+    if (type.isAbstract)
+        bases.push("ABC");
+    const baseSuffix = bases.length > 0 ? `(${bases.join(", ")})` : "";
+    lines.push(`class ${name}${baseSuffix}:`);
+    // Docstring
+    emitDocstring(type, lines);
+    // _shorthand_property ClassVar
+    lines.push("");
+    const shorthand = type.coercionProperty ? `"${type.coercionProperty}"` : "None";
+    lines.push(`    _shorthand_property: ClassVar[str | None] = ${shorthand}`);
+    // Field declarations (blank line between _shorthand and first field)
+    lines.push("");
+    for (const field of type.fields) {
+        lines.push(`    ${toSnakeCase(field.name)}: ${pythonTypeAnnotation(field)}${pythonDefaultValue(field)}`);
+    }
+    // load() method
+    lines.push("");
+    emitLoadMethod(type, lines);
+    // Collection helpers (between load and polymorphic dispatch)
+    for (const helper of type.collectionHelpers) {
+        emitCollectionLoadHelper(name, helper, lines);
+        lines.push("");
+        emitCollectionSaveHelper(name, helper, lines);
+    }
+    // Polymorphic dispatch
+    if (type.polymorphicDispatch) {
+        lines.push("");
+        lines.push("");
+        emitPolymorphicDispatch(name, type.polymorphicDispatch, type.isAbstract, lines);
+    }
+    // save() method
+    lines.push("");
+    emitSaveMethod(type, lines);
+    // to_wire() method (only when wire mappings exist)
+    if (type.wire) {
+        emitToWireMethod(type, lines);
+    }
+    // to_yaml() method
+    emitToYaml(name, lines);
+    // to_json() method
+    emitToJson(name, lines);
+    // Factory methods
+    if (type.factories.length > 0) {
+        const fieldNames = new Set(type.fields.map(f => f.name));
+        lines.push("");
+        for (const factory of type.factories) {
+            emitFactory(name, factory, visitor, fieldNames, lines);
+            lines.push("");
+        }
+    }
+    lines.push("");
+    // Method stubs — emit as a sibling Protocol class outside the dataclass
+    if (type.methods.length > 0) {
+        emitMethodHelpersProtocol(type, lines);
+    }
+}
+/**
+ * Emit a typing.Protocol class named `<TypeName>Helpers` that declares the
+ * `@method` contract for a concrete type. The generated dataclass does NOT
+ * satisfy this Protocol on its own — runtime code must provide an
+ * implementation (either by attaching methods to the class or by providing
+ * a wrapper type). Using `@runtime_checkable` allows isinstance() checks.
+ */
+function emitMethodHelpersProtocol(type, lines) {
+    const name = type.typeName.name;
+    lines.push("");
+    lines.push("");
+    lines.push("@runtime_checkable");
+    lines.push(`class ${name}Helpers(Protocol):`);
+    lines.push(`    """Helper contract for ${name}.`);
+    lines.push("");
+    lines.push(`    Runtime implementations must provide these methods on every ${name}`);
+    lines.push("    instance (either by attaching them to the generated class or by wrapping it).");
+    lines.push("    The type checker can verify conformance by annotating against this Protocol");
+    lines.push(`    or by calling isinstance(instance, ${name}Helpers) at runtime.`);
+    lines.push(`    """`);
+    for (const m of type.methods) {
+        const params = Object.entries(m.params)
+            .map(([pName, pType]) => `${toSnakeCase(pName)}: ${protocolType(pType)}`)
+            .join(", ");
+        const paramList = params ? `, ${params}` : "";
+        const ret = protocolType(m.returns);
+        const snakeName = toSnakeCase(m.name);
+        // Zero-param, non-verb methods are emitted as @property — idiomatic Python
+        // for accessor-style helpers (matches the C# emitter's heuristic).
+        const isProperty = Object.keys(m.params).length === 0 && !isMethodStyle(m.name);
+        lines.push("");
+        if (isProperty) {
+            lines.push("    @property");
+        }
+        lines.push(`    def ${snakeName}(self${paramList}) -> ${ret}:`);
+        if (m.description) {
+            lines.push(`        """${m.description}"""`);
+        }
+        lines.push("        ...");
+    }
+}
+/**
+ * Verbs that indicate an action — zero-param @methods whose name starts with
+ * one of these are emitted as regular Python methods. Everything else becomes
+ * a ``@property``. Mirrors the C# emitter's heuristic so both runtimes expose
+ * ``message.text`` as a property and ``message.to_text_content()`` as a method.
+ */
+const PY_METHOD_VERB_PREFIXES = [
+    "to", "get", "set", "fetch", "compute", "make", "build", "create",
+    "load", "save", "convert", "parse", "format", "render", "serialize",
+    "deserialize", "find", "calculate", "invoke", "execute", "run",
+];
+function isMethodStyle(name) {
+    const lower = name.toLowerCase();
+    for (const prefix of PY_METHOD_VERB_PREFIXES) {
+        if (lower === prefix)
+            return true;
+        if (lower.startsWith(prefix) && name.length > prefix.length) {
+            const next = name[prefix.length];
+            if (next === next.toUpperCase() && next !== next.toLowerCase()) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+// ============================================================================
+// Protocol class emission
+// ============================================================================
+/** Map a protocol type string to a Python type annotation. */
+function protocolType(typeStr) {
+    // Handle nullable types
+    if (typeStr.endsWith("?")) {
+        const inner = typeStr.slice(0, -1);
+        return `${protocolType(inner)} | None`;
+    }
+    // Handle array types
+    if (typeStr.endsWith("[]")) {
+        const inner = typeStr.slice(0, -2);
+        return `list[${protocolType(inner)}]`;
+    }
+    // Handle Record/dict types
+    if (typeStr === "Record<unknown>" || typeStr === "dictionary")
+        return "dict[str, Any]";
+    if (typeStr === "unknown" || typeStr === "any")
+        return "Any";
+    // Scalar types
+    const mapped = TYPE_MAP[typeStr];
+    if (mapped)
+        return mapped;
+    return typeStr;
+}
+/**
+ * Emit a Python Protocol class for a protocol type.
+ * Uses typing.Protocol for structural subtyping.
+ */
+function emitProtocolClass(type, lines) {
+    const name = type.typeName.name;
+    lines.push("@runtime_checkable");
+    lines.push(`class ${name}(Protocol):`);
+    // Docstring
+    if (type.description) {
+        const descLines = type.description.split("\n");
+        lines.push(`    """${descLines[0]}`);
+        for (let i = 1; i < descLines.length; i++) {
+            lines.push(`    ${descLines[i]}`);
+        }
+        lines.push(`    """`);
+    }
+    if (type.methods.length === 0) {
+        lines.push("    ...");
+        return;
+    }
+    for (const method of type.methods) {
+        const params = Object.entries(method.params)
+            .map(([pName, pType]) => `${toSnakeCase(pName)}: ${protocolType(pType)}`)
+            .join(", ");
+        const ret = protocolType(method.returns);
+        // Sync method
+        lines.push("");
+        if (method.description) {
+            lines.push(`    def ${toSnakeCase(method.name)}(self, ${params}) -> ${ret}:`);
+            lines.push(`        """${method.description}"""`);
+            if (method.optional) {
+                lines.push("        return None");
+            }
+            else {
+                lines.push("        ...");
+            }
+        }
+        else {
+            if (method.optional) {
+                lines.push(`    def ${toSnakeCase(method.name)}(self, ${params}) -> ${ret}:`);
+                lines.push("        return None");
+            }
+            else {
+                lines.push(`    def ${toSnakeCase(method.name)}(self, ${params}) -> ${ret}: ...`);
+            }
+        }
+        // Async variant (skip for sync-only methods)
+        if (!method.sync) {
+            lines.push("");
+            if (method.description) {
+                lines.push(`    async def ${toSnakeCase(method.name)}_async(self, ${params}) -> ${ret}:`);
+                lines.push(`        """${method.description} (async variant)"""`);
+                if (method.optional) {
+                    lines.push("        return None");
+                }
+                else {
+                    lines.push("        ...");
+                }
+            }
+            else {
+                if (method.optional) {
+                    lines.push(`    async def ${toSnakeCase(method.name)}_async(self, ${params}) -> ${ret}:`);
+                    lines.push("        return None");
+                }
+                else {
+                    lines.push(`    async def ${toSnakeCase(method.name)}_async(self, ${params}) -> ${ret}: ...`);
+                }
+            }
+        }
+    }
+    lines.push("");
+}
+// ============================================================================
+// Docstring
+// ============================================================================
+function emitDocstring(type, lines) {
+    const descLines = type.description.split("\n");
+    lines.push(`    """${descLines[0]}`);
+    for (let i = 1; i < descLines.length; i++) {
+        lines.push(`    ${descLines[i]}`);
+    }
+    if (type.fields.length > 0) {
+        lines.push("    ");
+        lines.push("    Attributes");
+        lines.push("    ----------");
+        for (const f of type.fields) {
+            lines.push(`    ${toSnakeCase(f.name)} : ${pythonDocstringType(f)}`);
+            lines.push(`        ${f.description}`);
+        }
+    }
+    lines.push(`    """`);
+}
+// ============================================================================
+// Type annotations — uses modern X | None syntax
+// ============================================================================
+function pythonTypeAnnotation(f) {
+    // Named enum field — use the enum type alias
+    if (f.enumName && f.allowedValues.length > 0) {
+        return f.isOptional ? `${f.enumName} | None` : f.enumName;
+    }
+    const cat = f.category;
+    switch (cat.kind) {
+        case "dict":
+            return f.isOptional ? "dict[str, Any] | None" : "dict[str, Any]";
+        case "collection_scalar":
+            return `list[${TYPE_MAP[cat.scalarType] || "Any"}]`;
+        case "collection_complex":
+            return `list[${cat.typeName}]`;
+        case "scalar": {
+            const pyType = TYPE_MAP[cat.scalarType] || "Any";
+            return f.isOptional ? `${pyType} | None` : pyType;
+        }
+        case "complex":
+            return f.isOptional ? `${cat.typeName} | None` : cat.typeName;
+    }
+}
+function pythonDocstringType(f) {
+    const cat = f.category;
+    let baseType;
+    switch (cat.kind) {
+        case "dict":
+            baseType = "dict[str, Any]";
+            break;
+        case "collection_scalar":
+            baseType = `list[${TYPE_MAP[cat.scalarType] || "Any"}]`;
+            break;
+        case "collection_complex":
+            baseType = `list[${cat.typeName}]`;
+            break;
+        case "scalar":
+            baseType = TYPE_MAP[cat.scalarType] || "Any";
+            break;
+        case "complex":
+            baseType = cat.typeName;
+            break;
+    }
+    if (f.isOptional)
+        return `Optional[${baseType}]`;
+    return baseType;
+}
+// ============================================================================
+// Default values
+// ============================================================================
+function pythonDefaultValue(f) {
+    const cat = f.category;
+    if (cat.kind === "collection_scalar" || cat.kind === "collection_complex") {
+        return " = field(default_factory=list)";
+    }
+    if (f.isOptional) {
+        return " = None";
+    }
+    // Enum fields — use the field's default value or the first allowed value
+    if (f.enumName && f.allowedValues.length > 0) {
+        const dv = typeof f.defaultValue === "string" && f.allowedValues.includes(f.defaultValue)
+            ? f.defaultValue
+            : f.allowedValues[0];
+        return ` = field(default="${dv}")`;
+    }
+    if (cat.kind === "scalar") {
+        const t = cat.scalarType;
+        if (t === "boolean") {
+            return ` = field(default=${f.defaultValue ? "True" : "False"})`;
+        }
+        if (t === "string") {
+            return ` = field(default="${f.defaultValue ?? ""}")`;
+        }
+        if (t === "number" || t === "numeric" || t === "float64" || t === "float32" || t === "float") {
+            return ` = field(default=${f.defaultValue ?? "0.0"})`;
+        }
+        if (t === "int64" || t === "int32" || t === "integer") {
+            return ` = field(default=${f.defaultValue ?? "0"})`;
+        }
+        if (t === "dictionary") {
+            return " = field(default_factory=dict)";
+        }
+        return ` = field(default=${f.defaultValue ?? "None"})`;
+    }
+    if (cat.kind === "dict") {
+        return " = field(default_factory=dict)";
+    }
+    if (cat.kind === "complex") {
+        return ` = field(default_factory=${f.typeName.name})`;
+    }
+    return " = None";
+}
+// ============================================================================
+// load() method
+// ============================================================================
+function emitLoadMethod(type, lines) {
+    const name = type.typeName.name;
+    lines.push("    @staticmethod");
+    lines.push(`    def load(data: Any, context: LoadContext | None = None) -> "${name}":`);
+    lines.push(`        """Load a ${name} instance.`);
+    lines.push("        Args:");
+    lines.push("            data (Any): The data to load the instance from.");
+    lines.push("            context (Optional[LoadContext]): Optional context with pre/post processing callbacks.");
+    lines.push("        Returns:");
+    lines.push(`            ${name}: The loaded ${name} instance.`);
+    lines.push("");
+    lines.push(`        """`);
+    lines.push("");
+    lines.push("        if context is not None:");
+    lines.push("            data = context.process_input(data)");
+    // Coercion checks — direct property setting instead of dict construction
+    if (type.load.coercions.length > 0) {
+        lines.push("        ");
+        lines.push("        # handle alternate representations");
+        for (const c of type.load.coercions) {
+            emitCoercionBranch(name, c, type, lines);
+        }
+    }
+    lines.push("        ");
+    lines.push(`        if not isinstance(data, dict):`);
+    lines.push(`            raise ValueError(f"Invalid data for ${name}: {data}")`);
+    // Create instance (polymorphic dispatch or direct)
+    if (type.load.hasPolymorphicDispatch && type.polymorphicDispatch) {
+        const discSnake = toSnakeCase(type.polymorphicDispatch.discriminatorField);
+        lines.push("");
+        lines.push(`        # load polymorphic ${name} instance`);
+        lines.push(`        instance = ${name}.load_${discSnake}(data, context)`);
+    }
+    else {
+        lines.push("");
+        lines.push(`        # create new instance`);
+        lines.push(`        instance = ${name}()`);
+    }
+    // Blank line(s) after instance creation
+    lines.push("");
+    if (type.load.hasPolymorphicDispatch) {
+        lines.push("");
+    }
+    // Per-property assignments
+    for (const a of type.load.assignments) {
+        lines.push(`        if data is not None and "${a.sourceName}" in data:`);
+        lines.push(`            ${emitLoadAssignment(a)}`);
+    }
+    // Context post-processing
+    lines.push("        if context is not None:");
+    lines.push("            instance = context.process_output(instance)");
+    lines.push("        return instance");
+    lines.push("");
+    lines.push("");
+}
+function emitLoadAssignment(a) {
+    const snake = toSnakeCase(a.fieldName);
+    const cat = a.category;
+    switch (cat.kind) {
+        case "scalar":
+        case "dict":
+        case "collection_scalar":
+            return `instance.${snake} = data["${a.sourceName}"]`;
+        case "collection_complex":
+            return `instance.${snake} = ${a.parentTypeName}.load_${snake}(data["${a.sourceName}"], context)`;
+        case "complex":
+            return `instance.${snake} = ${cat.typeName}.load(data["${a.sourceName}"], context)`;
+    }
+}
+/**
+ * Emit a single coercion branch — direct property setting with early return.
+ *
+ * For types where the coercion involves a dynamic discriminator with child
+ * variants, falls back to calling the dispatch method.
+ */
+function emitCoercionBranch(typeName, c, type, lines) {
+    const pyScalar = TYPE_MAP[c.scalarType] || c.scalarType;
+    lines.push(`        if isinstance(data, ${pyScalar}):`);
+    if (c.needsDispatch && type.polymorphicDispatch) {
+        // Dynamic discriminator — must go through dispatch
+        const discSnake = toSnakeCase(type.polymorphicDispatch.discriminatorField);
+        // Build a minimal dict for the dispatch method
+        const dictFields = c.assignments.map(a => {
+            const val = a.isInput ? "data" : `"${a.literalValue}"`;
+            return `"${a.fieldName}": ${val}`;
+        });
+        lines.push(`            return ${typeName}.load_${discSnake}({${dictFields.join(", ")}}, context)`);
+    }
+    else {
+        // Direct property setting — no intermediate dict
+        lines.push(`            instance = ${typeName}()`);
+        for (const a of c.assignments) {
+            const snake = toSnakeCase(a.fieldName);
+            if (a.isInput) {
+                lines.push(`            instance.${snake} = data`);
+            }
+            else {
+                lines.push(`            instance.${snake} = "${a.literalValue}"`);
+            }
+        }
+        lines.push("            if context is not None:");
+        lines.push("                instance = context.process_output(instance)");
+        lines.push("            return instance");
+    }
+}
+// ============================================================================
+// Collection helpers (load_X / save_X)
+// ============================================================================
+function emitCollectionLoadHelper(parentName, helper, lines) {
+    const snake = toSnakeCase(helper.propertyName);
+    const elemName = helper.elementTypeName.name;
+    const firstInnerField = helper.innerFields[0] || "kind";
+    lines.push("");
+    lines.push("    @staticmethod");
+    lines.push(`    def load_${snake}(data: dict | list, context: LoadContext | None) -> list[${elemName}]:`);
+    lines.push("        if isinstance(data, dict):");
+    lines.push(`            # convert simple named ${helper.propertyName} to list of ${elemName}`);
+    lines.push("            result = []");
+    lines.push("            for k, v in data.items():");
+    lines.push("                if isinstance(v, dict):");
+    lines.push("                    # value is an object, spread its properties");
+    lines.push(`                    result.append({"name": k, **v})`);
+    lines.push("                else:");
+    lines.push("                    # value is a scalar, use it as the primary property");
+    lines.push(`                    result.append({"name": k, "${firstInnerField}": v})`);
+    lines.push("            data = result");
+    lines.push(`        return [${elemName}.load(item, context) for item in data]`);
+}
+function emitCollectionSaveHelper(parentName, helper, lines) {
+    const snake = toSnakeCase(helper.propertyName);
+    const elemName = helper.elementTypeName.name;
+    lines.push("    @staticmethod");
+    lines.push(`    def save_${snake}(items: list[${elemName}], context: SaveContext | None) -> dict[str, Any] | list[dict[str, Any]]:`);
+    lines.push("        if context is None:");
+    lines.push("            context = SaveContext()");
+    if (helper.hasNameProperty) {
+        lines.push("");
+        lines.push('        if context.collection_format == "array":');
+        lines.push("            return [item.save(context) for item in items]");
+        lines.push("");
+        lines.push("        # Object format: use name as key");
+        lines.push("        result: dict[str, Any] = {}");
+        lines.push("        for item in items:");
+        lines.push("            item_data = item.save(context)");
+        lines.push('            name = item_data.pop("name", None)');
+        lines.push("            if name:");
+        lines.push("                # Check if we can use shorthand (only primary property set)");
+        lines.push("                if context.use_shorthand and hasattr(item, '_shorthand_property'):");
+        lines.push("                    shorthand_prop = item._shorthand_property");
+        lines.push("                    if shorthand_prop and len(item_data) == 1 and shorthand_prop in item_data:");
+        lines.push("                        result[name] = item_data[shorthand_prop]");
+        lines.push("                        continue");
+        lines.push("                result[name] = item_data");
+        lines.push("            else:");
+        lines.push('                # No name, fall back to array format for this item');
+        lines.push('                if "_unnamed" not in result:');
+        lines.push('                    result["_unnamed"] = []');
+        lines.push('                result["_unnamed"].append(item_data)');
+        lines.push("        return result");
+    }
+    else {
+        lines.push("");
+        lines.push("        # This type doesn't have a 'name' property, so always use array format");
+        lines.push("        return [item.save(context) for item in items]");
+    }
+}
+// ============================================================================
+// Polymorphic dispatch
+// ============================================================================
+function emitPolymorphicDispatch(parentName, dispatch, isAbstract, lines) {
+    const discSnake = toSnakeCase(dispatch.discriminatorField);
+    lines.push("    @staticmethod");
+    lines.push(`    def load_${discSnake}(data: dict, context: LoadContext | None) -> "${parentName}":`);
+    lines.push(`        # load polymorphic ${parentName} instance`);
+    lines.push(`        if data is not None and "${dispatch.discriminatorField}" in data:`);
+    lines.push(`            discriminator_value = str(data["${dispatch.discriminatorField}"]).lower()`);
+    for (let i = 0; i < dispatch.variants.length; i++) {
+        const v = dispatch.variants[i];
+        const keyword = i === 0 ? "if" : "elif";
+        lines.push(`            ${keyword} discriminator_value == "${v.value}":`);
+        lines.push(`                return ${v.typeName.name}.load(data, context)`);
+    }
+    // Default handling — matches template whitespace exactly
+    if (dispatch.defaultVariant) {
+        lines.push("");
+        lines.push("            else:");
+        if (dispatch.defaultVariant.isSelfReference) {
+            lines.push(`                # create new instance (stop recursion)`);
+            lines.push(`                return ${parentName}()`);
+        }
+        else {
+            lines.push("");
+            lines.push(`                # load default instance`);
+            lines.push(`                return ${dispatch.defaultVariant.typeName.name}.load(data, context)`);
+        }
+    }
+    else {
+        lines.push("");
+        lines.push("            else:");
+        lines.push(`                raise ValueError(f"Unknown ${parentName} discriminator value: {discriminator_value}")`);
+    }
+    lines.push("        else:");
+    if (isAbstract) {
+        lines.push("");
+        lines.push(`            raise ValueError("Missing ${parentName} discriminator property: '${dispatch.discriminatorField}'")`);
+    }
+    else {
+        lines.push(`            # create new instance`);
+        lines.push(`            return ${parentName}()`);
+    }
+    lines.push("");
+}
+// ============================================================================
+// save() method
+// ============================================================================
+function emitSaveMethod(type, lines) {
+    const name = type.typeName.name;
+    lines.push(`    def save(self, context: SaveContext | None = None) -> dict[str, Any]:`);
+    lines.push(`        """Save the ${name} instance to a dictionary.`);
+    lines.push("        Args:");
+    lines.push("            context (Optional[SaveContext]): Optional context with pre/post processing callbacks.");
+    lines.push("        Returns:");
+    lines.push("            dict[str, Any]: The dictionary representation of this instance.");
+    lines.push("");
+    lines.push(`        """`);
+    lines.push("        obj = self");
+    lines.push("        if context is not None:");
+    lines.push("            obj = context.process_object(obj)");
+    lines.push("");
+    if (type.save.hasBase) {
+        lines.push("");
+        lines.push("        # Start with parent class properties");
+        lines.push("        result = super().save(context)");
+        lines.push("");
+    }
+    else {
+        lines.push("");
+        lines.push("        result: dict[str, Any] = {}");
+    }
+    // Per-property save assignments
+    lines.push("");
+    for (const a of type.save.assignments) {
+        const snake = toSnakeCase(a.fieldName);
+        lines.push(`        if obj.${snake} is not None:`);
+        lines.push(`            ${emitSaveAssignment(a)}`);
+    }
+    // Context post-processing (only for root types without base)
+    if (!type.save.hasBase) {
+        lines.push("");
+        lines.push("        if context is not None:");
+        lines.push("            result = context.process_dict(result)");
+    }
+    lines.push("        return result");
+    lines.push("");
+}
+function emitSaveAssignment(a) {
+    const snake = toSnakeCase(a.fieldName);
+    const cat = a.category;
+    switch (cat.kind) {
+        case "scalar":
+        case "dict":
+        case "collection_scalar":
+            return `result["${a.targetName}"] = obj.${snake}`;
+        case "collection_complex":
+            return `result["${a.targetName}"] = ${a.parentTypeName}.save_${snake}(obj.${snake}, context)`;
+        case "complex":
+            return `result["${a.targetName}"] = obj.${snake}.save(context)`;
+    }
+}
+// ============================================================================
+// to_wire() method
+// ============================================================================
+function emitToWireMethod(type, lines) {
+    const name = type.typeName.name;
+    const wire = type.wire;
+    lines.push(`    def to_wire(self, provider: str) -> dict[str, Any]:`);
+    lines.push(`        """Convert to provider-specific wire format.`);
+    lines.push("        Args:");
+    lines.push("            provider (str): The provider to convert to (e.g., \"openai\", \"anthropic\").");
+    lines.push("        Returns:");
+    lines.push("            dict[str, Any]: The wire-format dictionary with provider-specific field names.");
+    lines.push("");
+    lines.push(`        """`);
+    lines.push("        data = self.save()");
+    lines.push("        result: dict[str, Any] = {}");
+    // Build the wire_map literal from the IR mappings
+    lines.push("        wire_map: dict[str, dict[str, str]] = {");
+    for (const mapping of wire.mappings) {
+        const entries = Object.entries(mapping.wireNames)
+            .map(([provider, wireName]) => `"${provider}": "${wireName}"`)
+            .join(", ");
+        lines.push(`            "${mapping.fieldName}": {${entries}},`);
+    }
+    lines.push("        }");
+    lines.push("        for key, value in data.items():");
+    lines.push("            mapping = wire_map.get(key)");
+    lines.push("            if mapping is not None and provider in mapping:");
+    lines.push("                result[mapping[provider]] = value");
+    lines.push("        return result");
+    lines.push("");
+}
+// ============================================================================
+// to_yaml() / to_json() methods
+// ============================================================================
+function emitToYaml(name, lines) {
+    lines.push(`    def to_yaml(self, context: SaveContext | None = None) -> str:`);
+    lines.push(`        """Convert the ${name} instance to a YAML string.`);
+    lines.push("        Args:");
+    lines.push("            context (Optional[SaveContext]): Optional context with pre/post processing callbacks.");
+    lines.push("        Returns:");
+    lines.push("            str: The YAML string representation of this instance.");
+    lines.push("");
+    lines.push(`        """`);
+    lines.push("        if context is None:");
+    lines.push("            context = SaveContext()");
+    lines.push("        return context.to_yaml(self.save(context))");
+    lines.push("");
+}
+function emitToJson(name, lines) {
+    lines.push(`    def to_json(self, context: SaveContext | None = None, indent: int = 2) -> str:`);
+    lines.push(`        """Convert the ${name} instance to a JSON string.`);
+    lines.push("        Args:");
+    lines.push("            context (Optional[SaveContext]): Optional context with pre/post processing callbacks.");
+    lines.push("            indent (int): Number of spaces for indentation. Defaults to 2.");
+    lines.push("        Returns:");
+    lines.push("            str: The JSON string representation of this instance.");
+    lines.push("");
+    lines.push(`        """`);
+    lines.push("        if context is None:");
+    lines.push("            context = SaveContext()");
+    lines.push("        return context.to_json(self.save(context), indent)");
+    lines.push("");
+}
+// ============================================================================
+// Factory methods
+// ============================================================================
+function emitFactory(parentName, factory, visitor, fieldNames, lines) {
+    const params = Object.entries(factory.params)
+        .map(([pName, pType]) => `${toSnakeCase(pName)}: ${paramType(pType)}`)
+        .join(", ");
+    const paramStr = params ? `, ${params}` : "";
+    // In Python, a @classmethod with the same name as a dataclass field shadows
+    // the field's default. Prefix with create_ to avoid the collision.
+    const methodName = fieldNames.has(factory.name) ? `create_${factory.name}` : factory.name;
+    lines.push("    @classmethod");
+    lines.push(`    def ${methodName}(cls${paramStr}) -> "${parentName}":`);
+    lines.push(`        """Create a ${parentName} with preset field values."""`);
+    lines.push(`        return ${visitor.visitExpr(factory.body)}`);
+}
+//# sourceMappingURL=emitter.js.map