Customize your Python class with Magic or Dunder methods

The magic methods ensure a consistent data model that retains the inherited feature of the built-in class while providing customized class behavior. These methods can enrich the class design and can enhance the readability of the language. So, in this article, we will see how to make use of the magic methods, how it works, and the available magic methods in Python. Let's go through each of the sections:

• Magic Method Syntax
• Common Magic Methods
• Magic Methods For Binary Operators
• Magic Methods For Unary Operators
• A Few Other Magic Methods

Magic Method Syntax

A method that is wrapped by two underscores on both sides is called Magic Methods. The motive behind the magic method is to overload Python's built-in methods and its operators. Here, _syntax prevents the programmers from defining the same name for custom methods. Each magic method serves its purpose. Let’s consider an example that checks for equivalence. Example: 

class EquivalenceClass(object):
    def __eq__(self, other):
        return type(self) == type(other)

print(EquivalenceClass() == EquivalenceClass())
print(EquivalenceClass() == 'MyClass')

Output

True
False

The __eq__ method takes two arguments – self and the object – to check equality. What is important to understand is, __eq__ method is invoked when the two objects are compared using the == operator. Let’s go through some of the common magic methods in python.

Common Magic Methods

In Python, we have a diverse range of magic methods – each serves its purpose. Here we will comb through, a few of the common magic methods:

• Creation
• Destruction
• Type Conversion
• Comparisons

Creation

Magic Methods entangled in creation, are performed when a class instance is created. Two of the magic methods associated are __init__ and __new__ methods.

__init__ method

The __init__ method of an object executes right away after the instance creation. Here, the method takes one positional argument – self – and any number of optional or keyword arguments. Let’s look into a simple example: Example: 

class InitClass(object):
    def __init__(self):
        print('Executing the __init__ method.')

ic = InitClass()

Output

Executing the __init__ method.

Here, the essential point to note is, you are not calling the __init__ method. Instead, the Python interpreter makes the call upon object instantiation. Let’s consider an example, which takes an optional argument: 

class Square(object):
    def __init__(self, number = 2):
        self._number = number

    def square(self):
        return self._number**2

s = Square()
print('Number: % i' % s._number)
print('Square: % i' % s.square())

Output

Number: 2
Square: 4

Here we can notice, the default value (2) is used by the __init__ method in the absence of an optional argument. Let’s check some facts about the __init__ method:

• The __init__ method provides initial data to the object, not to create an object.
• It only returns None; returning other than None raises TypeError.
• It customizes the instantiation of a class.

Next, we will proceed to the __new__ method. 

__new__ method

The __new__ method creates and returns the instance of a class. The primary argument of the __new__ method is the class that has to be instantiated, and the rest are the arguments mentioned during the class call. Let’s explore through an example: Example: 

class Students(object):
    def __init__(self, idNo, grade):
        self._idNo = idNo
        self._grade = grade

    def __new__(cls, idNo, grade):
        print("Creating Instance")
        instance = super(Students, cls).__new__(cls)
        if 5 <= grade <= 10:
            return instance
        else:
            return None

    def __str__(self):
        return '{0}({1})'.format(self.__class__.__name__, self.__dict__)


stud1 = Students(1, 7)
print(stud1)

stud2 = Students(2, 12)
print(stud2)

Output

 
Creating Instance
Students({'_idNo': 1, '_grade': 7})
Creating Instance
None

In most cases, we do not need to define a __new__ method. If we go for a __new__ method implementation, then referencing the superclass is a must. Another essential point to note, the __init__ method of the instantiated class get executes, only if the __new__  method returns an instance of the same class.

Destruction

__del__ method

The__del__ method is invoked on destroying an instance of a class - either through direct deletion or memory restoration by the garbage collector. Let's examine the below code: 

class MyClass(object):
    def __del__(self):
        print('Destroyed')

MyClass()
'Immutable String - not assigned to a variable'

Output

Destroyed

What happens when we create an object without assigning them to a variable? The garbage collector will keep the record of objects, which is not referenced to a variable, and delete it when another program statement executes. Here, we created an object of MyClass without assigning it to a variable. Upon execution of the program statement (Immutable String - not assigned to a variable), the garbage collector destroys the MyClass object. The same happens, when we delete the object directly; But here the deletion happens immediately. Just try the below code. x = MyClass() del x

Type Conversion

Type Conversion refers to the conversion of one data type to another; Python provides several magic methods to handle the conversion.

• __str__ method
• __int__, __float__ and __complex__ methods
• __bool__ method

__str__ method

The __str__ method requires one positional argument – self – and it returns a string. It is called when an object is passed to the str() constructor. Let’s consider an example: 

class MyString(object):
    def __str__(self):
        return 'My String !'

print(str(MyString()))

Output

My String!

Let’s take a look at another situation that invokes the __str__ method. The scenario is the usage of %s in a format string, which in turn invokes the __str__ method. 

class HelloClass(object):
    def __str__(self):
        return 'George'

print('Hello, % s' % HelloClass())

Output

Hello, George

__int__, __float__ and __complex__ methods

The __int__ method executes upon calling the int constructor, and it returns an int; It converts the complex objects into primitive int type. Likewise, __float__ and _complex__ methods execute on passing the object to float and complex constructor, respectively.

__bool__ method

The __bool__ magic method in python takes one positional argument and returns either true or false. Its purpose is either to check an object is true or false, or to explicitly convert to a Boolean.

Comparisons

Comparisons magic methods are invoked, when we check for equivalence (==, !=) or relations (<, and > =). Each of this operator in python is mapped to its corresponding magic methods. 

Binary Equality

1. __eq__ method The __eq__ method executes when two objects are compared using == operator. It takes two positional arguments - the self, and the object to check the equality. In most cases, if the object on the left side is defined, then its equivalence is checked first. Let’s see through an example: 

class MyEquivalence(object):
    def __eq__(self, other):
        print('MyEquivalence:\n'
              '% r\n % r' %(self, other))
        return self is other

class YourEquivalence(object):
    def __eq__(self, other):
        print('Your Equivalence:\n'
              '% r\n % r' %(self, other))
        return self is other

eq1 = MyEquivalence()
eq2 = YourEquivalence()
# checking for equivalence where eq1 is at the left side
print(eq1 == eq2)
# checking for equivalence where eq2 is at the left side
print(eq2 == eq1)

Output

MyEquivalence:
<__main__.MyEquivalence object at 0x7fa1d38e16d8>
<__main__.YourEquivalence object at 0x7fa1d1ea37b8>
False
Your Equivalence:
<__main__.YourEquivalence object at 0x7fa1d1ea37b8>
<__main__.MyEquivalence object at 0x7fa1d38e16d8>
False

The ordering rule isn’t applicable if one object is a direct subclass of the other. Let’s examine through an example: 

class MyEquivalence(object):
    def __eq__(self, other):
        print('MyEquivalence:\n'
              '% r\n % r' %(self, other))
        return self is other

class MySubEquivalence(MyEquivalence):
    def __eq__(self, other):
        print('MySubEquivalence:\n'
              '% r\n % r' %(self, other))
        return self is other

eqMain = MyEquivalence()
eqSub = MySubEquivalence()

# eqMain at the right side
print(eqMain == eqSub)

# eqSub at the right side
print(eqSub == eqMain)

Output

MySubEquivalence:
<__main__.MySubEquivalence object at 0x7f299ce802b0>
 <__main__.MyEquivalence object at 0x7f299e8be6d8>
False
MySubEquivalence:
<__main__.MySubEquivalence object at 0x7f299ce802b0>
 <__main__.MyEquivalence object at 0x7f299e8be6d8>
False

2. __ne__ method The __ne__ magic method executes, when != operator is used. In most cases, we don’t need to define the __ne__ method; Upon using the != operator, the python interpreter will execute the __eq__ method and reverse the result.

Relative Comparisons - __lt__ & __le__, __gt__ & __ge__ methods

The __lt__ and __le__ methods are invoked when < and <= operators are used, respectively.And, the __gt__ and __ge__ methods are invoked on using  > and >= operators, respectively. However,  it’s not necessary to use all these 4 methods; usage of __lt__ and __gt__ methods will meet the purpose. Just examine the below points to understand why we don’t require all these methods: 1. The __ge__ and __le__ methods can be replaced with the inverse of __lt__ and __gt__ methods, respectively. 2.  The disjunction of __lt__ and __eq__ methods can be used instead of the __le__ method, and similarly, the __gt__ and __eq__ methods for __ge__ method. Let’s take a look at the below example. Here, we will compare the object based on its creation time. 

import time
class ObjectCreationTime(object):
    def __init__(self, objName):
        self._created = time.time()
        self._objName = objName

    def __lt__(self, other):
        print('Creation Time:\n'
              '% s:% f\n % s:% f' %(self._objName, self._created,
                                 other._objName, other._created))
        return self._created < other._created

    def __gt__(self, other):
        print('Creation Time:\n'
              '% s:% f\n % s:% f' %(self._objName, self._created,
                                 other._objName, other._created))
        return self._created > other._created

obj1 = ObjectCreationTime('obj1')
obj2 = ObjectCreationTime('obj2')
print(obj1 < obj2)
print(obj1 > obj2)

Output

Creation Time:
obj1:1590679265.753279
obj2:1590679265.753280
True
Creation Time:
obj1:1590679265.753279
obj2:1590679265.753280
False

Magic Methods for binary operators

Let’s look into 3 magic methods provided by python for binary operators.

• Vanilla Method
• Reverse Method
• In-Place Method

Vanilla Method

Consider an expression, x + y; In vanilla method, this expression maps to x.__add__(y).  Let’s consider another expression, y – x. Here, the expression maps to y.__sub__(x). Similarly, a * b maps to a.__mul__(b) and a / b maps to a.__truediv__(b), and so on. One point to note,   the method of the left-side object is invoked and passes the right-side object as the parameter. In the case of x + y, the __add__ method of x is invoked and passes y as the parameter. Let’s examine with an example. 

class Count(object):
    def __init__(self, count):
        self._count = count
    def __add__(self, other):
        total_count = self._count + other._count
        return Count(total_count)
    def __str__(self):
        return 'Count: % i' % self._count



c1 = Count(2)
c2 = Count(5)
c3 = c1 + c2
print(c3)

Output

Count: 7

Reverse Method

In the Vanilla method, the method of the left-side object is invoked on executing a binary operator. However, if the left side object doesn’t have a method for the binary operator to map, the reverse method is called; it checks for the method of the right-side object to map. Let’s have a look at the below example: 

class Count(object):
    def __init__(self, count):
        self._count = count

    def __add__(self, other):
        total_count = self._count + other._count
        return Count(total_count)

    def __radd__(self, other):
        if other == 0:
            return self
        else:
            return self.__add__(other)

    def __str__(self):
        return 'Count:% i' % self._count
    
c2 = Count(2)
c3 = 0 + c2
print(c3)

Output

Count:2

Since 0 doesn’t have __add__ method corresponds to it, python interpreter would call __radd__ method –  c2.__radd__(0). Similarly, if the __sub__ method is not defined, it would call __rsub __.

In-Place Method

Both computation and assignment operations are performed while using the In-place methods. Some of the operators which map to In-place methods are +=, -=, *=, and so on. The In-place method names are preceded by i. For example, the statement x += y would map to x.__iadd__(y), and so on. Let’s go through the below example: 

class inPlace(object):
    def __init__(self, value):
        self._value = value
    def __iadd__(self, other):
        self._value = self._value + other._value
        return self._value
    def __str__(object):
        return self._value

inP1 = inPlace(5)
inP2 = inPlace(3)
inP1 += inP2
print(inP1)

Output

8

Magic Methods for Unary Operators

• __pos__ method
• __neg__ method
• __invert__ method

__pos__ method

The __pos__ method is invoked using the + operator. We have seen that + operator also functions as a binary operator. No worries, python interpreter knows which one to use – unary or binary – based on the situation. The __pos__ method takes a single positional argument – self –, performs the operation, and returns the result. Let’s examine through an example: 

class unaryOp(object):
    def __init__(self, value):
        self._value = value
    def __pos__(self):
        print('__pos__ magic method')
        return(+self._value)
   
up = unaryOp(5)
print(+up)

Output

__pos__ magic method
5

__neg__ method

The __neg__ method is called using the - operator. This operator also acts as a binary operator but based on the situation the interpreter determines which magic method to map. The __neg__ magic method accepts a single positional argument – self –, operates and returns the result. Let’s check the below example: 

class unaryOp(object):
    def __init__(self, value):
        self._value = value
    def __neg__(self):
        print('__neg__ magic method')
        return(-self._value)

up = unaryOp(5)
print(-up)

Output

__neg__ magic method
-5

__invert__ method

The last unary operator is the  __invert__ method, which is invoked using ~ operator.  The statement ~x is equivalent to x.__invert__(). Let’s consider an example: 

class invertClass(object):
    def __init__(self, value):
        self._value = value
    def __invert__(self):
        return self._value[::-1]
    def __str__(self):
        return self._value

invrt = invertClass('Hello, George')
invertedValue = ~invrt
print(invertedValue)

Output

egroeG, olleH

A Few Other Magic Methods

Let's discuss about few other magic methods:

• __len__ method
• __repr__ method
• __contains__ method

Overloading __len__ method

The len() method invokes the __len__ magic method. It takes one positional argument and returns the length of the object. Let's see the below code: 

class RectangleClass(object):
    def __init__(self, area, breadth):
        self._area = area
        self._breadth = breadth
        
    def __len__(self):
        return int(self._area / self._breadth)

rc = RectangleClass(90, 5)
print(len(rc))

Output

18

Importance of __repr__ method

The __repr__ magic method helps to represent an object in Python interactive terminal. It takes one positional argument – self. Let’s have a look, how an object is represented in Python interactive terminal without overloading the __repr__ method. 

class RectangleClass(object):
    def __init__(self, area, breadth):
        self._area = area
        self._breadth = breadth
        
    def __len__(self):
        return int(self._area / self._breadth)

## use python interactive terminal to check object representation.
RectangleClass(90, 5)

Output

<__main__.RectangleClass object at 0x7f9ecaae9710>

We can see, it returns the address of the object in the memory, which is not that useful. Let’s look into how we can overload the __repr__ method to return a useful object representation. 

class RectangleClass(object):
    def __init__(self, area, breadth):
        self._area = area
        self._breadth = breadth
        
    def __len__(self):
        return int(self._area / self._breadth)

    def __repr__(self):
        """object representation"""
        return 'RectangleClass(area =% d, breadth =% d)' %\
               (self._area, self._breadth)
         
RectangleClass(90, 5)   
RectangleClass(80, 4)   

Output

RectangleClass(area=90, breadth=5)
RectangleClass(area=80, breadth=4)

__contains__ magic method

The __contains__ method is called when ‘in’ expression executes. It takes two positional arguments – self and item – and returns true if the item is present or otherwise, it returns false. Let’s examine through an example: 

import datetime

class DateClass(object):
    def __init__(self, startDate, endDate):
        self.startDate = startDate
        self.endDate = endDate

    def __contains__(self, item):
        """ check whether a date is between the given range and
        return true or false"""
        return self.startDate <= item <= self.endDate

dtObj = DateClass(datetime.date(2019, 1, 1), datetime.date(2021, 12, 31))
result = datetime.date(2020, 6, 4) in dtObj
print("Whether (2020, 6, 4) is within the mentioned date range? ", result)

result = datetime.date(2022, 8, 2) in dtObj
print("Whether (2022, 8, 2) is within the mentioned date range? ", result)

Output

Whether (2020, 6, 4) is within the mentioned date range?  True
Whether (2022, 8, 2) is within the mentioned date range?  False

Summary Hence, we can conclude that magic methods are a consistent data model to customize class behavior and enhance readability without losing their inherited feature. However, before giving a customized feature, make sure that whether customization is necessary or not.