PEP: 840
Title: Name Resolution in Class Namespaces
Author: Jeremy Hylton <jeremy@python.org>,
        Guido van Rossum <guido@python.org>
Discussions-To: https://discuss.python.org/t/pep-840-name-resolution-in-class-namespaces/108166
Status: Draft
Type: Standards Track
Created: 15-Jul-2026
Python-Version: 3.16
Post-History: `16-Jul-2026 <https://discuss.python.org/t/pep-840-name-resolution-in-class-namespaces/108166>`__


Abstract
========

There is a long-standing inconsistency in the way variable names are
resolved in classes.  Several alternatives to resolve this
inconsistency are discussed.

Motivation
==========

Name resolution in a class namespace uses a partial dynamic lookup. A
name can be either local or global depending on whether an assignment
to the name has occured during the exection of the class body. If a
name is used before assignment, it will be looked up in globals (and
builtins).

If a class is defined within a function scope, a name may be resolved
to the nearest enclosing scope. If name local to an enclosing scope,
but the name is not bound, a NameError will occur.

The apparent consistency problem is that names may be both local and
global in the same class block, but they cannot be both local and
free. Or, name resolution behaves differently in a class depending on
whether it is defined at the top-level or inside another block.  If a
global variable exists, it can be used to resolve a free variable
unless that variable is bound in an enclosing scope of the class.

Here is an example of resolution of a free variable in a class:

>>> x = 0
>>> def f(x):
...     class A:
...         a = x
...     return A
...
>>> A = f(1)
>>> A.a  # the value of the parameter x, not the global x
1

The variable x is resolved to the parameter of the function x. The
global is ignored. This behavior is the standard name resolution
defined in :pep:`227` and :pep:`3104`.

If x is used as a local variable, the behavior is different at the
top-level and inside another block. If the same code also uses x as a
local variable, then the initial reference to x is resolved
differently.

>>> x = 0
>>> def f(x):
...     class A:
...         a = x
...         x = 42
...     return A
...
>>> A = f(1)
>>> A.a  # the value of the global x, not the parameter x
0

The first reference to x is no longer bound to the local variable x
defined in f, but instead uses the global variable.

The set of namespaces consulted are determined lexically, but it
cannot be determined statically whether a particular reference will be
resolved using the global namespace.

>>> x = 0
>>> def f(var):
...     class A:
...         x = 10
...         if var in locals():
...             del locals()[var]
...         a = x
...     return A
...
>>> A1 = f("x")
>>> A2 = f("y")
>>> A1.a, A2.a
(0, 10)


Background
==========

The Python 2.0 definition specifies exactly three namespaces to
check for each name -- the local namespace, the global namespace,
and the builtin namespace. Starting with Python 2.1, lexical scoping
was used and free variables could be resolved to a binding in an
enclosing scope. Class namespaces were a special case, and free variables
were not resolved in enclosing scopes. They used special LOAD_NAME /
STORE_NAME opcodes that explicit checked local and global namespaces.

In Python 3.4, free variables in classes were resolved in enclosing scopes,
but a local variable used before assignment was still resolved in the global
scope. The language specification was not updated at this time, so it
still specifies the pre-3.4 behavior:

  A class definition is an executable statement that may use and define names.
  These references follow the normal rules for name resolution with an exception
  that unbound local variables are looked up in the global namespace.

Class namespaces and top-level module namespaces both use LOAD_NAME / STORE_NAME
opcodes that reflect the early local / global / builtin scoping rules. Class
namespaces are also special, because the class namespace become the attributes
of the class object. Given these differences, the different scoping rules for
classes weren't considered when :pep:`227` was written.

A bug was filed in 2002. The PEP author closed the bug with the
comment, "Just don't write code that abuses the wart."
https://github.com/python/cpython/issues/36300
Another bug was filed in 2010, leading the same author to suggest a change.
https://github.com/python/cpython/issues/53472
Apparently, inconsistent behavior in namespaces can lead to
inconsistent responses to identical bugs.

Proposal
========

There are several alternatives we could choose among. A few simple
alternatives seem wrong. We could revert to pre-3.4 behavior, but it
was surprising the free variables did not work in class scopes. We
could keep the current behavior, but it is seems inconsistent.

One approach is to make class namespaces work more like function
namespaces. If a local variable is used at a time when it is not
bound, it raises a NameError. This rule is simple and consistent. The
primary drawback of this approach is that it will break code. Code
that depends on this feature is inscrutable, depending on the reader
to understand whether the local or global reference was
intended. Inscrutable, though, is not the same as undefined or broken

Another approach is to change the behavior of free variable
resolution to use the global namespaces when a name is unbound. If
current code would raise a NameError, because a variable was unbound
in the enclosing scope, it would be resolved in the global namespace.

There is a third approach that is a subtle variant of the second. If
a local variable is unbound, and that variable has a binding in an
enclosing scope, use that namespace rather than the global namespace.

>>> x = 0
>>> def f():
...     x = 1
...     class A:
...         x = 2
...         del x
...         a = x # Should this use f's local or global?
...     return A
...
>>> A = f()
>>> A.a
?

If a local variable is unbound and it can be resolved in another
namespace anyway, why only the global namespace? Why not use the
full set of standard name resolution rules?

This option seems most consistent, but makes the implementation more
complicated. It can't be statically determinted whether a variable is
bound at a particular point, so we would need to allocate a cell for
any local variable of the class that shadows a local variable in an
enclosing scope. Since dynamic manipulation of local variables is
unusual, we would expect the extra closures required to almost always
be unused. It would nonetheless be a somewhat unusual case-- a nested
class definition that has a local variable that shadows a local
variable in an enclosing scope.


Copyright
=========

This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.
