Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions custom_components/pyscript/decorator.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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."""
Expand Down Expand Up @@ -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()))
Expand Down Expand Up @@ -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))
Expand Down
10 changes: 10 additions & 0 deletions custom_components/pyscript/decorators/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
99 changes: 91 additions & 8 deletions custom_components/pyscript/eval.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."""

Expand Down Expand Up @@ -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."""
Expand Down Expand Up @@ -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
Expand All @@ -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 (
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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]
Expand All @@ -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):
Expand Down Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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:
Expand All @@ -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)
Expand Down
7 changes: 6 additions & 1 deletion custom_components/pyscript/global_ctx.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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."""
Expand Down
25 changes: 25 additions & 0 deletions docs/reference.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
^^^^^^^^^^^^^^

Expand Down
Loading