Python Class Attributes vs Instance Attributes

3Python Class Attributes: explained step by step

In the last lesson you met one class attribute in passing. This lesson looks at them properly, because the difference between data that belongs to the class and data that belongs to one object is behind some of the most confusing bugs in beginner object-oriented code.

Two places to store data

An attribute can be created in two places:

• In the class body, directly under class and outside every method. This makes a class attribute: one value, stored once on the class and shared by every object.
• In __init__, on self. This makes an instance attribute: every object gets its own copy.

class Player:
    game = "Space Race"        # class attribute: one copy, shared

    def __init__(self, name):
        self.name = name       # instance attribute: one copy per object

asha = Player("Asha")
ben = Player("Ben")
print(asha.name, ben.name)
print(asha.game, ben.game, Player.game)

Both players can read game, yet neither of them stores it. The value lives on Player, and every object finds it there.

Class constants

The most common use of a class attribute is a value that is the same for every object and rarely changes: a tax rate, a speed limit, a default size. By convention such names are written in UPPER_CASE. Keeping the value in one place means you change it once, instead of hunting through every method that used a copy of the number.

class Scooter:
    MAX_SPEED = 25

    def __init__(self, name):
        self.name = name
        self.speed = 0

    def accelerate(self, amount):
        self.speed = min(self.speed + amount, self.MAX_SPEED)

kick = Scooter("Kick")
kick.accelerate(20)
kick.accelerate(20)
print(kick.speed, Scooter.MAX_SPEED)

Inside a method you can read the constant as self.MAX_SPEED or as Scooter.MAX_SPEED. Outside the class, both kick.MAX_SPEED and Scooter.MAX_SPEED work.

A counter shared by all objects

A class attribute is also the natural home for facts about the class as a whole, such as "how many objects have been created". Each time __init__ runs, it adds one to the value stored on the class:

class Robot:
    built = 0                  # shared: how many robots exist

    def __init__(self, name):
        self.name = name
        Robot.built += 1       # read Robot.built, add 1, store it back on the class

Robot("R2")
Robot("R3")
Robot("Eve")
print(Robot.built)

Notice that the line uses the class name, not self. The next two sections explain why that matters.

Where Python looks: instance first, then class

When you write obj.speed, Python has to decide where speed lives. It always searches in the same order:

1. the object's own attributes (what __init__ stored on self),
2. then the class's attributes,
3. and if neither has the name, it raises AttributeError.

That one rule explains everything else on this page.

The shadowing surprise

Reading an attribute can fall back to the class. Assigning never does: obj.unit = "F" always stores the value on the object, even if the class already has a unit. The new instance attribute then shadows (hides) the class one, for that object only.

class Thermostat:
    unit = "C"

hall = Thermostat()
attic = Thermostat()
attic.unit = "F"                 # creates a NEW attribute on attic only
print(hall.unit, attic.unit, Thermostat.unit)

Thermostat.unit = "K"            # changes the class attribute itself
print(hall.unit, attic.unit, Thermostat.unit)

After attic.unit = "F", the attic has its own unit and the class still says "C". Changing the class later reaches every object that has not shadowed the name (hall), but not the one that has (attic).

This is also why self.built += 1 would be a bug in the counter above. It means self.built = self.built + 1: Python reads the class value (0), adds one, and stores 1 on the object as a brand-new instance attribute. The shared counter never moves. To change the class attribute, assign through the class: Robot.built += 1.

The shared-list pitfall

Shadowing only happens when you assign. Methods like append() change an existing list in place, so no assignment happens, nothing is shadowed, and every object sees the change. That makes a mutable class attribute (a list, dict or set) a trap when each object is meant to have its own:

class SharedPlaylist:
    songs = []                    # ONE list for every playlist

    def add(self, title):
        self.songs.append(title)

class OwnPlaylist:
    def __init__(self):
        self.songs = []           # a fresh list for each playlist

    def add(self, title):
        self.songs.append(title)

gym, road = SharedPlaylist(), SharedPlaylist()
gym.add("Eye of the Tiger")
print(road.songs)

chill, focus = OwnPlaylist(), OwnPlaylist()
chill.add("Weightless")
print(focus.songs)

The rule of thumb: anything mutable that belongs to one object must be created inside __init__.

Look inside with vars() and __dict__

When you are unsure where an attribute lives, ask Python. vars(obj) (the same dictionary as obj.__dict__) holds only the object's own attributes. The class keeps its attributes in Class.__dict__, which also contains some built-in entries starting with __, so filter those out and sorted() the names to get a tidy, predictable list.

class Dog:
    species = "Canis familiaris"

    def __init__(self, name):
        self.name = name

    def bark(self):
        return f"{self.name} says woof"

rex = Dog("Rex")
print(vars(rex))
print(sorted(key for key in Dog.__dict__ if not key.startswith("__")))
print("species" in vars(rex), rex.species)

The last line is a handy test for shadowing: if a name is in vars(obj), the object owns it; if not, Python is finding it on the class.

Which one should I use?

• Different for every object (a name, a score, a balance)? Instance attribute, set in __init__.
• The same for every object (a rate, a limit, a default)? Class attribute, written in UPPER_CASE.
• A fact about the class as a whole (how many objects exist)? Class attribute, changed through the class name.
• A list, dict or set that each object should own? Create it in __init__, never in the class body.