Python __instancecheck__() Magic Method

Rate this post

Syntax

class.__instancecheck__(self, instance)

Python’s class.__instancecheck__(self, instance) method implements the isinstance(instance, class) built-in function. It should return True if instance is a direct or indirect instantiated object of class (e.g., via Python inheritance).

We call this a “Dunder Method” for Double Underscore Method” (also called “magic method”). To get a list of all dunder methods with explanation, check out our dunder cheat sheet article on this blog.

Example

In the following example, you create custom classes Person, Friend, Parent, and Child. Both Parent and Friend inherit from Person. Child inherits from Parent. Thus, per transitive inheritance, Child inherits from Parent as well. However, Child doesn’t inherit from Friend.

class Person:
    pass

class Friend(Person):
    pass

class Parent(Person):
    pass

class Child(Parent):
    pass

alice = Child()

# Is alice an instance of Child? Yes!
print(isinstance(alice, Child))
# True

# Is alice an instance of Parent? Yes!
print(isinstance(alice, Parent))
# True

# Is alice an instance of Friend? No!
print(isinstance(alice, Friend))
# False

# Is alice an instance of Person? Yes!
print(isinstance(alice, Person))
# True

The __instancecheck__() dunder method is implemented implicitly and by default. That’s why you don’t need to define it explicitly. However, if you do so, you can manipulate the output of these function calls!

To override the __instancecheck__ magic method, you need to define it on the metaclass as exemplified in PEP 3119.

This is how you’d override the __instancecheck__ magic method for our example to now return False, no matter what:

class PersonMeta(type):
    def __instancecheck__(self, instance):
        return False
    
class Person(metaclass=PersonMeta):
    pass

class Friend(Person):
    pass

class Parent(Person):
    pass

class Child(Parent):
    pass


alice = Child()

# Is alice a Person? Not anymore!
print(isinstance(alice, Person))
# False

Note that the same statement print(isinstance(alice, Person)) previously printed True to the standard output—but with the override, it now prints False.

Background isinstance()

Python’s built-in isinstance(object, class) function takes an object and a class as input arguments. It returns True if the object is an instance of the class. Otherwise, it returns False.

Instead of a class, you can also pass a tuple of classes to check if the object is an instance of any of the classes in the tuple—such as in isinstance(object, (class_A, class_B, ...)).

Learn more in our detailed article:

Background Inheritance

Inheritance allows you to define a class that inherits all methods and properties from another class.

  • Parent class, also denoted as base class, is the class you inherit from. In Python, every class can be a parent class.
  • Child class, also denoted as derived class, inherits from the Parent class. In Python, you can create a child class that inherits all methods and attributes from the Parent using the class Child(Parent) syntax with the parent class enclosed in parentheses.

You can watch our related video on inheritance here:

Learn more in our detailed articles: