Type Annotations
params-proto v3 supports rich type annotations for parameters, providing type safety and automatic CLI help generation.
Known Type System Issues
✅ All major types are now fully supported in v3.0.0-rc24!
Previously broken types now working:
Literal[...]- Full validation of allowed valuesEnum- Conversion to enum members (case-insensitive matching)Path- Automatic instantiation viapathlib.Path()dict- Safe parsing usingast.literal_eval
Required Parameters and Callable Types
Key Design Principle: For required parameters (those without default values), params-proto always calls the type hint as a constructor.
This is the foundation for Union types and potential subcommand support.
How It Works
When a parameter has no default value, its type hint must be callable:
CLI Usage:
Union Types as Subcommands
This pattern enables Union types to act like subcommands:
CLI Usage:
The first positional argument selects which type to instantiate, and subsequent arguments configure that instance.
Why This Matters
This design enables:
- Type-safe subcommand patterns without special subcommand syntax
- Polymorphic configurations - choose between different config types at runtime
- Composable types - any callable (dataclass, class, function) works as a type hint
- Automatic CLI generation - params-proto generates appropriate help text for each union member
Required vs Optional
The callable type instantiation only applies to required parameters:
For optional parameters (with defaults), the type hint is used for type conversion and validation, not instantiation.
Class Name to CLI Command Conversion
Important: When using Union types, class names are converted to lowercase CLI commands:
CLI usage:
Conversion rule: PascalCase → kebab-case (e.g., HTTPServer → http-server, MLModel → ml-model)
Best Practices for Union Type Names
Use simple single-word names:
Acronyms and multi-word names now convert properly:
Basic Types
Primitive Types
CLI usage:
Type Conversion
Values are automatically converted to the annotated type:
Boolean conversion:
True:"true","1","yes","on"(case-insensitive)False:"false","0","no","off", or flag--no-{param}
Optional Types
Using | None (Python 3.10+)
Using Optional (Python 3.9+)
Union Types
Multiple Accepted Types
CLI usage:
Literal Types
Literal types restrict parameters to a specific set of allowed values with runtime validation.
CLI usage:
Help text shows allowed values:
Key features:
- Validates input against allowed values
- Works with strings, numbers, or mixed types
- Clear error messages showing valid options
Enum Types
Enums are converted to enum members with automatic case-insensitive name matching.
CLI usage:
Help text shows member names:
Key features:
- Converts CLI strings to enum members
- Case-insensitive name matching for user convenience
- Shows available options in help text
- Works with both
auto()and custom values
Collection Types
List Types
List types allow collecting multiple values from the CLI. Each element is converted to the specified type.
CLI usage:
Help text shows list notation:
How it works:
- Arguments after
--flagare collected until the next flag or end of arguments - Each value is converted to the element type (e.g.,
"256"→256forList[int]) - The result is always a list, even with a single value
Tuple Types
Tuple types allow collecting multiple values from the CLI with automatic element type conversion. Both variable-length and fixed-size tuples are supported.
CLI usage:
Help text notation:
- Variable-length:
--param (INT,...) - Fixed-size:
--param (INT,STR,FLOAT)
How it works:
- Arguments after
--flagare collected until the next flag or end of arguments - Each value is converted to its corresponding type position
- For
Tuple[T, ...], all values get converted to element type T - For fixed-size tuples, each value gets the type from its position
Path Types
pathlib.Path objects are automatically instantiated from string arguments.
CLI usage:
Key features:
- Strings automatically converted to Path objects
- Works with relative and absolute paths
- Ready to use with pathlib methods (
mkdir(),exists(), etc.) - Help text shows
PATHtype
Dictionary Types
Dictionary types are parsed safely using Python's ast.literal_eval - no code execution risk.
CLI usage:
Security note:
- Uses
ast.literal_evalwhich only evaluates Python literal structures - Safe for untrusted input - will never execute arbitrary code
- Supports: strings, numbers, lists, dicts, tuples, booleans, None
Key features:
- Safe parsing with
ast.literal_eval - Supports nested structures and mixed types
- Works with both single and double quotes:
{'a': 1}or{"a": 1} - Help text shows dict type:
{STR:INT}or{KEY:VALUE} - No code execution - purely data literal evaluation
Complex Types
Nested Unions
Literal with Union
Type Support Matrix
| Type | CLI Support | Help Display | Notes |
|---|---|---|---|
int | ✅ Full | INT | Fully working |
float | ✅ Full | FLOAT | Fully working |
str | ✅ Full | STR | Fully working |
bool | ✅ Full | (flag) | Supports --flag and --no-flag |
int | float | ✅ Full | VALUE | Ambiguous unions work |
str | None (Optional) | ✅ Full | STR | Correctly unwraps to inner type |
Literal[...] | ✅ Full | {a,b,c} | Full validation of allowed values |
Enum | ✅ Full | {A,B,C} | Enum member conversion (case-insensitive) |
List[T] | ✅ Full | [INT] or [STR] | Fully working with element type conversion |
Tuple[T, ...] | ✅ Full | (INT,...) or (INT,STR,FLOAT) | Fully working - variable and fixed-size tuples |
Path | ✅ Full | PATH | Automatic conversion to Path objects |
dict | ✅ Full | {STR:INT} | Safe parsing with ast.literal_eval |
Union[Class1, Class2] | ✅ Full | Subcommand | Works as pseudo-subcommands |
| Custom classes | ❌ Broken | - | Must be dataclasses with Union context |
Type Validation
Runtime Checks
Using Dataclass Validation
Type Hints Best Practices
1. Be Specific
2. Use Optional for Nullable Values
3. Document Type Constraints
4. Use Enums for Fixed Sets
Advanced Type Patterns
Generic Types
NewType for Documentation
Type Aliases
Environment Variable Types
Type conversion also works with environment variables:
Usage:
Troubleshooting
Type Mismatch Errors
Union Type Ambiguity
Related
- Core Concepts - Decorators and basic usage
- CLI Fundamentals - Type display in CLI
- CLI Patterns - Advanced patterns with type parameters
Union Types- Union types as subcommands- Configuration Patterns - Type annotations in configurations