Skip to content

Python Classes, Object Identity, and Shared State

Step 22 of 41

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:

  1. Distinguish instance variables from class variables by where they are created.
  2. Describe the attribute lookup order: instance first, then the class (and its parents).
  3. Predict the effect of assigning to a name that exists only on the class (shadowing).
  4. Explain why a mutable class attribute is shared by every instance and how to avoid the problem.
  5. Read __dict__ of an object and of a class, and say what each one contains.
  6. Apply name mangling for __name attributes 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.
Python
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)                 # EUR

currency 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:

  1. the instance's own __dict__;
  2. the class of the instance;
  3. 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.

Python
c1.currency = "USD"
print(c1.currency)      # USD
print(c2.currency)      # EUR
print(Cart.currency)    # EUR

The 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:

Python
Cart.currency = "GBP"
print(c1.currency)      # USD, shadowed, unaffected
print(c2.currency)      # GBP

For 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:

Python
del c1.currency
print(c1.currency)      # GBP, the class value is visible again

del 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:

Python
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 2

Writing Ticket.created += 1 updates the class variable. A subtle variant:

Python
class Ticket2:
    created = 0

    def __init__(self):
        self.created += 1      # reads class value, writes instance value

For 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.

Python
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)   # True

No 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__:

Python
class ShoppingCart:
    def __init__(self):
        self.items = []             # one new list per cart

After 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:

Python
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.

Python
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__:

Python
print("currency" in Cart.__dict__)       # True
print("__init__" in Cart.__dict__)       # True
print("owner" in Cart.__dict__)          # False

The 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:

Python
c.__dict__["lines"] = 5
print(c.lines)            # 5

One 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.

  1. A single leading underscore (_balance) means "internal, please do not touch". The interpreter does nothing special.
  2. A double leading underscore (__balance) triggers name mangling: within the class definition, __balance is rewritten using its class name, for example _Account__balance. Leading underscores in the class name are stripped for this prefix.
Python
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:

Python
print(acc.__balance)          # AttributeError: 'Account' object has no attribute '__balance'
print(acc._Account__balance)  # 150, still reachable by the mangled name

Two 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 getattr is 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.

Python
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.

Text
0.25 0.1
['lamp']
['_Cart__discount', 'owner']
False

sorted(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:

Python
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 __name to _Class__name inside 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 del removes 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 __name as _Class__name and I know it is not security.
  • I know that names ending with two underscores are not mangled.

Official sources