The right way to declare class variables in Python

python

class-variables

instance-variables

python-best-practices

byNikita Barsukov·Mar 8, 2025

Declare class variables in Python at class level so that they're accessible by all instances of that class. You do this by defining them immediately after the class definition but outside of any method:

class MyClass:
    shared_var = "Shared by everyone. It's a party! 🎉"

# Example usage:
print(MyClass.shared_var)  # Who owns this party? The class does!
instance = MyClass()
print(instance.shared_var)  # Instance says: "I've gate-crashed the party!"

These so-called class variables are ideal for storing shared data across instances. Make sure not to mistake them for instance variables which are unique to each instance and defined within methods.

Distinguishing class variables from instance variables

Class variables store data common to all instances, like default settings, constants, or communal counters. Instance variables, on the other hand, are used for data that can change between instances.

Guidelines when working with class variables

Limit class variable usage unless an attribute is truly universal.
Always initialize instance variables inside __init__.
Don't use mutable types as class variables unless a shared state is specifically intended.
Modify a class variable in a method using classmethods.

The perils of improper attribute use

Unexpected sharing of mutable types may lead to puzzling bugs that'll surely keep you up at night.
Excessive class variables can muddle your code and give you migraines.
Mixing up class and instance variables could lead to surprising behavior and makes instances terrible at keeping secrets from each other.

When an instance variable is a better choice over a class variable

When the attribute is unique to each individual object, like a name or an ID.
Security matters. If you care about encapsulation, stick to instance variables.
When the attribute is often changed, or is unique to the context of each instance.

Visualization

Think of houses built from a specific blueprint (🛠). This is like a class:

class HouseBlueprint:
    foundation = "Concrete"  # Same foundation, because we don't mess with the base!

Each house gets assigned its own color palette as an instance variable:

    def __init__(self, color):
        self.color = color  # No two houses are painted the same. That's boring!

Visual Comparison:

Blueprint (🛠):          |  Every House (🏠🏡🏘):
foundation = "Concrete"  |  color = "One of a kind color!"

You end up with a lot of houses all standing firm on the same foundation but each sporting a unique color. Diversity is the spice of the neighborhood after all! 🌈

Common pitfalls and misconceptions

The defining and usage of class and instance variables in Python can often lead to head scratches. Here are some misunderstandings and their explanations:

Misunderstanding: All variables defined in a class are class variables

Fact: Variables assigned within instance methods, especially __init__, are not nobles - they are commoners, or instance variables.

Misunderstanding: Class variables can only be accessed through the class

Fact: Class variables aren't snobby. You can access them through an instance too.

Misunderstanding: Changing a class variable on an instance won't affect the original class

Fact: Changing a class variable via an instance doesn't alter the original class variable. It just creates a new instance variable. The equivalent of stealing someone's identity. 😲

The art of appropriately modifying a class variable

Modify class variables through the class name to avoid identity theft, er, creating instance variables unintentionally.
Employ a classmethod for modifying class variables within methods.

class MyClass:
    shared_var = 0  # Started at zero, now we're here...

    @classmethod
    def increment(cls):  # "cls" doing the heavy lifting in this gym
        cls.shared_var += 1  # Another rep, another increment!