usage/sdk/python/

mod.rs

use std::path::PathBuf;

use crate::case::{AsPascalCase, AsSnakeCase};

use crate::sdk::{
    collect_choice_types, collect_type_imports, command_type_name, escape_py_docstring,
    escape_py_string, flag_names, generated_header, ChoiceTypeMap, CodeWriter, SdkFile, SdkOptions,
    SdkOutput,
};
use crate::spec::arg::SpecDoubleDashChoices;
use crate::spec::cmd::SpecCommand;
use crate::spec::config::{SpecConfigProp, SpecConfigValue};
use crate::spec::data_types::SpecDataTypes;
use crate::Framing;
use crate::{Spec, SpecArg, SpecFlag};

fn sanitize_py_comment(text: &str) -> String {
    text.replace(['\n', '\r'], " ")
}

mod runtime;

pub fn generate(spec: &Spec, opts: &SdkOptions) -> SdkOutput {
    let package_name = opts
        .package_name
        .clone()
        .unwrap_or_else(|| spec.bin.clone());

    SdkOutput {
        files: vec![
            SdkFile {
                path: PathBuf::from("types.py"),
                content: render_types(spec, &package_name, &opts.source_file),
            },
            SdkFile {
                path: PathBuf::from("client.py"),
                content: render_client(spec, &package_name, &opts.source_file),
            },
            SdkFile {
                path: PathBuf::from("runtime.py"),
                content: runtime::RUNTIME_PY.to_string(),
            },
            SdkFile {
                path: PathBuf::from("__init__.py"),
                content: render_init(&package_name),
            },
        ],
    }
}

fn render_init(package_name: &str) -> String {
    let class_name = AsPascalCase(package_name).to_string();
    format!(
        "from .client import {class_name}\n\
         from .runtime import CliError, CliJsonResult, CliResult, CliRunner, CliStream\n\
         from .types import *\n"
    )
}

// ---------------------------------------------------------------------------
// types.py
// ---------------------------------------------------------------------------

fn render_types(spec: &Spec, package_name: &str, source_file: &Option<String>) -> String {
    let mut w = CodeWriter::with_indent("    ");

    w.line(&generated_header("#", source_file));
    w.line("from __future__ import annotations");
    w.line("from dataclasses import dataclass");
    // `Any` only where an output alias needs it, so a client with no declared outputs is
    // generated exactly as before.
    if any_outputs(&spec.cmd, spec, package_name) {
        w.line("from typing import Any, Literal, Optional");
    } else {
        w.line("from typing import Literal, Optional");
    }
    w.line("");

    // spec metadata
    if let Some(version) = &spec.version {
        w.line(&format!("VERSION = \"{}\"", escape_py_string(version)));
    }
    if let Some(about) = &spec.about {
        w.line(&format!("ABOUT = \"{}\"", escape_py_string(about)));
    }
    if let Some(author) = &spec.author {
        w.line(&format!("AUTHOR = \"{}\"", escape_py_string(author)));
    }

    let choice_types = collect_choice_types(&spec.cmd);
    let root_global_flags: Vec<&SpecFlag> = spec
        .cmd
        .flags
        .iter()
        .filter(|f| f.global && !f.hide)
        .collect();
    let has_global_flags = !root_global_flags.is_empty();

    if !choice_types.is_empty() {
        w.line("");
        for (name, choices) in choice_types.iter() {
            let union = choices
                .iter()
                .map(|c| format!("\"{}\"", escape_py_string(c)))
                .collect::<Vec<_>>()
                .join(", ");
            w.line(&format!("{name} = Literal[{union}]"));
        }
    }

    if has_global_flags {
        w.line("");
        render_flags_dataclass(
            "GlobalFlags",
            &spec.cmd.name,
            &spec.cmd.name,
            &root_global_flags,
            &choice_types,
            &mut w,
        );
    }

    render_command_types(
        &spec.cmd,
        package_name,
        &spec.cmd.name,
        &choice_types,
        has_global_flags,
        &root_global_flags,
        spec,
        &mut w,
    );

    if !spec.config.props.is_empty() {
        w.line("");
        let config_name = format!("{}Config", AsPascalCase(package_name));
        w.line("");
        w.line("@dataclass");
        w.line(&format!("class {config_name}:"));
        w.indent();
        // Python dataclass requires non-default fields before default fields
        let (required, optional): (Vec<_>, Vec<_>) = spec
            .config
            .props
            .iter()
            .partition(|(_, p)| p.default.is_none());

        for (name, prop) in required.iter().chain(optional.iter()) {
            let py_type = config_prop_type(prop);
            // Rendered by the *declared* type, falling back to the literal's own when
            // none is declared — a spec may say `data_type=float default="1.5"`, and the
            // declaration is what the generated field is typed as. No `#true`-spelling or
            // quote-stripping to undo any more: the spec keeps values, not source text.
            // A bare Python literal only for a value that *is* one. Anything else is a
            // quoted string, escaped.
            //
            // This is generated code that gets imported, so text from the spec must never
            // reach it unquoted: a `data_type="integer"` whose default is the string
            // `__import__("os").system(…)` would otherwise be written as an expression and
            // run on import. Numeric strings are read as numbers when the spec parses, so
            // by here a `String` is a string.
            let default = match &prop.default {
                None => String::new(),
                Some(SpecConfigValue::Bool(b)) => {
                    format!(" = {}", if *b { "True" } else { "False" })
                }
                Some(SpecConfigValue::Int(i)) => format!(" = {i}"),
                Some(SpecConfigValue::Float(f)) => format!(" = {f:?}"),
                Some(SpecConfigValue::String(s)) => {
                    format!(" = \"{}\"", escape_py_string(s))
                }
            };
            if let Some(help) = &prop.help {
                w.line(&format!("# {}", sanitize_py_comment(help)));
            }
            w.line(&format!("{name}: {py_type}{default}"));
        }
        w.dedent();
    }

    w.finish()
}

#[allow(clippy::too_many_arguments)]
fn render_command_types(
    cmd: &SpecCommand,
    package_name: &str,
    root_cmd_name: &str,
    choice_types: &ChoiceTypeMap,
    has_global_flags: bool,
    global_flags: &[&SpecFlag],
    spec: &Spec,
    w: &mut CodeWriter,
) {
    if cmd.hide {
        return;
    }

    let name = command_type_name(cmd, package_name);
    let cmd_name = &cmd.name;
    let visible_args: Vec<&SpecArg> = cmd.args.iter().filter(|a| !a.hide).collect();
    let visible_flags: Vec<&SpecFlag> = cmd.flags.iter().filter(|f| !f.hide).collect();

    if !visible_args.is_empty() {
        w.line("");
        render_args_dataclass(
            &format!("{name}Args"),
            cmd_name,
            &visible_args,
            choice_types,
            w,
        );
    }

    if !visible_flags.is_empty() {
        w.line("");
        let all_flags: Vec<&SpecFlag> = if has_global_flags {
            global_flags
                .iter()
                .copied()
                .chain(
                    visible_flags
                        .iter()
                        .filter(|f| !global_flags.iter().any(|gf| gf.name == f.name))
                        .copied(),
                )
                .collect()
        } else {
            visible_flags
        };
        render_flags_dataclass(
            &format!("{name}Flags"),
            cmd_name,
            root_cmd_name,
            &all_flags,
            choice_types,
            w,
        );
    }

    // One alias per declared output, plus the schema and exit-code table beside it. The
    // alias is `Any` today and a `TypedDict` later: every generated signature names it
    // rather than `Any` directly, so filling it in is a substitution no caller sees.
    let outputs = crate::sdk::output_methods(cmd, spec, package_name);
    if !outputs.is_empty() {
        w.line("");
        for output in &outputs {
            if let Some(help) = &output.help {
                w.line(&format!("# {}", sanitize_py_comment(help)));
            }
            w.line(&format!("{} = Any", output.type_alias));
        }
    }
    for output in &outputs {
        // A string rather than a literal, so a schema that is not valid JSON cannot emit
        // a module that fails to import. `json.loads` it to hand to a validator.
        if let (Some(const_name), Some(schema)) = (&output.schema_const, &output.schema) {
            w.line("");
            w.line(&format!(
                "{const_name}: str = \"{}\"",
                escape_py_string(schema)
            ));
        }
    }
    let exit_codes = crate::sdk::exit_codes_for(cmd, spec);
    if !exit_codes.is_empty() {
        let entries = exit_codes
            .iter()
            .map(|e| format!("{}: \"{}\"", e.code, escape_py_string(&e.help)))
            .collect::<Vec<_>>()
            .join(", ");
        let union = exit_codes
            .iter()
            .map(|e| e.code.to_string())
            .collect::<Vec<_>>()
            .join(", ");
        let exit_name = crate::sdk::command_path_type_name(cmd, package_name);
        w.line("");
        w.line(&format!(
            "{}_EXIT_CODES: dict[int, str] = {{{entries}}}",
            crate::sdk::shouty(&exit_name)
        ));
        w.line(&format!("{exit_name}ExitCode = Literal[{union}]"));
    }

    for subcmd in cmd.subcommands.values() {
        render_command_types(
            subcmd,
            package_name,
            root_cmd_name,
            choice_types,
            has_global_flags,
            global_flags,
            spec,
            w,
        );
    }
}

fn render_args_dataclass(
    name: &str,
    cmd_name: &str,
    args: &[&SpecArg],
    choice_types: &ChoiceTypeMap,
    w: &mut CodeWriter,
) {
    w.line("");
    w.line("@dataclass");
    w.line(&format!("class {name}:"));
    w.indent();
    if args.is_empty() {
        w.line("pass");
    } else {
        // Python dataclass requires non-default fields before default fields
        let (required, optional): (Vec<_>, Vec<_>) = args
            .iter()
            .copied()
            .partition(|a| a.required && a.default.is_empty());

        for arg in required.iter().chain(optional.iter()) {
            let py_type = arg_py_type(arg, cmd_name, choice_types);
            let is_required_no_default = arg.required && arg.default.is_empty();
            let field = if !is_required_no_default && !arg.default.is_empty() {
                // has default value
                let default_val = &arg.default[0];
                format!(
                    "{}: Optional[{}] = \"{}\"",
                    sanitize_py_ident(&arg.name),
                    py_type,
                    escape_py_string(default_val)
                )
            } else if !is_required_no_default {
                // optional without explicit default
                format!(
                    "{}: Optional[{}] = None",
                    sanitize_py_ident(&arg.name),
                    py_type
                )
            } else {
                // required, no default
                format!("{}: {}", sanitize_py_ident(&arg.name), py_type)
            };
            if let Some(help) = &arg.help {
                w.line(&format!("# {}", sanitize_py_comment(help)));
            }
            w.line(&field);
        }
    }
    w.dedent();
}

fn render_flags_dataclass(
    name: &str,
    cmd_name: &str,
    root_cmd_name: &str,
    flags: &[&SpecFlag],
    choice_types: &ChoiceTypeMap,
    w: &mut CodeWriter,
) {
    w.line("");
    w.line("@dataclass");
    w.line(&format!("class {name}:"));
    w.indent();
    if flags.is_empty() {
        w.line("pass");
    } else {
        // Python dataclass requires non-default fields before default fields
        let (required, optional): (Vec<_>, Vec<_>) = flags
            .iter()
            .copied()
            .partition(|f| f.required && f.default.is_empty());

        for flag in required.iter().chain(optional.iter()) {
            let lookup_cmd = if flag.global { root_cmd_name } else { cmd_name };
            let py_type = flag_py_type(flag, lookup_cmd, choice_types);
            let prop_name = flag_property_name_py(flag);
            let optional = !(flag.required && flag.default.is_empty());
            let field = if !flag.default.is_empty() {
                // has explicit default — use first value
                let default_val = &flag.default[0];
                if flag.count {
                    let numeric = default_val.trim();
                    if let Ok(n) = numeric.parse::<i64>() {
                        format!("{prop_name}: {py_type} = {n}")
                    } else {
                        // invalid count default — cannot emit as valid Python int;
                        // fall back to 0 with a comment
                        format!(
                            "{prop_name}: {py_type} = 0  # default: {}",
                            sanitize_py_comment(default_val)
                        )
                    }
                } else if flag.arg.is_none() {
                    // boolean with default
                    match default_val.as_str() {
                        "true" | "#true" => format!("{prop_name}: {py_type} = True"),
                        "false" | "#false" => format!("{prop_name}: {py_type} = False"),
                        _ => {
                            // unrecognized boolean default — cannot emit as valid Python bool;
                            // fall back to Optional[bool] = None with a comment
                            format!(
                                "{prop_name}: Optional[bool] = None  # default: {}",
                                sanitize_py_comment(default_val)
                            )
                        }
                    }
                } else if flag.var {
                    // var flag with a default — list defaults are mutable and forbidden in dataclasses.
                    // use None and preserve the intended default in a comment.
                    format!(
                        "{prop_name}: Optional[{py_type}] = None  # default: {}",
                        sanitize_py_comment(default_val)
                    )
                } else {
                    format!(
                        "{prop_name}: Optional[{py_type}] = \"{}\"",
                        escape_py_string(default_val)
                    )
                }
            } else if optional {
                format!("{prop_name}: Optional[{py_type}] = None")
            } else {
                format!("{prop_name}: {py_type}")
            };
            let mut doc_parts = Vec::new();
            if let Some(help) = &flag.help {
                doc_parts.push(help.clone());
            }
            if let Some(env) = &flag.env {
                doc_parts.push(format!("Env: {env}"));
            }
            if let Some(deprecated) = &flag.deprecated {
                doc_parts.push(format!("Deprecated: {deprecated}"));
            }
            if flag.long.len() > 1 {
                let aliases: Vec<&str> = flag.long.iter().skip(1).map(|s| s.as_str()).collect();
                doc_parts.push(format!("Aliases: {}", aliases.join(", ")));
            }
            if !flag.short.is_empty() {
                let shorts: Vec<String> = flag.short.iter().map(|c| format!("-{c}")).collect();
                doc_parts.push(format!("Short: {}", shorts.join(", ")));
            }
            if !doc_parts.is_empty() {
                w.line(&format!("# {}", sanitize_py_comment(&doc_parts.join(". "))));
            }
            w.line(&field);
        }
    }
    w.dedent();
}

fn arg_py_type(arg: &SpecArg, cmd_name: &str, choice_types: &ChoiceTypeMap) -> String {
    let base = if let Some(choices) = &arg.choices {
        if let Some(resolved) = choice_types.lookup(cmd_name, &arg.name) {
            resolved.to_string()
        } else {
            let union = choices
                .choices
                .iter()
                .map(|c| format!("\"{}\"", escape_py_string(c)))
                .collect::<Vec<_>>()
                .join(", ");
            format!("Literal[{union}]")
        }
    } else {
        "str".to_string()
    };

    if arg.var {
        format!("list[{base}]")
    } else {
        base
    }
}

fn flag_py_type(flag: &SpecFlag, cmd_name: &str, choice_types: &ChoiceTypeMap) -> String {
    if flag.count {
        return "int".to_string();
    }

    match &flag.arg {
        Some(arg) => {
            let base = if let Some(choices) = &arg.choices {
                if let Some(resolved) = choice_types.lookup(cmd_name, &flag.name) {
                    resolved.to_string()
                } else {
                    let union = choices
                        .choices
                        .iter()
                        .map(|c| format!("\"{}\"", escape_py_string(c)))
                        .collect::<Vec<_>>()
                        .join(", ");
                    format!("Literal[{union}]")
                }
            } else {
                "str".to_string()
            };

            if flag.var {
                format!("list[{base}]")
            } else {
                base
            }
        }
        None => {
            if flag.var {
                "list[bool]".to_string()
            } else {
                "bool".to_string()
            }
        }
    }
}

fn config_prop_type(prop: &SpecConfigProp) -> String {
    match prop.data_type {
        SpecDataTypes::String => "str".to_string(),
        SpecDataTypes::Integer => "int".to_string(),
        SpecDataTypes::Float => "float".to_string(),
        SpecDataTypes::Boolean => "bool".to_string(),
        SpecDataTypes::Null => "object".to_string(),
    }
}

fn flag_property_name_py(flag: &SpecFlag) -> String {
    // Python uses snake_case for attributes
    if let Some(long) = flag.long.first() {
        return sanitize_py_ident(&AsSnakeCase(long).to_string());
    }
    if let Some(short) = flag.short.first() {
        return short.to_string();
    }
    sanitize_py_ident(&flag.name)
}

fn sanitize_py_ident(name: &str) -> String {
    let snake = AsSnakeCase(name).to_string();
    match snake.as_str() {
        "async" | "await" | "nonlocal" | "class" | "def" | "return" | "import" | "from"
        | "global" | "lambda" | "pass" | "raise" | "with" | "yield" | "del" | "try" | "except"
        | "finally" | "while" | "for" | "if" | "elif" | "else" | "and" | "or" | "not" | "in"
        | "is" | "as" | "break" | "continue" | "assert" | "type" | "input" | "id" | "list"
        | "dict" | "set" | "print" | "range" | "format" | "help" | "vars" | "dir" | "exec"
        | "exit" | "quit" | "bool" | "int" | "str" | "float" | "bytes" | "object" | "super"
        | "property" | "static" | "true" | "false" | "none" => format!("_{snake}"),
        _ => snake,
    }
}

// ---------------------------------------------------------------------------
// client.py
// ---------------------------------------------------------------------------

fn render_client(spec: &Spec, package_name: &str, source_file: &Option<String>) -> String {
    let mut w = CodeWriter::with_indent("    ");

    w.line(&generated_header("#", source_file));
    w.line("from __future__ import annotations");
    w.line("from typing import Optional");
    if any_outputs(&spec.cmd, spec, package_name) {
        w.line("from .runtime import CliJsonResult, CliResult, CliRunner, CliStream");
    } else {
        w.line("from .runtime import CliResult, CliRunner");
    }

    // collect imports from types
    let choice_types = collect_choice_types(&spec.cmd);
    let type_imports = collect_type_imports(&spec.cmd, package_name, &choice_types, spec);
    let has_global_flags = spec.cmd.flags.iter().any(|f| f.global && !f.hide);
    let mut all_imports = type_imports;
    if has_global_flags {
        all_imports.push("GlobalFlags".to_string());
    }
    all_imports.sort();
    all_imports.dedup();
    if !all_imports.is_empty() {
        w.line(&format!("from .types import {}", all_imports.join(", ")));
    }

    w.line("");

    let global_flags: Vec<&SpecFlag> = spec
        .cmd
        .flags
        .iter()
        .filter(|f| f.global && !f.hide)
        .collect();

    let class_name = AsPascalCase(package_name).to_string();
    render_class(
        &spec.cmd,
        &class_name,
        true,
        &global_flags,
        &spec.bin,
        spec,
        package_name,
        &mut w,
    );

    w.finish()
}

#[allow(clippy::too_many_arguments)]
fn render_class(
    cmd: &SpecCommand,
    class_name: &str,
    is_root: bool,
    global_flags: &[&SpecFlag],
    bin_name: &str,
    spec: &Spec,
    package_name: &str,
    w: &mut CodeWriter,
) {
    let visible_subcmds: Vec<_> = cmd.subcommands.iter().filter(|(_, c)| !c.hide).collect();

    let visible_args: Vec<&SpecArg> = cmd.args.iter().filter(|a| !a.hide).collect();
    let visible_flags: Vec<&SpecFlag> = cmd.flags.iter().filter(|f| !f.hide).collect();
    let has_args = !visible_args.is_empty();
    let has_flags = !visible_flags.is_empty() || !global_flags.is_empty();

    // docstring on class
    let mut class_doc = Vec::new();
    if let Some(help) = &cmd.help {
        class_doc.push(help.clone());
    } else if let Some(about) = &cmd.help_long {
        class_doc.push(about.clone());
    }
    if let Some(deprecated) = &cmd.deprecated {
        class_doc.push(format!("DEPRECATED: {deprecated}"));
    }
    if !cmd.aliases.is_empty() {
        class_doc.push(format!("Aliases: {}", cmd.aliases.join(", ")));
    }

    w.line(&format!("class {class_name}:"));
    w.indent();

    if !class_doc.is_empty() {
        w.line(&format!(
            "\"\"\"{}\"\"\"",
            escape_py_docstring(&class_doc.join(". "))
        ));
    }

    // constructor
    if is_root {
        w.line(&format!(
            "def __init__(self, bin_path: str = \"{}\") -> None:",
            escape_py_string(bin_name)
        ));
    } else {
        w.line("def __init__(self, runner: CliRunner) -> None:");
    }
    w.indent();
    if is_root {
        w.line("self._runner = CliRunner(bin_path)");
    } else {
        w.line("self._runner = runner");
    }
    for (name, _) in &visible_subcmds {
        let sub_class = AsPascalCase(name).to_string();
        let prop = sanitize_py_ident(name);
        w.line(&format!("self.{prop} = {sub_class}(self._runner)"));
    }
    w.dedent();

    // exec method — build signature with four explicit arms to avoid double comma
    let flags_type = if !global_flags.is_empty() && !visible_flags.is_empty() {
        format!("{class_name}Flags")
    } else if !global_flags.is_empty() && visible_flags.is_empty() {
        "GlobalFlags".to_string()
    } else if !visible_flags.is_empty() {
        format!("{class_name}Flags")
    } else {
        String::new()
    };
    let outputs = crate::sdk::output_methods(cmd, spec, package_name);
    // A command with declared outputs builds its argv in a helper, so `exec` and each
    // per-output method share one copy of the assembly. A command without one keeps the
    // body inline under `exec`, which is why no existing client regenerates.
    let (method, ret) = if outputs.is_empty() {
        ("exec", "CliResult")
    } else {
        ("_cmd_args", "list[str]")
    };
    let omit_param = if outputs.is_empty() {
        ""
    } else {
        ", _omit: str = \"\""
    };
    let sig = if has_args && !flags_type.is_empty() {
        format!("def {method}(self, args: {class_name}Args, flags: Optional[{flags_type}] = None{omit_param}) -> {ret}:")
    } else if has_args {
        format!("def {method}(self, args: {class_name}Args{omit_param}) -> {ret}:")
    } else if !flags_type.is_empty() {
        format!("def {method}(self, flags: Optional[{flags_type}] = None{omit_param}) -> {ret}:")
    } else {
        format!("def {method}(self{omit_param}) -> {ret}:")
    };

    // docstring on exec
    let mut exec_doc = Vec::new();
    if !cmd.usage.is_empty() {
        exec_doc.push(cmd.usage.clone());
    }
    for example in &cmd.examples {
        let label = example.header.as_deref().unwrap_or("Example");
        exec_doc.push(format!("{label}: {code}", code = example.code));
    }
    let exit_codes = crate::sdk::exit_codes_for(cmd, spec);
    if !exit_codes.is_empty() {
        exec_doc.push(format!(
            "Exit codes: {}.",
            exit_codes
                .iter()
                .map(|e| format!("{} — {}", e.code, e.help))
                .collect::<Vec<_>>()
                .join("; ")
        ));
    }
    // The argv helper is internal, so the docstring moves to the methods a caller sees.
    let caller_doc = exec_doc.clone();
    if !outputs.is_empty() {
        exec_doc.clear();
    }

    w.line("");
    if !exec_doc.is_empty() {
        w.line(&sig);
        w.indent();
        if exec_doc.len() == 1 {
            w.line(&format!(
                "\"\"\"{}\"\"\"",
                escape_py_docstring(&exec_doc[0])
            ));
        } else {
            w.line(&format!("\"\"\"{}", escape_py_docstring(&exec_doc[0])));
            for part in exec_doc.iter().skip(1) {
                w.line(&escape_py_docstring(part));
            }
            w.line("\"\"\"");
        }
    } else {
        w.line(&sig);
        w.indent();
    }

    let path: String = cmd
        .full_cmd
        .iter()
        .map(|s| format!("\"{}\"", escape_py_string(s)))
        .collect::<Vec<_>>()
        .join(", ");
    w.line(&format!("cmd_args: list[str] = [{path}]"));

    if has_args {
        let has_required_double_dash = visible_args
            .iter()
            .any(|a| matches!(a.double_dash, SpecDoubleDashChoices::Required));
        let has_automatic_double_dash = visible_args
            .iter()
            .any(|a| matches!(a.double_dash, SpecDoubleDashChoices::Automatic));

        // Args before `--`: all args without double_dash=required
        for arg in &visible_args {
            if matches!(arg.double_dash, SpecDoubleDashChoices::Required) {
                continue;
            }
            let ident = sanitize_py_ident(&arg.name);
            if let Some(sigil) = &arg.sigil {
                let sigil = escape_py_string(sigil);
                if arg.var {
                    w.line(&format!(
                        "if args.{ident} is not None: cmd_args.extend(\"{sigil}\" + str(value) for value in args.{ident})"
                    ));
                } else {
                    w.line(&format!(
                        "if args.{ident} is not None: cmd_args.append(\"{sigil}\" + str(args.{ident}))"
                    ));
                }
            } else if arg.var {
                w.line(&format!(
                    "if args.{ident} is not None: cmd_args.extend(args.{ident})"
                ));
            } else {
                w.line(&format!(
                    "if args.{ident} is not None: cmd_args.append(str(args.{ident}))"
                ));
            }
        }

        if has_required_double_dash {
            w.line("cmd_args.append(\"--\")");
            // Args after `--`: only double_dash=required args
            for arg in &visible_args {
                if !matches!(arg.double_dash, SpecDoubleDashChoices::Required) {
                    continue;
                }
                let ident = sanitize_py_ident(&arg.name);
                if arg.var {
                    w.line(&format!(
                        "if args.{ident} is not None: cmd_args.extend(args.{ident})"
                    ));
                } else {
                    w.line(&format!(
                        "if args.{ident} is not None: cmd_args.append(str(args.{ident}))"
                    ));
                }
            }
        } else if has_automatic_double_dash {
            w.line("# double_dash=automatic: \"--\" is implied after the first positional arg");
        }
    }

    let omit_arg = if outputs.is_empty() { "" } else { ", _omit" };
    if outputs.is_empty() {
        if has_flags {
            w.line("flag_args = self._build_flag_args(flags)");
            w.line("return self._runner.run(cmd_args + flag_args)");
        } else {
            w.line("return self._runner.run(cmd_args)");
        }
    } else if has_flags {
        w.line(&format!(
            "flag_args = self._build_flag_args(flags{omit_arg})"
        ));
        w.line("return cmd_args + flag_args");
    } else {
        w.line("return cmd_args");
    }
    w.dedent();

    // `exec` and one method per declared output, all thin delegates over `_cmd_args`.
    if !outputs.is_empty() {
        let call = match (has_args, flags_type.is_empty()) {
            (true, false) => "args, flags",
            (true, true) => "args",
            (false, false) => "flags",
            (false, true) => "",
        };
        let params = match (has_args, flags_type.is_empty()) {
            (true, false) => {
                format!("self, args: {class_name}Args, flags: Optional[{flags_type}] = None")
            }
            (true, true) => format!("self, args: {class_name}Args"),
            (false, false) => format!("self, flags: Optional[{flags_type}] = None"),
            (false, true) => "self".to_string(),
        };
        let comma = if call.is_empty() { "" } else { ", " };

        let write_doc = |w: &mut CodeWriter, doc: &[String]| {
            if doc.is_empty() {
                return;
            }
            if doc.len() == 1 {
                w.line(&format!("\"\"\"{}\"\"\"", escape_py_docstring(&doc[0])));
            } else {
                w.line(&format!("\"\"\"{}", escape_py_docstring(&doc[0])));
                for part in doc.iter().skip(1) {
                    w.line(&escape_py_docstring(part));
                }
                w.line("\"\"\"");
            }
        };

        w.line("");
        w.line(&format!("def exec({params}) -> CliResult:"));
        w.indent();
        write_doc(w, &caller_doc);
        w.line(&format!("return self._runner.run(self._cmd_args({call}))"));
        w.dedent();

        for output in &outputs {
            let (ret, runner) = match output.framing {
                Framing::Jsonl => ("CliStream", "run_jsonl"),
                _ => ("CliJsonResult", "run_json"),
            };
            let mut doc = Vec::new();
            if let Some(help) = &output.help {
                doc.push(help.clone());
            }
            doc.push(format!(
                "Selected with `{}`; any value of it in `flags` is ignored.",
                output.select.join(" ")
            ));
            if output.framing == Framing::Jsonl {
                doc.push(
                    "One object per line, as they arrive: iterate it rather than \
                     collecting, and close it if you stop early."
                        .to_string(),
                );
            }
            doc.extend(caller_doc.iter().cloned());

            // The property name a caller would have set, not the flag's spelling: the two
            // differ wherever `sanitize_py_ident` had to move out of the way of a keyword.
            let omit = output
                .omit
                .as_deref()
                .and_then(|name| {
                    global_flags
                        .iter()
                        .copied()
                        .chain(visible_flags.iter().copied())
                        .find(|f| flag_names(f, name))
                        .map(flag_property_name_py)
                })
                .unwrap_or_default();
            let selector = output
                .select
                .iter()
                .map(|w| format!("\"{}\"", escape_py_string(w)))
                .collect::<Vec<_>>()
                .join(", ");
            w.line("");
            w.line(&format!("def exec_{}({params}) -> {ret}:", output.suffix));
            w.indent();
            write_doc(w, &doc);
            w.line(&format!(
                "cmd_args = self._cmd_args({call}{comma}\"{omit}\")"
            ));
            w.line(&format!("cmd_args.extend([{selector}])"));
            w.line(&format!("return self._runner.{runner}(cmd_args)"));
            w.dedent();
        }
    }

    // _build_flag_args
    if has_flags {
        w.line("");
        let omit_param = if outputs.is_empty() {
            String::new()
        } else {
            ", _omit: str = \"\"".to_string()
        };
        w.line(&format!(
            "def _build_flag_args(self, flags: Optional[{flags_type}]{omit_param}) -> list[str]:"
        ));
        w.indent();
        w.line("result: list[str] = []");
        w.line("if flags is None: return result");

        let omit = outputs.iter().find_map(|o| o.omit.clone());
        let render = |flag: &SpecFlag, w: &mut CodeWriter| {
            // The selecting flag is left out when a method already picked the output, so a
            // caller-supplied `format` cannot end up on the line twice contradicting it.
            // Compared by property name, which is what a caller actually set.
            let guarded = omit.as_deref().is_some_and(|name| flag_names(flag, name));
            if guarded {
                let prop = flag_property_name_py(flag);
                w.line(&format!("if _omit != \"{prop}\":"));
                w.indent();
                render_flag_build_py(flag, w);
                w.dedent();
            } else {
                render_flag_build_py(flag, w);
            }
        };
        for flag in global_flags {
            render(flag, w);
        }
        for flag in &visible_flags {
            // skip global flags already rendered above
            if !global_flags.iter().any(|gf| gf.name == flag.name) {
                render(flag, w);
            }
        }

        w.line("return result");
        w.dedent();
    }

    // alias properties for subcommand aliases
    for (name, subcmd) in &visible_subcmds {
        for alias in &subcmd.aliases {
            let alias_prop = sanitize_py_ident(alias);
            let target_prop = sanitize_py_ident(name);
            let sub_class = AsPascalCase(name).to_string();
            w.line("");
            w.line("@property");
            w.line(&format!("def {alias_prop}(self) -> {sub_class}:"));
            w.indent();
            w.line(&format!(
                "\"\"\"Alias for {}.\"\"\"",
                escape_py_docstring(name)
            ));
            w.line(&format!("return self.{target_prop}"));
            w.dedent();
        }
    }

    w.dedent(); // end class

    // render subcommand classes
    for (name, subcmd) in &visible_subcmds {
        w.line("");
        let sub_class = AsPascalCase(name).to_string();
        render_class(
            subcmd,
            &sub_class,
            false,
            global_flags,
            bin_name,
            spec,
            package_name,
            w,
        );
    }
}

fn render_flag_build_py(flag: &SpecFlag, w: &mut CodeWriter) {
    let prop_name = flag_property_name_py(flag);
    let flag_arg_name = if let Some(long) = flag.long.first() {
        format!("--{}", escape_py_string(long))
    } else if let Some(short) = flag.short.first() {
        format!("-{short}")
    } else {
        format!("--{}", escape_py_string(&flag.name))
    };

    if flag.arg.is_some() {
        if flag.var {
            w.line(&format!("if flags.{prop_name} is not None:"));
            w.indent();
            w.line(&format!(
                "for v in flags.{prop_name}: result.extend([\"{flag_arg_name}\", str(v)])"
            ));
            w.dedent();
        } else {
            w.line(&format!(
                "if flags.{prop_name} is not None: result.extend([\"{flag_arg_name}\", str(flags.{prop_name})])"
            ));
        }
    } else if flag.count {
        w.line(&format!(
            "if flags.{prop_name} is not None and flags.{prop_name} > 0: result.extend([\"{flag_arg_name}\"] * flags.{prop_name})"
        ));
    } else if flag.var {
        w.line(&format!("if flags.{prop_name} is not None:"));
        w.indent();
        w.line(&format!("for v in flags.{prop_name}:"));
        w.indent();
        w.line(&format!("if v: result.append(\"{flag_arg_name}\")"));
        w.dedent();
        w.dedent();
    } else {
        w.line(&format!(
            "if flags.{prop_name}: result.append(\"{flag_arg_name}\")"
        ));
        if let Some(negate) = &flag.negate {
            w.line(&format!(
                "elif flags.{prop_name} is False: result.append(\"{}\")",
                escape_py_string(negate)
            ));
        }
    }
}

/// Whether anything in the tree declares an output, so the generated imports carry only
/// what is used.
fn any_outputs(cmd: &SpecCommand, spec: &Spec, package_name: &str) -> bool {
    !crate::sdk::output_methods(cmd, spec, package_name).is_empty()
        || cmd
            .subcommands
            .values()
            .any(|sub| any_outputs(sub, spec, package_name))
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use crate::sdk::{SdkLanguage, SdkOptions};
    use crate::test::SPEC_KITCHEN_SINK;
    use crate::Spec;

    fn make_opts() -> SdkOptions {
        SdkOptions {
            language: SdkLanguage::Python,
            package_name: None,
            source_file: Some("test.usage.kdl".to_string()),
        }
    }

    fn get_file<'a>(output: &'a crate::sdk::SdkOutput, name: &str) -> &'a str {
        output
            .files
            .iter()
            .find(|f| f.path.to_str() == Some(name))
            .unwrap_or_else(|| panic!("{name} should exist"))
            .content
            .as_str()
    }

    #[test]
    fn test_python_types() {
        let output = crate::sdk::generate(&SPEC_KITCHEN_SINK, &make_opts());
        insta::assert_snapshot!(get_file(&output, "types.py"));
    }

    #[test]
    fn test_python_client() {
        let output = crate::sdk::generate(&SPEC_KITCHEN_SINK, &make_opts());
        insta::assert_snapshot!(get_file(&output, "client.py"));
    }

    #[test]
    fn structured_output_client_imports_its_runtime_result_types() {
        let spec: Spec = r#"
            bin "reporter"
            flag "--json"
            output "text" default=#true
            output "json" framing="json" select="--json"
        "#
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        assert!(client.contains("CliJsonResult, CliResult, CliRunner, CliStream"));
    }

    #[test]
    fn nested_same_named_commands_get_distinct_exit_code_exports() {
        let spec: Spec = r#"
            bin "app"
            cmd "one" { cmd "show" { exit_code 1 "one failed" } }
            cmd "two" { cmd "show" { exit_code 2 "two failed" } }
        "#
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("ONE_SHOW_EXIT_CODES"), "{types}");
        assert!(types.contains("TWO_SHOW_EXIT_CODES"), "{types}");
        assert!(types.contains("OneShowExitCode"), "{types}");
        assert!(types.contains("TwoShowExitCode"), "{types}");
    }

    #[test]
    fn test_python_runtime() {
        let output = crate::sdk::generate(&SPEC_KITCHEN_SINK, &make_opts());
        insta::assert_snapshot!(get_file(&output, "runtime.py"));
    }

    #[test]
    fn test_python_init() {
        let output = crate::sdk::generate(&SPEC_KITCHEN_SINK, &make_opts());
        insta::assert_snapshot!(get_file(&output, "__init__.py"));
    }

    fn full_feature_spec() -> Spec {
        r##"
            bin "mytool"
            name "mytool"
            version "1.2.3"
            about "A powerful CLI tool"
            author "Jane Doe"

            flag "-v --verbose" help="Verbosity level" count=#true global=#true
            flag "-C --config <path>" help="Config file path" global=#true env="MYTOOL_CONFIG"
            flag "--dry-run" help="Show what would be done" negate="--no-dry-run"

            arg "input" help="Input file" required=#true
            arg "extra" var=#true help="Extra files"

            cmd "build" help="Build the project" deprecated="Use compile instead" {
                alias "b"
                arg "target" help="Build target" {
                    choices "debug" "release"
                }
                arg "output" help="Output directory" double_dash="required"
                flag "-j --jobs <n>" help="Parallel jobs" var=#true
                flag "--release" help="Build in release mode"
            }

            cmd "deploy" help="Deploy the project" {
                arg "env" help="Target environment" {
                    choices "staging" "production"
                }
                arg "tags" var=#true help="Deployment tags" var_min=1 var_max=5
                flag "-f --force" help="Force deploy" deprecated="Use --confirm instead"
                flag "--confirm" help="Confirm deployment"
            }
        "##
        .parse()
        .unwrap()
    }

    #[test]
    fn test_python_full_feature_types() {
        let spec = full_feature_spec();
        let output = crate::sdk::generate(&spec, &make_opts());
        insta::assert_snapshot!(get_file(&output, "types.py"));
    }

    #[test]
    fn test_python_full_feature_client() {
        let spec = full_feature_spec();
        let output = crate::sdk::generate(&spec, &make_opts());
        insta::assert_snapshot!(get_file(&output, "client.py"));
    }

    #[test]
    fn test_python_hyphenated_subcommands() {
        let spec: Spec = r##"
            bin "cli"
            cmd "add-remote" help="Add a remote" {
                arg "name"
                arg "url"
            }
            cmd "remove-remote" help="Remove a remote" {
                arg "name"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        insta::assert_snapshot!(get_file(&output, "client.py"));
    }

    #[test]
    fn test_python_minimal() {
        let spec: Spec = r##"
            bin "hello"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        insta::assert_snapshot!(get_file(&output, "client.py"));
    }

    /// Flags-only subcommand (no positional args) — tests exec signature without double comma.
    #[test]
    fn test_python_flags_only_subcommand() {
        let spec: Spec = r##"
            bin "app"
            cmd "status" help="Show status" {
                flag "--verbose" help="Show detailed status"
                flag "--json" help="Output as JSON"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        assert!(!client.contains("def exec(self, ,"));
        assert!(
            client.contains("def exec(self, flags: Optional[StatusFlags] = None) -> CliResult:")
        );
        insta::assert_snapshot!(client);
    }

    /// Choice type collision: same arg name with different choices in different subcommands.
    #[test]
    fn test_python_choice_collision() {
        let spec: Spec = r##"
            bin "tool"
            cmd "build" help="Build" {
                arg "env" help="Build environment" {
                    choices "debug" "release"
                }
            }
            cmd "deploy" help="Deploy" {
                arg "env" help="Deploy environment" {
                    choices "staging" "production"
                }
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        // Must have separate choice types due to collision
        assert!(types.contains("BuildEnvChoice"));
        assert!(types.contains("DeployEnvChoice"));
        assert!(types.contains(r#""debug""#));
        assert!(types.contains(r#""staging""#));
        insta::assert_snapshot!(types);
    }

    /// Args with default values — tests that defaults are preserved, not dropped to None.
    #[test]
    fn test_python_arg_defaults() {
        let spec: Spec = r##"
            bin "runner"
            arg "mode" default="fast" help="Run mode"
            arg "output" help="Output path" required=#true
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains(r#"mode: Optional[str] = "fast""#));
        assert!(types.contains("output: str"));
        // required arg must come before optional
        let output_pos = types.find("output: str").unwrap();
        let mode_pos = types.find(r#"mode: Optional[str] = "fast""#).unwrap();
        assert!(
            output_pos < mode_pos,
            "required arg must precede optional arg"
        );
    }

    /// Config props — covers config dataclass and config_prop_type.
    #[test]
    fn test_python_config_props() {
        let spec: Spec = r##"
            bin "myapp"
            config {
                prop "debug" default=#true data_type=boolean help="Enable debug mode"
                prop "port" default=8080 data_type=integer
                prop "rate" default="1.5" data_type=float
                prop "host" data_type=string
                prop "extra" data_type="null"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("class MyappConfig"));
        insta::assert_snapshot!(types);
    }

    /// A default whose text is not the type it claims to be must not become an expression.
    #[test]
    fn test_python_config_default_is_never_an_expression() {
        // types.py is imported, so anything written into it unquoted runs.
        //
        // The route this test was written for — `data_type=integer` beside a default of
        // arbitrary text — no longer parses at all; see
        // `a_default_the_declared_type_cannot_read_is_refused`. But a *string*-typed default
        // legitimately holds arbitrary text, which is the surface that still exists and the
        // one the generator has to quote. Two defences, and this is the second.
        let spec: Spec = r##"
            bin "myapp"
            config {
                prop "cmd" data_type=string default="__import__('os').system('touch /tmp/pwned')"
                prop "quoteful" data_type=string default="he said \"hi\""
                prop "multiline" data_type=string default="two\nlines"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");

        assert!(
            !types.contains("= __import__"),
            "a string default must not be emitted as an expression:\n{types}"
        );
        assert!(
            types.contains(r#"= "__import__('os').system('touch /tmp/pwned')""#),
            "it should be a quoted string:\n{types}"
        );
        // And a string containing quotes stays escaped rather than closing the literal.
        assert!(
            types.contains(r#"= "he said \"hi\"""#),
            "quotes inside a default should be escaped:\n{types}"
        );
        // A control character cannot be carried literally inside a Python literal at all: a
        // newline in a default wrote a module that fails to *import*, which is a worse failure
        // than one that says something wrong.
        assert!(
            types.contains(r#"= "two\nlines""#),
            "a newline in a default must be escaped:\n{types}"
        );
        assert!(
            !types.lines().any(|line| line.trim() == "lines\""),
            "the literal was split across lines:\n{types}"
        );
    }

    /// Hidden command, hidden arg/flag — covers early-return and empty dataclass paths.
    #[test]
    fn test_python_hidden_command() {
        let spec: Spec = r##"
            bin "app"
            cmd "visible" help="A visible command" {
                arg "name"
            }
            cmd "secret" hide=#true help="Hidden command" {
                arg "name"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("VisibleArgs"));
        assert!(!types.contains("SecretArgs"));
    }

    /// Flag edge cases: short-only, aliases, deprecated, count+default, required flag,
    /// repeatable boolean flag, non-bool value flag with default.
    #[test]
    fn test_python_flag_edge_cases() {
        let spec: Spec = r##"
            bin "tool"
            flag "-v" help="Short-only flag"
            flag "--type" help="Reserved keyword" deprecated="Use --kind"
            flag "--level" count=#true default="2" help="Count flag with default"
            flag "--format <fmt>" default="json" help="Value flag with default"
            flag "--confirm" required=#true help="Required flag"
            flag "--verbose" var=#true help="Repeatable boolean flag"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        insta::assert_snapshot!(types);
        let client = get_file(&output, "client.py");
        // short-only flag build
        assert!(client.contains(r#""-v""#));
        // repeatable boolean flag build
        assert!(client.contains("for v in flags.verbose:"));
        insta::assert_snapshot!(client);
    }

    /// double_dash=automatic, examples in exec doc, global flags with flags-only subcommand.
    #[test]
    fn test_python_exec_edge_cases() {
        let spec: Spec = r##"
            bin "runner"
            flag "-v --verbose" global=#true help="Verbosity"
            arg "input" help="Input file"
            arg "extra" double_dash="automatic" var=#true help="Extra files"
            cmd "run" help="Run a task" {
                example "runner run hello" header="Basic run"
                arg "task" help="Task to run" double_dash="automatic"
            }
            cmd "info" help="Show info" {}
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        assert!(client.contains("double_dash=automatic"));
        assert!(client.contains("Basic run: runner run hello"));
        // "info" has no own flags, only global flags => GlobalFlags type
        assert!(client.contains("flags: Optional[GlobalFlags] = None"));
        insta::assert_snapshot!(client);
    }

    /// Optional arg without default and empty flags dataclass.
    #[test]
    fn test_python_optional_arg_empty_flags() {
        let spec: Spec = r##"
            bin "app"
            arg "[name]" help="Optional arg without default"
            cmd "check" help="Check something" {
                arg "target" required=#true help="Required arg"
                arg "mode" default="quick" help="Optional arg with default"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        // optional arg without default should have = None
        assert!(types.contains("name: Optional[str] = None"));
        insta::assert_snapshot!(types);
    }

    /// Deeply nested subcommands — 3+ levels.
    #[test]
    fn test_python_deep_nesting() {
        let spec: Spec = r##"
            bin "app"
            cmd "db" help="Database operations" {
                cmd "migration" help="Migration management" {
                    cmd "create" help="Create a new migration" {
                        arg "name"
                        flag "--template <t>" help="Migration template"
                    }
                    cmd "run" help="Run pending migrations" {
                        flag "--step <n>" help="Number of migrations to run"
                    }
                }
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        // deeply nested class must exist
        assert!(client.contains("class Db:"));
        assert!(client.contains("class Migration:"));
        assert!(client.contains("class Create:"));
        insta::assert_snapshot!(client);
    }

    /// Test package_name override.
    #[test]
    fn test_python_package_name_override() {
        let spec: Spec = r##"
            bin "original-cli"
        "##
        .parse()
        .unwrap();
        let opts = SdkOptions {
            language: SdkLanguage::Python,
            package_name: Some("my_custom_sdk".to_string()),
            source_file: None,
        };
        let output = crate::sdk::generate(&spec, &opts);
        let init = get_file(&output, "__init__.py");
        assert!(init.contains("MyCustomSdk"));
        insta::assert_snapshot!(init);
    }

    /// Global flags with flags-only subcommand — covers GlobalFlags type branch.
    #[test]
    fn test_python_global_flags_flags_only() {
        let spec: Spec = r##"
            bin "app"
            flag "-v --verbose" global=#true help="Verbosity"
            cmd "status" help="Show status" {
                flag "--json" help="JSON output"
            }
            cmd "info" help="Show info" {}
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        // "info" subcommand has no own flags, only global flags => GlobalFlags type
        assert!(client.contains("Optional[GlobalFlags]"));
        insta::assert_snapshot!(client);
    }

    /// Flag with choices — flag arg with choices renders correct type.
    #[test]
    fn test_python_flag_with_choices() {
        let spec: Spec = r##"
            bin "tool"
            flag "--shell <shell>" help="Shell type" {
                choices "bash" "zsh" "fish"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("Literal[\"bash\", \"zsh\", \"fish\"]"));
        insta::assert_snapshot!(types);
    }

    /// Flag with env annotation — env variable appears in comment.
    #[test]
    fn test_python_flag_with_env() {
        let spec: Spec = r##"
            bin "app"
            flag "--config <path>" help="Config file" env="APP_CONFIG"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("Env: APP_CONFIG"));
        insta::assert_snapshot!(types);
    }

    /// Hidden flag excluded from types and client.
    #[test]
    fn test_python_flag_hide() {
        let spec: Spec = r##"
            bin "app"
            flag "--verbose" help="Verbosity"
            flag "--debug" hide=#true help="Hidden debug flag"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("verbose"));
        assert!(!types.contains("debug"));
    }

    /// Negate flag rendered in client build method.
    #[test]
    fn test_python_negate_flag_build() {
        let spec: Spec = r##"
            bin "app"
            flag "--dry-run" help="Dry run" negate="--no-dry-run"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        assert!(client.contains("--dry-run"));
        assert!(client.contains("--no-dry-run"));
        insta::assert_snapshot!(client);
    }

    /// Count flag rendered in client build method.
    #[test]
    fn test_python_count_flag_build() {
        let spec: Spec = r##"
            bin "app"
            flag "-v --verbose" count=#true help="Verbosity level"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        assert!(client.contains(r#""--verbose""#));
        assert!(client.contains("flags.verbose"));
        insta::assert_snapshot!(client);
    }

    /// Repeatable value flag with default — covers var + arg + default in client build.
    #[test]
    fn test_python_var_value_flag_with_default() {
        let spec: Spec = r##"
            bin "tool"
            flag "--tag <t>" var=#true default="latest" help="Tags"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains(r#"list[str]"#));
        assert!(types.contains(r#"default: latest"#));
        let client = get_file(&output, "client.py");
        assert!(client.contains("for v in flags.tag:"));
        insta::assert_snapshot!(types);
    }

    /// Flag with multiple long aliases — `-f --format --fmt <fmt>`.
    #[test]
    fn test_python_multiple_aliases() {
        let spec: Spec = r##"
            bin "tool"
            flag "-f --format --fmt <fmt>" help="Output format"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("Aliases: fmt"));
        let client = get_file(&output, "client.py");
        // should use first long for the flag argument name
        assert!(client.contains("--format"));
        insta::assert_snapshot!(client);
    }

    /// Boolean flag with default=#false — covers the "= False" branch.
    #[test]
    fn test_python_boolean_flag_default_false() {
        let spec: Spec = r##"
            bin "app"
            flag "--no-cache" default=#false help="Disable cache"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("no_cache: bool = False"));
        insta::assert_snapshot!(types);
    }

    /// Boolean config prop with default=#false — covers the "= False" branch.
    #[test]
    fn test_python_config_boolean_default_false() {
        let spec: Spec = r##"
            bin "app"
            config {
                prop "verbose" default=#false data_type=boolean help="Verbose output"
                prop "dry_run" default=#true data_type=boolean help="Dry run mode"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("verbose: bool = False"));
        assert!(types.contains("dry_run: bool = True"));
        insta::assert_snapshot!(types);
    }

    /// String config prop with default — covers String/Null match arm with default.
    #[test]
    fn test_python_config_string_with_default() {
        let spec: Spec = r##"
            bin "app"
            config {
                prop "host" default="localhost" data_type=string help="Server host"
                prop "name" default="myapp" data_type=string
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains(r#"host: str = "localhost""#));
        assert!(types.contains(r#"name: str = "myapp""#));
        insta::assert_snapshot!(types);
    }

    /// Config with all props having defaults — tests Default derive on config dataclass.
    #[test]
    fn test_python_config_all_optional() {
        let spec: Spec = r##"
            bin "app"
            config {
                prop "debug" default=#true data_type=boolean
                prop "port" default=8080 data_type=integer
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("class AppConfig:"));
        insta::assert_snapshot!(types);
    }

    /// Optional variadic arg — covers the optional + var branch in client rendering.
    #[test]
    fn test_python_optional_variadic_arg() {
        let spec: Spec = r##"
            bin "tool"
            arg "[files]" var=#true help="Input files"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("list[str]"));
        let client = get_file(&output, "client.py");
        // optional variadic arg should use extend with None guard
        assert!(client.contains("if args.files is not None: cmd_args.extend(args.files)"));
        insta::assert_snapshot!(client);
    }

    /// Example without lang attribute — tests single-line exec doc path.
    #[test]
    fn test_python_example_without_lang() {
        let spec: Spec = r##"
            bin "app"
            cmd "greet" help="Greet someone" {
                example "app greet hello"
                arg "name" help="Name to greet"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        assert!(client.contains("app greet hello"));
        insta::assert_snapshot!(client);
    }

    /// Required flag without default — tests non-optional flag type rendering.
    #[test]
    fn test_python_required_flag_type() {
        let spec: Spec = r##"
            bin "tool"
            flag "--token <t>" required=#true help="Auth token"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        // required flag without default should NOT be Optional
        assert!(types.contains("token: str"));
        assert!(!types.contains("token: Optional[str]"));
        insta::assert_snapshot!(types);
    }

    /// Global repeatable flags — covers flag_ts_simple var branches.
    #[test]
    fn test_python_global_repeatable_flags() {
        let spec: Spec = r##"
            bin "app"
            flag "-v --verbose" global=#true var=#true help="Repeatable verbose"
            flag "--tag <t>" global=#true var=#true help="Repeatable tag"
            cmd "run" help="Run" {
                arg "target"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        // GlobalFlags should have list[bool] and list[str] types
        assert!(types.contains("list[bool]"));
        assert!(types.contains("list[str]"));
        insta::assert_snapshot!(types);
    }

    /// Client edge cases: double_dash=automatic, examples, global flags, repeatable boolean flag.
    #[test]
    fn test_python_client_edge_cases() {
        let spec: Spec = r##"
            bin "runner"
            flag "-v --verbose" global=#true help="Verbosity"
            flag "--debug" var=#true help="Repeatable boolean flag"
            arg "input" help="Input file"
            arg "extra" double_dash="automatic" var=#true help="Extra files"
            cmd "run" help="Run a task" {
                example "runner run hello" header="Basic run" lang="bash"
                arg "task" help="Task to run" double_dash="automatic"
            }
            cmd "info" help="Show info" {}
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        assert!(client.contains("double_dash=automatic"));
        assert!(client.contains("Basic run: runner run hello"));
        // GlobalFlags type for info subcommand
        assert!(client.contains("Optional[GlobalFlags]"));
        // repeatable boolean flag
        assert!(client.contains("for v in flags.debug:"));
        insta::assert_snapshot!(client);
    }

    /// Config and flag edge cases — config with various data types, env, deprecated, aliases.
    #[test]
    fn test_python_config_and_flag_edge_cases() {
        let spec: Spec = r##"
            bin "myapp"
            config {
                prop "debug" default=#true data_type=boolean help="Enable debug mode"
                prop "port" default=8080 data_type=integer
                prop "rate" default="1.5" data_type=float
                prop "host" data_type=string
            }
            arg "input" help="Input file" env="MYAPP_INPUT"
            flag "--type" help="Reserved keyword" deprecated="Use --kind"
            flag "-f --format --fmt <fmt>" help="Flag with short and long alias"
            flag "-v" help="Short-only flag"
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let types = get_file(&output, "types.py");
        assert!(types.contains("MyappConfig"));
        insta::assert_snapshot!(types);
    }

    /// double_dash=automatic — covers arg ordering and separator insertion.
    #[test]
    fn test_python_double_dash_automatic() {
        let spec: Spec = r##"
            bin "runner"
            arg "input" help="Input file"
            arg "extra" double_dash="automatic" var=#true help="Extra files"
            flag "--verbose" var=#true help="Repeatable boolean flag"
            cmd "run" help="Run a task" {
                example "runner run hello" header="Basic run"
                arg "task" help="Task to run" double_dash="automatic"
            }
        "##
        .parse()
        .unwrap();
        let output = crate::sdk::generate(&spec, &make_opts());
        let client = get_file(&output, "client.py");
        assert!(client.contains("double_dash=automatic"));
        insta::assert_snapshot!(client);
    }
}