Configuration Patterns
params-proto v3 offers two ways to define configurations: function-based and class-based. Both use type hints and decorators, but serve different purposes.
Quick Comparison
| Aspect | Function-Based | Class-Based |
|---|---|---|
| Decorator | @proto.cli | @proto or @proto.prefix |
| Best for | Script entry points, CLI tools | Reusable configs, multiple instances |
| CLI | Automatic | Manual (via @proto.cli wrapper) |
| Instances | One per call | Create as many as needed |
| Access | Parameters | Attributes |
Rule of thumb: Use functions for scripts, classes for libraries and reusable components.
Function-Based Configurations
Basic CLI Function
The simplest way to create a CLI:
CLI usage:
When to Use Functions
✅ Perfect for:
- Script entry points (
if __name__ == "__main__") - CLI tools and utilities
- Simple configuration with few parameters
- When you need immediate CLI integration
❌ Not ideal for:
- Reusable configuration objects
- When you need multiple instances
- Library code (use
@protoclasses instead)
Documentation Extraction
Function documentation comes from two sources:
1. Inline comments:
2. Docstring Args section:
The help text combines both: inline comment first, then docstring details.
Required Parameters
Use Union types with required parameters for subcommand-like behavior:
CLI usage:
See Type System for details on required parameters.
Class-Based Configurations
Basic Configuration Class
Create reusable configuration objects:
Creating and Using Instances
Class-Level Access
When to Use Classes
✅ Perfect for:
- Reusable configuration objects
- Library code and frameworks
- When you need multiple independent instances
- Configuration hierarchies (inheritance)
- Integration with dataclasses
❌ Not ideal for:
- Simple scripts (use
@proto.clifunctions) - Direct CLI entry points (wrap with
@proto.cli)
Inheritance
Build configuration hierarchies:
Dataclass Integration
Combine with dataclasses for extra features:
Using Classes with CLI
Wrap class instances in a @proto.cli function:
Or use @proto.prefix for global configuration (see Advanced Patterns).
Methods in Configuration Classes
@proto classes can include methods just like regular classes. Methods (classmethod, staticmethod, and instance methods) work as expected:
Usage:
Post-Initialization Hook
@proto classes support __post_init__ (like dataclasses) for validation and computed attributes:
Usage:
Understanding Function Limitations and Solutions
The Fundamental Problem
Function-based parameter definitions have a limitation: they break the linkage between parameter definitions and their usage. Functions create a new scope for local variables, disconnecting parameters from their original definitions.
Consider:
In vanilla Python, you cannot easily access or iterate over function parameter defaults like you can with class attributes.
How params-proto Solves This: ProtoWrapper
When you decorate a function with @proto, params-proto doesn't just inspect the function—it wraps it in a special ProtoWrapper object. This wrapper provides the attribute access interface that vanilla Python functions lack.
The ProtoWrapper intercepts attribute access and function calls to enable the same ergonomic API that classes provide:
Behind the scenes:
- Parameter defaults are extracted from the function signature and stored internally
- Overrides are tracked in a separate dictionary
- Attribute access checks overrides first, then falls back to defaults
- Function calls merge defaults, overrides, and any kwargs before passing them to the original function
Alternative Approaches
If you don't want to use @proto for functions, here are traditional workarounds:
Option 1: Argument Data Class
Option 2: fn(**kwargs: Unpack) (Python 3.11+)
Option 3: Config Singleton
Choosing Between Functions and Classes
Use Functions When:
Use Classes When:
Use Both Together:
Common Patterns
Factory Pattern
Configuration Registry
Related
- Core Concepts - The three decorators
- CLI Fundamentals - Basic CLI features
- CLI Patterns - Advanced CLI patterns
- Type System - Complete type annotation reference
Advanced Patterns- Prefixes and subcommands- Parameter Overrides - Ways to override values
Hyperparameter Sweeps- Systematic exploration