Python Class Methods and Properties

An ordinary method defined inside a class is an instance method. Python passes the object it was called on as the first argument, which by convention is named self. Through self, the method reads and changes that object's attributes:

class Kiln:
    def __init__(self, capacity):
        self.capacity = capacity
        self.loaded = 0

    def load(self, pieces):
        if self.loaded + pieces > self.capacity:
            raise ValueError("Kiln is full")
        self.loaded += pieces

small, large = Kiln(12), Kiln(40)
large.load(30)
print(small.loaded, large.loaded)   # 0 30

Each kiln keeps its own loaded count. Attributes set on self are per-instance state; attributes assigned in the class body are class state, shared by every instance. Mixing them up, for example keeping a list of loaded pieces as a class attribute, makes every kiln share the same list. Most methods you write will be instance methods.

@classmethod makes the method receive the class as its first argument, conventionally cls. The most common use is an alternative constructor: another way to create an instance, from a different kind of input.

class Kiln:
    def __init__(self, capacity):
        self.capacity = capacity

    @classmethod
    def from_spec(cls, spec):
        """Create a kiln from text such as 'capacity=24'."""
        _, value = spec.split("=")
        return cls(int(value))

kiln = Kiln.from_spec("capacity=24")

Writing cls(...) rather than Kiln(...) matters for inheritance: if GasKiln subclasses Kiln, then GasKiln.from_spec(...) builds a GasKiln. Hard-coding Kiln would always return the parent type. The standard library uses this pattern widely, for example datetime.fromisoformat() and dict.fromkeys(). Class methods can also read and update class attributes, such as a counter of how many kilns exist.

@staticmethod gives a method no automatic first argument at all. It's a plain function that lives in the class's namespace because it's closely related to the class:

class Kiln:
    @staticmethod
    def parse_capacity(text):
        value = int(text.strip())
        if value <= 0:
            raise ValueError("capacity must be positive")
        return value

print(Kiln.parse_capacity(" 24 "))   # 24

It can be called on the class or on an instance, and it can't see either unless you pass them in. Use it for helpers that belong with the class conceptually, such as unit conversions or validation rules, so callers find them in one place.

A module-level function is often just as good, and simpler to test and import. Python doesn't force everything into classes; choose a static method when keeping the helper beside the class genuinely makes the code easier to find and read.

@property lets a method be read like an attribute. Adding a .setter runs code whenever the attribute is assigned, which is the Pythonic way to validate values without changing how callers use the class:

class Kiln:
    def __init__(self, capacity):
        self.capacity = capacity        # goes through the setter

    @property
    def capacity(self):
        return self._capacity

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

The real value is stored under a different name, _capacity. If the setter wrote self.capacity = value, it would call itself again and again until RecursionError. A property with no setter is read-only: assigning to it raises AttributeError. Properties can also be computed: @property def free_space(self): return self.capacity - self.loaded always reflects the current state.

Python developers start with plain attributes and switch to a property only when validation or computation is needed. Because the syntax for callers stays kiln.capacity, that change doesn't break any existing code, which is why Python code rarely has Java-style get_capacity() and set_capacity() methods.

Task: add a kiln alternative constructor and test valid and negative capacities.

class Kiln:
    def __init__(self, capacity):
        self.capacity = capacity

    @classmethod
    def from_text(cls, text):
        return cls(int(text))

    @property
    def capacity(self):
        return self._capacity

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

print(Kiln.from_text("18").capacity)      # 18
try:
    Kiln.from_text("-5")
except ValueError as error:
    print("Rejected:", error)             # Rejected: Capacity cannot be negative

The class method passes its value to cls, which runs __init__, which runs the setter, so validation applies however the kiln is created. For the worked check, the setter stores _capacity to avoid recursive setter calls: assigning self.capacity inside the setter would call the setter again.

The documentation covers classmethod, staticmethod and property. Continue with polymorphism and inner classes and magic methods. Practise with the Python exercises and Python quiz.