params-proto 3.2.0__tar.gz → 3.2.1__tar.gz

{params_proto-3.2.0 → params_proto-3.2.1}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "params-proto",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Declarative hyperparameter management skills for ML/AI experiments",
   "author": {
     "name": "Ge Yang"

{params_proto-3.2.0 → params_proto-3.2.1}/.idea/workspace.xml

@@ -4,13 +4,7 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="7a053ece-f497-4c97-ac58-a86c807155ac" name="Changes" comment="add design specs">
-      <change beforePath="$PROJECT_DIR$/src/params_proto/cli/cli_parse.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/params_proto/cli/cli_parse.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/params_proto/hyper/sweep.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/params_proto/hyper/sweep.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/params_proto/proto.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/params_proto/proto.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/tests/test_v3/test_cli_parsing.py" beforeDir="false" afterPath="$PROJECT_DIR$/tests/test_v3/test_cli_parsing.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/tests/test_v3/test_piter.py" beforeDir="false" afterPath="$PROJECT_DIR$/tests/test_v3/test_piter.py" afterDir="false" />
-    </list>
+    <list default="true" id="7a053ece-f497-4c97-ac58-a86c807155ac" name="Changes" comment="add design specs" />
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
     <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
@@ -263,7 +257,7 @@
       <workItem from="1768382679094" duration="3000" />
       <workItem from="1769135684123" duration="4247000" />
       <workItem from="1769569263076" duration="1863000" />
-      <workItem from="1769933004821" duration="1704000" />
+      <workItem from="1769933004821" duration="3502000" />
     </task>
     <task id="LOCAL-00001" summary="add design specs">
       <option name="closed" value="true" />

{params_proto-3.2.0 → params_proto-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: params-proto
-Version: 3.2.0
+Version: 3.2.1
 Summary: Modern Hyper Parameter Management for Machine Learning
 Project-URL: Homepage, https://github.com/geyang/params-proto
 Project-URL: Documentation, https://params-proto.readthedocs.io

{params_proto-3.2.0 → params_proto-3.2.1}/docs/key_concepts/union_types.md

@@ -61,10 +61,11 @@ def main(model: Model):
 ```
 
 ```python
-# Pattern 3: Optional simple parameters (workaround)
-# Note: Optional[str] is not fully supported; use str with default instead
+# Pattern 3: Optional simple parameters
+from typing import Optional
+
 @proto.cli
-def process(checkpoint: str = None, batch_size: int = 32):
+def process(checkpoint: Optional[str] = None, batch_size: int = 32):
     pass
 
 # CLI: python process.py --checkpoint model.pt
@@ -134,17 +135,18 @@ if __name__ == "__main__":
 `Optional[T]` is for parameters that **may or may not be provided**:
 
 ```python
+from typing import Optional
+
 @proto.cli
 def train(
-    checkpoint: str = None,      # Works (workaround)
-    # checkpoint: Optional[str] = None,  # ⚠️ Doesn't fully work yet
+    checkpoint: Optional[str] = None,  # Optional with None default
     epochs: int = 10,
 ):
     """Train model."""
     pass
 ```
 
-**Expected CLI usage:**
+**CLI usage:**
 
 ```bash
 python train.py --checkpoint model.pt       # Provide value
@@ -152,21 +154,15 @@ python train.py                             # Omit for None default
 python train.py --checkpoint model.pt --epochs 50
 ```
 
-```{note}
-**Current limitation:** `Optional[str]`, `Optional[int]`, etc. are not fully supported.
-Use regular parameters with defaults as a workaround:
+Both `Optional[str]` and `str = None` work equivalently:
 
 ```python
-# ✓ Works
+# Both work
 @proto.cli
-def train(checkpoint: str = None, epochs: int = 10):
-    pass
+def train(checkpoint: Optional[str] = None): ...
 
-# ⚠️ Doesn't work yet
 @proto.cli
-def train(checkpoint: Optional[str] = None, epochs: int = 10):
-    pass
-```
+def train(checkpoint: str = None): ...
 ```
 
 ## Key Differences
@@ -174,8 +170,8 @@ def train(checkpoint: Optional[str] = None, epochs: int = 10):
 | 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 (**currently use workaround**) |
-| `str` with default | Same as Optional | `--param value` | Simple optional parameters (**recommended workaround**) |
+| `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
 

{params_proto-3.2.0 → params_proto-3.2.1}/docs/release_notes.md

@@ -2,6 +2,22 @@
 
 This page contains the release history and changelog for params-proto.
 
+## Version 3.2.1 (2025-02-01)
+
+### 🐛 Bug Fixes
+
+- **Positional Arguments in Subcommands**: Fixed positional arguments being silently ignored after subcommand name
+  - Before: `myapp add my-env/v1.2.3` → positional arg silently dropped
+  - After: `myapp add my-env/v1.2.3` → positional arg captured by subcommand's required field
+  - Enables CLI patterns like `pip install requests`, `cargo add serde`
+  - Raises clear error for extra unrecognized positional arguments
+
+### 📚 Documentation
+
+- Fixed outdated notes claiming `Optional[str]` was not supported (it works)
+
+---
+
 ## Version 3.2.0 (2025-02-01)
 
 ### ✨ Features

{params_proto-3.2.0 → params_proto-3.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "params-proto"
-version = "3.2.0"
+version = "3.2.1"
 description = "Modern Hyper Parameter Management for Machine Learning"
 authors = [
     { name = "Ge Yang" }

{params_proto-3.2.0 → params_proto-3.2.1}/skills/params-proto/SKILL.md

@@ -10,7 +10,7 @@ description: |
   (6) Work with Union types for subcommand-like CLI patterns
 ---
 
-# params-proto v3.2.0
+# params-proto v3.2.1
 
 Declarative hyperparameter management for ML experiments with automatic CLI generation.
 

{params_proto-3.2.0 → params_proto-3.2.1}/src/params_proto/cli/cli_parse.py

@@ -57,6 +57,32 @@ def _normalize_class_name(class_name: str) -> str:
   return class_name.replace("-", "").replace("_", "").lower()
 
 
+def _get_required_fields(cls) -> List[str]:
+  """Get list of required field names (fields without defaults) in order."""
+  import dataclasses
+
+  required = []
+
+  # Check if it's a dataclass
+  if dataclasses.is_dataclass(cls):
+    for field in dataclasses.fields(cls):
+      has_default = (
+        field.default is not dataclasses.MISSING
+        or field.default_factory is not dataclasses.MISSING
+      )
+      if not has_default:
+        required.append(field.name)
+  else:
+    # For regular classes, check annotations and class-level defaults
+    annotations = getattr(cls, "__annotations__", {})
+    for name in annotations:
+      if not hasattr(cls, name):
+        # No class-level default
+        required.append(name)
+
+  return required
+
+
 def _match_class_by_name(name: str, classes: list) -> Union[type, None]:
   """Match a string to one of the Union classes.
 
@@ -187,6 +213,8 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
   positional_values = []
   union_selections = {}  # param_name -> selected_class
   union_attrs = {}  # (param_name, attr_name) -> value
+  union_positional = {}  # param_name -> [positional_args] for subcommand fields
+  current_union_param = None  # Track which union we're collecting positionals for
 
   args = sys.argv[1:]
   i = 0
@@ -377,12 +405,18 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
           selected_class = _match_class_by_name(arg, union_classes)
           if selected_class:
             union_selections[param_name] = selected_class
+            current_union_param = param_name  # Track for following positionals
+            union_positional[param_name] = []
             matched_union = True
             i += 1
             break
 
       if not matched_union:
-        positional_values.append(arg)
+        # If we have a current union, add positional to its list
+        if current_union_param is not None:
+          union_positional[current_union_param].append(arg)
+        else:
+          positional_values.append(arg)
         i += 1
 
   # Assign positional arguments to required parameters
@@ -433,6 +467,33 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
           # No annotations, treat as string
           attrs[attr_name] = value_str
 
+    # Assign positional args to required fields of the selected class
+    if param_name in union_positional and union_positional[param_name]:
+      positionals = union_positional[param_name]
+      required_fields = _get_required_fields(selected_class)
+
+      for field_idx, field_name in enumerate(required_fields):
+        if field_name in attrs:
+          # Already set by named arg, skip
+          continue
+        if field_idx < len(positionals):
+          # Get type annotation for conversion
+          if hasattr(selected_class, "__annotations__"):
+            field_type = selected_class.__annotations__.get(field_name, str)
+            try:
+              attrs[field_name] = _convert_type(positionals[field_idx], field_type)
+            except (ValueError, TypeError):
+              raise SystemExit(
+                f"error: invalid value for {field_name}: {positionals[field_idx]}"
+              )
+          else:
+            attrs[field_name] = positionals[field_idx]
+
+      # Check for extra positional args
+      if len(positionals) > len(required_fields):
+        extra = positionals[len(required_fields):]
+        raise SystemExit(f"error: unrecognized arguments: {' '.join(extra)}")
+
     # If selected_class is a proto.prefix singleton, merge its overrides
     from params_proto.proto import _SINGLETONS, ptype
 
@@ -447,6 +508,14 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
               attrs[key] = value
         break
 
+    # Check for missing required fields
+    required_fields = _get_required_fields(selected_class)
+    for field_name in required_fields:
+      if field_name not in attrs:
+        raise SystemExit(
+          f"error: {selected_class.__name__} requires argument: {field_name}"
+        )
+
     # Instantiate the class with collected attributes
     try:
       instance = selected_class(**attrs)

{params_proto-3.2.0 → params_proto-3.2.1}/tests/test_v3/test_nested_cli.py

@@ -816,3 +816,141 @@ class TestProtoPrefixRequiresPrefix:
     # Unprefixed should error for @proto.prefix class
     result = run_cli(script, ["train-config", "--epochs", "200"], expect_error=True)
     assert "unrecognized argument" in result["stderr"]
+
+
+class TestPositionalArgsInSubcommands:
+  """Test positional arguments captured by subcommand fields.
+
+  This tests the pattern: myapp add my-env/v1.2.3
+  Where 'add' is the subcommand and 'my-env/v1.2.3' is captured by the
+  subcommand's first required field.
+  """
+
+  def test_positional_arg_captured_by_subcommand_field(self, run_cli):
+    """Test positional arg after subcommand name is captured."""
+    script = dedent("""
+      from dataclasses import dataclass
+      from params_proto import proto
+
+      @dataclass
+      class AddCommand:
+          env: str  # Required field, no default
+
+      @dataclass
+      class RemoveCommand:
+          env: str  # Required field
+
+      @proto.cli
+      def main(command: AddCommand | RemoveCommand):
+          print(f"command={command.__class__.__name__}")
+          print(f"env={command.env}")
+
+      if __name__ == "__main__":
+          main()
+      """)
+
+    # Positional arg after subcommand should be captured by 'env' field
+    result = run_cli(script, ["add", "my-env/v1.2.3"])
+    lines = result["stdout"].strip().split("\n")
+    assert lines[0] == "command=AddCommand"
+    assert lines[1] == "env=my-env/v1.2.3"
+
+    result = run_cli(script, ["remove", "old-env/v0.9.0"])
+    lines = result["stdout"].strip().split("\n")
+    assert lines[0] == "command=RemoveCommand"
+    assert lines[1] == "env=old-env/v0.9.0"
+
+  def test_multiple_positional_args_in_subcommand(self, run_cli):
+    """Test multiple positional args captured by subcommand fields."""
+    script = dedent("""
+      from dataclasses import dataclass
+      from params_proto import proto
+
+      @dataclass
+      class InstallCommand:
+          package: str  # Required, first positional
+          version: str  # Required, second positional
+
+      @proto.cli
+      def main(command: InstallCommand):
+          print(f"package={command.package}")
+          print(f"version={command.version}")
+
+      if __name__ == "__main__":
+          main()
+      """)
+
+    result = run_cli(script, ["install", "requests", "2.28.0"])
+    lines = result["stdout"].strip().split("\n")
+    assert lines[0] == "package=requests"
+    assert lines[1] == "version=2.28.0"
+
+  def test_positional_with_named_args(self, run_cli):
+    """Test mixing positional and named args in subcommand."""
+    script = dedent("""
+      from dataclasses import dataclass
+      from params_proto import proto
+
+      @dataclass
+      class CloneCommand:
+          url: str  # Required positional
+          depth: int = 0  # Optional with default
+
+      @proto.cli
+      def main(command: CloneCommand):
+          print(f"url={command.url}")
+          print(f"depth={command.depth}")
+
+      if __name__ == "__main__":
+          main()
+      """)
+
+    # Positional url, named depth
+    result = run_cli(script, ["clone", "https://github.com/test", "--depth", "1"])
+    lines = result["stdout"].strip().split("\n")
+    assert lines[0] == "url=https://github.com/test"
+    assert lines[1] == "depth=1"
+
+  def test_positional_arg_missing_should_error(self, run_cli):
+    """Test that missing required positional arg errors."""
+    script = dedent("""
+      from dataclasses import dataclass
+      from params_proto import proto
+
+      @dataclass
+      class AddCommand:
+          env: str  # Required field
+
+      @proto.cli
+      def main(command: AddCommand):
+          print(f"env={command.env}")
+
+      if __name__ == "__main__":
+          main()
+      """)
+
+    # Missing required positional should error
+    result = run_cli(script, ["add"], expect_error=True)
+    assert result["returncode"] != 0
+
+  def test_extra_positional_should_error(self, run_cli):
+    """Test that extra unrecognized positional args error."""
+    script = dedent("""
+      from dataclasses import dataclass
+      from params_proto import proto
+
+      @dataclass
+      class AddCommand:
+          env: str  # Required field
+
+      @proto.cli
+      def main(command: AddCommand):
+          print(f"env={command.env}")
+
+      if __name__ == "__main__":
+          main()
+      """)
+
+    # Extra positional arg should error
+    result = run_cli(script, ["add", "env1", "extra-arg"], expect_error=True)
+    assert result["returncode"] != 0