Union Types: Subcommands and Configuration Selection
Union types enable powerful multi-way dispatching in your CLI programs, allowing users to choose between different configurations or implementations at runtime. This is essential for building flexible, composable CLI tools.
Why Union Types Matter
When building complex CLI applications, you often need to support multiple alternatives:
- Different optimizer algorithms (Adam vs SGD vs RMSprop)
- Different model architectures (ResNet vs Vision Transformer vs CNN)
- Different data loaders or preprocessing strategies
- Different deployment environments (local vs cloud vs GPU)
Without Union types, you'd need separate scripts or manual conditional logic. With Union types, params-proto automatically generates:
- ✅ Subcommand-like syntax that feels natural
- ✅ Isolated parameter spaces (each option has its own parameters)
- ✅ Type-safe dispatch with
isinstance()checks - ✅ Automatic help generation per option
Quick Reference
Note
Version 3.2.0+: Subcommand attributes are unprefixed by default. Use
--lrinstead of--optimizer.lr. The prefixed syntax still works for backwards compatibility.
Union[ClassA, ClassB]: Choosing Classes
Use Union types when you need to select which class to instantiate. This creates subcommand-like behavior where each option has isolated parameters.
Example: Camera Selection
First, let's see how users interact with this from the command line:
Now the implementation:
How it works:
camerais a required parameter with Union type- params-proto instantiates the selected class
- Attributes are unprefixed by default (
--fov,--aspect) - Use
isinstance()to dispatch on the selected type
Optional[T]: Simple Optional Parameters
Optional[T] is for parameters that may or may not be provided:
CLI usage:
Both Optional[str] and str = None work equivalently:
Key Differences
| Type | Purpose | CLI Syntax | When to Use |
|---|---|---|---|
Union[ClassA, ClassB] | Choose which class instance | --param:ClassName or positional | Multiple configurations (optimizers, models, etc.) |
Optional[str] | Value may or may not be provided | --param value | Optional simple parameters |
str = None | Same as Optional | --param value | Alternative syntax for optional parameters |
Syntax Variations
Class selection (all work):
Attribute overrides (v3.2.0+: unprefixed by default):
Using @proto.prefix for Required Prefixes
If you want to require prefixed syntax for a class (e.g., for disambiguation), decorate it with @proto.prefix:
Examples
Example 1: Optimizer Selection
Command-line usage:
Implementation:
Example 2: Configuration Class
Command-line usage:
Implementation:
Example 3: Mixed Union and Regular Parameters
Command-line usage:
Implementation:
Key point: Union parameters are required, while other parameters can be optional with defaults.
Example 4: @proto.prefix Classes Require Prefixed Syntax
When a Union class is decorated with @proto.prefix, its CLI attributes require prefixed syntax:
Command-line usage:
This is useful when:
- You have multiple Union params with overlapping attribute names
- You want explicit namespacing for clarity
- You're using the class as a singleton config elsewhere
Related
- Core Concepts - Three main decorators
- CLI Fundamentals - Basic CLI features
- CLI Patterns - Advanced CLI patterns
- Configuration Patterns - Function vs class configurations
- Type System - Type annotation reference