Skip to content

Store classes themselves in module and class namespaces - #915

Merged
craigbarratt merged 2 commits into
custom-components:masterfrom
dmamelin:classes-without-evallocalvar
Nov 21, 2026
Merged

craigbarratt merged 2 commits into
custom-components:masterfrom
dmamelin:classes-without-evallocalvar

Conversation

@dmamelin

@dmamelin dmamelin commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

I'd been thinking about reworking how classes are stored for a while, and #902 pushed me to a complete solution. I didn't get to present it before #902 was merged, so this PR removes part of it: the code that unwraps classes. Its import and global scope changes stay, and all of its tests still pass. Thanks to @HoneyBearTech, for the push, and for the tests in #902 and #907.

Root cause

A class defined at module level was kept in the global symbol table as an EvalLocalVar wrapper. That table is also the module's __dict__ and the globals of @pyscript_compile functions, so the wrapper leaked wherever the table was read. #902 unwraps it in the places that read it, and #907 does the same for nested classes, but globals(), getattr(mod, ...), lambdas and native code still get the wrapper.

Changes

  • A class is bound to its name only once it has been created, with the same binding as an assignment, as in Python. Module-level names and class attributes hold the class itself; EvalLocalVar is only used, like CPython's cells, for function locals shared with closures. If the class body, metaclass or a decorator raises, the name keeps its previous binding.
  • An annotation naming the class being defined (e.g. nxt: Node | None in Node) is evaluated once the class exists, before class decorators run, so @dataclass sees InitVar[Node] or ClassVar[...]. An annotation naming something still not defined is kept as source text, as with from __future__ import annotations.
  • global x; del x for an unbound x raises NameError, and from x import missing raises ImportError, for any name, not only for classes.
  • The unwrapping from Fix TypeError when a class type hint uses | with another class from the same script (#875) #902 is removed (unwrap_defined and its uses in EvalAttrSet, ast_attribute, assign_name, ast_delete and ast_importfrom): eval.py is +45/−61 lines: +22/−61 for the change itself, and 23 more lines to evaluate self-referencing annotations once the class exists (without them, nxt: Node would stay the string 'Node', and @dataclass wouldn't see an InitVar[Node]). All 39 CPython-comparison scenarios from Fix TypeError when a class type hint uses | with another class from the same script (#875) #902 pass without it (29 of them fail on master before Fix TypeError when a class type hint uses | with another class from the same script (#875) #902), since there's no wrapper left to unwrap.

Compared with master

On 22 examples, with CPython 3.14 as reference, 20 give the same result as CPython here and 3 on master. The full comparison is in the first comment.

  • Fixed: globals(), lambdas, issubclass and X | None in @pyscript_compile, nested classes (Store nested classes themselves on the outer class (#875) #907), nxt: Node | None in Node, @dataclass referring to its own class (including InitVar/ClassVar), typing.get_type_hints(), the name after a class body raises, an Enum with a nested class, and head: T in a generic function (part of Errors with type annotation handling in 1.7.0 #796).
  • Still different from CPython: an annotation naming a class defined later is the string 'B', since CPython 3.14 evaluates annotations lazily (on master it raises NameError).

Breaking changes

All of these follow CPython.

A method can't use a nested class by its bare name:

class Outer:
    class Inner:
        v = 4
    def make(self):
        return Inner.v     # NameError; use Outer.Inner.v

A class can't be used as a value in its own body:

class Node:
    kind = Node            # NameError
    def m(self, x=Node):   # NameError
        return x

del of an unbound global raises NameError:

def drop():
    global gone
    del gone               # NameError if gone isn't defined

A missing name in from x import y raises ImportError instead of AttributeError:

try:
    from json import nope
except AttributeError:     # no longer caught; use except ImportError
    pass

Also as in CPython 3.14, a typo in a class or module annotation is no longer reported when the class or module is loaded:

class C:
    x: Undefinedd = 3      # no NameError; the annotation is the string 'Undefinedd'

Tests

All in tests/test_unit_eval.py:

  • the tests of Store nested classes themselves on the outer class (#875) #907, with its test of a method using a nested class by its bare name turned into a comparison with CPython;
  • 6 new globalNameTests cases and 2 nested-class cases, compared with CPython, and an evalTests case for annotations;
  • an old evalTests case that deleted an unbound global is adjusted.

Closes #907, whose tests are included.

Risk

Every class statement now binds its name differently, and functions no longer capture module-level classes, so this affects all user classes, not only the cases above. Checked: the full test suite, the 39 scenarios from #902, the 22 examples compared with CPython, pre-commit, and my production Home Assistant with its scripts, apps and modules.

Bind a class to its name once it has been created, like an assignment,
instead of keeping it in an EvalLocalVar that leaked through globals(),
module attributes, lambdas and native code. This removes the unwrapping
added by custom-components#902. An annotation naming the class being defined is evaluated
once the class exists, before its decorators run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmamelin

dmamelin commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor Author
Comparison with master and CPython 3.14 (22 examples)

Unchanged: fixed by #902, or the same as master

The #875 example: | with a class of the same script in a class body

class Foo:
    pass
class Bar:
    z: Foo | None = None
Bar.z
#master   None
#cpython  None
#this pr  None

A self-referencing annotation

class Node:
    nxt: Node = None
Node.__annotations__["nxt"].__name__
#master   'Node'
#cpython  'Node'
#this pr  'Node'

A @dataclass with an InitVar of its own class

from dataclasses import dataclass, InitVar, fields
@dataclass
class Node:
    val: int = 0
    parent: InitVar[Node] = None
    def __post_init__(self, parent):
        pass
[f.name for f in fields(Node)]
#master   ['val']
#cpython  ['val']
#this pr  ['val']

Fixed by this PR

globals() for a class of the same script

class Local:
    pass
globals()["Local"] is Local
#master   False
#cpython  True
#this pr  True

A lambda returning a module-level class

class Foo:
    pass
get = lambda: Foo
get() is Foo
#master   False
#cpython  True
#this pr  True

issubclass in @pyscript_compile

class Base:
    pass
class Sub(Base):
    pass
@pyscript_compile
def check():
    return issubclass(Sub, Base)
check()
#master   False
#cpython  True
#this pr  True

Foo | None in @pyscript_compile

class Foo:
    pass
@pyscript_compile
def native():
    return Foo | None
native() == (Foo | None)
#master   TypeError: unsupported operand type(s) for |: 'EvalLocalVar' and 'NoneType'
#cpython  True
#this pr  True

A nested class

class Outer:
    class Inner:
        pass
(Outer.Inner | None) == (Outer.Inner | None)
#master   TypeError: unsupported operand type(s) for |: 'EvalLocalVar' and 'NoneType'
#cpython  True
#this pr  True

A class referring to itself with |

class Node:
    nxt: Node | None = None
Node.nxt
#master   TypeError: unsupported operand type(s) for |: 'EvalLocalVar' and 'NoneType'
#cpython  None
#this pr  None

A @dataclass referring to itself

from dataclasses import dataclass
@dataclass
class Node:
    val: int = 0
    nxt: Node | None = None
Node(1, Node(2)).nxt.val
#master   TypeError: unsupported operand type(s) for |: 'EvalLocalVar' and 'NoneType'
#cpython  2
#this pr  2

The name after a class body raises

try:
    class A:
        raise ValueError
except ValueError:
    pass
"A" in globals()
#master   True
#cpython  False
#this pr  False

An Enum with a nested class

from enum import Enum
class Color(Enum):
    RED = 1
    class Helper:
        pass
Color.RED.value
#master   NameError: name 'Helper' is not defined
#cpython  1
#this pr  1

An annotation with a type parameter in a function (#796)

def first[T](items: list[T]) -> T:
    head: T = items[0]
    return head
first([5, 6])
#master   NameError: name 'T' is not defined
#cpython  5
#this pr  5

typing.get_type_hints() for a self-referencing annotation

import typing
class Node:
    nxt: Node = None
typing.get_type_hints(Node)["nxt"] is Node
#master   False
#cpython  True
#this pr  True

A @dataclass with a ClassVar of its own class

from dataclasses import dataclass, fields
from typing import ClassVar
@dataclass
class Node:
    registry: ClassVar[dict[str, Node]] = {}
    val: int = 0
[f.name for f in fields(Node)]
#master   NameError: name 'Node' is not defined
#cpython  ['val']
#this pr  ['val']

Breaking: worked on master, now an error, as in CPython

A method using a nested class by its bare name

class Outer:
    class Inner:
        v = 4
    def make(self):
        return Inner.v
Outer().make()
#master   4
#cpython  NameError: name 'Inner' is not defined
#this pr  NameError: name 'Inner.v' is not defined

A default value referring to its own class

class Node:
    def m(self, x=Node):
        return x
Node().m() is Node
#master   True
#cpython  NameError: name 'Node' is not defined
#this pr  NameError: name 'Node' is not defined

A class attribute referring to its own class

class Node:
    kind = Node
Node.kind.__name__
#master   'Node'
#cpython  NameError: name 'Node' is not defined
#this pr  NameError: name 'Node' is not defined

del of an unbound global

def drop():
    global gone
    del gone
drop()
"ok"
#master   'ok'
#cpython  NameError: name 'gone' is not defined
#this pr  NameError: name 'gone' is not defined

from x import missing and except AttributeError

try:
    from json import nope
    r = "ok"
except AttributeError:
    r = "AttributeError caught"
r
#master   'AttributeError caught'
#cpython  ImportError: cannot import name 'nope' from 'json' (.../json/__init__.py)
#this pr  ImportError: cannot import name 'nope' from 'json' (.../json/__init__.py)

As in CPython 3.14, a typo in an annotation is no longer reported

A typo in an annotation

class C:
    x: Undefinedd = 3
C.x
#master   NameError: name 'Undefinedd' is not defined
#cpython  3
#this pr  3

Better than master, still different from CPython

An annotation naming a class defined later

class A:
    b: B = None
class B:
    pass
A.__annotations__["b"]
#master   NameError: name 'B' is not defined
#cpython  <class 'B'>
#this pr  'B'

@dmamelin dmamelin changed the title store classes themselves in module and class namespaces Store classes themselves in module and class namespaces Nov 21, 2026

@craigbarratt craigbarratt left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @dmamelin. Storing the class itself is the right fix, and it's nice to see the unwrapping go.

One small thing: eval_pending_annotations only sees the class name, so an annotation that also uses a class attribute stays a string. For example, class A: Alias = int; x: A | Alias gives 'A | Alias', while CPython gives A | int. Evaluating with {**cls.__dict__, cls_name: cls} fixes it.

@HoneyBearTech, thanks for the tests from #907, which this PR includes. Since it supersedes #907, there's no need to rebase that one.

@dmamelin

Copy link
Copy Markdown
Contributor Author

@craigbarratt Good catch, thanks, fixed. One change from your suggestion: I put the class's own names after the class name, {cls_name: cls, **cls.__dict__}, so they take precedence, as in CPython, where an annotation looks in the class namespace first. For example, class B: z: B | B = None; B = float gives float in CPython, while {**cls.__dict__, cls_name: cls} would give B. Added a CPython-comparison case for both.

@craigbarratt
craigbarratt merged commit c28d130 into custom-components:master Nov 21, 2026
6 checks passed
@craigbarratt

Copy link
Copy Markdown
Member

Thanks, looks great!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants