add ANY_VALUE sentinel (#189)

Author: NodeJSmith

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+- Added `ANY_VALUE` sentinel for clearer semantics in predicates - use this to indicate "any value is acceptable"
+
+### Changed
+- `NOT_PROVIDED` predicate is now used only to indicate that a parameter was not provided to a function
+
 ## [0.15.5] - 2025-11-14
 
 ### Changed

docs/pages/core-concepts/bus/index.md

@@ -241,7 +241,7 @@ filtering.
 ### Dictionary filtering
 
 ```python
-from hassette.const import NOT_PROVIDED
+from hassette.const import ANY_VALUE
 
 # Literal match
 self.bus.on_call_service(
@@ -255,7 +255,7 @@ self.bus.on_call_service(
 self.bus.on_call_service(
     domain="light",
     service="turn_on",
-    where={"brightness": NOT_PROVIDED},
+    where={"brightness": ANY_VALUE},
     handler=self.on_brightness_set,
 )
 

src/hassette/__init__.py

@@ -4,7 +4,7 @@
 from .app import App, AppConfig, AppSync, only_app
 from .bus import Bus, accessors, conditions, predicates
 from .config import HassetteConfig
-from .const import MISSING_VALUE, NOT_PROVIDED
+from .const import ANY_VALUE, MISSING_VALUE, NOT_PROVIDED
 from .core import Hassette
 from .events import StateChangeEvent
 from .models import entities, states
@@ -15,6 +15,7 @@
 logging.getLogger("hassette").addHandler(logging.NullHandler())
 
 __all__ = [
+    "ANY_VALUE",
     "MISSING_VALUE",
     "NOT_PROVIDED",
     "Api",

src/hassette/bus/accessors.py

@@ -1,7 +1,7 @@
 """
 Accessors are combined with predicates to easily and cleanly extract values from events. Instead of writing
-a lambda like ``lambda e: e.payload.data.old_state.state``, you can use the accessor ``get_state_value_old`` or
-use ``get_path("payload.data.old_state.state")`` for a more generic solution.
+a lambda like ``lambda e: e.payload.data.old_state_value``, you can use the accessor ``get_state_value_old`` or
+use ``get_path("payload.data.old_state_value")`` for a more generic solution.
 
 You generally will not need to use these directly — the main bus helpers use them under the hood to provide
 the relevant data to predicates. For example, ``on_state_change`` uses ``get_state_value_old`` and

src/hassette/bus/predicates.py

@@ -48,7 +48,7 @@ def is_kitchen_light(entity_id: str) -> bool:
 from logging import getLogger
 from typing import Any, Generic, TypeVar
 
-from hassette.const import MISSING_VALUE, NOT_PROVIDED
+from hassette.const import ANY_VALUE, MISSING_VALUE
 from hassette.events import CallServiceEvent
 from hassette.events.base import EventT
 from hassette.models.states import StateT
@@ -142,14 +142,14 @@ class ValueIs(Generic[EventT, V]):
 
     Args:
         source: Callable that extracts the value to compare from the event.
-        condition: A literal or callable tested against the extracted value. If NOT_PROVIDED, always True.
+        condition: A literal or callable tested against the extracted value. If ANY_VALUE, always True.
     """
 
     source: Callable[[EventT], V]
-    condition: ChangeType = NOT_PROVIDED
+    condition: ChangeType = ANY_VALUE
 
     def __call__(self, event: EventT) -> bool:
-        if self.condition is NOT_PROVIDED:
+        if self.condition is ANY_VALUE:
             return True
         value = self.source(event)
         return compare_value(value, self.condition)
@@ -366,9 +366,10 @@ def __post_init__(self) -> None:
 
         for k, cond in self.spec.items():
             source = get_service_data_key(k)
+            c: ChangeType
             # presence check
-            if cond is NOT_PROVIDED:
-                c: ChangeType = Present()
+            if cond is ANY_VALUE:
+                c = Present()
             # auto-glob wrapping
             elif self.auto_glob and isinstance(cond, str) and is_glob(cond):
                 c = Glob(cond)

src/hassette/const/__init__.py

@@ -1,8 +1,9 @@
 from .colors import COLORS, Color
-from .misc import MISSING_VALUE, NOT_PROVIDED
+from .misc import ANY_VALUE, MISSING_VALUE, NOT_PROVIDED
 from .sensor import DEVICE_CLASS, STATE_CLASS, UNIT_OF_MEASUREMENT
 
 __all__ = [
+    "ANY_VALUE",
     "COLORS",
     "DEVICE_CLASS",
     "MISSING_VALUE",

src/hassette/const/misc.py

@@ -13,3 +13,6 @@ def __bool__(self) -> bool:
 
 NOT_PROVIDED = FalseySentinel("NOT_PROVIDED")
 """Sentinel value to indicate a value was not provided."""
+
+ANY_VALUE = FalseySentinel("ANY_VALUE")
+"""Sentinel value to indicate any value is acceptable (used in predicates for presence checks)."""

tests/predicates/test_predicates.py

@@ -9,7 +9,7 @@
 from hassette import conditions as C
 from hassette import predicates as P
 from hassette.bus.utils import compare_value, ensure_tuple, normalize_where
-from hassette.const import MISSING_VALUE, NOT_PROVIDED
+from hassette.const import ANY_VALUE, MISSING_VALUE, NOT_PROVIDED
 from hassette.events import CallServiceEvent, Event
 
 
@@ -315,15 +315,15 @@ def brightness_gt_200(value: int) -> bool:
 
 
 def test_service_data_where_with_not_provided() -> None:
-    """Test ServiceDataWhere requiring key presence with NOT_PROVIDED."""
+    """Test ServiceDataWhere requiring key presence with ANY_VALUE."""
     event = _create_service_event(domain="light", service="turn_on", service_data={"entity_id": "light.kitchen"})
 
     # Key exists
-    predicate = P.ServiceDataWhere({"entity_id": NOT_PROVIDED})
+    predicate = P.ServiceDataWhere({"entity_id": ANY_VALUE})
     assert predicate(event) is True
 
     # Key missing
-    predicate = P.ServiceDataWhere({"brightness": NOT_PROVIDED})
+    predicate = P.ServiceDataWhere({"brightness": ANY_VALUE})
     assert predicate(event) is False
 
 

tests/predicates/test_service_data_where.py

@@ -2,7 +2,7 @@
 from types import SimpleNamespace
 
 from hassette.bus.predicates import ServiceDataWhere
-from hassette.const import NOT_PROVIDED
+from hassette.const import ANY_VALUE
 from hassette.events import Event
 
 
@@ -13,16 +13,16 @@ def _make_event(service_data: dict[str, typing.Any]) -> Event:
 
 
 def test_service_data_where_not_provided_requires_presence() -> None:
-    """Test that ServiceDataWhere with NOT_PROVIDED requires key presence."""
-    predicate = ServiceDataWhere({"required": NOT_PROVIDED})
+    """Test that ServiceDataWhere with ANY_VALUE requires key presence."""
+    predicate = ServiceDataWhere({"required": ANY_VALUE})
 
     assert predicate(_make_event({"required": 0})) is True
     assert predicate(_make_event({})) is False
 
 
 def test_service_data_where_typing_any_requires_presence() -> None:
-    """Test that ServiceDataWhere with NOT_PROVIDED works with any value type."""
-    predicate = ServiceDataWhere({"required": NOT_PROVIDED})
+    """Test that ServiceDataWhere with ANY_VALUE works with any value type."""
+    predicate = ServiceDataWhere({"required": ANY_VALUE})
 
     assert predicate(_make_event({"required": "value"})) is True
     assert predicate(_make_event({})) is False
@@ -74,7 +74,7 @@ def test_service_data_where_multiple_conditions() -> None:
     predicate = ServiceDataWhere(
         {
             "entity_id": "light.*",
-            "brightness": NOT_PROVIDED,  # Must be present
+            "brightness": ANY_VALUE,  # Must be present
             "transition": 2,
         }
     )