diff --git a/custom_components/pyscript/eval.py b/custom_components/pyscript/eval.py index e27f430..be1af9d 100644 --- a/custom_components/pyscript/eval.py +++ b/custom_components/pyscript/eval.py @@ -1091,6 +1091,11 @@ async def ast_classdef(self, arg): if "__init__" in sym_table: sym_table["__init__evalfunc_wrap__"] = sym_table["__init__"] del sym_table["__init__"] + # store nested classes themselves on the class; the EvalLocalVar objects stay valid for methods + if type(sym_table) is dict: # pylint: disable=unidiomatic-typecheck + for name, val in sym_table.items(): + if isinstance(val, EvalLocalVar) and val.is_defined(): + sym_table[name] = val.get() cls = metaclass(arg.name, tuple(bases), sym_table, **keywords) if inspect.iscoroutine(cls): cls = await cls diff --git a/docs/plans/nested-class-attr.md b/docs/plans/nested-class-attr.md new file mode 100644 index 0000000..85e8b90 --- /dev/null +++ b/docs/plans/nested-class-attr.md @@ -0,0 +1,60 @@ +# Plan: nested-class-attr + +## What Sean asked for +"start on the nested class annotation fix": the last remaining case from #875. + +## What we found +Checked on upstream's latest code and on #902's branch; both behave the same. +- A class defined inside another class's body is stored in the outer class as pyscript's internal placeholder (`EvalLocalVar`), not as the class itself. So once the outer class is built, `Outer.Inner` is the placeholder: + - `Outer.Inner | None` fails with the same `TypeError` as #875. This applies anywhere, for example in another class's type hints: `y: Outer.Inner | None = None`. + - `type(Outer.Inner()) is Outer.Inner` and `isinstance(Outer.Inner(), Outer.Inner)` give `False` (Python: `True`). +- These already work: `x: Inner | None` written inside the outer class's own body, methods and dataclasses using the nested class, and `list[Inner]`. +- **Must keep working:** today a method can use the nested class by its bare name (`def make(self): return Inner.v` gives `4`). Real Python raises `NameError` there, but scripts may rely on it, so the fix must not change it. + +## What we'll change +1. **`custom_components/pyscript/eval.py`, `ast_classdef`:** just before the outer class object is created, replace each defined placeholder in the class's namespace with the value it holds, so the class's attributes are the real nested classes. The placeholders themselves stay valid, so methods that already hold one keep working. A namespace from a custom metaclass that can't be walked is left as it is. *Check:* the tests below. +2. **Tests in `tests/test_unit_eval.py`**, each checked against real Python: + - `Outer.Inner | None`, at module level and in another class's type hints; + - `type(Outer.Inner()) is Outer.Inner` and `isinstance`; + - a dataclass with a nested dataclass; + - two levels of nesting. + One test also pins today's behaviour of a method using the nested class by its bare name, so it can't break silently. + *Check:* the new tests fail on upstream's current code and pass with step 1. +3. **All project checks** on Python 3.14, as CI runs them: `pytest`, `ruff check`, `ruff format --check`, `pylint`, `mypy`, and `codespell`. +4. **Upstream PR.** After your final approval, one commit goes on a clean branch cut from upstream `master`, with a prefilled link for you to open the PR ("Refs #875"). The PR text notes the overlap with #902 and #906. + +## Contribution rules that apply +- `docs/contributing.rst` and `tests/README.md`: dev setup from `tests/requirements_test.txt`, pre-commit hooks, `pytest`, PRs from a fork. +- Pre-commit runs ruff (check and format, line length 109), codespell, pylint and mypy. CI (`validate.yml`, Python 3.14) runs hassfest, ruff, pytest with coverage, pylint and mypy. +- No PR template; we follow the maintainer's habits: one small fix per PR, with tests. Commits are signed off. + +## Who's on it +Engineer, Security Officer and Auditor. Research is done (above); QA is skipped as too small for this job (the Auditor runs the tests). No second security review: nothing security-related is touched. + +## Risks +- **Overlap:** #902 and #906 both also change `ast_classdef`. Each is a small, separate edit, but whichever merges later needs a small update; we'll do it. +- **Custom metaclasses** whose class namespace isn't a plain dictionary: handled by leaving those alone, and tested. + +## Out of scope +- Making methods stop seeing nested classes by bare name (a Python difference, but changing it could break scripts). +- The module name shown when printing a nested type hint (`custom_components.pyscript.eval.Inner` instead of `Outer.Inner`), which is only cosmetic. + +--- + +## Record (2026-11-20) + +**Status:** built and checked, with no open problems. Not yet sent upstream. + +**What shipped on this branch:** one commit, `store nested classes themselves on the outer class (#875)` (`9306a84`). Just before a class is created, each defined placeholder in a plain-dict class namespace is replaced by the class it holds (+5 lines in `eval.py`), with tests (+211) compared against CPython 3.14. It applies cleanly to upstream `master` (`8131a78`), and all 210 tests, ruff, pylint, mypy and codespell pass. + +**Review rounds:** +- Security: clear. +- Audit round 1: + - **Must-fix:** a guard that swallowed errors could leave a custom class namespace half-updated. Fixed: only plain-dict namespaces are rewritten, and custom ones are left exactly as upstream leaves them. + - **Should-fix, accepted:** a method that replaces the nested class with `nonlocal` no longer updates `Outer.Inner`. Real Python refuses this code (SyntaxError), so the code is unchanged and the commit message now promises only that methods *reading* the nested class keep working. +- Audit round 2: approved. Its one wording fix to the commit message was applied. + +**Decisions:** +- Methods that use the nested class by its bare name keep working (a pyscript-only behaviour), pinned by a test. +- Cut from upstream `master`; #902 and #906 touch the same function, so whichever merges later gets a small update. +- Plan check, QA and plain-English check were skipped (job too small; the reviewer's quota was used up). diff --git a/tests/test_unit_eval.py b/tests/test_unit_eval.py index 549b725..5d6c6c8 100644 --- a/tests/test_unit_eval.py +++ b/tests/test_unit_eval.py @@ -2448,3 +2448,215 @@ async def test_with_exit_does_not_swallow_cancel(hass): await Function.waiter_sync() await Function.waiter_stop() await Function.reaper_stop() + + +NESTED_CLASS_CASES = { + "union_module_level": ( + "class Outer:\n class Inner:\n pass\nres = (Outer.Inner | None) == (Outer.Inner | None)\n" + ), + "union_other_class_annotation": ( + "class Outer:\n class Inner:\n pass\n" + "class Bar:\n y: Outer.Inner | None = None\n" + "res = [Bar.y, Bar.__annotations__['y'] == (Outer.Inner | None)]\n" + ), + "identity": ( + "class Outer:\n class Inner:\n pass\n" + "res = [type(Outer.Inner()) is Outer.Inner, isinstance(Outer.Inner(), Outer.Inner)]\n" + ), + "dataclass": ( + "from dataclasses import dataclass\n" + "@dataclass\nclass Outer:\n @dataclass\n class Inner:\n a: int = 1\n" + " x: Inner | None = None\n" + "res = [Outer().x, Outer(Outer.Inner()).x.a, type(Outer.Inner()) is Outer.Inner]\n" + ), + "two_levels": ( + "class Outer:\n class Mid:\n class Inner:\n v = 7\n" + "res = [Outer.Mid.Inner.v, type(Outer.Mid.Inner()) is Outer.Mid.Inner," + " (Outer.Mid.Inner | None) == (Outer.Mid.Inner | None)]\n" + ), +} + + +@pytest.mark.parametrize("name", list(NESTED_CLASS_CASES)) +async def test_nested_class_attr_matches_python(hass, name): + """Test that a class defined in a class body is the class itself, compared with CPython.""" + hass.data[DOMAIN] = {CONFIG_ENTRY: MockConfigEntry(domain=DOMAIN, data={CONF_ALLOW_ALL_IMPORTS: True})} + Function.init(hass) + State.init(hass) + State.register_functions() + TrigTime.init(hass) + DecoratorRegistry.init(hass) + + source = NESTED_CLASS_CASES[name] + expected_ns: dict = {} + exec(source, expected_ns) # pylint: disable=exec-used + expected = expected_ns["res"] + + global_ctx = GlobalContext("test", global_sym_table={}, manager=GlobalContextMgr) + ast = AstEval("test", global_ctx=global_ctx) + Function.install_ast_funcs(ast) + ast.parse(source) + try: + await ast.eval() + assert global_ctx.global_sym_table["res"] == expected + finally: + await Function.waiter_sync() + await Function.waiter_stop() + await Function.reaper_stop() + + +async def test_nested_class_bare_name_in_method(hass): + """Test that a method can still use a nested class by its bare name.""" + hass.data[DOMAIN] = {CONFIG_ENTRY: MockConfigEntry(domain=DOMAIN, data={CONF_ALLOW_ALL_IMPORTS: True})} + Function.init(hass) + State.init(hass) + State.register_functions() + TrigTime.init(hass) + DecoratorRegistry.init(hass) + + # pyscript only: CPython raises NameError here, so this can't be compared with CPython + global_ctx = GlobalContext("test", global_sym_table={}, manager=GlobalContextMgr) + ast = AstEval("test", global_ctx=global_ctx) + Function.install_ast_funcs(ast) + ast.parse( + "class Outer:\n class Inner:\n v = 4\n def make(self):\n return Inner.v\n" + "res = [Outer().make(), Outer.Inner.v]\n" + ) + await ast.eval() + assert global_ctx.global_sym_table["res"] == [4, 4] + + await Function.waiter_sync() + await Function.waiter_stop() + await Function.reaper_stop() + + +class NoKeysNamespace: + """Class namespace that supports item access but has no keys() or items().""" + + def __init__(self): + """Initialize the namespace.""" + self.d = {} + + def __setitem__(self, key, value): + """Set an item.""" + self.d[key] = value + + def __getitem__(self, key): + """Get an item.""" + return self.d[key] + + def __contains__(self, key): + """Check for an item.""" + return key in self.d + + def __delitem__(self, key): + """Delete an item.""" + del self.d[key] + + +class NoKeysMeta(type): + """Metaclass whose __prepare__ returns a namespace without keys().""" + + @classmethod + def __prepare__(mcs, name, bases, **kwargs): + """Return the custom namespace.""" + return NoKeysNamespace() + + def __new__(mcs, name, bases, ns, **kwargs): + """Build the class from the custom namespace.""" + return super().__new__(mcs, name, bases, dict(ns.d)) + + +NESTED_PREPARE_SOURCE = """ +class Outer(metaclass=NoKeysMeta): + class Inner: + pass + v = 3 + +res = [Outer.v, Outer.Inner is not None] +""" + + +async def test_nested_class_prepare_without_keys(hass): + """Test that a class namespace from __prepare__ that can't be iterated still builds the class.""" + hass.data[DOMAIN] = {CONFIG_ENTRY: MockConfigEntry(domain=DOMAIN, data={CONF_ALLOW_ALL_IMPORTS: True})} + Function.init(hass) + State.init(hass) + State.register_functions() + TrigTime.init(hass) + DecoratorRegistry.init(hass) + + expected_ns: dict = {"NoKeysMeta": NoKeysMeta} + exec(NESTED_PREPARE_SOURCE, expected_ns) # pylint: disable=exec-used + global_ctx = GlobalContext("test", global_sym_table={"NoKeysMeta": NoKeysMeta}, manager=GlobalContextMgr) + ast = AstEval("test", global_ctx=global_ctx) + Function.install_ast_funcs(ast) + ast.parse(NESTED_PREPARE_SOURCE) + await ast.eval() + assert global_ctx.global_sym_table["res"] == expected_ns["res"] == [3, True] + + await Function.waiter_sync() + await Function.waiter_stop() + await Function.reaper_stop() + + +class RejectSecondRewrite(dict): + """Class namespace that refuses to rebind "Second".""" + + def __setitem__(self, key, value): + """Set an item, but only allow "Second" to be bound once.""" + if key == "Second" and key in self: + raise TypeError("Second may only be bound once") + super().__setitem__(key, value) + + +class CheckNamespaceMeta(type): + """Metaclass that requires its two nested classes to arrive in the same form.""" + + @classmethod + def __prepare__(mcs, name, bases, **kwargs): + """Return the custom namespace.""" + return RejectSecondRewrite() + + def __new__(mcs, name, bases, ns, **kwargs): + """Build the class, checking the namespace is consistent.""" + if type(ns["First"]) is not type(ns["Second"]): + raise ValueError("mixed namespace representations") + return super().__new__(mcs, name, bases, dict(ns)) + + +NESTED_REJECT_SOURCE = """ +class Outer(metaclass=CheckNamespaceMeta): + class First: + pass + class Second: + pass + +res = Outer.__name__ +""" + + +async def test_nested_class_prepare_dict_subclass(hass): + """Test that a custom __prepare__ namespace is left as it is and the class still builds.""" + hass.data[DOMAIN] = {CONFIG_ENTRY: MockConfigEntry(domain=DOMAIN, data={CONF_ALLOW_ALL_IMPORTS: True})} + Function.init(hass) + State.init(hass) + State.register_functions() + TrigTime.init(hass) + DecoratorRegistry.init(hass) + + expected_ns: dict = {"CheckNamespaceMeta": CheckNamespaceMeta} + exec(NESTED_REJECT_SOURCE, expected_ns) # pylint: disable=exec-used + global_ctx = GlobalContext( + "test", global_sym_table={"CheckNamespaceMeta": CheckNamespaceMeta}, manager=GlobalContextMgr + ) + ast = AstEval("test", global_ctx=global_ctx) + Function.install_ast_funcs(ast) + ast.parse(NESTED_REJECT_SOURCE) + try: + await ast.eval() + assert global_ctx.global_sym_table["res"] == expected_ns["res"] == "Outer" + finally: + await Function.waiter_sync() + await Function.waiter_stop() + await Function.reaper_stop()