v3.0.0-rc24: Complete Type System

Complete Type System Support 🎉

All major Python types now fully supported with comprehensive CLI integration!

New Features

Literal Type Validation

Restrict parameters to specific allowed values:

# String literals
python app.py --optimizer adam --device cuda

# Numeric literals
python app.py --precision 32

# Mixed types
python app.py --mode auto

Enum Member Conversion

Case-insensitive enum conversion with clear validation:

# Exact case
python app.py --optimizer SGD

# Case-insensitive (CLI convenience)
python app.py --optimizer adam

Path Type Support

Automatic pathlib.Path instantiation:

python app.py --input-dir ./data --output-file results.txt
# Paths ready to use with all pathlib methods

Dictionary Parsing (Security-Safe)

Safe dict parsing using ast.literal_eval:

python app.py --config '{"lr": 0.01, "batch_size": 32}'
python app.py --params '{"model": {"layers": 3}, "tags": ["ml", "v2"]}'

Type System Summary

Now fully supporting:

• ✅ Primitives: int, float, str, bool
• ✅ Special: Optional[T], Union[A, B]
• ✅ Collections: List[T], Tuple[T, ...], dict
• ✅ Validation: Literal[...], Enum
• ✅ Paths: pathlib.Path
• ✅ Custom: Any callable type

Implementation Details

General Callable Type Pattern:

• Enum types: Excluded from custom class handling, converted to members
• Literal types: Validated against allowed values
• Path: Handled by general callable instantiation (Path(value))
• dict: Safe parsing with ast.literal_eval (no code execution)

Architecture:

• Enhanced _convert_type() with Literal, Enum, dict support
• Enhanced _get_type_name() for help text generation
• General fallback: Any callable type instantiated with string value
• Modified CLI parser to exclude Literal/Enum from Union handling

Tests

• 17 comprehensive tests in test_advanced_types.py (all passing)
• 48 existing CLI parsing tests (all still passing)
• 65 total tests ensuring full compatibility

Documentation

Comprehensive sections in type-system.md:

• Literal types with validation examples
• Enum types with case-insensitive matching
• Path types with filesystem operations
• Dictionary types with nested structure support
• Security notes on ast.literal_eval

Installation

pip install params-proto==3.0.0-rc24

This release completes the type system, providing comprehensive support for all common Python types in CLI applications!

v3.0.0-rc23

Tuple[T] CLI Parsing Support

✨ Features

• Variable-length tuples: Tuple[int, ...] collects values with consistent type
• Fixed-size tuples: Tuple[int, str, float] with mixed types at each position
• Multiple value collection: --sizes 256 512 1024 → sizes=(256, 512, 1024)
• Automatic type conversion: Each value converted to its position's type
• Works with defaults and prefixes: Full support for @proto.prefix classes
• Help text: Shows tuple notation like (INT,...) or (INT,STR,FLOAT)

Examples

@proto.cli
def train(
    # Variable-length: same type for all elements
    learning_schedule: Tuple[float, ...] = (0.1, 0.01),
    # Fixed-size: specific type at each position
    image_size: Tuple[int, int] = (224, 224),
    # Mixed types: int, str, float at positions 0, 1, 2
    config: Tuple[int, str, float] = (10, "default", 0.5),
):
    pass

CLI usage:

# Variable-length tuple
python train.py --learning-schedule 0.5 0.1 0.01

# Fixed-size tuple
python train.py --image-size 256 256

# Mixed type tuple
python train.py --config 42 custom 0.75

Implementation Details

• Updated _convert_type() to handle both Tuple[T, ...] and Tuple[T1, T2, ...] patterns
• Updated CLI parser to collect multiple values for tuple parameters
• Updated help text generation with proper tuple type notation
• Full test coverage: 9 new test cases, all passing

Type System Progress

Now fully supporting:

• ✅ Primitive types: int, float, str, bool
• ✅ Optional types: Optional[T], T | None
• ✅ Collection types: List[T], Tuple[T, ...], Tuple[T1, T2, ...]
• ✅ Union/Subcommand types: Union[Class1, Class2]

Still in development:

• ⚠️ Literal[...] and Enum (help works, no validation)
• ❌ Path (strings not converted)
• ❌ dict (not implemented)

Installation

pip install params-proto==3.0.0-rc23

v3.0.0-rc22

Documentation Update

📚 List[T] CLI Parsing Documentation

• Comprehensive guide for using list types in CLI
• Added practical examples showing --items a b c → list of values
• Help text generation showing [STR], [INT], [FLOAT] notation
• Documentation explaining how multiple values are collected until next flag
• Type support matrix updated to show List[T] as ✅ Full support

What's Included

v3.0.0-rc22 includes all features and fixes from rc21 plus enhanced documentation for the List[T] feature that was implemented in rc21.

Key Features

• ✅ Full List[T] CLI parsing support
• ✅ Element type conversion (List[int], List[float], List[str])
• ✅ Works with defaults and @proto.prefix classes
• ✅ Comprehensive help text generation
• ✅ All 9 test cases passing

Installation

```bash
pip install params-proto==3.0.0-rc22
```

v3.0.0-rc20

🐛 Bug Fix: Optional[T] CLI Parsing

The issue: Optional[T] types were incorrectly treated as Union subcommands, requiring special syntax instead of working as simple optional parameters.

Before (v3.0.0-rc19) ❌

from typing import Optional
from params_proto import proto

@proto.cli
def train(checkpoint: Optional[str] = None, learning_rate: float = 0.001):
    print(f"checkpoint={checkpoint}, lr={learning_rate}")

This would fail:

python train.py --checkpoint model.pt
# error: unrecognized argument: --checkpoint

After (v3.0.0-rc20) ✅

Now works correctly with standard syntax:

# Using the optional parameter
python train.py --checkpoint model.pt
# Output: checkpoint=model.pt, lr=0.001

# Omitting the optional parameter (uses None default)
python train.py
# Output: checkpoint=None, lr=0.001

# Works seamlessly with other parameters
python train.py --checkpoint model.pt --learning-rate 0.01
# Output: checkpoint=model.pt, lr=0.01

Improved Help Output

Before:  --checkpoint VALUE   Path to checkpoint file
After:   --checkpoint STR     Path to checkpoint file

Technical Improvements

• cli_parse.py:_get_union_classes(): Now filters out NoneType from Union type arguments
• cli_parse.py Union handling: Added detection for Optional[T] patterns (Union with single non-None type) and treats them as regular optional parameters
• type_utils.py:_get_type_name(): Now recognizes Optional[T] patterns and recursively extracts the correct inner type name for help text
• Help text: Now shows specific types (STR, INT, FLOAT) instead of generic VALUE for Optional types

Test Results

✅ All 253 tests passing - no regressions

• test_optional_str_cli_parsing - PASSED
• test_optional_int_cli_parsing - PASSED
• test_proto_cli_optional_types - PASSED (with improved help output)

v3.0.0-rc18

Bug Fixes

• EnvVar Instantiation Fix: Fixed @proto.prefix classes with EnvVar fields failing on instantiation with AttributeError: '_EnvVar' object has no attribute '__get__'

Example

from params_proto import proto, EnvVar

@proto.prefix
class Config:
    host: str = EnvVar @ "HOST" | "localhost"

# Before: AttributeError
# After: works correctly
c = Config()

Documentation

• Added EnvVar + inheritance documentation and tests
• Updated CLAUDE.md with full release procedure

v3.0.0-rc17

Changes

Features

• Inherited Fields: Support inherited fields in @proto classes. Parent class fields are now properly included in vars(), CLI args, and work with EnvVar

Documentation

• Added EnvVar + inheritance documentation and tests
• Updated skill docs with inheritance examples

Example

class BaseConfig:
    host: str = EnvVar @ "HOST" | "localhost"
    port: int = EnvVar @ "PORT" | 8080

@proto.prefix
class AppConfig(BaseConfig):
    debug: bool = EnvVar @ "DEBUG" | False

v3.0.0-rc16

Changes

• Support Python 3.10 by using Union[] syntax (#17)

v3.0.0-rc15

🐛 Bug Fixes

• EnvVar dtype Conversion: Fixed EnvVar.get() to apply the dtype parameter for type conversion.
  Previously, the dtype was stored but not used when reading from environment variables, causing
  values to always be returned as strings.

  import os
  from params_proto import EnvVar
  
  os.environ["PORT"] = "9000"
  
  # Before fix: returned '9000' (str)
  # After fix: returns 9000 (int)
  port = EnvVar("PORT", dtype=int, default=8012).get()

  All dtypes are now properly applied: int, float, bool, and str.

Install

pip install params-proto==3.0.0rc15

---

🤖 Generated with Claude Code

v3.0.0-rc7

What's New

• Claude Skill: Added hierarchical Claude skill documentation in skill/ directory for AI assistant integration

Install

pip install params-proto==3.0.0-rc7

Full Changelog: v3.0.0-rc6...v3.0.0-rc7

v3.0.0-rc6

Changes in rc6

• Boolean flags now show BOOL type in help text for consistency with INT, STR, FLOAT
• Boolean flags with default=True show --no-flag form in help (since that's what changes behavior)
• Fixed ANSI colorization to properly highlight type names

Install

pip install params-proto==3.0.0-rc6

Full Changelog

v3.0.0-rc5...v3.0.0-rc6