What Does isinstance() Do in Python?

Why Would You Use the Python isinstance() Function?

The isinstance() function determines whether an object is an instance of a class. It also detects whether the object is an instance of a superclass. To use isinstance(), you pass it two arguments:

1. The instance you want to analyze
2. The class you want to compare the instance against

These arguments must only be passed by position, not by keyword.

If the object you pass as the first argument is an instance of the class you pass as the second argument, then isinstance() returns True. Otherwise, it returns False.

When you first start learning Python, you’re told that objects are everywhere. Does this mean that every integer, string, list, or function you come across is an object? Yes, it does! In the code below, you’ll analyze some basic data types:

>>> shape = "sphere"
>>> number = 8

>>> isinstance(shape, str)
True

>>> isinstance(number, int)
True

>>> isinstance(number, float)
False

You create two variables, shape and number, which hold str and int objects, respectively. You then pass shape and str to the first call of isinstance() to prove this. The isinstance() function returns True, showing that "sphere" is indeed a string.

Next, you pass number and int to the second call to isinstance(), which also returns True. This tells you 8 is an integer. The third call returns False because 8 isn’t a floating-point number.

Knowing the type of data you’re passing to a function is essential to prevent problems caused by invalid types. While it’s better to avoid passing incorrect data in the first place, using isinstance() gives you a way to avert any undesirable consequences.

Take a look at the code below:

>>> def calculate_area(length, breadth):
...     return length * breadth

>>> calculate_area(5, 3)
15

>>> calculate_area(5, "3")
'33333'

Your function takes two numeric values, multiplies them, and returns the answer. Your function works, but only if you pass it two numbers. If you pass it a number and a string, your code won’t crash, but it won’t do what you expect either.

The string gets replicated when you pass a string and an integer to the multiplication operator (*). In this case, the "3" gets replicated five times to form "33333", which probably isn’t the result you expected.

Things get worse when you pass in two strings:

>>> calculate_area("5", "3")
Traceback (most recent call last):
  File "<python-input-8>", line 1, in <module>
    calculate_area("5", "3")
    ~~~~~~~~~~~~~~^^^^^^^^^^
  File "<python-input-5>", line 2, in calculate_area
    return length * breadth
           ~~~~~~~^~~~~~~~~
TypeError: can't multiply sequence by non-int of type 'str'

The multiplication operator can’t cope with two strings, so the code crashes. This is where you could use isinstance() to warn the user about the invalid data.

The improved version of your calculate_area() function demonstrates this:

>>> def calculate_area(length, breadth):
...     if isinstance(length, int) and isinstance(breadth, int):
...         return length * breadth
...     raise TypeError("Both arguments must be integers")

>>> calculate_area(5, 3)
15

>>> calculate_area(5, "3")
Traceback (most recent call last):
  ...
TypeError: Both arguments must be integers

>>> calculate_area("5", "3")
Traceback (most recent call last):
  ...
TypeError: Both arguments must be integers

To avoid unexpected results, you use two calls to isinstance(), along with the Boolean and operator, to check that you haven’t passed either length or breadth as a string—or any other non-integer—by mistake.

If isinstance() detects invalid data, the if statement causes your function to raise a TypeError exception. Of course, if two integers are passed, the results will be the same as before.

In practice, you should also check whether the length and breadth parameters could be float types. You’ll learn how to incorporate multiple checks into isinstance() later.

This example of checking for a data type illustrates a common usage of isinstance(). You’ve reduced the chance of invalid results wandering further through your code.

Now that you’ve been introduced to the basics of isinstance(), you’ll move on to learn how it can be used to analyze instances within a class hierarchy.

Can isinstance() Detect Subclasses?

In addition to detecting the class of an instance, isinstance() can also tell you if your instance is an object of a superclass. Remember that an instance is considered an object of its parent class, any of its superclasses, and the class you used to create it.

Suppose you’re creating a class hierarchy for a pool game simulator. You could begin with a Ball class containing .color and .shape data attributes, along with .rebound() and .detect_collision() methods. You could then create a PoolBall subclass for your game. It would inherit everything Ball has, but you could also tweak its contents to meet the specific requirements of the pool game.

Having done this, you might decide to design some more ball game simulations. Instead of creating a fresh Ball class, you could reuse your existing one and create more subclasses.

For example, Ball could serve as the superclass for the SoccerBall, PoolBall, and AmericanFootBall classes, each sharing the same basic content but implementing methods differently to behave appropriately within their respective games.

Take the .rebound() method defined within the AmericanFootBall class, whose shape resembles a prolate spheroid. This method will require different calculations from those of SoccerBall and PoolBall instances, which are both spheres.

The code below defines some Ball subclasses:

class Ball:
    def __init__(self, color, shape):
        self.color = color
        self.shape = shape

class PoolBall(Ball):
    def __init__(self, color, number):
        super().__init__(color, shape="sphere")
        self.number = number

class AmericanFootBall(Ball):
    def __init__(self, color):
        super().__init__(color, shape="prolate spheroid")

This code defines a straightforward class hierarchy containing a Ball superclass with two subclasses named PoolBall and AmericanFootBall. When you create an instance of the Ball class, you must pass it values for its .color and .shape attributes.

The data you pass when you create your instance is defined within the .__init__() instance initializer method. This gets called automatically each time you create an instance of the class. You can use it to make any colored ball and give it any shape you wish.

Now, take a closer look at the PoolBall class. To create this as a subclass of Ball, you define it using class PoolBall(Ball). Your PoolBall will have access to all the methods and data attributes from Ball.

When you create a PoolBall instance, you pass it a color and number, but not a shape, since this is all .__init__() demands. However, PoolBall instances still have a .shape data attribute that needs to be initialized.

To initialize .shape, you call the original .__init__() method defined in the Ball superclass using super().__init__(color, shape="sphere"). This passes your desired color and the string "sphere" to the superclass initializer. The string "sphere" is assigned to the shape parameter in the parent class. All PoolBall instances will always be spherical in shape with the color you desire.

To ensure that the number value is assigned to the .number attribute, you again use self.number. Your new PoolBall instance will have a color, a shape of "sphere", and a number.

Similarly, any AmericanFootBall instances will have a .color attribute and "prolate spheroid" as their .shape attribute value. They won’t have a .number attribute because it isn’t needed.

>>> from balls import AmericanFootBall, Ball, PoolBall

>>> eight_ball = PoolBall("black", 8)
>>> football = AmericanFootBall("brown")
>>> ball = Ball("green", "sphere")

>>> isinstance(eight_ball, PoolBall)
True

>>> isinstance(eight_ball, Ball)
True

>>> isinstance(eight_ball, AmericanFootBall)
False

>>> isinstance(eight_ball, object)
True

>>> isinstance(football, object)
True

>>> isinstance(ball, object)
True

>>> isinstance(object, object)
True

>>> isinstance(True, int)
True

>>> isinstance(True, bool)
True

>>> isinstance(False, int)
True

>>> isinstance(False, bool)
True

>>> test_data = [10, True, False]

>>> for element in test_data:
...     print("int" if isinstance(element, int) else "bool")
int
int
int

>>> for element in test_data:
...     print("bool" if isinstance(element, bool) else "int")
'int'
'bool'
'bool'

>>> for element in test_data:
...     print("bool") if type(element) is bool else print("int")
int
bool
bool

>>> class Top:
...     pass


>>> class Middle(Top):
...     pass


>>> class Bottom(Middle):
...     pass


>>> Bottom.mro()
[<class '__main__.Bottom'>,
 <class '__main__.Middle'>,
 <class '__main__.Top'>,
 <class 'object'>]

>>> isinstance(Bottom(), Top)
True

>>> isinstance(football, AmericanFootBall)
True
>>> isinstance(football, PoolBall)
False
>>> isinstance(ball, Ball)
True
>>> isinstance(ball, AmericanFootBall)
False
>>> isinstance(football, Ball)
True
>>> isinstance(ball, PoolBall)
False
>>> isinstance(1, bool)
False
>>> isinstance(0, bool)
False

How Does isinstance() Differ From type()?

The isinstance() function is just one example of several introspection functions that allow you to examine Python objects to learn more about them. As you just learned, Python also provides type(). If you pass it an instance, then you’ll be rewarded with the class to which that instance belongs.

Consider once more the Ball and PoolBall classes you created earlier. To begin with, you create a new PoolBall instance:

>>> from balls import Ball, PoolBall

>>> eight_ball = PoolBall("black", 8)

You can see from the code that eight_ball is an instance of PoolBall. You can also use type() to confirm this:

>>> type(eight_ball)
<class 'balls.PoolBall'>

>>> type(eight_ball) is PoolBall
True

As expected, type() returns details of the class to which eight_ball belongs—in this case, a PoolBall class.

However, you should be careful when using it because it isn’t designed to identify superclass membership. For example, because eight_ball is a PoolBall, and PoolBall is a subclass of Ball, isinstance() will confirm that eight_ball is also a Ball, but type() won’t:

>>> isinstance(eight_ball, Ball)
True

>>> type(eight_ball) is Ball
False

While isinstance() indeed confirms what you know to be true, at first glance, type() appears to disagree.

The reason type() returns False is because it’s not designed to recognize inheritance hierarchies. Unlike isinstance(), type() is designed to look at an instance and tell you the class that instance was created from. When you attempt to use type() to interrogate any further up the class hierarchy, you’re using the wrong tool for the job.

Earlier, you used type() to check for the bool type. This is perfectly safe because the bool class has been designed so that it can’t be subclassed. In other words, there will never be any subclasses of bool that could be passed to type(). So, using type() to check whether a bool is a subclass of int would be pointless.

Next, you’ll learn how to extend the basic functionality of isinstance().

Can You Use isinstance() to Check for Multiple Types?

Besides being able to tell you if your instance belongs to a single class, you can also use isinstance() to determine if it belongs to one of several classes. To do this, pass in a tuple of classes. There’s no need to make separate isinstance() calls.

Suppose you wanted to determine whether data was an integer or a floating-point number. Here’s one way you could do it:

>>> "Number" if isinstance(3.14, (int, float)) else "Not a number"
'Number'

>>> "Number" if isinstance("3.14", (int, float)) else "Not a number"
'Not a number'

By using this code, you’re checking whether a value, first 3.14, then "3.14", is either an integer or a floating-point number. To do this, you pass in a tuple containing both class types you want to check for as the second parameter of isinstance(). In the first case, 3.14, because it’s a float, is shown to be a number. In the second case, "3.14" is a string, so it’s not considered a number.

You can even pass a nested tuple, meaning a tuple that contains other tuples, as the second argument to isinstance():

>>> "Number" if isinstance(3.14, ((int,), (float,))) else "Not a number"
'Number'

>>> "Number" if isinstance(3.14, (int, float)) else "Not a number"
'Number'

In using a nested tuple, you’ve created a semantically equivalent piece of code to your earlier example. The first example contains a nested tuple, while the second contains a flat tuple, as before. The trailing commas surrounding int and float in the first example are necessary to ensure tuples are present because each has only one element. Try replacing 3.14 with "3.14" and you’ll see the same Not a number result as before.

Using nested tuples is helpful if the nested tuple containing the types to be checked is constructed using existing tuples from different sources. In most cases, you’ll rarely use nested tuples in this way.

Although passing multiple types to isinstance() is common, you can also use a union type expression. This allows you to group together multiple data types separated by the bitwise OR (|) operator. When you pass a type to be tested into isinstance(), the function will return True if the type matches any of the types defined in your union.

Instead of passing the tuple (int, float) to isinstance(), you could do the following:

>>> "Number" if isinstance(3.14, int | float) else "Not a number"
'Number'

>>> "Number" if isinstance("3.14", int | float) else "Not a number"
'Not a number'

In both examples, you’ve replaced the earlier (int, float) tuple with the int | float union type expression. Unsurprisingly, the results are the same.

Next, you’ll see how isinstance() works with abstract base classes.

How Can You Use isinstance() With Abstract Base Classes?

Earlier, you learned how isinstance() can tell you if an object is an instance of a class or one of its superclasses. You also know that creating subclasses helps avoid reinventing the wheel when something similar to one of your existing classes becomes necessary. In some cases, you’ll never need to use instances of these superclasses. This is where you might find abstract base classes useful.

from abc import ABC, abstractmethod

class Ball(ABC):
    def __init__(self, color, shape):
        self.color = color
        self.shape = shape

    @abstractmethod
    def get_state(self):
        pass

class PoolBall(Ball):
    def __init__(self, color, number):
        super().__init__(color, shape="sphere")
        self.number = number

    def get_state(self):
        print(f"Color {self.color}, Number {self.number}, Shape {self.shape}")

class AmericanFootBall(Ball):
    def __init__(self, color):
        super().__init__(color, shape="prolate spheroid")

    def get_state(self):
        print(f"Color {self.color}, Shape {self.shape}")

>>> from balls_v2 import Ball

>>> test_ball = Ball("white", "sphere")
Traceback (most recent call last):
  ...
TypeError: Can't instantiate abstract class Ball without an
⮑ Implementation for abstract method 'get_state'

>>> from balls_v2 import AmericanFootBall, Ball, PoolBall

>>> eight_ball = PoolBall("black", 8)
>>> football = AmericanFootBall("brown")

>>> isinstance(eight_ball, Ball)
True

>>> isinstance(football, Ball)
True

Does isinstance() Use Duck Typing?

One interesting aspect of using isinstance() is that it sometimes uses duck typing to decide whether your instance belongs to a class. When you use duck typing, class membership isn’t decided by its true membership, but by its abilities.

Suppose an instance of one of your classes shares similar behavior to another unrelated class. In that case, using duck typing means you’d consider it an instance of that unrelated class. In other words:

If it looks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck. (Source)

However, duck typing can cause isinstance() to produce surprising results, as you’ll see next.

from collections.abc import Iterable

class PlayersVersionOne(Iterable):
    def __init__(self, players):
        self.players = players

    def __iter__(self):
        return iter(self.players)

>>> from player_iterables import PlayersVersionOne

>>> for player in PlayersVersionOne(["Fast Ed", "Slow Jo", "Still Su"]):
...     print(player)
Fast Ed
Slow Jo
Still Su

>>> from collections.abc import Iterable

>>> isinstance(
...     PlayersVersionOne(["Fast Ed", "Slow Jo", "Still Su"]),
...     Iterable
... )
True

# ...

class PlayersVersionTwo:
    def __init__(self, players):
        self.players = players

    def __iter__(self):
        return iter(self.players)

>>> from collections.abc import Iterable
>>> from player_iterables import PlayersVersionTwo

>>> for player in PlayersVersionTwo(["Fast Ed", "Slow Jo", "Still Su"]):
...     print(player)
Fast Ed
Slow Jo
Still Su

>>> isinstance(
...     PlayersVersionTwo(["Fast Ed", "Slow Jo", "Still Su"]),
...     Iterable
... )
True

# ...

class PlayersVersionThree:
    def __init__(self, players):
        self.players = players

    def __getitem__(self, index):
        if index >= len(self.players):
            raise IndexError("Invalid Index")
        return self.players[index]

>>> from player_iterables import PlayersVersionThree

>>> for player in PlayersVersionThree(["Fast Ed", "Slow Jo", "Still Su"]):
...     print(player)
Fast Ed
Slow Jo
Still Su

>>> isinstance(
...     PlayersVersionThree(["Fast Ed", "Slow Jo", "Still Su"]),
...     Iterable,
... )
False

# ...

class PlayersVersionFour:
    def __init__(self, players):
        self.players = players

    def __iter__(self):
        pass

>>> from player_iterables import PlayersVersionFour

>>> isinstance(
...     PlayersVersionFour(["Fast Ed", "Slow Jo", "Still Su"]),
...     Iterable,
... )
True

>>> iter(PlayersVersionOne(["Fast Ed", "Slow Jo", "Still Su"]))
<list_iterator object at 0x72834fbf00a0>

>>> iter(PlayersVersionTwo(["Fast Ed", "Slow Jo", "Still Su"]))
<list_iterator object at 0x72834fa680a0>

>>> iter(PlayersVersionThree(["Fast Ed", "Slow Jo", "Still Su"]))
<iterator object at 0x72834fbf01f0>

>>> iter(PlayersVersionFour(["Fast Ed", "Slow Jo", "Still Su"]))
Traceback (most recent call last):
  ...
TypeError: iter() returned non-iterator of type 'NoneType'

What Should You Learn Next?

Congratulations on reaching the end of this tutorial! Hopefully, it’s sparked your interest in using isinstance() to perform introspection on your objects. This can help you better understand the objects your program uses and the relationships between them.

However, isinstance() isn’t the only introspection function you can use. You might like to delve deeper and look into the following commonly used functions:

These aren’t the only built-in functions or introspection tools available. You can find more in Python’s inspect module.

Conclusion

This tutorial showed you how to use isinstance() to investigate the type of an object. You should now have a solid understanding of how to use it, along with some of its gotchas.

In this tutorial, you’ve learned how to:

• Use isinstance() to determine the class or superclass an object belongs to
• Prefer isinstance() over type() when confirming class membership
• Apply isinstance() to both abstract base classes and concrete classes
• Recognize that when duck typing is involved, isinstance() may not return the result you expect
• Explore additional introspection functions beyond isinstance()

While you’ve had a solid overview of what isinstance() can do, you’re strongly encouraged to practice what you’ve learned and to explore introspection further. Understanding what these functions reveal will help you better grasp how your code works and the objects you’re working with.

Frequently Asked Questions

Now that you have some experience with isinstance() in Python, you can use the questions and answers below to check your understanding and recap what you’ve learned.

These FAQs are related to the most important concepts you’ve covered in this tutorial. Click the Show/Hide toggle beside each question to reveal the answer.

Take the Quiz: Test your knowledge with our interactive “What Does isinstance() Do in Python?” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

What Does isinstance() Do in Python?

Take this quiz to learn how Python's isinstance() introspection function reveals object classes and why it might not always show what you expect.