Add support for schema 46 metadata fields (#1403)

* Add support for schema 46 metadata fields

Schema 46 (upstream PR #1501) adds two metadata fields:
- `allowed`: list of allowed values for numeric value metadata and
  configuration metadata, where each entry is either a single value
  (`{value}`) or an inclusive range (`{from, to, step?}`)
- `purpose`: free-form string on configuration metadata

`AllowedValue` is exposed as a discriminated union of two frozen
dataclasses (`AllowedSingleValue`, `AllowedRangeValue`) so consumers
use `isinstance()` to discriminate. The `ValueMetadata.allowed`
accessor is a `cached_property` because parsing allocates new dataclass
instances; the cache is invalidated in `update()` only when the
incoming patch contains the `allowed` key.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Address Copilot review: use cast instead of dict copy in allowed parser

Copilot flagged that `ValueMetadata.allowed` built a new `dict(entry)`
on every iteration (plus a `type: ignore`) inside a method explicitly
cached to reduce allocations. Replace with `typing.cast`, which is a
runtime no-op, so each iteration now touches the original entry dict
directly and drops the `type: ignore`.

Only the `if` branch needs an explicit cast — mypy narrows the `else`
branch automatically from `"value" in entry` being false.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add from_dict classmethods to AllowedSingleValue/AllowedRangeValue

Follow the codebase convention of putting dict-to-dataclass conversion
into a `from_dict` classmethod rather than inline in the caller. The
`allowed` property accessor now delegates to these methods.

No `to_dict` needed — `AllowedValue` is read-only server metadata that
is never sent back, matching the event model precedent.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix ref to self

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: raman325

test/conftest.py

@@ -262,7 +262,7 @@ def version_data_fixture() -> dict[str, Any]:
         "serverVersion": "test_server_version",
         "homeId": "test_home_id",
         "minSchemaVersion": 0,
-        "maxSchemaVersion": 45,
+        "maxSchemaVersion": 46,
     }
 
 

test/model/test_value.py

@@ -5,11 +5,14 @@
 from zwave_js_server.const import ConfigurationValueType, SetValueStatus
 from zwave_js_server.model.node import Node
 from zwave_js_server.model.value import (
+    AllowedRangeValue,
+    AllowedSingleValue,
     ConfigurationValue,
     ConfigurationValueFormat,
     MetaDataType,
     SetValueResult,
     ValueDataType,
+    ValueMetadata,
     get_value_id_str,
 )
 
@@ -77,6 +80,55 @@ def test_secret(lock_schlage_be469):
     assert zwave_value.metadata.stateful
 
 
+def test_metadata_purpose():
+    """`purpose` is None by default and exposes the raw string when set."""
+    assert ValueMetadata(MetaDataType(type="number")).purpose is None
+    metadata = ValueMetadata(MetaDataType(type="number", purpose="dimmer ramp rate"))
+    assert metadata.purpose == "dimmer ramp rate"
+
+
+def test_metadata_allowed_parsing():
+    """`allowed` returns None by default and parses both shapes via isinstance."""
+    assert ValueMetadata(MetaDataType(type="number")).allowed is None
+
+    metadata = ValueMetadata(
+        MetaDataType(
+            type="number",
+            allowed=[
+                {"value": 0},
+                {"from": 10, "to": 20, "step": 2},
+                {"from": -5, "to": 5},
+            ],
+        )
+    )
+    allowed = metadata.allowed
+    assert allowed is not None
+    assert allowed == [
+        AllowedSingleValue(value=0),
+        AllowedRangeValue(from_=10, to=20, step=2),
+        AllowedRangeValue(from_=-5, to=5, step=None),
+    ]
+    # Discrimination via isinstance is the public API.
+    assert isinstance(allowed[0], AllowedSingleValue)
+    assert isinstance(allowed[1], AllowedRangeValue)
+
+
+def test_metadata_allowed_cache_invalidation():
+    """`allowed` is cached and only re-parsed when `update()` touches the key."""
+    metadata = ValueMetadata(MetaDataType(type="number", allowed=[{"value": 1}]))
+    first = metadata.allowed
+    assert metadata.allowed is first  # cache hit
+
+    # Updating an unrelated field keeps the cached list.
+    metadata.update(MetaDataType(label="renamed"))
+    assert metadata.allowed is first
+
+    # Updating the `allowed` key invalidates the cache.
+    metadata.update(MetaDataType(allowed=[{"from": 0, "to": 5}]))
+    assert metadata.allowed is not first
+    assert metadata.allowed == [AllowedRangeValue(from_=0, to=5, step=None)]
+
+
 def test_configuration_value_type(inovelli_switch_state):
     """Test configuration value types."""
     value = ConfigurationValue(

test/test_client.py

@@ -463,7 +463,7 @@ async def test_additional_user_agent_components(client_session, url):
             {
                 "command": "initialize",
                 "messageId": "initialize",
-                "schemaVersion": 45,
+                "schemaVersion": 46,
                 "additionalUserAgentComponents": {
                     "zwave-js-server-python": __version__,
                     "foo": "bar",

test/test_dump.py

@@ -106,7 +106,7 @@ async def test_dump_additional_user_agent_components(
         {
             "command": "initialize",
             "messageId": "initialize",
-            "schemaVersion": 45,
+            "schemaVersion": 46,
             "additionalUserAgentComponents": {
                 "zwave-js-server-python": __version__,
                 "foo": "bar",

test/test_main.py

@@ -58,7 +58,7 @@ def test_dump_state(
     assert captured.out == (
         "{'type': 'version', 'driverVersion': 'test_driver_version', "
         "'serverVersion': 'test_server_version', 'homeId': 'test_home_id', "
-        "'minSchemaVersion': 0, 'maxSchemaVersion': 45}\n"
+        "'minSchemaVersion': 0, 'maxSchemaVersion': 46}\n"
         "{'type': 'result', 'success': True, 'result': {}, 'messageId': 'initialize'}\n"
         "test_result\n"
     )

zwave_js_server/const/__init__.py

@@ -13,7 +13,7 @@
 # minimal server schema version we can handle
 MIN_SERVER_SCHEMA_VERSION = 44
 # max server schema version we can handle (and our code is compatible with)
-MAX_SERVER_SCHEMA_VERSION = 45
+MAX_SERVER_SCHEMA_VERSION = 46
 
 VALUE_UNKNOWN = "unknown"
 

zwave_js_server/model/value.py

@@ -4,7 +4,8 @@
 
 from dataclasses import dataclass, field
 from enum import IntEnum, StrEnum
-from typing import TYPE_CHECKING, Any, TypedDict
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, NotRequired, Self, TypedDict, cast
 
 from ..const import (
     VALUE_UNKNOWN,
@@ -30,6 +31,54 @@ class ValueType(StrEnum):
     STRING = "string"
 
 
+class AllowedSingleValueDataType(TypedDict):
+    """Represent a single allowed value entry (`{value: number}`)."""
+
+    value: int
+
+
+# `from` is a Python keyword, so the functional TypedDict form is required.
+AllowedRangeValueDataType = TypedDict(
+    "AllowedRangeValueDataType",
+    {"from": int, "to": int, "step": NotRequired[int]},
+)
+
+
+# AllowedValue is a discriminated union: either a single value or an inclusive range.
+# The TypeScript type is `{ value: number } | { from: number; to: number; step?: number }`.
+AllowedValueDataType = AllowedSingleValueDataType | AllowedRangeValueDataType
+
+
+@dataclass(frozen=True)
+class AllowedSingleValue:
+    """A single allowed value for a numeric metadata field (schema 46+)."""
+
+    value: int
+
+    @classmethod
+    def from_dict(cls, data: AllowedSingleValueDataType) -> AllowedSingleValue:
+        """Initialize from dict."""
+        return cls(value=data["value"])
+
+
+@dataclass(frozen=True)
+class AllowedRangeValue:
+    """An inclusive allowed value range for a numeric metadata field (schema 46+)."""
+
+    from_: int
+    to: int
+    step: int | None = None
+
+    @classmethod
+    def from_dict(cls, data: AllowedRangeValueDataType) -> Self:
+        """Initialize from dict."""
+        return cls(from_=data["from"], to=data["to"], step=data.get("step"))
+
+
+# Discriminated union — use isinstance() to differentiate.
+AllowedValue = AllowedSingleValue | AllowedRangeValue
+
+
 class MetaDataType(TypedDict, total=False):
     """Represent a metadata data dict type."""
 
@@ -48,13 +97,15 @@ class MetaDataType(TypedDict, total=False):
     stateful: bool
     secret: bool
     default: int
+    allowed: list[AllowedValueDataType]  # schema 46+
     # Configuration Value specific attributes
     valueSize: int
     format: int
     noBulkSupport: bool  # deprecated
     isAdvanced: bool
     requiresReInclusion: bool
     isFromConfig: bool
+    purpose: str  # schema 46+, configuration metadata only
 
 
 class ValueDataType(TypedDict, total=False):
@@ -184,6 +235,25 @@ def secret(self) -> bool | None:
         """Return secret."""
         return self.data.get("secret")
 
+    @cached_property
+    def allowed(self) -> list[AllowedValue] | None:
+        """Return allowed values.
+
+        Each entry is either an `AllowedSingleValue` or an `AllowedRangeValue`;
+        use ``isinstance`` to discriminate. Cached because parsing allocates
+        new dataclass instances; the cache is invalidated by `update()`.
+        """
+        if (raw := self.data.get("allowed")) is None:
+            return None
+        return [
+            (
+                AllowedSingleValue.from_dict(cast("AllowedSingleValueDataType", entry))
+                if "value" in entry
+                else AllowedRangeValue.from_dict(entry)
+            )
+            for entry in raw
+        ]
+
     @property
     def default(self) -> int | None:
         """Return default."""
@@ -216,9 +286,17 @@ def is_from_config(self) -> bool | None:
         """Return isFromConfig."""
         return self.data.get("isFromConfig")
 
+    @property
+    def purpose(self) -> str | None:
+        """Return purpose."""
+        return self.data.get("purpose")
+
     def update(self, data: MetaDataType) -> None:
         """Update data."""
         self.data.update(data)
+        # Invalidate cached_property entries when their backing key changed.
+        if "allowed" in data:
+            self.__dict__.pop("allowed", None)
 
 
 class Value: