Class attributes, properties and encapsulation

Why this matters

As classes grow, two questions come up. Where should data that belongs to the type rather than to each object live (a counter, a default, a constant)? And how do you keep an object's data valid, for example a temperature below absolute zero or a negative price, without forcing every caller to use clumsy get_x()/set_x() methods? Python answers with class attributes, properties, and the classmethod/staticmethod decorators. It also takes a distinctive stance on privacy that you need to understand to read other people's code.

Class attributes

Anything assigned directly in the class body (not inside a method) is a class attribute, stored in the class's __dict__ and shared by all instances:

class Circle:
    pi = 3.14159              # class attribute

    def __init__(self, r):
        self.r = r            # instance attribute

    def area(self):
        return self.pi * self.r ** 2

c = Circle(2)
print(c.area(), Circle.pi, c.pi)

12.56636 3.14159 3.14159

self.pi works because lookup falls through from the instance to the class (lesson 1). Class attributes are good for constants and defaults.

The rule that causes most bugs

Recall: reading an attribute falls through to the class; assigning always creates or updates the attribute on the instance.

class Config:
    retries = 3

a = Config()
b = Config()
a.retries = 5          # creates a.__dict__['retries']; class unchanged
print(a.retries, b.retries, Config.retries)

5 3 3

That is fine, even useful (a per-instance override). The danger is mutable class attributes, because mutating is not assigning:

class Basket:
    items = []                 # ONE list, on the class
    def add(self, x):
        self.items.append(x)   # reads self.items -> the class's list, mutates it

a, b = Basket(), Basket()
a.add("apple")
print(b.items)

['apple']

Every basket shares one list. The fix is to create per-instance state in __init__: self.items = []. The same trap with augmented assignment on an immutable class attribute goes the other way: self.count += 1 reads the class's count, adds 1, and then assigns the result to a new instance attribute, so the class counter never changes. To update a class attribute, assign through the class: Config.count += 1 or type(self).count += 1.

Properties: attributes with code behind them

Suppose a Product has a price that must never be negative. In Java you would hide the field and write getPrice()/setPrice(). In Python you start with a plain attribute, and if you later need validation, you turn it into a property without changing any calling code:

class Product:
    def __init__(self, name, price):
        self.name = name
        self.price = price           # goes through the setter below

    @property
    def price(self):
        return self._price

    @price.setter
    def price(self, value):
        if value < 0:
            raise ValueError("price cannot be negative")
        self._price = value

p = Product("pen", 2.5)
print(p.price)
p.price = 3
print(p.price)
p.price = -1

2.5
3
Traceback (most recent call last):
  ...
ValueError: price cannot be negative

How it works underneath: @property replaces the function with a property object stored in the class. A property is a descriptor, an object with __get__/__set__ methods that Python calls during attribute access. Lookup actually checks the class for such data descriptors before the instance __dict__, so p.price runs the getter and p.price = 3 runs the setter. The real value lives in p._price.

A property without a setter is read-only, which is ideal for computed values:

class Rectangle:
    def __init__(self, w, h):
        self.w, self.h = w, h

    @property
    def area(self):
        return self.w * self.h

r = Rectangle(3, 4)
print(r.area)      # no parentheses: it looks like data
r.w = 10
print(r.area)      # always up to date
r.area = 5

12
40
AttributeError: property 'area' of 'Rectangle' object has no setter

classmethod and staticmethod

A normal method receives the instance. Two decorators change that.

A classmethod receives the class as its first argument, conventionally cls. Its most common use is an alternative constructor:

class Date:
    def __init__(self, year, month, day):
        self.year, self.month, self.day = year, month, day

    @classmethod
    def from_iso(cls, text):
        y, m, d = (int(part) for part in text.split("-"))
        return cls(y, m, d)

    def __repr__(self):
        return f"Date({self.year}, {self.month}, {self.day})"

print(Date.from_iso("2026-11-01"))

Date(2026, 11, 1)

Using cls(...) rather than Date(...) means a subclass calling from_iso gets an instance of the subclass. You have used classmethods already: dict.fromkeys(...) and int.from_bytes(...) are both alternative constructors.

A staticmethod receives neither instance nor class. It is a plain function that lives in the class's namespace because it belongs there logically:

class Date:
    ...
    @staticmethod
    def is_leap(year):
        return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)

print(Date.is_leap(2024), Date.is_leap(1900))   # True False

Rule of thumb: needs the instance? normal method. Needs the class (to construct, or to read class attributes)? classmethod. Needs neither? staticmethod, or simply a module-level function.

Encapsulation, the Python way

Python has no private keyword. Instead:

• name: public, part of the class's interface.
• _name: internal by convention. Nothing stops access, but a leading underscore tells readers "implementation detail, may change, do not touch". from module import * also skips such names.
• __name (two leading underscores, inside a class): name mangled. The compiler rewrites it to _ClassName__name, so a subclass using the same name gets its own separate attribute.

class Vault:
    def __init__(self):
        self.__code = 1234

v = Vault()
print(v.__dict__)
print(v._Vault__code)
v.__code

{'_Vault__code': 1234}
1234
AttributeError: 'Vault' object has no attribute '__code'

Mangling prevents accidents, not determined access. The Python community's phrase is "we are all consenting adults here": mark internals with _, provide properties where invariants matter, and trust callers.

Common mistakes

• Infinite recursion in a setter: writing self.price = value inside the price setter calls the setter again: RecursionError: maximum recursion depth exceeded. Store into self._price.
• Calling a property: r.area() gives TypeError: 'int' object is not callable, because r.area already returned the number.
• Mutable class attributes shared by accident, and self.count += 1 silently creating an instance attribute.
• Forgetting the decorator name pattern: the setter must be decorated with @<property name>.setter and have the same function name as the getter.

Recap

• Class attributes live on the class and are shared; assigning through an instance shadows them, mutating through an instance changes the shared object.
• @property (plus @name.setter) turns attribute access into method calls, letting you validate or compute without changing callers.
• @classmethod receives cls and is used for alternative constructors; @staticmethod receives nothing extra.
• _name means internal by convention; __name is mangled to _Class__name to avoid subclass clashes.

Going further: read the "Descriptor HowTo Guide" in the Python documentation, which shows how property, classmethod and staticmethod are implemented in pure Python.