Migration Guide: v2 to v3
This guide will help you migrate from params-proto v2 to v3.
What Changed?
params-proto v3 is a complete redesign with a cleaner, more Pythonic API. The key changes are:
| Aspect | v2 | v3 |
|---|---|---|
| API Style | Class inheritance (ParamsProto) | Decorators (@proto) |
| Type Hints | Optional | Required |
| Documentation | Manual docstrings | Inline comments |
| Functions | Not supported | Full support |
| Union Types | Limited support | Full support |
| Prefixes | Manual prefix string | @proto.prefix decorator |
Quick Comparison
v2 Syntax
v3 Syntax
Step-by-Step Migration
Step 1: Replace Inheritance with Decorator
v2:
v3:
Step 2: Add Type Hints
Type hints are required in v3. Add them to all your parameters:
v2:
v3:
Step 3: Convert Documentation
Inline comments automatically become help text in v3:
v2:
v3:
Step 4: Update Prefixed Configs
The prefix system is much simpler in v3:
v2:
v3:
Step 5: CLI Entry Points
v2:
v3:
Or with classes:
Step 6: Parameter Overrides
Override syntax is similar but more flexible:
v2:
v3 (same plus more options):
Feature Mapping
Environment Variables
v2:
v3:
Flags (Boolean Arguments)
v2:
v3:
Nested Configs
v2:
v3:
Common Patterns
Pattern 1: ML Training Script
v2:
v3:
Pattern 2: Experiment Sweeps
v2:
v3:
Breaking Changes
1. No More parse_args()
v2 required calling Args.parse_args(). v3 handles this automatically with @proto.cli.
2. Type Hints Required
All parameters must have type annotations in v3.
3. Different Import Path
4. Prefix Syntax Changed
Gradual Migration Strategy
You can migrate gradually:
- Add v3 alongside v2: Keep v2 code, add new configs with v3
- Migrate module by module: Convert one module at a time
- Update tests: Ensure tests pass after each module migration
- Remove v2 dependencies: Once fully migrated, remove v2 imports
Need Help?
- Check the
User Guidefor detailed v3 documentation - See
Examplesfor real-world v3 patterns - Open an issue on GitHub
v2 Documentation
The v2 documentation is archived at params-proto-v2.