Skip to content

Fix TypeError when a class type hint uses | with another class from the same script (#875) - #902

Open
HoneyBearTech wants to merge 2 commits into
custom-components:masterfrom
HoneyBearTech:fix-class-annotation-union-875
Open

HoneyBearTech wants to merge 2 commits into
custom-components:masterfrom
HoneyBearTech:fix-class-annotation-union-875

Conversation

@HoneyBearTech

@HoneyBearTech HoneyBearTech commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Closes #875

What was broken
A type hint with | that names a class defined in the same script failed to load:

class Foo:
    pass

class Bar:
    z: Foo | None = None
TypeError: unsupported operand type(s) for |: 'EvalLocalVar' and 'NoneType'

Why
A class defined at module level is stored in the global symbol table as an EvalLocalVar. ast_name only unwrapped it when the global table was the current symbol table, so inside
another class's body Foo came back as the wrapper. Most uses still worked through the wrapper's __getattr__, but operators such as | didn't.

What I changed
When a name is found in the global symbol table after the local tables, ast_name now unwraps a defined EvalLocalVar. A class that is still being defined stays wrapped, so a
self-reference like nxt: Node = None inside Node works as before. Names declared global inside a function are read and assigned exactly as before.

Testing

  • New cases in tests/test_unit_eval.py:
    • the annotation from the issue, both in a plain class and in a dataclass;
    • the Node self-reference;
    • a check that rebinding a class through global inside a function still updates functions defined earlier.
  • The full test suite, pylint, mypy and ruff all pass on Python 3.14.

Second commit: the global path (as suggested in review)
A module-level class used through global inside a function still came back wrapped, so Foo | None raised TypeError, Foo is type(Foo()) was False, and Foo.x = 3 set x on the wrapper. Rebinding or deleting through global also wasn't seen by functions defined earlier.

  • Assignment and del through global now update the existing EvalLocalVar in place, and a load through global unwraps it.
  • A binding (assignment, import, from ... import) and a read of mod.Foo now store or return the value, not the wrapper, so one script can no longer change another module's Foo through a shared wrapper.
  • A class statement reuses an existing wrapper, so a class defined again is seen by functions defined earlier.
  • Imports inside a function are local to it, and names in a class body stay in the class, as in Python.

from mod import Foo and Foo = mod.Foo are now snapshots, as in Python. The new tests run each case in CPython and in pyscript and compare the results.

Known limits
Listed in the second commit's message. The main ones: getattr(mod, "Foo"), mod.__dict__ and vars(mod) still return the wrapper, and so does a module-level class read inside a lambda or @pyscript_compile function.

…mponents#875)

A class defined at module level is stored in the global symbol table as an
EvalLocalVar. ast_name only unwrapped that when the global table was the
current symbol table, so inside another class's body a name like Foo came
back as the wrapper. Most uses still worked through its __getattr__, but
operators didn't, so an annotation such as "z: Foo | None = None" raised
TypeError.

Unwrap a defined EvalLocalVar when a name is found in the global symbol
table after the local ones. A class that's still being defined stays
wrapped, so a self-reference like "nxt: Node = None" inside Node keeps
working as before. Names declared global inside a function are looked up
and assigned as before.

Signed-off-by: Sean Stoube <31805425+HoneyBearTech@users.noreply.github.com>
@HoneyBearTech HoneyBearTech changed the title unwrap module-level classes used in class body annotations (#875) Fix TypeError when a class type hint uses | with another class from the same script (#875) Nov 19, 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 @HoneyBearTech, this is a nice fix with a clear explanation!

Unwrapping a defined EvalLocalVar when the lookup falls through to the global table is the right change. It also fixes a couple of related cases beyond #875. Inside another class's body, subclassing a module-level class (class C(Foo):) used to raise TypeError: EvalLocalVar.__init__() takes 2 positional arguments but 4 were given, and Foo is type(Foo()) returned False. Both work now.

The global path is still broken (not blocking)

This bug predates the PR: a module-level class used through a global declaration still comes back wrapped. For example:

class Foo:
    x = 1

def read():
    return Foo

def f():
    global Foo
    Foo | None           # TypeError: unsupported operand type(s) for |: 'EvalLocalVar' and 'NoneType'
    Foo is type(Foo())   # False
    Foo.x = 3            # silently sets x on the wrapper, so Foo.x is still 1

def rebind():
    global Foo
    Foo = Other          # read(), defined earlier, still returns the old Foo

Deleting through global has the same problem: after global Foo; del Foo, functions defined earlier still see the old class. If Foo is then defined again, they don't see the new one.

You were right not to just unwrap the global load. That breaks your keep() test, because global Foo; Foo = Foo then replaces the wrapper with the plain class, and functions defined earlier keep the old wrapper. The root cause is that assignment through global replaces the table entry (self.global_sym_table[var_name] = val in recurse_assign). Module-level assignment instead updates an existing EvalLocalVar in place with .set(). I tried two changes together:

  • in recurse_assign, when the global table already holds an EvalLocalVar, call .set(val) on it instead of replacing it
  • in ast_name, unwrap the value in the global_names lookup, just as this PR does for the fall-through lookup

With those changes all 202 tests pass, including keep(), and the |, is, attribute-assignment and rebinding cases above all behave like Python. del would need the matching change in the global branch of ast_delete, calling set_undefined() on the wrapper instead of removing the entry.

If you'd like to add that here, with tests, that would be great. Otherwise we're happy to merge this as is and do the global path in a follow-up commit. Just let us know which you prefer.

honeybeartech-homelab-automation Bot pushed a commit to HoneyBearTech/pyscript that referenced this pull request Nov 20, 2026
Signed-off-by: Sean Stoube <31805425+HoneyBearTech@users.noreply.github.com>
@HoneyBearTech

Copy link
Copy Markdown
Contributor Author

@craigbarratt I'll add that here with tests. Thank you!

…lobal (custom-components#875)

A module-level class is stored in the global symbol table as an EvalLocalVar,
and functions defined at module level hold on to that wrapper. Used through a
global declaration, the class still came back wrapped, so inside a function
with "global Foo", "Foo | None" raised TypeError, "Foo is type(Foo())" was
False and "Foo.x = 3" set x on the wrapper. Assigning or deleting through
global replaced or removed the table entry, so functions defined earlier kept
seeing the old class after "global Foo; Foo = Other" or "global Foo; del Foo".

As suggested in review, assignment through global now calls .set() on an
existing EvalLocalVar instead of replacing it, del through global calls
set_undefined() on it (and raises NameError if it is already undefined, like
the module-level branch), and a load through global unwraps it when it is
defined. An undefined one is left wrapped, as the lookup that falls through
to the global symbol table already does, so a class defined through global
can still refer to itself in its annotations.

Updating a wrapper in place is only safe if no other binding shares it, and
functions defined earlier should also see a class defined again or imported
under the same name. So:

- Assignment, import and from-import now bind names through one helper,
  assign_name(). It stores the value held by a defined EvalLocalVar rather
  than the wrapper, so "from mod import Foo", "from mod import *" and
  "Foo = globals()['Original']" no longer share another binding's wrapper.
  Otherwise "global Foo; Foo = Other" or "del Foo" in the importer would
  change mod's own Foo, for every script importing mod. A plain module-level
  "Foo = Other" or "del Foo" after "from mod import Foo" already did this
  before.

- Reading an attribute of a module, as in "mod.Foo", now also gives the
  value held by mod's EvalLocalVar, so "Foo = mod.Foo" and
  "globals()['Foo'] = mod.Foo" store the class itself, and "mod.Foo | None",
  "mod.Foo is mod.modread()" and isinstance(obj, mod.Foo) work. For a name
  mod has deleted it raises AttributeError, as in Python. "mod.Foo = Other"
  updates mod's EvalLocalVar in place, so mod's own functions see the new
  value, as in Python.

- Like assignment, import and from-import now update an existing
  EvalLocalVar for the name, so functions defined earlier see the imported
  value, and a name declared global in a function is bound in the global
  table instead of locally.

- Names bound by import or from-import inside a function are now local to
  it, as in Python, so a nested function can use them; for example
  "import mod as m" inside a function used to be invisible to a nested
  function. In a function with a nested function, reading any local name
  before it is bound, or after it is deleted, now raises UnboundLocalError
  instead of NameError, as in Python. Without a nested function, reading an
  imported name before the import raises UnboundLocalError when a
  module-level name of that name exists, instead of finding it.

- In a class body, assignment, import, del, and class and def statements
  bind in the class namespace, even inside a function that declares the
  name global, and reading a name finds the class's own binding before the
  global one, as in Python. Assignment and import there replace an
  EvalLocalVar left by a nested class instead of updating it, so a method
  doesn't pick up the new value as an enclosing variable. A global
  declaration in the class body itself applies to the class body only, as
  in Python: the name is bound and read in the global table there, but no
  longer becomes global in the enclosing function once the class statement
  completes. In a class body at module level it no longer raises
  SyntaxError.

- "from mod import Foo" of a name mod has deleted raises ImportError with
  Python's message, and "from mod import *" skips it, since del now leaves
  an undefined EvalLocalVar in mod.

- A class statement always made a new EvalLocalVar, so functions defined
  earlier never saw a class defined again under the same name, and inside
  the new class body the name was undefined. It now reuses an existing
  wrapper and sets the new class once the class statement completes. Until
  then the name still holds the old class, also if the class body raises,
  as in Python. A first definition works as before.

This changes how imports and aliases behave: "from mod import Foo" and
"Foo = mod.Foo" now take a snapshot of mod's Foo, as in Python, and no
longer follow later changes to Foo inside mod; "mod.Foo" itself does.

Known limits:

- getattr(mod, "Foo"), mod.__dict__ and vars(mod) still hand out mod's
  EvalLocalVar, and so does "mod.Foo" inside a lambda or @pyscript_compile
  function; after mod deletes Foo, hasattr(mod, "Foo") and dir(mod) still
  report it
- a lambda or @pyscript_compile function gets a module-level class as its
  EvalLocalVar: reading an attribute works and follows a later rebind, but
  calling it or "|" raises TypeError, and "is", "==", isinstance() and
  issubclass() against the class give False
- a function defined with @pyscript_compile in a class body that declares
  its name global is still bound in the class namespace, not the global
  table
- in a function without a nested function, reading an imported name before
  the import gives the builtin of that name if there is one, and raises
  NameError if there is neither a module-level name nor a builtin, instead
  of UnboundLocalError
- a dotted import such as "import os.path" inside a function is not local
  to it, so a nested function can't use it
- a method reads a class nested in its class body (class C: class Foo: ...)
  as if it were an enclosing variable, instead of the module-level name
- "global Zed; del Zed" on a name that was never defined doesn't raise
  NameError
- after "global Foo; del Foo", a bare read of Foo through global gives back
  the undefined wrapper instead of raising NameError. Reading an attribute,
  calling it or using it in isinstance() still raises NameError, but "|"
  raises TypeError, and "is", "==", bool(), str() and setting an attribute
  don't raise at all

Signed-off-by: Sean Stoube <31805425+HoneyBearTech@users.noreply.github.com>
@HoneyBearTech

Copy link
Copy Markdown
Contributor Author

Thank you @craigbarratt for the careful review and the suggested fix. I've added the global path here as a second commit, so the first commit is unchanged.

Your three changes are in, but on their own they bring back a cross-module problem. from mod import Foo copied mod's EvalLocalVar into the importer, so after that, global Foo; Foo = Other (or del Foo) in the importer updated the shared wrapper and changed mod's own Foo, for every script importing mod. A plain module-level Foo = Other after from mod import Foo already did this on master. So the commit also:

  • stores the value, not the wrapper, whenever a name is bound (assignment, import, from ... import), and when reading mod.Foo, so a binding never shares another module's wrapper; mod.Foo = Other now updates mod's wrapper in place
  • reuses an existing wrapper in a class statement, so after global Foo; del Foo a class defined again is seen by functions defined earlier (with your version that raised NameError)
  • makes imports inside a function local to it, and keeps class-body names in the class namespace, both as in Python; these were needed so the in-place updates don't reach the wrong scope

This does change one thing users might notice: from mod import Foo and Foo = mod.Foo are now snapshots, as in Python, and no longer follow later changes inside mod.

The tests run each case in CPython and in pyscript and compare the results. The commit message lists what still differs from Python. The full suite, ruff, pylint, mypy and codespell pass on 3.14.

It's bigger than your sketch, so if you'd rather take only part of it, or merge the first commit on its own and look at this one separately, that's fine too.

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

Labels

None yet

Projects

None yet

2 participants