Advanced Patterns
This guide covers advanced configuration patterns: prefixed configurations for multi-namespace composition and Union-based subcommands.
Prefixed Configurations
@proto.prefix creates singleton configuration groups with automatic CLI prefixes, enabling modular configuration composition.
Basic Usage
Create global configuration namespaces:
CLI usage:
Singleton Behavior
Prefixed configs are singletons - one global instance per class:
Multiple Prefix Groups
Organize related settings into logical modules:
CLI:
Real-World Example: ML Training
Usage:
When to Use Prefixes
✅ Use @proto.prefix for:
- Global configuration needed across modules
- Organizing complex systems into logical groups
- Reusable configuration components
- Multi-namespace CLI organization
❌ Don't use for:
- Multiple instances needed (use
@proto) - Simple function-local config (use parameters)
Overriding Prefixed Configs
Direct assignment:
CLI override:
proto.bind():
See Parameter Overrides for details.
Union-Based Subcommands
Use Union types with required parameters to create subcommand-like behavior.
Key Principle
For required parameters (no default), params-proto calls the type hint as a constructor.
This enables Union types to act like subcommands:
CLI usage:
How It Works
- Required parameter -
commandhas no default value - Union type -
Train | Evaluate | Exportprovides options - Callable types - Each type is a dataclass (callable)
- Automatic instantiation - params-proto calls the selected type
- Isolated parameters - Each dataclass has its own parameters
Class Name Conversion
Class names convert to kebab-case CLI commands:
Best practices:
See CLI Generation for details.
Advantages
✅ Type-safe - Full IDE autocomplete and type checking ✅ No new syntax - Uses existing Union mechanism ✅ Composable - Works with any callable (dataclass, class) ✅ Isolated parameters - Each command has its own namespace ✅ Automatic help - Command-specific help generation ✅ Shared parameters - Main function params apply to all commands
Limitations
❌ Not traditional subcommands - Uses required parameters, not argparse subparsers
❌ Single level - Nested subcommands (like git remote add) not directly supported
❌ Dispatch required - Must handle dispatch with isinstance() checks
Pattern: Shared Parameters
Main function parameters apply to all subcommands:
CLI:
Both commands can use --verbose.
Pattern: Configuration-Based Dispatch
Use configuration classes with Union types:
Clean separation of command logic and configuration.
Combining Prefixes and Union Types
Use both together for maximum flexibility:
CLI:
Configuration Profiles
Create switchable profiles using proto.bind():
Best Practices
1. Use Descriptive Names
2. Group Related Settings
3. Document Each Group
4. Keep Hierarchies Flat
Related
- Core Concepts - Three main decorators
- Configuration Patterns - Function vs class configurations
- CLI Fundamentals - Basic CLI features
- CLI Patterns - Advanced CLI patterns
- Naming Conventions - Name conversion rules
- Type System - Type annotation reference
- Parameter Overrides - Override methods