params-proto 3.0.0rc26__py3-none-any.whl → 3.0.0rc27__py3-none-any.whl

params_proto/__init__.py

@@ -1,3 +1,4 @@
 from .app import app
-from .proto import EnvVar, Field, get_var, proto
+from .envvar import EnvVar, Field, get_var
+from .proto import proto
 from .hyper import Sweep

params_proto/envvar.py

@@ -25,24 +25,50 @@ class _EnvVar:
       db_url: str = EnvVar("DATABASE_URL", default="localhost")
       data_dir: str = EnvVar("$DATA_DIR/models", default="/tmp/models")
 
+  4. OR operation with multiple env var names (tries each in order):
+      api_key: str = EnvVar @ "API_KEY" @ "SECRET_KEY" | "default"
+      # Or function syntax:
+      api_key: str = EnvVar("API_KEY", "SECRET_KEY", default="default")
+
   The pipe operator (|) allows clean chaining of env var name with fallback value.
+  Values are loaded lazily - environment variables are read at access time, not definition time.
   """
 
-  def __init__(self, template: str = None, *, default: Any = None):
+  def __init__(self, *templates: str, default: Any = None, dtype: type = None):
     """
     Create an environment variable reader.
 
     Args:
-        template: Environment variable name or template string (e.g., "$VAR" or "VAR")
-        default: Default value if environment variable is not set
+        *templates: One or more environment variable names or template strings.
+                   When multiple are provided, they are checked in order (OR operation).
+        default: Default value if no environment variable is set
+        dtype: Optional type to convert the value to (overrides annotation inference)
     """
-    self.template = template
+    # Store templates as a tuple for immutability
+    self.templates = tuple(t for t in templates if t is not None)
     self.default = default
+    self.dtype = dtype
     self._env_name = None
+    # For lazy loading - cached value
+    self._cached_value = None
+    self._is_cached = False
+
+  @property
+  def template(self):
+    """Backward compatibility: return first template or None."""
+    return self.templates[0] if self.templates else None
 
   def __matmul__(self, other: Any):
     """
-    Support EnvVar @ "VAR_NAME" or EnvVar @ default_value syntax.
+    Support EnvVar @ "VAR_NAME" syntax, chainable for OR operation.
+
+    Examples:
+        EnvVar @ "VAR_NAME"              # Single env var
+        EnvVar @ "VAR1" @ "VAR2"         # OR: try VAR1, then VAR2
+        EnvVar @ "VAR1" @ "VAR2" | default  # With fallback
+
+    Note: The | operator has lower precedence than @, so
+    `EnvVar @ "A" @ "B" | default` is parsed as `(EnvVar @ "A" @ "B") | default`.
 
     Args:
         other: Either an environment variable name (str) or a default value
@@ -51,11 +77,11 @@ class _EnvVar:
         New _EnvVar instance configured with the given parameter
     """
     if isinstance(other, str):
-      # EnvVar @ "VAR_NAME" - treat as env var name
-      return _EnvVar(template=other, default=None)
+      # EnvVar @ "VAR_NAME" - add to templates list (OR operation)
+      return _EnvVar(*self.templates, other, default=self.default, dtype=self.dtype)
     else:
       # EnvVar @ some_value - treat as default value
-      return _EnvVar(template=None, default=other)
+      return _EnvVar(*self.templates, default=other, dtype=self.dtype)
 
   def __or__(self, other: Any):
     """
@@ -63,46 +89,56 @@ class _EnvVar:
 
     Syntax: EnvVar @ "VAR_NAME" | default_value
 
+    Note: Using `or` instead of `|` will NOT work because `or` has lower
+    precedence than @ and evaluates truthiness instead of calling __or__.
+
     Args:
         other: Default value to use if env var is not set
 
     Returns:
-        New _EnvVar instance with both template and default
+        New _EnvVar instance with both template(s) and default
     """
-    return _EnvVar(template=self.template, default=other)
+    return _EnvVar(*self.templates, default=other, dtype=self.dtype)
 
-  def __call__(self, template: str, *, default: Any = None):
+  def __call__(self, *templates: str, default: Any = None, dtype: type = None):
     """
-    Support EnvVar("VAR_NAME", default=...) function call syntax.
+    Support EnvVar("VAR_NAME", ..., default=...) function call syntax.
+
+    Examples:
+        EnvVar("DATABASE_URL", default="localhost")
+        EnvVar("API_KEY", "SECRET_KEY", default="fallback")  # OR operation
+        EnvVar("PORT", dtype=int, default=8080)  # With type conversion
 
     Args:
-        template: Environment variable name or template string
-        default: Default value if environment variable is not set
+        *templates: One or more environment variable names or template strings
+        default: Default value if no environment variable is set
+        dtype: Optional type to convert the value to
 
     Returns:
         New _EnvVar instance configured with the given parameters
     """
-    return _EnvVar(template=template, default=default)
+    return _EnvVar(*templates, default=default, dtype=dtype)
 
-  def get(self) -> Any:
+  def _resolve_single(self, name: str) -> tuple[Any, bool]:
     """
-    Get the value from environment variable.
+    Resolve a single environment variable name/template.
+
+    Args:
+        name: Environment variable name or template string
 
     Returns:
-        Value from environment or default
+        Tuple of (value, found) where found indicates if the env var was set
     """
-    # Use only the explicitly set template
-    # NO auto-inference for security reasons
-    if not self.template:
-      return self.default
-
-    name = self.template
-
     # Handle template strings with $ prefix or ${} syntax
     if name.startswith("$") or "${" in name:
       # Parse and expand template
       vars_in_template = parse_env_template(name)
       if vars_in_template:
+        # Check if any variable in template is actually set
+        any_set = any(var in os.environ for var in vars_in_template)
+        if not any_set:
+          return None, False
+
         # Expansion for both $VAR and ${VAR} syntax
         expanded = name
         for var in vars_in_template:
@@ -110,14 +146,69 @@ class _EnvVar:
           # Replace both ${VAR} and $VAR forms
           expanded = expanded.replace(f"${{{var}}}", var_value)
           expanded = expanded.replace(f"${var}", var_value)
-        return expanded if expanded != name else self.default
+        return expanded, True
 
     # Simple env var lookup
-    return os.environ.get(name, self.default)
+    if name in os.environ:
+      return os.environ[name], True
+    return None, False
+
+  def get(self, *, lazy: bool = True) -> Any:
+    """
+    Get the value from environment variable(s).
+
+    When multiple templates are specified (OR operation), tries each in order
+    and returns the first one that is set in the environment.
+
+    Args:
+        lazy: If True (default), cache the result for subsequent calls.
+              Set to False to always re-read from environment.
+
+    Returns:
+        Value from environment or default, converted to dtype if specified
+    """
+    from params_proto.type_utils import _convert_type
+
+    # Return cached value if lazy loading is enabled and we have a cached value
+    if lazy and self._is_cached:
+      return self._cached_value
+
+    # No templates means return default
+    if not self.templates:
+      result = self.default
+    else:
+      # Try each template in order (OR operation)
+      result = None
+      for name in self.templates:
+        value, found = self._resolve_single(name)
+        if found:
+          result = value
+          break
+      else:
+        # No env var was found, use default
+        result = self.default
+
+    # Apply dtype conversion if specified and we have a value
+    if result is not None and self.dtype is not None:
+      result = _convert_type(result, self.dtype)
+
+    # Cache the result for lazy loading
+    if lazy:
+      self._cached_value = result
+      self._is_cached = True
+
+    return result
+
+  def invalidate_cache(self):
+    """Clear the cached value, forcing re-read from environment on next get()."""
+    self._cached_value = None
+    self._is_cached = False
 
   def __repr__(self):
-    if self.template:
-      return f"EnvVar({self.template!r}, default={self.default!r})"
+    if self.templates:
+      if len(self.templates) == 1:
+        return f"EnvVar({self.templates[0]!r}, default={self.default!r})"
+      return f"EnvVar({', '.join(repr(t) for t in self.templates)}, default={self.default!r})"
     return f"EnvVar(default={self.default!r})"
 
 

params_proto/proto.py

@@ -1117,166 +1117,4 @@ def partial(config_class: Type, method: bool = False):
 
 proto.partial = partial
 
-
-class _EnvVar:
-  """
-  Environment variable reader that supports three syntaxes:
-
-  1. Matmul operator with env var name:
-      batch_size: int = EnvVar @ "BATCH_SIZE"
-
-  2. Matmul operator with pipe for default:
-      learning_rate: float = EnvVar @ "LR" | 0.001
-
-  3. Function call syntax:
-      db_url: str = EnvVar("DATABASE_URL", default="localhost")
-      data_dir: str = EnvVar("$DATA_DIR/models", default="/tmp/models")
-      port: int = EnvVar("PORT", dtype=int, default=8080)
-
-  The pipe operator (|) allows clean chaining of env var name with fallback value.
-  """
-
-  def __init__(self, template: str = None, *, default: Any = None, dtype: type = None):
-    """
-    Create an environment variable reader.
-
-    Args:
-        template: Environment variable name or template string (e.g., "$VAR" or "VAR")
-        default: Default value if environment variable is not set
-        dtype: Optional type to convert the value to (overrides annotation inference)
-    """
-    self.template = template
-    self.default = default
-    self.dtype = dtype
-    self._env_name = None
-
-  def __matmul__(self, other: Any):
-    """
-    Support EnvVar @ "VAR_NAME" or EnvVar @ default_value syntax.
-
-    Args:
-        other: Either an environment variable name (str) or a default value
-
-    Returns:
-        New _EnvVar instance configured with the given parameter
-    """
-    if isinstance(other, str):
-      # EnvVar @ "VAR_NAME" - treat as env var name
-      return _EnvVar(template=other, default=None)
-    else:
-      # EnvVar @ some_value - treat as default value
-      return _EnvVar(template=None, default=other)
-
-  def __or__(self, other: Any):
-    """
-    Support chaining with | to specify default value.
-
-    Syntax: EnvVar @ "VAR_NAME" | default_value
-
-    Args:
-        other: Default value to use if env var is not set
-
-    Returns:
-        New _EnvVar instance with both template and default
-    """
-    return _EnvVar(template=self.template, default=other, dtype=self.dtype)
-
-  def __call__(self, template: str, *, default: Any = None, dtype: type = None):
-    """
-    Support EnvVar("VAR_NAME", default=..., dtype=...) function call syntax.
-
-    Args:
-        template: Environment variable name or template string
-        default: Default value if environment variable is not set
-        dtype: Optional type to convert the value to
-
-    Returns:
-        New _EnvVar instance configured with the given parameters
-    """
-    return _EnvVar(template=template, default=default, dtype=dtype)
-
-  def get(self) -> Any:
-    """
-    Get the value from environment variable.
-
-    Returns:
-        Value from environment or default, converted to dtype if specified
-    """
-    import os
-
-    from params_proto.parse_env_template import parse_env_template
-    from params_proto.type_utils import _convert_type
-
-    # Use only the explicitly set template
-    # NO auto-inference for security reasons
-    if not self.template:
-      return self.default
-
-    name = self.template
-
-    # Handle template strings with $ prefix or ${} syntax
-    if name.startswith("$") or "${" in name:
-      # Parse and expand template
-      vars_in_template = parse_env_template(name)
-      if vars_in_template:
-        # Expansion for both $VAR and ${VAR} syntax
-        expanded = name
-        for var in vars_in_template:
-          var_value = os.environ.get(var, "")
-          # Replace both ${VAR} and $VAR forms
-          expanded = expanded.replace(f"${{{var}}}", var_value)
-          expanded = expanded.replace(f"${var}", var_value)
-        value = expanded if expanded != name else self.default
-        # Apply dtype conversion if specified
-        if value is not None and self.dtype is not None:
-          return _convert_type(value, self.dtype)
-        return value
-
-    # Simple env var lookup
-    value = os.environ.get(name)
-    if value is not None:
-      # Apply dtype conversion if specified
-      if self.dtype is not None:
-        return _convert_type(value, self.dtype)
-      return value
-    return self.default
-
-  def __repr__(self):
-    if self.template:
-      return f"EnvVar({self.template!r}, default={self.default!r})"
-    return f"EnvVar(default={self.default!r})"
-
-
-# Create singleton instance for @ syntax, but also keep class available
-EnvVar = _EnvVar()
-
-
-def get_var(default: Any = None, *, env: str = None):
-  """
-  Mark a field as an environment variable.
-
-  Args:
-      default: Default value if env var not set
-      env: Environment variable name (defaults to field name)
-  """
-  import os
-
-  def getter():
-    env_name = env or "FIELD_NAME"  # Will be replaced at decoration time
-    return os.environ.get(env_name, default)
-
-  return getter
-
-
-def Field(fn: Callable):
-  """
-  Decorator to mark a method as a computed field.
-
-  Args:
-      fn: The method to decorate
-
-  Returns:
-      The decorated method
-  """
-  fn._is_field = True
-  return fn
+# EnvVar, get_var, and Field are now imported from params_proto.envvar

{params_proto-3.0.0rc26.dist-info → params_proto-3.0.0rc27.dist-info}/METADATA

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

@@ -1,9 +1,9 @@
-params_proto/__init__.py,sha256=3TxfXQRi2wHNfNjD-pKcPO6xyAC5j2RY24VH3oul1hg,95
+params_proto/__init__.py,sha256=JJfjHf6dpkNpLDGOyH0KBWFo44nQoxSIzmwfGZb36ZU,114
 params_proto/app.py,sha256=UySpd1op3M44Szk6Ekyn0fJcnZsQvMTMPdaEybwWsLE,19
 params_proto/documentation.py,sha256=mIqmcwGWo8tM1BuNzLIwVTzdbQ3qyPus7yWTaOce4dM,8091
-params_proto/envvar.py,sha256=Gui4AJGPiBSDSyIC3KjmXGmewFmgihAF0QEOm-ufFVo,4323
+params_proto/envvar.py,sha256=PxSgNkk-GHksMiAYhRozSjCX3aCinfaPfCpuhuEbeho,7964
 params_proto/parse_env_template.py,sha256=mXTvKpNhT2jGr3HpwKw42shd18O0QACmSJn6yWMDdKA,1298
-params_proto/proto.py,sha256=Q3NSmjxKZC7yKGref5F3o7KJEnALaaHWjwd1kDJRDXQ,41914
+params_proto/proto.py,sha256=h-igiykTm1AwJrwUFa6rJaLZ3u4-8p6fAE7k_4hTo5w,37117
 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
@@ -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.0.0rc26.dist-info/METADATA,sha256=8k3wrzgdJnM0Oh_8lw9sBJmlmKusAVZgjg3kx_WhYIw,8995
-params_proto-3.0.0rc26.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-params_proto-3.0.0rc26.dist-info/licenses/LICENSE.md,sha256=c2qSYi9tUMZtzj9SEsMeKhub5LJUmHwBtDLiIMM5b6U,1526
-params_proto-3.0.0rc26.dist-info/RECORD,,
+params_proto-3.0.0rc27.dist-info/METADATA,sha256=LOsTpFkjezao5QzAyBeoo0uyHTbk9hcwbjudxu5-n5Q,8995
+params_proto-3.0.0rc27.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+params_proto-3.0.0rc27.dist-info/licenses/LICENSE.md,sha256=c2qSYi9tUMZtzj9SEsMeKhub5LJUmHwBtDLiIMM5b6U,1526
+params_proto-3.0.0rc27.dist-info/RECORD,,