Python Class Method Decorator @classmethod

In Python, the @classmethod decorator is used to declare a method in the class as a class method that can be called using ClassName.MethodName(). The class method can also be called using an object of the class.

The @classmethod is an alternative of the classmethod() function. It is recommended to use the @classmethod decorator instead of the function because it is just a syntactic sugar.

@classmethod Characteristics

  • Declares a class method.
  • The first parameter must be cls, which can be used to access class attributes.
  • The class method can only access the class attributes but not the instance attributes.
  • The class method can be called using ClassName.MethodName() and also using object.
  • It can return an object of the class.

The following example declares a class method.

Example: @classmethod
class Student:
    name = 'unknown' # class attribute
    def __init__(self):
        self.age = 20  # instance attribute

    @classmethod
    def tostring(cls):
        print('Student Class Attributes: name=',cls.name)

Above, the Student class contains a class attribute name and an instance attribute age. The tostring() method is decorated with the @classmethod decorator that makes it a class method, which can be called using the Student.tostring(). Note that the first parameter of any class method must be cls that can be used to access the class's attributes. You can give any name to the first parameter instead of cls.

Now, you can use the class method, as shown below.

Example: Access Class Method
>>> Student.tostring()
Student Class Attributes: name=unknown

However, the same method can be called using an object also.

Example: Calling Class Method using Object
>>> std = Student()
>>> std.tostring() 
Student Class Attributes: name=unknown
>>> Student().tostring() 
Student Class Attributes: name=unknown

The class method can only access class attributes, but not the instance attributes. It will raise an error if trying to access the instance attribute in the class method.

Example: @classmethod
class Student:
    name = 'unknown' # class attribute
    def __init__(self):
        self.age = 20  # instance attribute

    @classmethod
    def tostring(cls):
        print('Student Class Attributes: name=',cls.name,', age=', cls.age)
Example: Access Class Method
>>> Student.tostring()
Traceback (most recent call last):
  File "<pyshell#22>", line 1, in <module>
    Student.tostring()
  File "<pyshell#21>", line 7, in display
    print('Student Class Attributes: name=',cls.name,', age=', cls.age)
AttributeError: type object 'Student' has no attribute 'age'

The class method can also be used as a factory method to get an object of the class, as shown below.

Example: @classmethod
class Student:
    
    def __init__(self, name, age):
        self.name = name  # instance attribute
        self.age = age # instance attribute

    @classmethod
    def getobject(cls):
        return cls('Steve', 25)

The following calls the class method to get an object.

Example: Class Method as Factory Method
>>> std = Student.getobject()
>>> std.name
'Steve'    
>>> std.age
25

@classmethod vs @staticmethod

The following table lists the difference between the class method and the static method:

@classmethod @staticmethod
Declares a class method. Declares a static method.
It can access class attributes, but not the instance attributes. It cannot access either class attributes or instance attributes.
It can be called using the ClassName.MethodName() or object.MethodName(). It can be called using the ClassName.MethodName() or object.MethodName().
It can be used to declare a factory method that returns objects of the class. It cannot return an object of the class.
Want to check how much you know Python?