classmethod()

The "alternative constructor" decorator — bound to the CLASS, so subclasses get their own type when they call it.

Built-in function / decoratorPython 2.2+
Common call
@classmethod def from_str(cls, s): ...
Returns
a bound method — first arg is cls, not self
Replaces
a plain function that takes the class as an explicit argument
Watch out
subclasses inherit the classmethod — cls refers to the CALLING class, not the defining class
classmethod(functionfunction — The function to wrap. Its first parameter will receive the class when called. Used as @classmethod decorator syntax rather than a direct call.type: callable · required)
→ classmethod

Parameters

NameTypeRequiredDescription
functioncallableyesThe function to wrap. Its first parameter will receive the class when called. Used as @classmethod decorator syntax rather than a direct call.

Return value

classmethod — A descriptor that, when accessed on the class or an instance, produces a bound method whose FIRST argument is the class (conventionally `cls`) rather than the instance. Used almost exclusively via the @classmethod decorator syntax.

Common patterns

Alternative constructor
The most common use — parse from a specific input format.
class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y
    @classmethod
    def from_string(cls, s):
        x, y = map(int, s.split(","))
        return cls(x, y)
Subclass-aware factory
cls is the CALLING class — subclasses get the right type.
class Base:
    @classmethod
    def make(cls):
        return cls()

class Sub(Base): pass

type(Sub.make()) is Sub   # True
Access class-level state
Read or modify class attributes without an instance.
class Counter:
    total = 0
    @classmethod
    def bump(cls):
        cls.total += 1
Prefer over static + explicit class name
classmethod scales with subclassing; hard-coded class names do not.
# WORSE: return SomeClass(...)
# BETTER: return cls(...)

Examples

1. Basic factory
Point.from_string("1,2")
Returns
Point(1, 2)
2. Subclass gets subclass
class SubPoint(Point): pass SubPoint.from_string("3,4")
Returns
SubPoint(3, 4)
3. Called via instance
p = Point(0, 0) p.from_string("5,6")
Returns
Point(5, 6) # cls still Point
4. Class-level counter
Counter.bump(); Counter.total
Returns
1
5. Access as bound method
type(Point.from_string)
Returns
<class 'method'>

Pitfalls

1. cls refers to the CALLING class, not the defining class
A subclass inheriting a classmethod calls it with the SUBCLASS as cls. This is usually what you want (subclasses get the right type back), but it can surprise if you assumed cls was fixed.
Assumed defining class
class SubPoint(Point): pass
SubPoint.from_string("1,2")
SubPoint(1, 2) # cls is SubPoint, not Point
By design — factories
return cls(x, y)   # honors the calling subclass
correct type per subclass
2. Do NOT hard-code the class name inside a classmethod
Writing the defining class name defeats the purpose. `Point(x, y)` inside `from_string` would ALWAYS return Point, breaking subclasses. Use `cls(x, y)`.
Ignores subclass
return Point(x, y)   # inside classmethod
always Point, even for subclasses
Use cls
return cls(x, y)
right class per subclass
3. classmethod is a DESCRIPTOR — not usable outside a class
A raw @classmethod-decorated function has to be attached to a class to work as intended. Standalone use gives you a classmethod object with limited API.
Standalone useless
@classmethod
def f(cls): ...
f(SomeClass)
TypeError — not directly callable
Attach to a class
class C:
    @classmethod
    def f(cls): ...

C.f()
works
4. Not the same as a class-level function
`def f(cls):` inside a class is just a regular method with a confusingly-named first arg — Python passes the INSTANCE, not the class. Without @classmethod, the decorator sugar is missing.
Confusing name
class C:
    def cls_method(cls): pass
C().cls_method()
cls is the instance, not the class
Decorate it
    @classmethod
    def cls_method(cls): ...
cls is C

When to use

Use it
  • Alternative constructors — from_string, from_dict, from_json
  • Factory methods that should honor subclassing
  • Reading or modifying class-level state
  • Registries and counters attached to a class
Reach for something else
  • Instance methods → plain method with self
  • Utility functions with no cls or class relevance → staticmethod (or module-level function)
  • Getters / setters that transform an attribute → property
  • Hard-coded class name inside — defeats the pattern

Notes

Complexity
O(1) descriptor invocation
Return
A bound method whose first arg is the class
CPython impl
Objects/funcobject.c :: classmethod_descr_get
Memory
Small descriptor object per class
Thread-safe
Yes for the method itself; depends on what it does with cls

FAQ

classmethod receives the calling class as its first argument (`cls`). staticmethod receives NOTHING implicit — it is just a regular function attached to a class. Use classmethod when you need the class (for alternative constructors, subclass-aware factories, class-level state). Use staticmethod for pure utility functions.

History

2.2
classmethod introduced with new-style classes.
3.9
classmethod wrapping other descriptors (like property) supported, then reverted in 3.11 due to bugs.