nested groups support

[mosquito]

This pull request introduces comprehensive support for nested argument groups in the argclass library, allowing groups to contain other groups at any depth. This feature is implemented in the core parser and thoroughly documented with examples for CLI, environment variables, and config files (INI/JSON/TOML). The changes also add robust error handling for group instance reuse and clarify the naming and sectioning rules for nested groups.

Nested Groups Support

• Added support for arbitrary nesting of Group fields within other Group classes in the core parser logic, including correct CLI, environment variable, and config file naming and sectioning. This includes recursive group traversal, attribute path-based naming, and config value resolution for nested groups. (argclass/parser.py, argclass/defaults.py) [1] [2] [3] [4] [5] [6] [7]

• Implemented error detection for reusing the same Group instance in multiple attributes, raising ArgclassError with a helpful message. (argclass/parser.py)

Documentation and Examples

• Updated all major documentation files to explain and demonstrate nested groups, including new code examples for CLI, environment variables, and config files (INI/JSON/TOML). (README.md, docs/groups.md, docs/environment.md, docs/config-files.md, CLAUDE.md, docs/index.md) [1] [2] [3] [4] [5] [6]

• Clarified how naming works for nested groups in all sources, and documented the effect (or lack thereof) of prefix= on config section names. [1] [2]

Demo and Example Code Updates

• Added and updated demo code in argclass/__main__.py to showcase nested groups, including new printouts and usage instructions. [1] [2] [3]

Internal Refactoring

• Improved type hints, code structure, and error messages to support and clarify the nested group logic.

These changes make argclass significantly more powerful and flexible for complex configuration schemas, while ensuring predictable and intuitive behavior across all supported input sources.

[Copilot]

Pull request overview

This PR adds first-class support for nested Group fields inside other Group classes throughout argclass, enabling arbitrary-depth grouping with consistent naming across CLI args, environment variables, and config-file defaults resolution.

Changes:

• Refactors core parser group wiring to recursively traverse nested groups, generate correct CLI/env/config names, and detect reused Group instances.
• Extends config defaults lookup (get_value(section=...)) to support dotted section paths for nested groups (INI literal section match first, then JSON/TOML dict descent).
• Adds comprehensive tests and updates documentation/examples to describe nested-group rules, naming, and limitations.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
argclass/parser.py	Recursive group traversal for nested groups; adds same-instance reuse detection; supports annotated group fields auto-instantiation and validation.
argclass/defaults.py	Supports dotted section paths for nested group config lookup (literal section first, then nested dict descent).
tests/test_nested_groups.py	Adds coverage for nested groups across CLI/env/config formats, help output, priority, secrets, lists, and reuse detection.
argclass/__main__.py	Updates demo to showcase nested groups.
README.md	Documents nested groups with a quick example and links to detailed docs.
docs/groups.md	Adds nested groups documentation (naming rules, help titles, prefix behavior, annotation rules, reuse error).
docs/environment.md	Documents env var naming for nested groups.
docs/config-files.md	Documents config-file layout for nested groups and the prefix= non-effect on section names.
docs/tutorial.md	Adds tutorial example demonstrating nested groups.
docs/pitfalls.md	Documents the “reused Group instance” error and how to fix it.
docs/index.md	Updates overview text to mention nested groups.
docs/llms.txt	Reorganizes/clarifies docs-source links and adds nested-groups summary for LLM consumption.
CLAUDE.md	Updates project-local guidance with nested groups example.
tasks/todo.md	Adds a design/implementation checklist and rationale for nested groups feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.