Config file generation

[mosquito]

Summary

Adds config file generation to argclass — the inverse of the existing config_files= reading. A ConfigGenerator walks the parser tree (mirroring Parser._fill_group), builds a nested dict of the current state, and renders
it. Symmetric with AbstractDefaultsParser and its subclasses.

Built-in generators

Class	Output	Comments
INIConfigGenerator	INI	; lines from help=
JSONConfigGenerator	JSON	dropped (no comments in spec)
TOMLConfigGenerator	TOML	# lines from help=
EnvConfigGenerator	.env	# lines from help=

TOML emission is hand-rolled (~50 lines) so the zero-dependency guarantee stays intact. Covers str/int/float/bool/list/None.

Extension points

• ConfigGenerator — base class. Subclass and override render(data, help_map) to add a new format.
• GenerateConfigAction — argparse Action that takes a generator= passthrough kwarg. Wires --generate-config FILE (use - for stdout) in user CLIs. Reads CLI args from the argparse namespace and env vars from
  os.environ at dump time, so the output reflects the parser's current resolved state even when invoked mid-parse.
• NonConfigAction — opt-out marker for "fire and exit" actions (--version, --check-updates, GenerateConfigAction itself). Generators consult __emit_config__ and skip such args from dumps.
  argparse's built-in --help / --version are recognised by enum value.

Sources reflected in the dump

Whatever argclass would resolve at the moment of dumping ends up in the output — defaults, config_files=, env vars (explicit env_var= or auto_env_var_prefix=), and CLI args. This makes generation useful for
more than scaffolding: format conversion (load INI, dump TOML), snapshotting a deployed config, or materialising env-based config to a file.

Demo

python -m argclass genconfig --generate-ini -
python -m argclass genconfig --generate-toml /tmp/myapp.toml
DEMO_HOST=prod.example.com python -m argclass genconfig --generate-env -
python -m argclass genconfig --port 9999 --tags a b c --generate-toml -

Public API additions

argclass.ConfigGenerator
argclass.INIConfigGenerator
argclass.JSONConfigGenerator
argclass.TOMLConfigGenerator
argclass.EnvConfigGenerator
argclass.GenerateConfigAction
argclass.NonConfigAction

Plus the introspection helpers in argclass.emit: should_emit, current_value, derive_env_var, group_cli_segment, flatten_sections, and the HelpMap / EnvMap type aliases.

Other changes

• Parser._make_parser plumbs a one-line back-reference (parser.argclass_parser = self) so GenerateConfigAction can recover the argclass parser from the argparse parser during invocation.
• INIConfigGenerator skips None values (would otherwise reload as empty strings via configparser). Same behaviour now in TOML / .env.

Tests

tests/test_generate_config.py — 75 tests covering:

• Per-format round-trip (INI / JSON / TOML / .env).
• Cross-format round-trip with a richly-shaped parser (3-level nested groups, list[T], bool, Optional, Secret(), explicit env_var=, auto_env_var_prefix=, CLI args at every level).
• Mid-parse --generate-config capturing CLI args + env vars.
• NonConfigAction opt-out (and inheritance from it).
• Custom ConfigGenerator subclass (user-defined format).
• Edge cases: empty dicts, None values, type-conversion failures, back-reference missing, etc.

100% line/branch coverage on argclass/emit.py. Existing tests untouched.

Documentation

• New dedicated page docs/config-generation.md with usage, source-precedence semantics, EnvConfigGenerator walkthrough, NonConfigAction rules, custom-format subclass example, security
  note, and a format-migration guide (one-shot script, --generate-config mid-flight, bulk pipelines).
• Section added to README.md with quick examples.
• Snippet in docs/llms.txt for LLM consumers.
• Cross-references from docs/arguments.md "Argparse Passthrough Kwargs" section.
• New API entries in docs/api.md via autoclass.
• Demo subcommand python -m argclass genconfig with four --generate-{ini,toml,json,env} flags so the feature is self-documenting.

Limitations (intentional, documented)

• Subparsers are skipped from dumps (they're runtime branches, not config-time state). Dump each subparser separately if needed.
• Secrets emit their actual values — treat output files as credential-bearing.
• JSON has no comments; help text is dropped only in that format.