params-proto 3.1.2__py3-none-any.whl → 3.2.1__py3-none-any.whl

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.
 
@@ -164,12 +190,31 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
         is_bool = annotation == bool
         prefix_params[kebab_key] = (singleton, param_name, annotation, is_bool)
 
+  # 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
+  unprefixed_attrs = {}
+  for kebab_name, (param_name, union_classes) in union_params.items():
+    for cls in union_classes:
+      # Skip if class is a @proto.prefix singleton (requires prefixed attrs)
+      is_prefix_class = cls in _SINGLETONS.values()
+      if is_prefix_class:
+        continue
+      if hasattr(cls, "__annotations__"):
+        for attr_name in cls.__annotations__:
+          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)
+
   # Parse arguments
   result = {}
   prefix_values = {}  # (singleton, param_name) -> value
   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
@@ -336,6 +381,17 @@ def parse_cli_args(wrapper) -> Dict[str, Any]:
             i += 2
         continue
 
+      # Check unprefixed union attrs when cli_prefix=False
+      if key in unprefixed_attrs:
+        union_param_name, attr_name = unprefixed_attrs[key]
+        # Get the value
+        if i + 1 >= len(args):
+          raise SystemExit(f"error: argument --{key} requires a value")
+        value_str = args[i + 1]
+        union_attrs[(union_param_name, attr_name)] = value_str
+        i += 2
+        continue
+
       # Unknown argument
       raise SystemExit(f"error: unrecognized argument: {arg}")
 
@@ -349,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
@@ -405,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
 
@@ -419,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/hyper/sweep.py

@@ -143,6 +143,77 @@ class ParameterIterator:
     """Return number of configs (materializes list)."""
     return len(self.list)
 
+  def save(self, filename="sweep.jsonl", overwrite=True, verbose=True):
+    """
+    Save parameter configurations to JSONL file.
+
+    Args:
+        filename: Path to output file (str or PathLike)
+        overwrite: If True, overwrite existing file; if False, append
+        verbose: If True, print save confirmation
+
+    Example:
+        configs = piter @ {"lr": [0.001, 0.01]} * {"batch_size": [32, 64]}
+        configs.save("experiment.jsonl")
+    """
+    import json
+    import os
+    from urllib import parse
+
+    # Convert Path objects to string
+    filename_str = os.fspath(filename) if hasattr(os, "fspath") else str(filename)
+    configs = self.list
+
+    with open(filename_str, "w" if overwrite else "a+") as f:
+      for item in configs:
+        f.write(json.dumps(item) + "\n")
+
+    if verbose:
+      try:
+        from termcolor import colored as c
+
+        print(
+          c("saved", "blue"),
+          c(len(configs), "green"),
+          c("items to", "blue"),
+          filename_str,
+          ".",
+          "file://" + parse.quote(os.path.realpath(filename_str)),
+        )
+      except ImportError:
+        print(f"Saved {len(configs)} items to {filename_str}")
+
+  @staticmethod
+  def load(filename="sweep.jsonl"):
+    """
+    Load parameter configurations from JSONL file.
+
+    Args:
+        filename: Path to input file (str or PathLike)
+
+    Returns:
+        ParameterIterator with loaded configurations
+
+    Example:
+        configs = ParameterIterator.load("experiment.jsonl")
+        for config in configs:
+            run_experiment(**config)
+    """
+    import json
+    import os
+
+    # Convert Path objects to string
+    filename_str = os.fspath(filename) if hasattr(os, "fspath") else str(filename)
+
+    configs = []
+    with open(filename_str, "r") as f:
+      for line in f:
+        line = line.strip()
+        if line and not line.startswith("//"):
+          configs.append(json.loads(line))
+
+    return ParameterIterator(iter(configs))
+
 
 class PiterFactory:
   """

params_proto/proto.py

@@ -669,20 +669,32 @@ class ptype(type):
 
     # Get the original class
     original_cls = type.__getattribute__(cls, "__proto_original_class__")
+    annotations = getattr(cls, "__proto_annotations__", {})
 
-    # Create instance
-    instance = object.__new__(original_cls)
+    # Check if this is a dataclass (has generated __init__ that accepts kwargs)
+    is_dataclass = hasattr(original_cls, "__dataclass_fields__")
 
-    # Set attributes
-    annotations = getattr(cls, "__proto_annotations__", {})
-    for name in annotations.keys():
-      if name in final_kwargs:
-        setattr(instance, name, final_kwargs[name])
-      elif hasattr(cls, "__proto_defaults__") and name in cls.__proto_defaults__:
-        setattr(instance, name, cls.__proto_defaults__[name])
-      else:
-        # Required field
-        setattr(instance, name, None)
+    if is_dataclass:
+      # For dataclasses: use the constructor directly
+      instance = original_cls(**final_kwargs)
+    else:
+      # For regular classes: create instance and set attributes manually
+      instance = object.__new__(original_cls)
+      for name in annotations.keys():
+        if name in final_kwargs:
+          setattr(instance, name, final_kwargs[name])
+        elif hasattr(cls, "__proto_defaults__") and name in cls.__proto_defaults__:
+          setattr(instance, name, cls.__proto_defaults__[name])
+        else:
+          # Required field
+          setattr(instance, name, None)
+      # Call __post_init__ if defined (dataclasses call it in __init__)
+      if hasattr(instance, '__post_init__'):
+        instance.__post_init__()
+
+    # Update the instance's class to the decorated class
+    # This allows isinstance(instance, DecoratedClass) to work
+    object.__setattr__(instance, "__class__", cls)
 
     # Copy methods from original class and wrap to return self
     for name in dir(original_cls):
@@ -722,10 +734,6 @@ class ptype(type):
 
       setattr(instance, name, make_wrapper(method))
 
-    # Call __post_init__ if defined (like dataclasses)
-    if hasattr(instance, '__post_init__'):
-      instance.__post_init__()
-
     return instance
 
 
@@ -1013,6 +1021,10 @@ def cli(obj: Any = None, *, prog: str = None):
   """
   Set up an object as a CLI entry point.
 
+  By default, subcommand attributes don't require prefix (--epochs works).
+  If the subcommand class is decorated with @proto.prefix, prefix is required
+  (--config.epochs).
+
   Args:
       obj: The class, function, or Union type to setup as CLI.
            If None, returns a decorator.

{params_proto-3.1.2.dist-info → params_proto-3.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: params-proto
-Version: 3.1.2
+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.1.2.dist-info → params_proto-3.2.1.dist-info}/RECORD

@@ -3,15 +3,15 @@ params_proto/app.py,sha256=UySpd1op3M44Szk6Ekyn0fJcnZsQvMTMPdaEybwWsLE,19
 params_proto/documentation.py,sha256=mIqmcwGWo8tM1BuNzLIwVTzdbQ3qyPus7yWTaOce4dM,8091
 params_proto/envvar.py,sha256=A87jxSAQ2tjbKLbrm96lblV90zNdtBGCSV6QRe2DrgA,8398
 params_proto/parse_env_template.py,sha256=mXTvKpNhT2jGr3HpwKw42shd18O0QACmSJn6yWMDdKA,1298
-params_proto/proto.py,sha256=81q5EyPYtH7uHCT0L2ydiin5Na2kfJ2VO3LmDfu8AXM,38386
+params_proto/proto.py,sha256=AGUHrU0OmWxqkYvJJqR6SzQTxZz_Zis0XYYaiFentmo,39077
 params_proto/type_utils.py,sha256=x68rL5m76ZFRKsCRgH_i_4vLpt6ldWEsEAalgacFIH8,7364
 params_proto/cli/__init__.py,sha256=sLpN3GmaBqd_d0J0nvUNOeGlV74_-jQGW0nDUU34tjA,493
 params_proto/cli/ansi_help.py,sha256=-1gzbvOpi9GjPlqgiINOYQAfIstzg0-ukv1se88TYCQ,10967
-params_proto/cli/cli_parse.py,sha256=aRXkPdfyRFJeXb6W6NwQ1bkkkhjUQlvin1k4GaUtbFg,14848
+params_proto/cli/cli_parse.py,sha256=kVBSgCCVZk32NOfPfyj-pYWXBLyqitFZzsfme8LspcE,18835
 params_proto/cli/help_gen.py,sha256=Iv9MWC7TJT4_OUWozTfCr8-Nmp_-K8Ohoim_dtsN5AY,12921
 params_proto/hyper/__init__.py,sha256=4zMnKk9H7NPlaTTRzbL2MC7anzwkBbd2_kW51aYhCPs,157
 params_proto/hyper/proxies.py,sha256=OMiaKK-gQx-zT1xeCmZevBSDgWUwwkzz0n54A5_wC60,4492
-params_proto/hyper/sweep.py,sha256=F6uac1o7_zzahgvnwcuqwn-7C48Xl-RlHKsrk6wulsU,29475
+params_proto/hyper/sweep.py,sha256=QUjsNdpJUoZU2WMF022LRqTh9rx5dgabpRCfs895q2Q,31444
 params_proto/v1/__init__.py,sha256=NGYZ6Iqicc5M6iyWT6N8FsD0iGLl2by5yZUIsHKhjXw,48
 params_proto/v1/hyper.py,sha256=zFzViWtSkQdqDJXuan33X2OZwKSHHY39Q5HSNPXl0iQ,2883
 params_proto/v1/params_proto.py,sha256=g2TMTG0SXyp01gsvd9EO42m28Hr2aS79xzOnMeH_WVk,8728
@@ -20,7 +20,7 @@ params_proto/v2/hyper.py,sha256=onBAkT8Ja8IkeHEOq1AwCdTuBzAnthIe766ZE0lAy-M,1146
 params_proto/v2/partial.py,sha256=_ovi4NY8goYgHurfYt1OV0E9DSMXGYucjMVIyG1Q_xc,983
 params_proto/v2/proto.py,sha256=KvinzgzwRQr2bHDNtrU7App2kgAyB-SEfBe4SNYceh0,18995
 params_proto/v2/utils.py,sha256=5EWvwboZDTsCYfzSED_J6RVFyNLIlf95nIu4p_ZSVxA,3540
-params_proto-3.1.2.dist-info/METADATA,sha256=vbXuWaBI3YY_BHQfuhWaebllCwVD5K0Q_myC_XFNku4,8991
-params_proto-3.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-params_proto-3.1.2.dist-info/licenses/LICENSE.md,sha256=c2qSYi9tUMZtzj9SEsMeKhub5LJUmHwBtDLiIMM5b6U,1526
-params_proto-3.1.2.dist-info/RECORD,,
+params_proto-3.2.1.dist-info/METADATA,sha256=IhhYdm8bYV3OEnUYmaRNo2Wb_8Sm58dCEBuuBIa0nbg,8991
+params_proto-3.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+params_proto-3.2.1.dist-info/licenses/LICENSE.md,sha256=c2qSYi9tUMZtzj9SEsMeKhub5LJUmHwBtDLiIMM5b6U,1526
+params_proto-3.2.1.dist-info/RECORD,,