Python Class Namespace: How Attribute Lookup Works
Understand how the Python class namespace works, how attribute lookup resolves names, and how class and instance namespaces differ in real code.

What a Class Namespace Actually Is
When you define a class in Python, the body of the class executes in its own namespace. Understanding how that class namespace works is essential for predicting attribute access, how inheritance resolves names, and why certain bugs appear only when instances share mutable defaults.
When you write:
class Counter:
total = 0
label = "counter"The names total and label live in the class namespace. Accessing Counter.total retrieves the value from that namespace. The class namespace is distinct from the module namespace that surrounds the class definition, and it is also distinct from the namespace of any instance created from the class.
This separation matters because it determines where Python looks for a name when you access an attribute. For ordinary attributes, the lookup order is well-defined: the instance namespace first, then the class namespaces in the method resolution order.
How Instance and Class Namespaces Differ
For ordinary classes, every instance has its own __dict__ that holds instance attributes. The class itself also has a __dict__ that holds class attributes. When you assign self.total = 5 inside a method, you are writing to the instance namespace, not the class namespace. When you assign Counter.total = 10 at module level, you are writing to the class namespace.
class Counter:
total = 0
c1 = Counter()
c2 = Counter()
c1.total = 5
print(c1.total) # 5 - instance namespace
print(c2.total) # 0 - class namespace
print(Counter.total) # 0 - class namespaceThe instance c1 now has its own total attribute. The class namespace still holds total = 0. The instance c2 has no instance-level total, so Python falls back to the class namespace.
This behavior is a common source of confusion. Assigning to an attribute through an instance does not modify the class attribute; it shadows it. The class namespace remains unchanged unless you explicitly assign through the class object itself.
How Methods Use the Class Namespace
When a method accesses an attribute through self—for example, self.timeout—Python uses the normal instance attribute lookup rules. Consider this example:
class Config:
timeout = 30
def get_timeout(self):
return self.timeoutThe method get_timeout reads self.timeout. If the instance has no timeout attribute in its namespace, Python falls back to the class namespace and returns the class attribute timeout.
This lookup mechanism is what makes class attributes useful as defaults. An instance can override the default by assigning its own attribute, and the method will pick up the instance value. If no override exists, the class default applies.
The same resolution applies to methods themselves. A method defined in the class body is stored in the class namespace as a function object. Accessing it through an instance produces a bound method, which automatically passes the instance as the first argument.
The Method Resolution Order and Inheritance
When a class inherits from another class, attribute lookup extends beyond the immediate class namespace. Python consults the method resolution order, which is the sequence of classes that Python checks when looking up an attribute.
class Base:
kind = "base"
class Derived(Base):
pass
d = Derived()
print(d.kind) # "base" - found in Base's namespaceThe instance d has no kind in its own namespace. Derived has no kind in its namespace either. Python follows the MRO to Base and finds it there.
The MRO is computed using the C3 linearization algorithm. For simple single-inheritance hierarchies, the order is straightforward: the class itself, then its parent, then the grandparent. For multiple inheritance, the order is more complex and follows the C3 rules.
Understanding the MRO matters when you override attributes in subclasses. If a subclass defines an attribute with the same name as a base class attribute, the subclass's namespace takes precedence during lookup.
Common Mistakes with Class Namespaces
One frequent mistake is using a mutable class attribute as a shared default. Because the class namespace is shared across all instances, a mutable value stored there is visible to every instance.
class Registry:
items = []
r1 = Registry()
r2 = Registry()
r1.items.append("first")
print(r2.items) # ["first"] - shared through class namespaceBoth instances see the same list because items lives in the class namespace. If the intent was to give each instance its own list, the attribute should be initialized in __init__ instead.
Another mistake is assuming that assigning through an instance updates the class namespace. It does not. The assignment creates an instance attribute that shadows the class attribute. To update the class-level value, assign through the class object.
A third mistake is writing bare names inside a method and expecting Python to search the class namespace. Python's name resolution inside a method follows the local scope first, then enclosing scopes, then global scope, then builtins. Class attributes are not part of this lexical scope chain; to read one, use self.attribute or ClassName.attribute.
Runtime Cost of Attribute Lookup
Attribute lookup through the instance and class namespaces has a runtime cost. At a conceptual level, an attribute access checks the instance __dict__, then walks the class namespaces in the MRO. For code executed in hot loops, this cost is measurable, though usually small.
Python's attribute access is implemented in the LOAD_ATTR bytecode instruction. The interpreter performs the lookup dynamically. There is no compile-time resolution of attribute names, which is why attribute access is slower than local variable access.
When performance matters, developers sometimes cache attribute lookups in local variables:
def process(self, items):
limit = self.limit
for item in items:
if item > limit:
...This reads self.limit once and avoids repeated namespace lookups inside the loop. The behavior is identical, but the local variable access is faster.
Class Namespaces and Maintainability
The distinction between class and instance namespaces has direct consequences for code maintainability. Class attributes are shared state. If any code path mutates a mutable class attribute, the change is visible to all instances and to all code that reads the class attribute directly.
For configuration-like values that should not change, consider using immutable types or naming conventions that signal intent. For per-instance state, always initialize in __init__.
When subclassing, be aware that attribute lookup on a subclass includes the parent's class namespace. Overriding a class attribute in the subclass creates a new entry in the subclass's namespace, which shadows the parent's value for instances of the subclass. Instances of the parent remain unaffected.
This behavior is useful for defining defaults that subclasses can override, but it can also hide bugs. If a subclass accidentally assigns to a class attribute name that the parent uses internally, the parent's methods will see the subclass's value when called on a subclass instance.
Using __dict__ to Inspect Namespaces
Python exposes the namespace dictionaries directly. The class namespace is accessible through ClassName.__dict__, and the instance namespace through instance.__dict__.
class Sample:
value = 42
s = Sample()
s.extra = "added"
print(Sample.__dict__)
print(s.__dict__)The class __dict__ includes value along with other class-level entries such as __module__ and __qualname__. The instance __dict__ contains only extra, because value was never assigned through the instance.
Inspecting __dict__ is useful for debugging and for metaprogramming. Frameworks that build classes dynamically, such as ORMs and serialization libraries, read and write these dictionaries to map class definitions to external schemas.
One caution: __dict__ is a mapping proxy for classes, not a regular dictionary. You can read from it, but you cannot mutate it directly. To modify the class namespace, use setattr or assign through the class object.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.