diff --git a/custom_components/pyscript/decorator.py b/custom_components/pyscript/decorator.py index cd5fbc4c..0e7d0ffc 100644 --- a/custom_components/pyscript/decorator.py +++ b/custom_components/pyscript/decorator.py @@ -23,7 +23,7 @@ TriggerDecorator, TriggerHandlerDecorator, ) -from .eval import AstEval, EvalFunc, EvalFuncVar +from .eval import AstEval, EvalFunc, EvalFuncVar, EvalFuncVarClassInst from .function import Function from .state import State @@ -91,6 +91,11 @@ def register(cls, dec_type: type[Decorator]) -> None: ) cls._decorators[dec_type.name] = dec_type + @classmethod + def registered_names(cls) -> set[str]: + """Return the names of all registered decorator types.""" + return set(cls._decorators) + @classmethod async def get_decorator_by_expr(cls, ast_ctx: AstEval, dec_expr: ast.expr) -> Decorator | None: """Return decorator instance from an AST decorator expression.""" @@ -248,6 +253,11 @@ def __init__(self, ast_ctx: AstEval, eval_func_var: EvalFuncVar) -> None: self.logger = self.eval_func.logger + # set for per-instance method triggers; self is injected on dispatch + self.instance_weak: weakref.ReferenceType | None = ( + eval_func_var.class_inst_weak if isinstance(eval_func_var, EvalFuncVarClassInst) else None + ) + def on_func_var_deleted(): if self.status is DecoratorManagerStatus.RUNNING: self.hass.async_create_task(self.safe_await(self.stop())) @@ -285,7 +295,14 @@ async def _call(self, data: DispatchData) -> None: else: accepted = {a.arg for a in func_args.args + func_args.kwonlyargs} call_kwargs = {k: v for k, v in data.func_args.items() if k in accepted} - result = await data.call_ast_ctx.call_func(self.eval_func, None, **call_kwargs) + self_args = () + if self.instance_weak is not None: + inst = self.instance_weak() + if inst is None: + return + call_kwargs.pop("self", None) + self_args = (inst,) + result = await data.call_ast_ctx.call_func(self.eval_func, None, *self_args, **call_kwargs) except Exception as e: for result_handler_dec in result_handlers: await self.safe_await(result_handler_dec.handle_call_exception(data, e)) diff --git a/custom_components/pyscript/decorators/base.py b/custom_components/pyscript/decorators/base.py index 3babc243..f0100ee6 100644 --- a/custom_components/pyscript/decorators/base.py +++ b/custom_components/pyscript/decorators/base.py @@ -64,8 +64,18 @@ async def check_expression_vars(self, state_vars: dict[str, Any]) -> bool: """Evaluate expression and dispatch an exception event via manager on failure.""" if not self.has_expression(): raise AttributeError(f"{self} has no expression defined") + # per-instance method trigger: make self visible to the condition + inst_weak = getattr(self.dm, "instance_weak", None) + if inst_weak is not None: + inst = inst_weak() + if inst is None: + return False + state_vars = {**state_vars, "self": inst} try: return await self._ast_expression.eval(state_vars) except Exception as exc: await self.dm.handle_exception(exc) return False + finally: + # eval() persists state_vars; drop self so it can't keep the instance alive + getattr(self._ast_expression, "local_sym_table", {}).pop("self", None) diff --git a/custom_components/pyscript/eval.py b/custom_components/pyscript/eval.py index e27f4306..1c5ad60c 100644 --- a/custom_components/pyscript/eval.py +++ b/custom_components/pyscript/eval.py @@ -96,6 +96,15 @@ } +def dec_name_from_expr(dec: ast.expr) -> str | None: + """Return a decorator's name from its AST expression, or None if not a plain name or call.""" + if isinstance(dec, ast.Name): + return dec.id + if isinstance(dec, ast.Call) and isinstance(dec.func, ast.Name): + return dec.func.id + return None + + def ast_eval_exec_factory(ast_ctx, mode): """Generate a function that executes eval() or exec() with given ast_ctx.""" @@ -342,6 +351,8 @@ def __init__( self.trigger_service = set() self.has_closure = False self.async_func = async_func + # trigger decorators deferred to per-instance registration (see ast_functiondef) + self.deferred_dm_decorators: list[ast.expr] | None = None def get_name(self): """Return the function name.""" @@ -608,7 +619,7 @@ def trigger_stop(self): Function.service_remove(self.global_ctx_name, domain, name) self.trigger_service = set() - async def eval_decorators(self, ast_ctx): + async def eval_decorators(self, ast_ctx, defer_trig=False): """Evaluate the function decorators arguments.""" code_str, code_list = ast_ctx.code_str, ast_ctx.code_list ast_ctx.code_str, ast_ctx.code_list = self.code_str, self.code_list @@ -617,6 +628,10 @@ async def eval_decorators(self, ast_ctx): dec_trig = [] dec_dm = [] for dec in self.func_def.decorator_list: + if defer_trig and dec_name_from_expr(dec) in TRIG_DECORATORS: + # deferred method trigger; its arguments are evaluated per instance + # at instantiation time (they may reference self) + continue if known_dec := await ast_ctx.global_ctx.get_decorator_by_expr(ast_ctx, dec): dec_dm.append(known_dec) elif ( @@ -917,6 +932,7 @@ def __init__(self, name: str, global_ctx: "GlobalContext", logger_name: str | No self.sym_table = self.global_sym_table self.local_sym_table: SymTable = {} self.user_locals: SymTable = {} + self.in_class_body = False self.curr_func: EvalFunc | None = None self.filename = name self.code_str: str | None = None @@ -1078,12 +1094,15 @@ async def ast_classdef(self, arg): sym_table = {} self.sym_table_stack.append(self.sym_table) self.sym_table = sym_table + prev_in_class_body = self.in_class_body + self.in_class_body = True for arg1 in arg.body: val = await self.aeval(arg1) if isinstance(val, EvalReturn): raise SyntaxError(f"{val.name()} statement outside function") if isinstance(val, EvalStopFlow): raise SyntaxError(f"{val.name()} statement outside loop") + self.in_class_body = prev_in_class_body self.sym_table = self.sym_table_stack.pop() decorators = [await self.aeval(dec) for dec in arg.decorator_list] @@ -1096,6 +1115,15 @@ async def ast_classdef(self, arg): cls = await cls for dec_func in reversed(decorators): cls = await self.call_func(dec_func, None, cls) + # names of methods whose triggers register per instance; at construction the + # most-derived definition of each name wins (see register_method_triggers) + deferred = set() + for meth_name, meth_val in sym_table.items(): + meth_func = meth_val.get_func() if isinstance(meth_val, EvalFuncVar) else None + if meth_func is not None and meth_func.deferred_dm_decorators: + deferred.add(meth_name) + if deferred: + cls.__pyscript_method_triggers__ = deferred sym_table_assign[arg.name].set(cls) async def ast_functiondef(self, arg, async_func=False): @@ -1158,7 +1186,22 @@ async def executor_wrap(*args, **kwargs): await func.eval_defaults(self) await func.resolve_nonlocals(self) name = func.get_name() - dec_trig, dec_other, dec_dm = await func.eval_decorators(self) + # a self-taking method's trigger can't bind at definition time (no instance yet); + # skip eager evaluation of its trigger decorators and defer registration to + # register_method_triggers. Self-less methods keep class-level behavior. + # With legacy decorators the registry is empty, so triggers stay on the old path. + pos_args = func.get_positional_args() + deferred_dec_exprs = [ + dec for dec in arg.decorator_list if dec_name_from_expr(dec) in TRIG_DECORATORS + ] + defer_trig = ( + self.in_class_body + and bool(pos_args) + and pos_args[0] == "self" + and bool(deferred_dec_exprs) + and bool(self.global_ctx.get_decorator_names().intersection(TRIG_DECORATORS)) + ) + dec_trig, dec_other, dec_dm = await func.eval_decorators(self, defer_trig) self.dec_eval_depth += 1 for dec_func in dec_other: func = await self.call_func(dec_func, None, func) @@ -1174,20 +1217,19 @@ async def executor_wrap(*args, **kwargs): if isinstance(func, EvalFunc): func.decorators = dec_trig func.dm_decorators = dec_dm - if self.dec_eval_depth == 0: + func_var = EvalFuncVar(func) + func_var.set_ast_ctx(self) + if defer_trig: + func.deferred_dm_decorators = deferred_dec_exprs + elif self.dec_eval_depth == 0: func.trigger_stop() try: await func.trigger_init(self.global_ctx, name) except Exception as e: self.log_exception(e) - func_var = EvalFuncVar(func) - func_var.set_ast_ctx(self) if len(dec_dm) > 0: await self.get_global_ctx().create_decorator_manager(dec_dm, self, func_var) - else: - func_var = EvalFuncVar(func) - func_var.set_ast_ctx(self) else: func_var = func @@ -1879,6 +1921,46 @@ async def ast_call(self, arg): func = func.get() return await self.call_func(func, func_name, *args, **kwargs) + async def register_method_triggers(self, inst): + """Register deferred method triggers for a new instance.""" + cls = type(inst) + names: set[str] = set() + for klass in cls.__mro__: + names.update(klass.__dict__.get("__pyscript_method_triggers__", ())) + if not names: + return + keep = [] + for meth_name in names: + # the most-derived definition of the name wins, as when calling it directly + meth_val = next( + (klass.__dict__[meth_name] for klass in cls.__mro__ if meth_name in klass.__dict__), + None, + ) + meth_func = meth_val.get_func() if isinstance(meth_val, EvalFuncVar) else None + dec_exprs = meth_func.deferred_dm_decorators if meth_func else None + if not dec_exprs: + continue + ast_ctx = meth_val.get_ast_ctx() + # evaluate decorator arguments now, with self visible, so they can + # reference instance attributes (eg: the entity to watch) + arg_ctx = AstEval(f"{ast_ctx.name}.{meth_name}", ast_ctx.global_ctx) + Function.install_ast_funcs(arg_ctx) + arg_ctx.local_sym_table = {"self": inst} + decs = [] + for dec in dec_exprs: + known = await ast_ctx.global_ctx.get_decorator_by_expr(arg_ctx, dec) + if known is not None: + decs.append(known) + if not decs: + continue + func_var = EvalFuncVarClassInst(meth_func, ast_ctx, weakref.ref(inst)) + dm = await ast_ctx.global_ctx.create_decorator_manager(decs, ast_ctx, func_var) + # drop the manager from the global set once the instance dies + weakref.finalize(func_var, ast_ctx.global_ctx.dms.discard, dm) + keep.append(func_var) + if keep: + inst.__pyscript_method_trigger_vars__ = keep + async def call_func(self, func, func_name, *args, **kwargs): """Call a function with the given arguments.""" if func_name is None: @@ -1901,6 +1983,7 @@ async def call_func(self, func, func_name, *args, **kwargs): # since our __init__ function is async, call the renamed one # await inst.__init__evalfunc_wrap__.call(self, *args, **kwargs) + await self.register_method_triggers(inst) return inst if inspect.iscoroutinefunction(func): return await func(*args, **kwargs) diff --git a/custom_components/pyscript/global_ctx.py b/custom_components/pyscript/global_ctx.py index 0eb5c470..0f2df18d 100644 --- a/custom_components/pyscript/global_ctx.py +++ b/custom_components/pyscript/global_ctx.py @@ -71,9 +71,13 @@ async def get_decorator_by_expr(self, ast_ctx: AstEval, dec: ast.expr) -> Decora """Return decorator instance from an AST decorator expression.""" return await DecoratorRegistry.get_decorator_by_expr(ast_ctx, dec) + def get_decorator_names(self) -> set[str]: + """Return the names of all registered decorator types.""" + return DecoratorRegistry.registered_names() + async def create_decorator_manager( self, decs: list[Decorator], ast_ctx: AstEval, func_var: EvalFuncVar - ) -> None: + ) -> FunctionDecoratorManager: """Create decorator manager from an AST decorator expression.""" dm = FunctionDecoratorManager(ast_ctx, func_var) for dec in decs: @@ -86,6 +90,7 @@ async def create_decorator_manager( await dm.safe_await(dm.start()) else: self.dms_delay_start.add(dm) + return dm def trigger_unregister(self, func: EvalFunc) -> None: """Unregister a trigger function.""" diff --git a/docs/reference.rst b/docs/reference.rst index 58bc328b..a2cc10e8 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -396,6 +396,31 @@ A Python function with decorators is still a normal Python function that can be Python function. The decorators have no effect in the case where you call it directly from another function. +Trigger decorators on class methods +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Trigger decorators work on methods that take ``self``. Each instance gets its own trigger, and +``self`` is available in the method, in the condition string, and in the decorator arguments. +Decorator arguments are evaluated when each instance is created, so instances can watch +different entities: + +.. code:: python + + class LightSwitch: + def __init__(self, entity_id): + self.entity_id = entity_id + + @state_trigger(f"{self.entity_id} == 'on'") + def on_turn_on(self, var_name=None, value=None): + ... + +The trigger string is fixed when the instance is created; changing the attribute later does not +move the trigger -- create a new instance instead. + +Triggers are cleaned up automatically when the instance is collected. With inheritance, the +most-derived definition of the method wins, as when calling it directly: an override without +trigger decorators removes the inherited trigger. + @state_trigger ^^^^^^^^^^^^^^ diff --git a/tests/test_method_triggers.py b/tests/test_method_triggers.py new file mode 100644 index 00000000..65ffd722 --- /dev/null +++ b/tests/test_method_triggers.py @@ -0,0 +1,375 @@ +"""Test trigger decorators on class methods (per-instance registration).""" + +from ast import literal_eval +import asyncio +from datetime import datetime as dt +from unittest.mock import mock_open, patch + +import pytest + +from custom_components.pyscript import trigger +from custom_components.pyscript.const import DOMAIN +from custom_components.pyscript.function import Function +from homeassistant.const import EVENT_HOMEASSISTANT_STARTED, EVENT_STATE_CHANGED +from homeassistant.setup import async_setup_component + + +async def setup_script(hass, notify_q, now, source): + """Initialize and load the given pyscript.""" + scripts = ["/some/config/dir/pyscripts/hello.py"] + + Function.hass = None + + with ( + patch("custom_components.pyscript.os.path.isdir", return_value=True), + patch("custom_components.pyscript.glob.iglob", return_value=scripts), + patch("custom_components.pyscript.global_ctx.open", mock_open(read_data=source)), + patch("custom_components.pyscript.open", mock_open(read_data=source)), + patch("custom_components.pyscript.trigger.dt_now", return_value=now), + patch("homeassistant.config.load_yaml_config_file", return_value={}), + patch("custom_components.pyscript.watchdog_start", return_value=None), + patch("custom_components.pyscript.os.path.getmtime", return_value=1000), + patch("custom_components.pyscript.global_ctx.os.path.getmtime", return_value=1000), + patch("custom_components.pyscript.install_requirements", return_value=None), + ): + assert await async_setup_component(hass, "pyscript", {DOMAIN: {}}) + + trigger.__dict__["dt_now"] = lambda: now + + if notify_q: + + async def state_changed(event): + if event.data["entity_id"] != "pyscript.done": + return + await notify_q.put(event.data["new_state"].state) + + hass.bus.async_listen(EVENT_STATE_CHANGED, state_changed) + + +async def wait_until_done(notify_q): + """Wait for the done handshake.""" + return await asyncio.wait_for(notify_q.get(), timeout=4) + + +@pytest.mark.asyncio +async def test_method_trigger_self_bound(hass): + """A @state_trigger method fires with the right self and keeps per-instance state.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class Counter: + def __init__(self, name): + self.name = name + self.count = 0 + + @state_trigger("pyscript.avar1 == '1'") + def bump(self, var_name=None, value=None): + self.count = self.count + 1 + pyscript.done = [self.name, self.count] + +c = Counter("c1") +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.avar1", "1") + assert literal_eval(await wait_until_done(notify_q)) == ["c1", 1] + + hass.states.async_set("pyscript.avar1", "0") + hass.states.async_set("pyscript.avar1", "1") + assert literal_eval(await wait_until_done(notify_q)) == ["c1", 2] + + +@pytest.mark.asyncio +async def test_method_trigger_two_instances(hass): + """Two instances each get their own trigger and fire independently.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class Counter: + def __init__(self, name): + self.name = name + + @state_trigger("pyscript.bvar1 == '1'") + def bump(self, var_name=None, value=None): + pyscript.done = self.name + +c1 = Counter("c1") +c2 = Counter("c2") +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.bvar1", "1") + got = {await wait_until_done(notify_q) for _ in range(2)} + assert got == {"c1", "c2"} + + +@pytest.mark.asyncio +async def test_method_trigger_death_stops(hass): + """When the instance is collected, its trigger stops firing.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class Counter: + def __init__(self, name): + self.name = name + + @state_trigger("pyscript.cvar1 == '1'") + def bump(self, var_name=None, value=None): + pyscript.done = self.name + +c = Counter("alive") + +@service +def kill(): + global c + del c + pyscript.done = "killed" +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.cvar1", "1") + assert await wait_until_done(notify_q) == "alive" + + await hass.services.async_call("pyscript", "kill", blocking=True) + assert await wait_until_done(notify_q) == "killed" + + # let the instance's finalize stop the trigger + await asyncio.sleep(0.1) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.cvar1", "0") + hass.states.async_set("pyscript.cvar1", "1") + with pytest.raises(asyncio.TimeoutError): + await asyncio.wait_for(notify_q.get(), timeout=1) + + +@pytest.mark.asyncio +async def test_selfless_method_trigger_unchanged(hass): + """A trigger method without self keeps the old class-level (static) behavior.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class Helper: + @state_trigger("pyscript.dvar1 == '1'") + def static_thing(var_name=None, value=None): + pyscript.done = "static" +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.dvar1", "1") + assert await wait_until_done(notify_q) == "static" + + +@pytest.mark.asyncio +async def test_self_in_condition(hass): + """A trigger condition can reference self.; only matching instances fire.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class Thing: + def __init__(self, target): + self.target = target + + @state_trigger("pyscript.evar1 == self.target") + def fire(self, var_name=None, value=None): + pyscript.done = self.target + +a = Thing("hello") +b = Thing("world") +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.evar1", "world") + assert await wait_until_done(notify_q) == "world" + + hass.states.async_set("pyscript.evar1", "nope") + hass.states.async_set("pyscript.evar1", "hello") + assert await wait_until_done(notify_q) == "hello" + + +@pytest.mark.asyncio +async def test_trigger_method_override_undecorated(hass): + """An undecorated override replaces the inherited trigger method.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class Base: + @state_trigger("pyscript.fvar1 == '1'") + def handler(self, var_name=None, value=None): + pyscript.done = "base" + +class Sub(Base): + def handler(self, var_name=None, value=None): + pyscript.done = "sub" + +s = Sub() +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.fvar1", "1") + with pytest.raises(asyncio.TimeoutError): + await asyncio.wait_for(notify_q.get(), timeout=1) + + +@pytest.mark.asyncio +async def test_trigger_method_override_decorated(hass): + """A decorated override replaces the inherited trigger method, firing once.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class Base: + @state_trigger("pyscript.gvar1 == '1'") + def handler(self, var_name=None, value=None): + pyscript.done = "base" + +class Sub(Base): + @state_trigger("pyscript.gvar1 == '1'") + def handler(self, var_name=None, value=None): + pyscript.done = "sub" + +s = Sub() +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.gvar1", "1") + assert await wait_until_done(notify_q) == "sub" + with pytest.raises(asyncio.TimeoutError): + await asyncio.wait_for(notify_q.get(), timeout=1) + + +@pytest.mark.asyncio +async def test_trigger_method_inherited(hass): + """A subclass without an override gets the inherited trigger method.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class Base: + @state_trigger("pyscript.hvar1 == '1'") + def handler(self, var_name=None, value=None): + pyscript.done = "inherited" + +class Sub(Base): + def __init__(self, tag): + self.tag = tag + +s = Sub("sub-instance") +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.hvar1", "1") + assert await wait_until_done(notify_q) == "inherited" + + +@pytest.mark.asyncio +async def test_method_trigger_dynamic_entity(hass): + """Decorator arguments can use self, so each instance watches its own entity.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class LightSwitch: + def __init__(self, entity): + self.entity = entity + + @state_trigger(f"{self.entity} == 'on'") + def on_turn_on(self, var_name=None, value=None): + pyscript.done = self.entity + +sw1 = LightSwitch("pyscript.ivar1") +sw2 = LightSwitch("pyscript.ivar2") +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.ivar2", "on") + assert await wait_until_done(notify_q) == "pyscript.ivar2" + + hass.states.async_set("pyscript.ivar1", "off") + hass.states.async_set("pyscript.ivar1", "on") + assert await wait_until_done(notify_q) == "pyscript.ivar1" + + +@pytest.mark.asyncio +async def test_method_trigger_self_in_all_dec_args(hass): + """A deferred decorator's arguments can use self, eg: a per-instance task_unique name.""" + notify_q = asyncio.Queue(0) + await setup_script( + hass, + notify_q, + dt(2020, 7, 1, 11, 59, 59, 999999), + """ +class T: + def __init__(self, entity, tag): + self.entity = entity + self.tag = tag + + @task_unique(f"tu-{self.tag}") + @state_trigger(f"{self.entity} == '1'") + def go(self, var_name=None, value=None): + pyscript.done = self.tag + +a = T("pyscript.jvar1", "a") +b = T("pyscript.jvar2", "b") +""", + ) + + hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED) + await hass.async_block_till_done() + + hass.states.async_set("pyscript.jvar1", "1") + assert await wait_until_done(notify_q) == "a" + + hass.states.async_set("pyscript.jvar2", "1") + assert await wait_until_done(notify_q) == "b"