params-proto 3.2.3__tar.gz → 3.3.0__tar.gz

{params_proto-3.2.3 → params_proto-3.3.0}/.idea/workspace.xml

@@ -4,7 +4,10 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="7a053ece-f497-4c97-ac58-a86c807155ac" name="Changes" comment="add design specs" />
+    <list default="true" id="7a053ece-f497-4c97-ac58-a86c807155ac" name="Changes" comment="add design specs">
+      <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_class_level_methods.py" beforeDir="false" afterPath="$PROJECT_DIR$/tests/test_v3/test_class_level_methods.py" afterDir="false" />
+    </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
     <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
@@ -224,8 +227,8 @@
   <component name="SharedIndexes">
     <attachedChunks>
       <set>
-        <option value="bundled-js-predefined-d6986cc7102b-9b0f141eb926-JavaScript-PY-253.30387.127" />
-        <option value="bundled-python-sdk-3944b0c99280-6d6dccd035ac-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-253.30387.127" />
+        <option value="bundled-js-predefined-d6986cc7102b-9b0f141eb926-JavaScript-PY-253.30387.173" />
+        <option value="bundled-python-sdk-4762d8aabb82-6d6dccd035ac-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-253.30387.173" />
       </set>
     </attachedChunks>
   </component>
@@ -260,6 +263,8 @@
       <workItem from="1769933004821" duration="4284000" />
       <workItem from="1770101044881" duration="1209000" />
       <workItem from="1770110071925" duration="622000" />
+      <workItem from="1770163240415" duration="5903000" />
+      <workItem from="1770274540569" duration="373000" />
     </task>
     <task id="LOCAL-00001" summary="add design specs">
       <option name="closed" value="true" />

{params_proto-3.2.3 → params_proto-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: params-proto
-Version: 3.2.3
+Version: 3.3.0
 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.3 → params_proto-3.3.0}/docs/release_notes.md

@@ -2,14 +2,36 @@
 
 This page contains the release history and changelog for params-proto.
 
-## Version 3.2.3 (2025-02-04)
+## Version 3.3.0 (2025-02-04)
+
+### ✨ Features
+
+- **Deep Nested Dot Notation for CLI**: Support for overriding nested dataclass fields via CLI
+  ```bash
+  # Before (not supported):
+  python train.py train-config --model.hidden-size 512  # error
+
+  # Now works:
+  python train.py train-config --epochs 200 --model.hidden-size 512 --model.num-layers 8
+  ```
+  - Recursively detects nested dataclass fields in type annotations
+  - Supports arbitrary nesting depth (e.g., `--model.encoder.layers 12`)
+  - Automatically constructs nested dataclass instances
+
+---
+
+## Version 3.2.4 (2025-02-04)
 
 ### 🐛 Bug Fixes
 
 - **Context Manager Protocol**: Fixed regression where `__enter__` and `__exit__` methods were stripped from `@proto` and `@proto.prefix` decorated classes
   - Classes implementing context managers now work correctly with `with` statements
-  - Also preserves other user-defined protocol methods: `__call__`, `__iter__`, `__next__`, `__getitem__`, `__len__`, etc.
-  - Root cause: method copying skipped all dunder methods, but should preserve user-defined ones
+  - Also preserves all user-defined protocol methods: `__call__`, `__iter__`, `__next__`, `__getitem__`, `__len__`, etc.
+
+- **Simplified Implementation**: Removed method wrapping that caused issues
+  - Decorated class is now a proper subclass of the original, so methods are inherited naturally
+  - No more wrapping of methods to return `self` - use explicit `return self` if needed
+  - Standard Python semantics: classmethods receive `cls`, not bound to instance
 
 ### 🧪 Testing
 

{params_proto-3.2.3 → params_proto-3.3.0}/pyproject.toml

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

{params_proto-3.2.3 → params_proto-3.3.0}/src/params_proto/cli/cli_parse.py

@@ -83,6 +83,101 @@ def _get_required_fields(cls) -> List[str]:
   return required
 
 
+def _is_nested_dataclass(annotation) -> bool:
+  """Check if annotation is a nested dataclass type."""
+  import dataclasses
+
+  # Skip primitive types and common non-dataclass types
+  if annotation in {int, str, float, bool, list, dict, tuple, set, Path, type(None)}:
+    return False
+
+  # Check if it's a type and a dataclass
+  if isinstance(annotation, type) and dataclasses.is_dataclass(annotation):
+    return True
+
+  return False
+
+
+def _get_nested_attrs(cls, prefix: str = "") -> Dict[str, tuple]:
+  """Recursively get all nested dataclass attributes.
+
+  Returns dict mapping dotted-kebab-name -> (dotted_underscore_path, leaf_type)
+
+  Example for TrainConfig with nested ModelConfig:
+    {
+      "model.hidden-size": ("model.hidden_size", int),
+      "model.num-layers": ("model.num_layers", int),
+    }
+  """
+  import dataclasses
+
+  result = {}
+  annotations = getattr(cls, "__annotations__", {})
+
+  for attr_name, attr_type in annotations.items():
+    kebab_attr = attr_name.replace("_", "-")
+    full_kebab = f"{prefix}{kebab_attr}" if prefix else kebab_attr
+    full_underscore = f"{prefix.replace('-', '_')}{attr_name}" if prefix else attr_name
+
+    if _is_nested_dataclass(attr_type):
+      # Recursively get nested attributes
+      nested = _get_nested_attrs(attr_type, prefix=f"{full_kebab}.")
+      result.update(nested)
+    else:
+      # Leaf attribute
+      result[full_kebab] = (full_underscore, attr_type)
+
+  return result
+
+
+def _set_nested_value(d: dict, path: str, value: Any) -> None:
+  """Set a value in a nested dict using dot notation path.
+
+  Example: _set_nested_value({}, "model.hidden_size", 512)
+           Results in {"model": {"hidden_size": 512}}
+  """
+  parts = path.split(".")
+  current = d
+  for part in parts[:-1]:
+    if part not in current:
+      current[part] = {}
+    current = current[part]
+  current[parts[-1]] = value
+
+
+def _build_nested_instance(cls, flat_attrs: dict, nested_attrs: dict):
+  """Build a dataclass instance with nested dataclass fields.
+
+  Args:
+      cls: The dataclass class to instantiate
+      flat_attrs: Dict of top-level attribute values
+      nested_attrs: Dict of nested dicts for nested dataclass fields
+
+  Returns:
+      Instance of cls with nested dataclasses properly constructed
+  """
+  import dataclasses
+
+  final_attrs = dict(flat_attrs)
+  annotations = getattr(cls, "__annotations__", {})
+
+  for attr_name, attr_type in annotations.items():
+    if attr_name in nested_attrs and _is_nested_dataclass(attr_type):
+      # Recursively build nested dataclass
+      nested_data = nested_attrs[attr_name]
+      # Separate flat and nested for the nested class
+      nested_flat = {}
+      nested_nested = {}
+      for k, v in nested_data.items():
+        if isinstance(v, dict):
+          nested_nested[k] = v
+        else:
+          nested_flat[k] = v
+      final_attrs[attr_name] = _build_nested_instance(attr_type, nested_flat, nested_nested)
+
+  return cls(**final_attrs)
+
+
 def _match_class_by_name(name: str, classes: list) -> Union[type, None]:
   """Match a string to one of the Union classes.
 
@@ -193,6 +288,7 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
   # Build unprefixed union attribute map for classes NOT decorated with @proto.prefix
   # Maps attr-name -> (union_param_name, attr_name_underscore)
   # Classes in _SINGLETONS are @proto.prefix decorated and require prefixed attrs
+  # Also includes nested dataclass attributes (e.g., "model.hidden-size")
   unprefixed_attrs = {}
   for kebab_name, (param_name, union_classes) in union_params.items():
     for cls in union_classes:
@@ -201,12 +297,20 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
       if is_prefix_class:
         continue
       if hasattr(cls, "__annotations__"):
-        for attr_name in cls.__annotations__:
+        for attr_name, attr_type in cls.__annotations__.items():
           kebab_attr = attr_name.replace("_", "-")
           # Map to the union param (first one wins if multiple unions have same attr)
           if kebab_attr not in unprefixed_attrs:
             unprefixed_attrs[kebab_attr] = (param_name, attr_name)
 
+          # Check for nested dataclass and add its attributes
+          if _is_nested_dataclass(attr_type):
+            nested_attrs = _get_nested_attrs(attr_type, prefix=f"{kebab_attr}.")
+            for nested_kebab, (nested_path, nested_type) in nested_attrs.items():
+              full_path = f"{attr_name}.{nested_path.split('.', 1)[1] if '.' in nested_path else nested_path}"
+              if nested_kebab not in unprefixed_attrs:
+                unprefixed_attrs[nested_kebab] = (param_name, full_path)
+
   # Parse arguments
   result = {}
   prefix_values = {}  # (singleton, param_name) -> value
@@ -451,21 +555,65 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
   # Instantiate Union classes with collected attributes
   for param_name, selected_class in union_selections.items():
     # Collect attributes for this Union parameter
-    attrs = {}
-    for (union_param, attr_name), value_str in union_attrs.items():
+    # Separate flat (top-level) and nested attributes
+    flat_attrs = {}
+    nested_attrs = {}  # For nested dataclass fields
+
+    for (union_param, attr_path), value_str in union_attrs.items():
       if union_param == param_name:
-        # Get the type annotation for this attribute
-        if hasattr(selected_class, "__annotations__"):
-          attr_type = selected_class.__annotations__.get(attr_name, str)
-          try:
-            attrs[attr_name] = _convert_type(value_str, attr_type)
-          except (ValueError, TypeError):
-            raise SystemExit(
-              f"error: invalid value for --{param_name.replace('_', '-')}.{attr_name.replace('_', '-')}: {value_str}"
-            )
+        # Check if this is a nested path (contains dots)
+        if "." in attr_path:
+          # Nested attribute like "model.hidden_size"
+          parts = attr_path.split(".")
+          top_level = parts[0]
+          rest_path = ".".join(parts[1:])
+
+          # Get the type of the nested field
+          if hasattr(selected_class, "__annotations__"):
+            top_type = selected_class.__annotations__.get(top_level)
+            if top_type and _is_nested_dataclass(top_type):
+              # Find the leaf type by traversing the path
+              current_type = top_type
+              for part in parts[1:]:
+                if hasattr(current_type, "__annotations__"):
+                  current_type = current_type.__annotations__.get(part, str)
+                else:
+                  current_type = str
+                  break
+
+              try:
+                value = _convert_type(value_str, current_type)
+              except (ValueError, TypeError):
+                raise SystemExit(
+                  f"error: invalid value for --{attr_path.replace('_', '-')}: {value_str}"
+                )
+
+              # Store in nested structure
+              if top_level not in nested_attrs:
+                nested_attrs[top_level] = {}
+              _set_nested_value(nested_attrs[top_level], rest_path, value)
+              continue
+
+          # Fallback: treat as string
+          if top_level not in nested_attrs:
+            nested_attrs[top_level] = {}
+          _set_nested_value(nested_attrs[top_level], rest_path, value_str)
         else:
-          # No annotations, treat as string
-          attrs[attr_name] = value_str
+          # Top-level attribute
+          if hasattr(selected_class, "__annotations__"):
+            attr_type = selected_class.__annotations__.get(attr_path, str)
+            try:
+              flat_attrs[attr_path] = _convert_type(value_str, attr_type)
+            except (ValueError, TypeError):
+              raise SystemExit(
+                f"error: invalid value for --{param_name.replace('_', '-')}.{attr_path.replace('_', '-')}: {value_str}"
+              )
+          else:
+            # No annotations, treat as string
+            flat_attrs[attr_path] = value_str
+
+    # Merge flat_attrs into attrs for compatibility with existing code
+    attrs = flat_attrs
 
     # Assign positional args to required fields of the selected class
     if param_name in union_positional and union_positional[param_name]:
@@ -508,17 +656,21 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
               attrs[key] = value
         break
 
-    # Check for missing required fields
+    # Check for missing required fields (only check top-level, nested have defaults)
     required_fields = _get_required_fields(selected_class)
     for field_name in required_fields:
-      if field_name not in attrs:
+      if field_name not in attrs and field_name not in nested_attrs:
         raise SystemExit(
           f"error: {selected_class.__name__} requires argument: {field_name}"
         )
 
     # Instantiate the class with collected attributes
     try:
-      instance = selected_class(**attrs)
+      if nested_attrs:
+        # Build with nested dataclass support
+        instance = _build_nested_instance(selected_class, attrs, nested_attrs)
+      else:
+        instance = selected_class(**attrs)
       result[param_name] = instance
     except TypeError as e:
       raise SystemExit(f"error: failed to instantiate {selected_class.__name__}: {e}")

{params_proto-3.2.3 → params_proto-3.3.0}/src/params_proto/proto.py

@@ -694,59 +694,9 @@ class ptype(type):
 
     # Update the instance's class to the decorated class
     # This allows isinstance(instance, DecoratedClass) to work
+    # Since cls is a subclass of original_cls, methods are inherited naturally
     object.__setattr__(instance, "__class__", cls)
 
-    # Copy methods from original class and wrap to return self
-    for name in dir(original_cls):
-      # Skip proto fields (fields are handled above)
-      if name in annotations:
-        continue
-
-      # For dunder methods, only copy user-defined ones (not inherited from object/type)
-      if name.startswith("__"):
-        # Check if this dunder method is user-defined (not from object or type)
-        is_user_defined = False
-        for klass in original_cls.__mro__:
-          if klass is object or klass is type:
-            break
-          if name in klass.__dict__:
-            is_user_defined = True
-            break
-        if not is_user_defined:
-          continue
-
-      # Check raw descriptor in MRO to detect staticmethod/classmethod (handles inheritance)
-      raw_attr = None
-      for klass in original_cls.__mro__:
-        if name in klass.__dict__:
-          raw_attr = klass.__dict__[name]
-          break
-
-      attr = getattr(original_cls, name)
-
-      # Only process actual methods (staticmethod, classmethod, or function)
-      if isinstance(raw_attr, staticmethod):
-        # For staticmethod, use directly (no binding needed)
-        method = attr
-      elif isinstance(raw_attr, classmethod) or inspect.isfunction(raw_attr) or inspect.ismethod(attr):
-        # For instance methods and classmethods, bind to instance
-        # Note: classmethods bound to instance is intentional for @proto
-        # semantics where instances have all attributes accessible
-        method = attr.__get__(instance, original_cls)
-      else:
-        # Not a method (e.g., _EnvVar, property, or other callable), skip
-        continue
-
-      # Wrap it to return self if it returns None
-      def make_wrapper(m):
-        def wrapper(*args, **kwargs):
-          result = m(*args, **kwargs)
-          return instance if result is None else result
-
-        return wrapper
-
-      setattr(instance, name, make_wrapper(method))
-
     return instance
 
 
@@ -869,30 +819,32 @@ def proto(
       else:
         metaclass = ptype
 
-      # Recreate the class with ptype as its metaclass
-      # Collect class namespace (attributes and methods)
-      namespace = {}
-      for key in dir(obj):
-        if not key.startswith("__") or key in ("__annotations__", "__module__", "__qualname__", "__doc__"):
-          try:
-            # Use __dict__ to preserve classmethod/staticmethod descriptors
-            # getattr() would return bound methods instead of descriptors
-            if key in obj.__dict__:
-              namespace[key] = obj.__dict__[key]
-            else:
-              namespace[key] = getattr(obj, key)
-          except AttributeError:
-            pass
+      # Create new class with metaclass as subclass of original
+      # Since new class inherits from obj, methods are inherited naturally.
+      # We only need to provide:
+      # - Module/qualname metadata
+      # - Annotations (so annotated fields are visible on the class)
+      # - Resolved default values (with EnvVars resolved)
+      namespace = {
+        "__module__": obj.__module__,
+        "__qualname__": obj.__qualname__,
+        "__doc__": obj.__doc__,
+        "__annotations__": annotations,
+      }
 
-      # Replace _EnvVar objects with resolved values from defaults
-      # This ensures the descriptor doesn't interfere with class attribute access
-      for key, value in defaults.items():
-        namespace[key] = value
+      # Add resolved default values (EnvVars are already resolved in defaults dict)
+      # Also set None for annotated fields without defaults so they're accessible
+      for key in annotations.keys():
+        if key in defaults:
+          namespace[key] = defaults[key]
+        else:
+          namespace[key] = None
 
-      # Create new class with metaclass
-      # IMPORTANT: Use (obj,) as bases to make new class a SUBCLASS of original.
-      # This ensures super() works correctly - the original class is in the MRO,
-      # so Python's super() validation passes when checking isinstance(self, original_class).
+      # Create new class as SUBCLASS of original.
+      # This ensures:
+      # 1. super() works correctly (original class is in MRO)
+      # 2. Methods, staticmethods, classmethods are inherited naturally
+      # 3. isinstance(instance, DecoratedClass) works
       new_cls = metaclass(
         obj.__name__,
         (obj,),

{params_proto-3.2.3 → params_proto-3.3.0}/tests/test_v3/test_class_level_methods.py

@@ -150,13 +150,15 @@ class TestProtoPrefixWithMethods:
 
     obj = Config()
 
-    # Classmethod should have access to config attributes via instance
+    # Classmethod should have access to config attributes via class
     assert obj.get_lr() == 0.01
 
-    # Note: classmethods on instances are bound to the instance,
-    # so they see instance attributes (not class-level updates)
-    obj.lr = 0.001
-    assert obj.get_lr() == 0.001
+    # Note: classmethods receive the class (cls), not instance,
+    # so they see class-level values (standard Python behavior)
+    obj.lr = 0.001  # Instance attribute
+    assert obj.get_lr() == 0.01  # Still sees class default
+    Config.lr = 0.002  # Class attribute
+    assert obj.get_lr() == 0.002  # Now sees class update
 
   def test_proto_prefix_with_instance_method(self):
     """Test @proto.prefix on class with regular instance method."""

{params_proto-3.2.3 → params_proto-3.3.0}/tests/test_v3/test_nested_cli.py

@@ -171,33 +171,27 @@ class TestThreeLayerNesting:
           main()
       """)
 
-    # Try to override nested model config via deep dot notation
-    # This tests if --config.model.hidden_size works
+    # Override nested model config via deep dot notation
+    # Plain dataclasses use unprefixed syntax (--epochs, not --config.epochs)
+    # Only @proto.prefix decorated classes require prefixed syntax
     result = run_cli(
       script,
       [
-        "--config:TrainConfig",
-        "--config.epochs",
+        "train-config",  # subcommand name (kebab-case)
+        "--epochs",
         "200",
-        "--config.model.hidden_size",
+        "--model.hidden-size",
         "512",
-        "--config.model.num_layers",
+        "--model.num-layers",
         "8",
       ],
-      expect_error=True,  # This may not be supported yet
     )
 
-    # Check if it succeeded or failed
-    if result["returncode"] == 0:
-      lines = result["stdout"].strip().split("\n")
-      assert lines[0] == "epochs=200"
-      assert lines[1] == "model.hidden_size=512"
-      assert lines[2] == "model.num_layers=8"
-    else:
-      # If it failed, this documents the current limitation
-      pytest.skip(
-        "Deep nested dot notation (--config.model.hidden_size) not yet supported"
-      )
+    assert result["returncode"] == 0, f"CLI failed: {result['stderr']}"
+    lines = result["stdout"].strip().split("\n")
+    assert lines[0] == "epochs=200"
+    assert lines[1] == "model.hidden_size=512"
+    assert lines[2] == "model.num_layers=8"
 
 
 class TestThreeLayerUnionNesting:

{params_proto-3.2.3 → params_proto-3.3.0}/tests/test_v3/test_proto_core.py

@@ -71,7 +71,8 @@ def test_canonical_usage():
   Nerf.lr = 0.001
 
   # main function
-  nerf = Nerf().main()
+  nerf = Nerf()
+  nerf.main()
   assert nerf.seed == 100, "should be overriden"
   assert nerf.lr == 0.001, "should be overriden"