params-proto 3.1.0__tar.gz → 3.1.2__tar.gz

{params_proto-3.1.0 → params_proto-3.1.2}/.idea/workspace.xml

@@ -32,6 +32,7 @@
   </component>
   <component name="HighlightingSettingsPerFile">
     <setting file="file://$USER_HOME$/Library/Caches/JetBrains/PyCharm2025.2/python_stubs/-1979844046/_typing.py" root0="SKIP_INSPECTION" />
+    <setting file="file://$PROJECT_DIR$/pyproject.toml" root0="SKIP_INSPECTION" />
   </component>
   <component name="KubernetesApiPersistence">{}</component>
   <component name="KubernetesApiProvider">{
@@ -253,7 +254,7 @@
       <workItem from="1767857192117" duration="3689000" />
       <workItem from="1768126847510" duration="6729000" />
       <workItem from="1768382679094" duration="3000" />
-      <workItem from="1769135684123" duration="659000" />
+      <workItem from="1769135684123" duration="4247000" />
     </task>
     <task id="LOCAL-00001" summary="add design specs">
       <option name="closed" value="true" />

{params_proto-3.1.0 → params_proto-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: params-proto
-Version: 3.1.0
+Version: 3.1.2
 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.0 → params_proto-3.1.2}/docs/index.md

@@ -21,7 +21,7 @@ pip install params-proto=={VERSION}
 
 ```bash
 /plugin marketplace add geyang/params-proto
-/plugin install params-proto@geyang/params-proto
+/plugin install params-proto@params-proto
 ```
 
 Now you can convert this function into a CLI program:

{params_proto-3.1.0 → params_proto-3.1.2}/docs/quick_start.md

@@ -18,7 +18,7 @@ params-proto includes a plugin that helps Claude write better configs and CLIs.
 
 ```bash
 /plugin marketplace add geyang/params-proto
-/plugin install params-proto@geyang/params-proto
+/plugin install params-proto@params-proto
 ```
 
 The plugin provides a skill that automatically activates when you're working with params-proto code.

{params_proto-3.1.0 → params_proto-3.1.2}/docs/release_notes.md

@@ -2,6 +2,24 @@
 
 This page contains the release history and changelog for params-proto.
 
+## Version 3.1.1 (2025-01-25)
+
+### 🐛 Bug Fixes
+
+- **EnvVar Descriptor Protocol**: EnvVar now works in plain classes without `@proto` decorator
+  - Previously `EnvVar @ "VAR" | default` returned `_EnvVar` object in plain classes
+  - Now auto-resolves via `__get__` descriptor when accessed as class attribute
+  - Fixes: `AttributeError: '_EnvVar' object has no attribute 'decode'`
+
+### ♻️ API Changes
+
+- **Removed `.get()` method**: Use class attribute access instead
+  - Old: `EnvVar("PORT", dtype=int).get()`
+  - New: `class C: port = EnvVar("PORT", dtype=int)` then `C.port`
+  - Use `invalidate_cache()` to force re-read from environment
+
+---
+
 ## Version 3.1.0 (2025-01-23)
 
 ### ✨ Features
@@ -34,10 +52,9 @@ This page contains the release history and changelog for params-proto.
   - Function syntax: `EnvVar("PRIMARY", "FALLBACK", default="value")`
   - Returns first env var that is set, or default if none are set
 
-- **EnvVar Lazy Loading**: Environment variables are cached after first read
-  - `ev.get()` caches result for subsequent calls
-  - `ev.get(lazy=False)` forces re-read from environment
-  - `ev.invalidate_cache()` clears cached value
+- **EnvVar Lazy Loading**: Environment variables are cached after first access
+  - Values cached after first access via descriptor
+  - `invalidate_cache()` clears cached value for re-read
 
 ### 🐛 Bug Fixes
 

{params_proto-3.1.0 → params_proto-3.1.2}/pyproject.toml

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

{params_proto-3.1.0 → params_proto-3.1.2}/skills/params-proto/SKILL.md

@@ -10,14 +10,14 @@ description: |
   (6) Work with Union types for subcommand-like CLI patterns
 ---
 
-# params-proto v3.1.0
+# params-proto v3.1.1
 
 Declarative hyperparameter management for ML experiments with automatic CLI generation.
 
 ## Installation
 
 ```bash
-pip install params-proto==3.1.0
+pip install params-proto==3.1.1
 ```
 
 ## Three Decorators

{params_proto-3.1.0 → params_proto-3.1.2}/src/params_proto/envvar.py

@@ -153,24 +153,44 @@ class _EnvVar:
       return os.environ[name], True
     return None, False
 
-  def get(self, *, lazy: bool = True) -> Any:
+  def invalidate_cache(self):
+    """Clear the cached value, forcing re-read from environment on next access."""
+    self._cached_value = None
+    self._is_cached = False
+
+  def __get__(self, obj, objtype=None):
     """
-    Get the value from environment variable(s).
+    Descriptor protocol: auto-resolve EnvVar when accessed as a class attribute.
+
+    This enables EnvVar to work in plain classes (not decorated with @ParamsProto):
+
+        class MyConfig:
+            api_key: str = EnvVar @ "API_KEY" | "default"
+
+        # Accessing MyConfig.api_key returns the resolved value, not the _EnvVar object
+        print(MyConfig.api_key)  # "default" or value of $API_KEY
 
-    When multiple templates are specified (OR operation), tries each in order
-    and returns the first one that is set in the environment.
+    Values are cached after first resolution. Use invalidate_cache() to force re-read:
+
+        envvar = MyConfig.__dict__['api_key']  # Get the _EnvVar object
+        envvar.invalidate_cache()
+        print(MyConfig.api_key)  # Re-reads from environment
 
     Args:
-        lazy: If True (default), cache the result for subsequent calls.
-              Set to False to always re-read from environment.
+        obj: Instance (None if accessed on class)
+        objtype: The class being accessed
 
     Returns:
-        Value from environment or default, converted to dtype if specified
+        The resolved environment variable value
     """
     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:
+    # Don't resolve the singleton EnvVar instance itself (has no templates)
+    if not self.templates:
+      return self
+
+    # Return cached value if available
+    if self._is_cached:
       return self._cached_value
 
     # No templates means return default
@@ -192,18 +212,12 @@ class _EnvVar:
     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
+    # Cache the result
+    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.templates:
       if len(self.templates) == 1:

{params_proto-3.1.0 → params_proto-3.1.2}/src/params_proto/proto.py

@@ -177,7 +177,7 @@ class ProtoWrapper:
       if is_env_var:
         # Resolve env var at decoration time
         # NO auto-inference from parameter name for security reasons
-        env_value = default.get()
+        env_value = default.__get__(None, None)
 
         # Apply type conversion based on dtype (if provided) or annotation
         if env_value is not None:
@@ -801,7 +801,17 @@ def proto(
 
       for name in annotations.keys():
         if hasattr(obj, name):
-          value = getattr(obj, name)
+          # Look up value in class dict hierarchy to bypass descriptors like _EnvVar.__get__
+          value = None
+          for klass in obj.__mro__:
+            if klass is object:
+              continue
+            if name in vars(klass):
+              value = vars(klass)[name]
+              break
+          else:
+            value = getattr(obj, name)
+
           # Check for EnvVar first (before callable check, since _EnvVar has __call__)
           is_env_var = (
             hasattr(value, "__class__") and value.__class__.__name__ == "_EnvVar"
@@ -809,7 +819,7 @@ def proto(
 
           if is_env_var:
             # Resolve env var at decoration time
-            env_value = value.get()
+            env_value = value.__get__(None, None)
             annotation = annotations.get(name, str)
 
             # Apply type conversion based on dtype (if provided) or annotation
@@ -848,6 +858,11 @@ def proto(
           except AttributeError:
             pass
 
+      # 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
+
       # Create new class with metaclass
       new_cls = metaclass(
         obj.__name__,

{params_proto-3.1.0 → params_proto-3.1.2}/tests/test_v3/test_proto_envvar.py

@@ -445,11 +445,11 @@ def test_proto_envvar_class_with_type_conversion():
     del os.environ["RATIO"]
 
 
-def test_envvar_get_with_dtype():
-  """Test EnvVar.get() applies dtype conversion correctly.
+def test_envvar_dtype_conversion():
+  """Test EnvVar applies dtype conversion correctly via descriptor.
 
-  This tests the direct .get() method, not via @proto decoration.
-  Previously, dtype was stored but not applied in .get().
+  Tests that dtype parameter works for type conversion when accessed
+  as a class attribute (via __get__ descriptor).
   """
   import os
 
@@ -463,37 +463,51 @@ def test_envvar_get_with_dtype():
 
   try:
     # Test int conversion
-    port = EnvVar("PORT", dtype=int, default=8012).get()
-    assert port == 9000, f"Expected 9000, got {port}"
-    assert isinstance(port, int), f"Expected int, got {type(port)}"
+    class IntConfig:
+      port = EnvVar("PORT", dtype=int, default=8012)
+
+    assert IntConfig.port == 9000, f"Expected 9000, got {IntConfig.port}"
+    assert isinstance(IntConfig.port, int), f"Expected int, got {type(IntConfig.port)}"
 
     # Test float conversion
-    threshold = EnvVar("THRESHOLD", dtype=float, default=0.5).get()
-    assert threshold == 0.75, f"Expected 0.75, got {threshold}"
-    assert isinstance(threshold, float), f"Expected float, got {type(threshold)}"
+    class FloatConfig:
+      threshold = EnvVar("THRESHOLD", dtype=float, default=0.5)
+
+    assert FloatConfig.threshold == 0.75, f"Expected 0.75, got {FloatConfig.threshold}"
+    assert isinstance(FloatConfig.threshold, float), f"Expected float, got {type(FloatConfig.threshold)}"
 
     # Test bool conversion - "true"
-    debug = EnvVar("DEBUG", dtype=bool, default=False).get()
-    assert debug is True, f"Expected True, got {debug}"
-    assert isinstance(debug, bool), f"Expected bool, got {type(debug)}"
+    class BoolConfig:
+      debug = EnvVar("DEBUG", dtype=bool, default=False)
+
+    assert BoolConfig.debug is True, f"Expected True, got {BoolConfig.debug}"
+    assert isinstance(BoolConfig.debug, bool), f"Expected bool, got {type(BoolConfig.debug)}"
 
     # Test bool conversion - "1"
-    enabled = EnvVar("ENABLED", dtype=bool, default=False).get()
-    assert enabled is True, f"Expected True, got {enabled}"
+    class EnabledConfig:
+      enabled = EnvVar("ENABLED", dtype=bool, default=False)
+
+    assert EnabledConfig.enabled is True, f"Expected True, got {EnabledConfig.enabled}"
 
     # Test bool conversion - "false"
-    disabled = EnvVar("DISABLED", dtype=bool, default=True).get()
-    assert disabled is False, f"Expected False, got {disabled}"
+    class DisabledConfig:
+      disabled = EnvVar("DISABLED", dtype=bool, default=True)
+
+    assert DisabledConfig.disabled is False, f"Expected False, got {DisabledConfig.disabled}"
 
     # Test default value when env var not set
-    missing = EnvVar("MISSING_VAR", dtype=int, default=42).get()
-    assert missing == 42, f"Expected 42 (default), got {missing}"
-    assert isinstance(missing, int), f"Expected int, got {type(missing)}"
+    class MissingConfig:
+      missing = EnvVar("MISSING_VAR", dtype=int, default=42)
+
+    assert MissingConfig.missing == 42, f"Expected 42 (default), got {MissingConfig.missing}"
+    assert isinstance(MissingConfig.missing, int), f"Expected int, got {type(MissingConfig.missing)}"
 
     # Test without dtype - should return string
-    port_str = EnvVar("PORT", default="8012").get()
-    assert port_str == "9000", f"Expected '9000', got {port_str}"
-    assert isinstance(port_str, str), f"Expected str, got {type(port_str)}"
+    class StrConfig:
+      port_str = EnvVar("PORT", default="8012")
+
+    assert StrConfig.port_str == "9000", f"Expected '9000', got {StrConfig.port_str}"
+    assert isinstance(StrConfig.port_str, str), f"Expected str, got {type(StrConfig.port_str)}"
 
   finally:
     del os.environ["PORT"]
@@ -503,8 +517,8 @@ def test_envvar_get_with_dtype():
     del os.environ["DISABLED"]
 
 
-def test_envvar_get_with_dtype_template():
-  """Test EnvVar.get() applies dtype with template syntax."""
+def test_envvar_dtype_with_template():
+  """Test EnvVar applies dtype with template syntax."""
   import os
 
   from params_proto import EnvVar
@@ -513,9 +527,11 @@ def test_envvar_get_with_dtype_template():
 
   try:
     # Test with $ prefix template
-    count = EnvVar("$COUNT", dtype=int, default=0).get()
-    assert count == 100, f"Expected 100, got {count}"
-    assert isinstance(count, int), f"Expected int, got {type(count)}"
+    class TemplateConfig:
+      count = EnvVar("$COUNT", dtype=int, default=0)
+
+    assert TemplateConfig.count == 100, f"Expected 100, got {TemplateConfig.count}"
+    assert isinstance(TemplateConfig.count, int), f"Expected int, got {type(TemplateConfig.count)}"
 
   finally:
     del os.environ["COUNT"]
@@ -795,27 +811,117 @@ def test_envvar_lazy_loading():
   os.environ.pop("LAZY_TEST_VAR", None)
 
   try:
-    # Create EnvVar without env var set
-    ev = EnvVar @ "LAZY_TEST_VAR" | "default"
+    # Create class with EnvVar without env var set
+    class LazyConfig:
+      value = EnvVar @ "LAZY_TEST_VAR" | "default"
 
-    # First call - should return default
-    assert ev.get() == "default", f"Expected 'default', got {ev.get()}"
+    # First access - should return default
+    assert LazyConfig.value == "default", f"Expected 'default', got {LazyConfig.value}"
 
-    # Set env var after EnvVar was created
+    # Set env var after class was defined
     os.environ["LAZY_TEST_VAR"] = "lazy_value"
 
     # Cached value should still be default (lazy loading)
-    assert ev.get() == "default", f"Expected cached 'default', got {ev.get()}"
+    assert LazyConfig.value == "default", f"Expected cached 'default', got {LazyConfig.value}"
 
-    # Invalidate cache
-    ev.invalidate_cache()
+    # Invalidate cache via class __dict__
+    LazyConfig.__dict__["value"].invalidate_cache()
 
     # Now should read the new value
-    assert ev.get() == "lazy_value", f"Expected 'lazy_value', got {ev.get()}"
+    assert LazyConfig.value == "lazy_value", f"Expected 'lazy_value', got {LazyConfig.value}"
 
-    # Test non-lazy mode
+    # Test invalidate and re-read with updated value
     os.environ["LAZY_TEST_VAR"] = "updated_value"
-    assert ev.get(lazy=False) == "updated_value", f"Expected 'updated_value', got {ev.get(lazy=False)}"
+    LazyConfig.__dict__["value"].invalidate_cache()
+    assert LazyConfig.value == "updated_value", f"Expected 'updated_value', got {LazyConfig.value}"
 
   finally:
     os.environ.pop("LAZY_TEST_VAR", None)
+
+
+def test_envvar_descriptor_in_plain_class():
+  """Test EnvVar auto-resolves in plain classes (without @proto decorator).
+
+  This is a critical feature for users who want to use EnvVar in classes
+  that are not decorated with @proto, such as:
+
+      class VuerClient:
+          URI: str = EnvVar @ "VUER_CLIENT_URI" | "ws://localhost:8012"
+
+  Without the descriptor protocol, accessing VuerClient.URI would return
+  an _EnvVar object instead of the resolved value.
+  """
+  import os
+
+  from params_proto import EnvVar
+
+  # Clean up
+  os.environ.pop("PLAIN_CLASS_VAR", None)
+  os.environ.pop("PLAIN_CLASS_PORT", None)
+
+  try:
+    # Test 1: Plain class with EnvVar and default (env var NOT set)
+    class PlainConfig:
+      uri: str = EnvVar @ "PLAIN_CLASS_VAR" | "ws://localhost:8012"
+      port: int = EnvVar @ "PLAIN_CLASS_PORT" | 8080
+
+    # Accessing class attribute should return resolved value, not _EnvVar
+    assert PlainConfig.uri == "ws://localhost:8012", f"Expected default, got {PlainConfig.uri}"
+    assert isinstance(PlainConfig.uri, str), f"Expected str, got {type(PlainConfig.uri)}"
+
+    # Note: Without @proto, type conversion doesn't happen
+    # (the int annotation is not processed)
+    assert PlainConfig.port == 8080, f"Expected 8080, got {PlainConfig.port}"
+
+    # Test 2: With env var set
+    os.environ["PLAIN_CLASS_VAR"] = "ws://192.168.1.1:9000"
+
+    class PlainConfig2:
+      uri: str = EnvVar @ "PLAIN_CLASS_VAR" | "ws://localhost:8012"
+
+    assert PlainConfig2.uri == "ws://192.168.1.1:9000", f"Expected env value, got {PlainConfig2.uri}"
+
+    # Test 3: Instance access also works
+    c = PlainConfig2()
+    assert c.uri == "ws://192.168.1.1:9000", f"Expected env value on instance, got {c.uri}"
+
+  finally:
+    os.environ.pop("PLAIN_CLASS_VAR", None)
+    os.environ.pop("PLAIN_CLASS_PORT", None)
+
+
+def test_envvar_descriptor_websocket_max_size():
+  """Test EnvVar works for websocket max size pattern (the bug report case).
+
+  This tests the exact pattern that caused the original bug:
+      WEBSOCKET_MAX_SIZE: int = EnvVar @ "WEBSOCKET_MAX_SIZE" | 2**28
+
+  The issue was that accessing WEBSOCKET_MAX_SIZE returned an _EnvVar object
+  instead of the int value, causing: AttributeError: '_EnvVar' object has no attribute 'decode'
+  """
+  import os
+
+  from params_proto import EnvVar
+
+  os.environ.pop("WEBSOCKET_MAX_SIZE", None)
+
+  try:
+    class VuerClient:
+      URI: str = EnvVar @ "VUER_CLIENT_URI" | "ws://localhost:8012"
+      WEBSOCKET_MAX_SIZE: int = EnvVar @ "WEBSOCKET_MAX_SIZE" | 2**28
+
+    # Both should resolve to values, not _EnvVar objects
+    assert VuerClient.URI == "ws://localhost:8012", f"Expected default URI, got {VuerClient.URI}"
+    assert VuerClient.WEBSOCKET_MAX_SIZE == 2**28, f"Expected 2**28, got {VuerClient.WEBSOCKET_MAX_SIZE}"
+
+    # Verify types
+    assert isinstance(VuerClient.URI, str), f"URI should be str, got {type(VuerClient.URI)}"
+    assert isinstance(VuerClient.WEBSOCKET_MAX_SIZE, int), f"WEBSOCKET_MAX_SIZE should be int, got {type(VuerClient.WEBSOCKET_MAX_SIZE)}"
+
+    # The value should be usable (the original bug was .decode() failing)
+    # This simulates websocket operations that need to check max size
+    assert VuerClient.WEBSOCKET_MAX_SIZE > 0
+
+  finally:
+    os.environ.pop("WEBSOCKET_MAX_SIZE", None)
+    os.environ.pop("VUER_CLIENT_URI", None)