Skip to content
Closed
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
77 changes: 58 additions & 19 deletions custom_components/pyscript/eval.py
Original file line number Diff line number Diff line change
Expand Up @@ -316,6 +316,16 @@ def getattr(self):
"""Get the attribute value."""
return unwrap_defined(getattr(self.obj, self.attr))

def delattr(self):
"""Delete the attribute."""
# as with setattr, mark a pyscript module's EvalLocalVar undefined in place
if isinstance(self.obj, ModuleType) and isinstance(vars(self.obj).get(self.attr), EvalLocalVar):
if not vars(self.obj)[self.attr].is_defined():
raise AttributeError(f"module '{self.obj.__name__}' has no attribute '{self.attr}'")
vars(self.obj)[self.attr].set_undefined()
else:
delattr(self.obj, self.attr)


class EvalFunc:
"""Class for a callable pyscript function."""
Expand Down Expand Up @@ -840,21 +850,38 @@ async def check_for_closure(self, arg):
class EvalFuncVar:
"""Class for a callable pyscript function."""

# keep our own fields out of __dict__, so functools.wraps() can't copy them onto a wrapper
__slots__ = ("__dict__", "__weakref__", "ast_ctx", "func")

def __init__(self, func: EvalFunc) -> None:
"""Initialize instance with given EvalFunc function."""
self.func = func
self.ast_ctx: AstEval | None = None

@property
def __name__(self):
"""Return the function name, like a Python function."""
return self.func.get_name()

@__name__.setter
def __name__(self, name):
"""Set the function name, eg by functools.wraps()."""
self.func.set_name(name)

@property
def __doc__(self):
"""Return the function doc string, like a Python function."""
return self.func.get_doc_string()

@__doc__.setter
def __doc__(self, doc_string):
"""Set the function doc string, eg by functools.wraps()."""
self.func.doc_string = doc_string

def get_func(self) -> EvalFunc:
"""Return the EvalFunc function."""
return self.func

def remove_func(self):
"""Remove and return the EvalFunc function."""
func = self.func
self.func = None
return func

async def call(self, ast_ctx, *args, **kwargs):
"""Call the EvalFunc function."""
return await self.func.call(ast_ctx, *args, **kwargs)
Expand Down Expand Up @@ -897,6 +924,8 @@ async def __call__(self, *args, **kwargs):
class EvalFuncVarClassInst(EvalFuncVar):
"""Class for a callable pyscript class instance function."""

__slots__ = ("class_inst_weak",)

def __init__(self, func: EvalFunc, ast_ctx: "AstEval", class_inst_weak: weakref.ReferenceType) -> None:
"""Initialize instance with given EvalFunc function."""
super().__init__(func)
Expand Down Expand Up @@ -1191,17 +1220,30 @@ async def executor_wrap(*args, **kwargs):
dec_trig, dec_other, dec_dm = await func.eval_decorators(self)
self.dec_eval_depth += 1
for dec_func in dec_other:
func = await self.call_func(dec_func, None, func)
if isinstance(func, EvalFunc):
# pass decorators an EvalFuncVar, like a Python function object; functools.wraps()
# then only updates its __dict__, not the fields of the wrapper's EvalFunc
func = EvalFuncVar(func)
func.set_ast_ctx(self)
func_arg = func
func = await self.call_func(dec_func, None, func_arg)
if isinstance(func, EvalFuncVar):
# set the function name back to its original instead of the decorator function we just called
func.set_name(name)
func = func.remove_func()
dec_trig += func.decorators
dec_dm += func.dm_decorators
if func is not func_arg:
dec_trig += func.get_func().decorators
dec_dm += func.get_func().dm_decorators
elif isinstance(func, EvalFunc):
func.set_name(name)
self.dec_eval_depth -= 1
if isinstance(func, EvalFunc):
func = EvalFuncVar(func)
if isinstance(func, EvalFuncVar):
# keep the EvalFuncVar a decorator returned, since the decorator may hold
# references to it and may have set attributes like __wrapped__ on it
func_var = func
func_var.set_ast_ctx(self)
func = func_var.get_func()
func.decorators = dec_trig
func.dm_decorators = dec_dm
if self.dec_eval_depth == 0:
Expand All @@ -1210,14 +1252,9 @@ async def executor_wrap(*args, **kwargs):
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 @@ -1534,10 +1571,12 @@ async def ast_delete(self, arg):
else:
raise NameError(f"name '{arg1.id}' is not defined")
elif isinstance(arg1, ast.Attribute):
var_name = await self.ast_attribute_collapse(arg1, check_undef=False)
if not isinstance(var_name, str):
raise NameError("state name should be 'domain.entity' or 'domain.entity.attr'")
State.delete(var_name)
# as with assignment, a dotted name is a state only if its first part isn't defined
var_name = await self.ast_attribute_collapse(arg1)
if var_name is not None:
State.delete(var_name)
else:
EvalAttrSet(await self.aeval(arg1.value), arg1.attr).delattr()
else:
raise NotImplementedError(f"unknown target type {arg1} in del")

Expand Down
5 changes: 4 additions & 1 deletion custom_components/pyscript/global_ctx.py
Original file line number Diff line number Diff line change
Expand Up @@ -178,14 +178,17 @@ def find_first_file(file_paths: list[list[str]]) -> list[str] | None:
if path.endswith("/__init__"):
path = os.path.dirname(path)
ctx_name = self.name
if os.path.basename(self.file_path or "") != "__init__.py" and "." in ctx_name:
# a plain module is relative to its parent package, so drop its own name
ctx_name = ctx_name[0 : ctx_name.rfind(".")]
for _ in range(import_level - 1):
path = os.path.dirname(path)
idx = ctx_name.rfind(".")
if path.find("/") < 0 or idx < 0:
raise ImportError("attempted relative import above parent package")
ctx_name = ctx_name[0:idx]
ctx_name += f".{module_name}"
module_info = [ctx_name, f"{path}/{module_path}.py", path]
module_info = [ctx_name, f"{path}/{module_path}.py", os.path.dirname(f"{path}/{module_path}.py")]
path += f"/{module_path}"
file_paths.append([ctx_name, f"{path}/__init__.py", path])
file_paths.append(module_info)
Expand Down
95 changes: 95 additions & 0 deletions docs/plans/issues-batch-2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# Plan: issues-batch-2

## What Sean asked for
"look at issues in custom-components/pyscript find me 5 of the most important ones and start fixing them"

## What we found
We went through all 138 open issues and checked each likely bug on upstream's latest `master` (`309a3ff`).
- Most are feature requests, how-to questions, Home Assistant or install problems, or already fixed. About 25 are already fixed on `master` (for example #512, #538, #761, #792, #819 and the blocking-call warnings #608, #612, #619 and #620). Others are covered by open upstream PRs (#899, #896, #907, #908, #869).
- **Only two open issues are real, still-broken bugs that a small fix can solve.** We reproduced both:
- **#808:** a decorator written with `functools.wraps` loses its own body. Its `try`/`except` never runs, so the error it should catch gets through.
- **#726:** in an app with subfolders, a correct relative import (`from .a import foo` in `subfolder/b.py`) fails. A reload can also unload part of the app.
- We also found one bug while checking that has no issue yet: `del obj.attr` on a normal object fails with `NameError`, because pyscript treats it as deleting a Home Assistant state.
- Two issues ask for clearer docs, and the maintainer agreed in the threads: logging for apps and scripts (#821, #520, #265), and `watch=` firing only when a value changes (#864).

So the five are two bug fixes, one small bug fix without an issue, and two docs fixes. Generator expressions (#564) are **left out** (see "Out of scope"). We can add them if you want them.

## What we'll change
Each item becomes its own small upstream PR, cut from upstream `master`, with its tests.

1. **#808: decorators that use `functools.wraps`** (`custom_components/pyscript/eval.py`, `tests/test_unit_eval.py`).
- Before calling a user decorator, pyscript will hand it a wrapped copy of the function. That way `wraps` can't overwrite pyscript's own fields on the decorator's inner function.
- If the decorator returns the function unchanged, it is unwrapped again.
- *Check:* new tests cover a `wraps` decorator that catches an error, one that passes arguments through, stacked decorators, one that returns the function unchanged, and that `__wrapped__` is set. Each test fails on today's code and passes with the fix, and each result matches real Python.
2. **#726: relative imports inside an app's subfolders** (`custom_components/pyscript/global_ctx.py`, `tests/test_apps_modules.py`).
- A module imported as `subfolder.b` will resolve its own relative imports from `subfolder/`, as Python does. Today it uses the app's top folder.
- This is a one-line change.
- *Check:* new tests cover the issue's exact example, and confirm that a reload unloads nothing it shouldn't. The PR text will say plainly that scripts using today's workaround (`from .subfolder.a` inside `subfolder/b.py`) need to switch to the normal form.
3. **`del obj.attr` on normal objects** (`custom_components/pyscript/eval.py`, `tests/test_unit_eval.py`).
- Only names that refer to Home Assistant states (`domain.entity`, `domain.entity.attr`) will be deleted as states.
- Attributes of normal objects, including `del self.x` in a method, will be deleted like in Python.
- *Check:* tests cover objects, `self` in methods, a missing attribute (`AttributeError`, as in Python), and the existing state-deletion tests still pass.
4. **Docs: logging** (`docs/reference.rst`, maybe `docs/tutorial.rst`), for #821, #520 and #265.
- The docs will give the logger names for apps (`custom_components.pyscript.apps.<app>`), scripts and modules.
- They will add one full `logger:` example: quiet by default, one app at info, one script at debug.
- *Check:* the docs build cleanly with the project's Sphinx setup, and the logger names match the code.
5. **Docs: `@state_trigger` and repeated values** (`docs/reference.rst`), for #864.
- The docs will say that `watch=` and trigger expressions fire only when a value changes, so a sensor that repeats the same value doesn't fire them.
- They will show the workaround from the issue (`watch=["sensor.x.last_updated"]`).
- *Check:* the docs build cleanly, and the behaviour matches the code (`trigger.py`).
6. **All project checks** on Python 3.14, as CI runs them: `pytest`, `ruff check`, `ruff format --check`, `pylint`, `mypy`, and the pre-commit hooks (including codespell).
7. **Upstream PRs.** After your final approval, each fix goes on its own clean branch from upstream `master`, with a prefilled link for you to open the PR. Each PR description uses "Closes #N" (or no issue for item 3), then what was broken, why, what changed, and testing.

## Contribution rules that apply
- The project has `docs/contributing.rst` and `tests/README.md`, and no CONTRIBUTING.md or PR template. Their rules:
- Set up the dev environment from `tests/requirements_test.txt`.
- Run the pre-commit hooks: ruff check and format, codespell, check-json, yamllint, pylint and mypy.
- Run `pytest`, and send PRs from a fork.
- CI (`validate.yml`, Python 3.14) runs hassfest, ruff, pytest with coverage, pylint and mypy.
- The maintainer's habits: one small fix per PR, with its tests and with a docs change when behaviour changes. Titles name the fix and the issue number. Commits are signed off.

## Who's on it
Three Engineers on separate files, working in parallel:
- one Engineer for items 1 and 3 (`eval.py`, separate parts);
- one for item 2 (`global_ctx.py`);
- one for items 4 and 5 (docs).

After that, QA, the Security Officer and the Auditor review the work. Research is done (above). There's no second security review, because no security-related code is touched.

## Risks
- **#808** changes how every user decorator gets its function. The whole test suite passes with a first version of the fix, and the Auditor will look closely at this item.
- **#726** changes behaviour for anyone using today's workaround. This is stated in the PR text.
- **Overlap with open upstream PRs:** #907 and #909 also touch `eval.py`. Whichever merges later may need a small update; we'd do it.

## Out of scope
- **#564, generator expressions** (for example `sum(x for x in y)`). A 4-line version works, but it builds the whole list first. So `any(...)` doesn't stop early, and an endless generator would freeze Home Assistant. The maintainer called a full version "quite hard". This is a feature that needs his buy-in, not a bug fix.
- Issues that need the maintainer's design: #891, #877 and #885, #831, #788 (stubs for `service.call`), and #855 (Jupyter listen address).
- Commenting on the issues that are already fixed on `master`. This stays on the roadmap, if you want it.

---

## Record (2026-11-21)

**Status:** built and checked, with no open problems. Not yet sent upstream.

**What shipped on this branch:** five commits, each one meant to become its own upstream PR. Each one applies on its own to upstream `master` (`309a3ff`) and passes the tests there.
- `181956e` keep a decorator's wrapper body when it uses functools.wraps (#808): `eval.py` +42/−15, 6 new test cases.
- `75137bc` delete object attributes in del instead of treating them as states: `eval.py` +16/−4, 5 new test cases.
- `d16e990` document the logger names for scripts, apps and modules (#821, #520, #265): docs only.
- `cf83267` document that state triggers only fire when a value changes (#864): docs only.
- `c53ef6c` fix relative imports inside an app's subfolders (#726): `global_ctx.py` +4/−1, 1 new test.

**Checks:** all 207 tests, ruff, pylint, mypy, codespell and a strict Sphinx docs build pass on Python 3.14. hassfest only runs on GitHub. The new tests fail on upstream's code without the fixes, and every new case matches real Python.

**Review rounds:**
- QA: passed.
- Security: clear.
- Audit:
- **Must-fix, fixed:** the #726 package check compared the end of the file path with `/__init__.py`. On Windows that would treat an app's `__init__.py` as a plain module. It now uses `os.path.basename`. The fix was checked by rerunning the tests, ruff, mypy and pylint.
- **Should-fix, not changed:** after `del mod.Foo` (a class defined in another pyscript module), `hasattr(mod, "Foo")` stays True. The class is kept as an empty placeholder so that the module's own functions see it as deleted, and pyscript already does the same for a module-level `del Foo`. This is a rare case and is a known limit.

**Decisions:**
- The #808 fix keeps the function object a decorator returns, and doesn't unwrap it as the first version did. A decorator that stores the function (a registry) keeps a working one, and attributes like `__wrapped__` survive. `remove_func()` had no other users, so it was removed.
- #726 needed a second small change beyond the first idea. A plain module's relative imports now start from its package, not from itself, which removes the phantom contexts. Scripts that use the old workaround (`from .subfolder.a` inside `subfolder/b.py`) must switch to `from .a`. The PR text says so.
- Unchanged: relative imports from a plain file inside a `modules/` package still aren't supported, as before.
- The plan check and the plain-English check were skipped: their reviewer's monthly quota is used up.
Loading
Loading