@staticmethod and When a Plain Function Is Better

18 min · Intermediate

Some logic belongs next to a class but needs neither an object nor the class itself. Python gives two places for it: a static method, or a plain function in the module. Choosing well keeps classes small and code easy to find.

A helper that needs no object

Static method is a method marked with @staticmethod. Python passes it neither self nor cls, so it works like a plain function that is stored in the class for organisation.

Checking whether an order code is well formed needs only the code text. It reads no instance data and no class data.

Python

class Order:    @staticmethod    def is_valid_code(code):        return code.startswith("ORD-") and code[4:].isdigit()

A static method says that in the code.

Example 1 · Class or object, same result

Python

1class Order:2    @staticmethod3    def is_valid_code(code):4        return code.startswith("ORD-") and code[4:].isdigit()5
6print(Order.is_valid_code("ORD-2041"))7print(Order.is_valid_code("2041"))8print(Order().is_valid_code("ORD-1"))

Output

True
False
True

What this code does

"ORD-2041" starts with ORD- and the rest is digits, so the result is True.
"2041" does not start with ORD-, so the result is False.
The call through an object, Order().is_valid_code(...), gives the same kind of answer.

Python passes no automatic first argument. The method behaves like a normal function that happens to live in Order.

Calling it from the class or an object

A static method is called as Order.is_valid_code(...). It also works through an instance, and the instance is not passed in.

Python

1class Order:2    def __init__(self, code):3        if not Order.is_valid_code(code):4            raise ValueError("bad order code")5        self.code = code6
7    @staticmethod8    def is_valid_code(code):9        return code.startswith("ORD-") and code[4:].isdigit()

Inside the class, other methods can use it too.

Example 2 · One rule used by the constructor

Python

1class Order:2    def __init__(self, code):3        if not Order.is_valid_code(code):4            raise ValueError("bad order code")5        self.code = code6
7    @staticmethod8    def is_valid_code(code):9        return code.startswith("ORD-") and code[4:].isdigit()10
11print(Order("ORD-77").code)12try:13    Order("77")14except ValueError as error:15    print("Rejected:", error)

Output

ORD-77
Rejected: bad order code

What this code does

__init__ calls the static method through the class name.
The bad code is stopped before the order exists.

The constructor and any outside caller use the same rule, defined once.

When a plain function is better

A module-level function needs no class name and no decorator. If the helper has nothing to do with the idea of the class, or many classes use it, keep it outside.

Python

1def format_money(cents):2    return f"{cents / 100:.2f}"3
4class Invoice:5    def __init__(self, cents):6        self.cents = cents7
8    def label(self):9        return "Total: " + format_money(self.cents)

Example 3 · The same helper as a function

Python

1def format_money(cents):2    return f"{cents / 100:.2f}"3
4class Invoice:5    def __init__(self, cents):6        self.cents = cents7
8    def label(self):9        return "Total: " + format_money(self.cents)10
11print(Invoice(259900).label())12print(format_money(500))

Output

Total: 2599.00
5.00

What this code does

format_money uses no class data, so it stays a plain function.
Other classes, such as a receipt, can call it without importing Invoice.

Example 4 · Forgetting @staticmethod

Python

1class Pricing:2    def apply_discount(amount, percent):3        return amount - amount * percent / 1004
5print(Pricing.apply_discount(200, 10))6try:7    Pricing().apply_discount(200, 10)8except TypeError as error:9    print(error)

Output

180.0
Pricing.apply_discount() takes 2 positional arguments but 3 were given

What this code does

Called on the class, the function is a plain function and works.
Called on an object, Python inserts the object as the first argument, so three values go to two parameters.

Python is not Java: there is no rule that every function lives in a class. A utils class full of static methods is usually just a module.

Choosing the method type

Ask what the code needs, in this order, and stop at the first yes.

It reads or changes data of one object: instance method (self).
It builds objects or uses class-level data: class method (cls).
It needs neither, and readers expect to find it with the class: static method.
It needs neither and other code uses it as well: plain function in the module.

Three method kinds compared by what Python passes in. An instance method receives self, the object. A classmethod receives cls, the class itself. A staticmethod receives nothing extra, so it works like a plain function stored in the class.

Next step

Check your understanding

10 quick questions

1class Order:2 @staticmethod3 def is_valid_code(code):4 return code.startswith("ORD-") and code[4:].isdigit()5 6print(Order.is_valid_code("ORD-2041"))7print(Order.is_valid_code("2041"))8print(Order().is_valid_code("ORD-1"))

1class Order:2 def __init__(self, code):3 if not Order.is_valid_code(code):4 raise ValueError("bad order code")5 self.code = code6 7 @staticmethod8 def is_valid_code(code):9 return code.startswith("ORD-") and code[4:].isdigit()10 11print(Order("ORD-77").code)12try:13 Order("77")14except ValueError as error:15 print("Rejected:", error)

1def format_money(cents):2 return f"{cents / 100:.2f}"3 4class Invoice:5 def __init__(self, cents):6 self.cents = cents7 8 def label(self):9 return "Total: " + format_money(self.cents)

1def format_money(cents):2 return f"{cents / 100:.2f}"3 4class Invoice:5 def __init__(self, cents):6 self.cents = cents7 8 def label(self):9 return "Total: " + format_money(self.cents)10 11print(Invoice(259900).label())12print(format_money(500))

1class Pricing:2 def apply_discount(amount, percent):3 return amount - amount * percent / 1004 5print(Pricing.apply_discount(200, 10))6try:7 Pricing().apply_discount(200, 10)8except TypeError as error:9 print(error)