Python Instance and Class Attributes: Shared State and Name Mangling
Introduction
Python instance attributes belong to a particular object, while class attributes are found through its class. Reading a shared list and mutating it is different from assigning a new list to an instance. That distinction explains why two shopping carts can unexpectedly show the same products.
This PCAP-31-03 lesson covers objective 4.2 in Object-Oriented Programming (34% of the score, 12 of 40 items). You will trace shadowing, inspect instance dictionaries and class mapping proxies, and explain how name mangling prevents accidental subclass name clashes.
Learning objectives
After this lesson you can:
- Distinguish instance variables from class variables by where they are created.
- Describe the attribute lookup order: instance first, then the class (and its parents).
- Predict the effect of assigning to a name that exists only on the class (shadowing).
- Explain why a mutable class attribute is shared by every instance and how to avoid the problem.
- Read
__dict__of an object and of a class, and say what each one contains. - Apply name mangling for
__nameattributes and explain why it is not real privacy.
Two places where data can live
For the plain classes in these examples, distinguish storage on an instance from storage on its class. Properties, descriptors, and custom attribute hooks can implement other behavior.
- An instance variable is created by assigning to
self.something(usually in__init__). It belongs to one object. - A class variable belongs to the class. It can be assigned in the class body or later through the class object, and is visible through instances unless shadowed or intercepted.
class Cart:
currency = "EUR" # class variable
def __init__(self, owner):
self.owner = owner # instance variable
self.lines = 0 # instance variable
c1 = Cart("Alice")
c2 = Cart("Bruno")
print(c1.currency, c2.currency) # EUR EUR
print(c1.owner, c2.owner) # Alice Bruno
print(Cart.currency) # EURcurrency is written once and read through three paths: the class and both instances. owner exists once per instance and is not reachable from the class (Cart.owner raises AttributeError).
The lookup rule
For ordinary attributes without descriptors or custom hooks, reading obj.name checks:
- the instance's own
__dict__; - the class of the instance;
- its parent classes in the Python method resolution order.
The first match wins. If nothing is found, AttributeError is raised. This simplified rule applies to the examples here. With default attribute access, a data descriptor such as property takes priority over an instance dictionary entry; a custom __getattribute__ can change lookup, and __getattr__ can handle a missing name. See inspecting Python attributes when diagnosing those cases.
| Expression | Where Python looks | Result in the Cart example |
|---|---|---|
c1.owner |
instance | "Alice" |
c1.currency |
instance (absent), then class | "EUR" |
Cart.currency |
class | "EUR" |
Cart.owner |
class (absent) | AttributeError |
c1.missing |
instance, class, parents | AttributeError |
Assigning versus reading: shadowing
For the plain attributes here, assignment through an instance stores an instance value and leaves the class value unchanged. Properties or a custom __setattr__ can instead intercept an assignment.
c1.currency = "USD"
print(c1.currency) # USD
print(c2.currency) # EUR
print(Cart.currency) # EURThe assignment created a new instance variable currency on c1. It now shadows (hides) the class variable for that instance only. c2 and the class are untouched. To change the value for every instance that has not shadowed it, assign through the class:
Cart.currency = "GBP"
print(c1.currency) # USD, shadowed, unaffected
print(c2.currency) # GBPFor these plain attributes: instance.x = v updates the instance; Class.x = v updates the class. First distinguish a read from a write, then check whether the code customizes attribute access.
Deleting restores the view of the class
Removing the instance variable removes the shadow:
del c1.currency
print(c1.currency) # GBP, the class value is visible againdel c1.currency deletes from the instance only. If the instance had no such attribute, it would raise AttributeError even though the class has one.
Counters and the += trap
A classic example uses a class variable as a counter of created objects:
class Ticket:
created = 0
def __init__(self):
Ticket.created += 1
self.number = Ticket.created
t1 = Ticket()
t2 = Ticket()
print(Ticket.created, t1.number, t2.number) # 2 1 2Writing Ticket.created += 1 updates the class variable. A subtle variant:
class Ticket2:
created = 0
def __init__(self):
self.created += 1 # reads class value, writes instance valueFor this integer attribute, self.created += 1 has the same effect as reading it, adding 1, and assigning the result back to the instance. This equivalence does not describe every use of augmented assignment. The right side finds the class value (0) and the left side creates an instance variable with value 1. After two objects are created, Ticket2.created is still 0 and each instance holds 1. The exam likes this pattern because the code looks like a counter and behaves like nothing of the kind.
The mutable class attribute trap
For an integer or string, augmented addition produces a value that is assigned back to the target. A mutable class variable behaves differently: the object is shared and methods usually mutate it in place.
class ShoppingCart:
items = [] # one list, stored on the class
def add(self, product):
self.items.append(product) # mutates the shared list
alice = ShoppingCart()
bruno = ShoppingCart()
alice.add("keyboard")
bruno.add("mouse")
print(alice.items) # ['keyboard', 'mouse']
print(bruno.items) # ['keyboard', 'mouse']
print(alice.items is bruno.items) # TrueNo assignment to self.items occurs, so nothing is shadowed: both carts reach the same list through the class. This is the scenario "find why independent shopping carts share one item list". The fix is to create the list per instance, in __init__:
class ShoppingCart:
def __init__(self):
self.items = [] # one new list per cartAfter recreating alice and bruno with the corrected class, alice.items is bruno.items is False. Redefining a class does not retrofit existing instances.
A related variation uses rebinding and therefore behaves differently:
class Box:
tags = []
def label(self, tag):
self.tags = self.tags + [tag] # builds a NEW list, assigned to the instance
b1, b2 = Box(), Box()
b1.label("fragile")
print(b1.tags, b2.tags, Box.tags) # ['fragile'] [] []self.tags + [tag] creates a new list, and the assignment stores it on b1 only. Compare it with self.tags += [tag], which on a list extends it in place via __iadd__ and then assigns the same object to self.tags: the class list would be modified for everyone, and b1 would also gain an instance variable pointing to it. Spotting whether the code mutates or rebinds is the key skill.
Reading __dict__
Every object that stores its attributes in a dictionary exposes it as __dict__. It is the most direct way to see where a value lives.
class Cart:
currency = "EUR"
def __init__(self, owner):
self.owner = owner
self.lines = 0
c = Cart("Alice")
print(c.__dict__) # {'owner': 'Alice', 'lines': 0}
c.currency = "USD"
print(c.__dict__) # {'owner': 'Alice', 'lines': 0, 'currency': 'USD'}Notice what is not in the instance dictionary: currency appeared only after the shadowing assignment, and the class-defined methods are not stored there. An instance dictionary can hold a callable explicitly assigned to the instance.
The class has its own __dict__:
print("currency" in Cart.__dict__) # True
print("__init__" in Cart.__dict__) # True
print("owner" in Cart.__dict__) # FalseThe class dictionary contains the class variables, the methods and some special entries such as __module__ and __doc__. You are not expected to memorise its exact content, which varies between Python versions, only to know that class variables and methods live there while per-object data lives in the instance dictionary.
For an ordinary instance, __dict__ is a mutable dictionary that you can inspect and modify, which is useful for introspection but unusual in production code:
c.__dict__["lines"] = 5
print(c.lines) # 5One more fact worth knowing: the __dict__ of a class is a read-only view (a mapping proxy), so you cannot assign into it like Cart.__dict__["x"] = 1; use setattr(Cart, "x", 1) or a normal assignment instead.
Private components and name mangling
Python has no private keyword. Two conventions express intent.
- A single leading underscore (
_balance) means "internal, please do not touch". The interpreter does nothing special. - A double leading underscore (
__balance) triggers name mangling: within the class definition,__balanceis rewritten using its class name, for example_Account__balance. Leading underscores in the class name are stripped for this prefix.
class Account:
def __init__(self, owner, balance):
self.owner = owner
self.__balance = balance # stored as _Account__balance
def deposit(self, amount):
self.__balance += amount
def balance(self):
return self.__balance
acc = Account("Alice", 100)
acc.deposit(50)
print(acc.balance()) # 150
print(acc.__dict__) # {'owner': 'Alice', '_Account__balance': 150}From outside the class, acc.__balance is not mangled in the same way, because mangling applies to names written inside the class body. So the lookup fails:
print(acc.__balance) # AttributeError: 'Account' object has no attribute '__balance'
print(acc._Account__balance) # 150, still reachable by the mangled nameTwo lessons follow. First, mangling prevents accidental access and, more importantly, accidental name clashes in subclasses. Second, it is not security: anyone who knows the pattern _ClassName__name can read or write the value. The exam question "can a mangled attribute be accessed from outside?" has the answer "yes, by its mangled name".
Rules worth remembering:
- Names that end with two underscores (such as
__init__) are not mangled. - Mangling uses the lexical class where the code is written, even when the object belongs to a subclass. A string passed to
getattris not rewritten automatically. - Mangled names appear in
__dict__under their transformed form, which is how you can prove what happened.
Single versus double underscore
| Form | Mangled? | Intended meaning | Reachable from outside |
|---|---|---|---|
name |
no | public | yes |
_name |
no | internal by convention | yes |
__name |
yes, to _Class__name |
private to the class, avoids subclass clashes | yes, by the mangled name |
__name__ |
no | special name reserved by Python | yes |
Worked example: the cart that remembers too much
Statement. An online shop shows the code below. Predict the output and explain each line by naming where each value is stored.
class Cart:
tax_rate = 0.2
items = []
def __init__(self, owner):
self.owner = owner
self.__discount = 0
def add(self, name):
self.items.append(name)
def set_discount(self, value):
self.__discount = value
a = Cart("Alice")
b = Cart("Bruno")
a.add("lamp")
b.tax_rate = 0.1
Cart.tax_rate = 0.25
a.set_discount(5)
print(a.tax_rate, b.tax_rate)
print(b.items)
print(sorted(a.__dict__))
print("items" in b.__dict__)Step 1: classify every attribute. tax_rate and items are class variables. owner and _Cart__discount are instance variables (the second is the mangled form of __discount).
Step 2: follow a.add("lamp"). self.items.append(name) finds items on the class (the instance dictionary has no such key) and mutates the shared list. Both carts see ['lamp'].
Step 3: follow the tax rates. b.tax_rate = 0.1 creates an instance variable on b, which shadows the class value. Cart.tax_rate = 0.25 then updates the class value. a has no instance variable named tax_rate, so it reads 0.25; b keeps its shadow, 0.1.
Step 4: evaluate the prints.
0.25 0.1
['lamp']
['_Cart__discount', 'owner']
Falsesorted(a.__dict__) sorts the keys alphabetically; the underscore character sorts before lowercase letters, so _Cart__discount comes first. "items" in b.__dict__ is False because items was never assigned on the instance; it is found on the class.
Why the tempting alternatives fail. Answering 0.2 0.1 assumes that Cart.tax_rate = 0.25 has no effect, but a never shadowed it. Answering [] for b.items assumes each cart has its own list, which only happens if __init__ creates one. Expecting __discount in the keys ignores that mangling renames it. Expecting True in the last line confuses reading through the class with storing in the instance.
Common pitfalls and exam tips
| Pitfall | Why it happens | Remedy |
|---|---|---|
| Confusing a plain instance write with a class write | The instance shadows the class value | Separate ordinary writes from descriptor or custom-hook behavior |
| Sharing a list or dict through the class | Class variables are created once | Create mutable state in __init__ |
Treating self.count += 1 as a class counter |
It reads the class value and writes an instance value | Write Class.count += 1 |
Looking for __name after mangling |
The stored key is _Class__name |
Check __dict__ |
| Believing mangling is secure | Mangled names are fully reachable | Treat it as a safeguard against accidents |
Expecting methods in the instance __dict__ |
Methods live on the class | Look in the class __dict__ |
Exam tip. For every attribute in a question, write "class" or "instance" next to it before tracing. Then apply the lookup rule on reads and the "assignment targets the object" rule on writes.
Exam tip. If a class body contains an empty [], {} or set() assigned at class level, expect sharing to be the point of the question.
Exam tip. When a question prints __dict__ and the class uses double underscores, rewrite the name as _ClassName__name before choosing the answer.
End-of-lesson case study
Situation. A learning platform counts how many quizzes each student has opened and keeps a registry of students. A teammate wrote:
class Student:
registry = []
opened = 0
def __init__(self, name):
self.name = name
Student.registry.append(name)
def open_quiz(self):
self.opened += 1
s1 = Student("Mia")
s2 = Student("Noah")
s1.open_quiz()
s1.open_quiz()
s2.open_quiz()
print(Student.registry)
print(Student.opened, s1.opened, s2.opened)
print("opened" in s1.__dict__)The teammate expects Student.opened to be 3. What is printed, and how should the code change to count globally while still keeping a per-student count?
Solution, commented. Student.registry is one list on the class and each constructor appends to it, so the first line prints ['Mia', 'Noah']; sharing is intended here.
self.opened += 1 reads opened from the class (0) and stores the result in the instance. s1 therefore ends with 2, s2 with 1, and the class variable stays 0. The second line prints 0 2 1, and the last line prints True because opened now exists in the instance dictionary of s1.
To count globally, first define total_opened = 0 in the class body, then update it with Student.total_opened += 1. To keep a per-student figure, create self.opened = 0 in __init__ and increment it as self.opened += 1. Using two different names (total_opened on the class, opened on each instance) prevents the confusion that caused the bug.
Key terms
- Instance variable: an attribute stored in one object, usually created in
__init__. - Class variable: an attribute defined in the class body and shared through the class.
- Shadowing: creating an instance variable with the same name as a class variable, which hides the class value for that instance.
- Ordinary attribute lookup: instance storage followed by the class MRO; data descriptors and custom hooks require the fuller rule.
__dict__: the dictionary of an object's own attributes (and the mapping of a class's members).- Name mangling: the rewriting of
__nameto_Class__nameinside a class body. - Encapsulation convention: the use of leading underscores to signal that a member is internal.
Summary checklist
- I can say whether an attribute is an instance or a class variable by reading the code.
- I apply the lookup rule on reads and the "assignment targets the object" rule on writes.
- I can explain shadowing and how
delremoves it. - I recognise the shared mutable class attribute bug and its fix.
- I can read
__dict__of an instance and of a class. - I can rewrite
__nameas_Class__nameand I know it is not security. - I know that names ending with two underscores are not mangled.
Official sources
-
Python Institute, PCAP-31-03 exam syllabus (objective 4.2): https://pythoninstitute.org/pcap-31-03-exam-syllabus (opens in a new tab)
-
Python documentation, Classes tutorial (class and instance variables, private variables): https://docs.python.org/3.14/tutorial/classes.html (opens in a new tab)
-
Python documentation, data model: https://docs.python.org/3.14/reference/datamodel.html (opens in a new tab)
-
Descriptor precedence and managed attributes: https://docs.python.org/3.14/howto/descriptor.html (opens in a new tab)
