{"title":"type & isinstance","description":"","content":"`isinstance` checks whether an object belongs to a class (or any of its subclasses). `issubclass` does the same shape of check, but between two classes. These two functions are how Python code asks \"what kind of thing is this?\" without getting tripped up by inheritance, and they're the right tool whenever a strict `type(obj) == SomeClass` check would silently miss valid input.\n\n---\n\n# Why You Need More Than `type()`\n\nThe most direct way to ask \"what's this object?\" in Python is the built-in `type()`. It returns the exact class of the object.\n\n\n```python\nclass Product:\n def __init__(self, name, price):\n self.name = name\n self.price = price\n\nmouse = Product(\"Wireless Mouse\", 29.99)\nprint(type(mouse))\nprint(type(mouse) == Product)\n```\n\n\nThat works fine until inheritance shows up. Imagine an online store with two kinds of products: physical products that ship in a box, and digital products that get emailed as a download link.\n\n\n```python\nclass Product:\n def __init__(self, name, price):\n self.name = name\n self.price = price\n\nclass PhysicalProduct(Product):\n def __init__(self, name, price, weight_kg):\n super().__init__(name, price)\n self.weight_kg = weight_kg\n\nclass DigitalProduct(Product):\n def __init__(self, name, price, download_url):\n super().__init__(name, price)\n self.download_url = download_url\n\ndef is_product(item):\n return type(item) == Product\n\nmouse = PhysicalProduct(\"Wireless Mouse\", 29.99, 0.1)\nebook = DigitalProduct(\"Python Guide\", 14.99, \"https://store/dl/123\")\n\nprint(is_product(mouse))\nprint(is_product(ebook))\n```\n\n\nBoth `mouse` and `ebook` are products in any reasonable sense of the word, but the check says no. `type()` returns the exact class, and neither object's exact class is `Product`. They're subclasses, and the equality check ignores that relationship.\n\nThis is where `isinstance` comes in. It walks up the inheritance chain and returns `True` for the class itself and for any of its ancestors.\n\n\n```python\ndef is_product(item):\n return isinstance(item, Product)\n\nmouse = PhysicalProduct(\"Wireless Mouse\", 29.99, 0.1)\nebook = DigitalProduct(\"Python Guide\", 14.99, \"https://store/dl/123\")\n\nprint(is_product(mouse))\nprint(is_product(ebook))\n```\n\n\nThe takeaway: when you care about \"is this thing usable as a `Product`?\", `isinstance` is what you want. When you care about \"is this thing exactly a `Product` and nothing more\", `type(obj) == Product` is fine. The first case is far more common.\n\n---\n\n# How `isinstance` Walks the Class Hierarchy\n\n`isinstance(obj, cls)` returns `True` if `cls` is the object's class or appears anywhere in its ancestor chain. Python builds that chain when you define a class: each class remembers its parents, all the way up to `object`, the root of everything.\n\nThe diagram below shows the chain for `mouse`. `isinstance(mouse, Product)` starts at the bottom and walks up until it either finds `Product` or runs out of ancestors.\n\n\n```mermaid\nflowchart BT\n A[PhysicalProduct
mouse is this]:::cyan --> B[Product]:::orange\n B --> C[object
root of all classes]:::green\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nWhen you call `isinstance(mouse, Product)`, Python checks the chain: `PhysicalProduct`, `Product`, `object`. `Product` is in the chain, so the answer is `True`. The same call against `DigitalProduct` finds no match in `mouse`'s chain and returns `False`.\n\nEvery object in Python is ultimately an instance of `object`, so `isinstance(anything, object)` is always `True`.\n\n\n```python\nprint(isinstance(42, object))\nprint(isinstance(\"Wireless Mouse\", object))\nprint(isinstance([1, 2, 3], object))\n```\n\n\n\n> **INFO**\n>\n> **Cost:** `isinstance` walks the method resolution order (MRO) of the object's class. In practice this is short (usually 2-5 entries) and the check is implemented in C, so it's effectively free. Don't worry about calling it in hot loops.\n\n\n---\n\n# Checking Against Multiple Types\n\nYou'll often need to ask \"is this a number?\" without caring whether it's an int or a float. `isinstance` accepts a tuple as its second argument and returns `True` if the object matches any class in the tuple.\n\n\n```python\ndef parse_price(value):\n if not isinstance(value, (int, float)):\n raise TypeError(f\"Price must be a number, got {type(value).__name__}\")\n return float(value)\n\nprint(parse_price(29))\nprint(parse_price(29.99))\n\ntry:\n parse_price(\"29.99\")\nexcept TypeError as e:\n print(e)\n```\n\n\nThe tuple form reads naturally and runs as a single check. It's the idiomatic way to validate input that could be one of several related types.\n\nPython 3.10 added a second form using the `|` (union) operator, the same syntax type hints use. It works wherever a tuple of classes would.\n\n\n```python\ndef parse_price(value):\n if not isinstance(value, int | float):\n raise TypeError(f\"Price must be a number, got {type(value).__name__}\")\n return float(value)\n\nprint(parse_price(29.99))\n```\n\n\nBoth forms produce the same result. Pick the one that fits the codebase's style. New code targeting Python 3.10 or later often uses `int | float` because it matches the type-hint syntax developers already see in function signatures.\n\n---\n\n# The `bool` Surprise\n\nHere's a gotcha that catches almost everyone the first time. In Python, `bool` is a subclass of `int`. `True` is, literally, the integer 1 wearing a different name, and `False` is 0. That means `isinstance(True, int)` returns `True`, even though most code that says \"is this an int?\" doesn't mean to include booleans.\n\n\n```python\nprint(isinstance(True, bool))\nprint(isinstance(True, int))\nprint(isinstance(False, int))\nprint(issubclass(bool, int))\n```\n\n\nThis bites when validating numeric input. A function that says \"give me an integer quantity\" usually doesn't want to accept `True` as a quantity of 1.\n\n\n```python\ndef add_to_cart(product, quantity):\n if not isinstance(quantity, int):\n raise TypeError(\"quantity must be an integer\")\n print(f\"Added {quantity} x {product}\")\n\nadd_to_cart(\"Wireless Mouse\", 2)\nadd_to_cart(\"USB Cable\", True)\n```\n\n\nThe second call sneaks through because `True` is technically an `int`. The fix is to reject `bool` explicitly when you don't want it.\n\n\n```python\ndef add_to_cart(product, quantity):\n if isinstance(quantity, bool) or not isinstance(quantity, int):\n raise TypeError(\"quantity must be an integer (not a bool)\")\n print(f\"Added {quantity} x {product}\")\n\nadd_to_cart(\"Wireless Mouse\", 2)\ntry:\n add_to_cart(\"USB Cable\", True)\nexcept TypeError as e:\n print(e)\n```\n\n\nOrder matters in that check. The `bool` test runs first so it can short-circuit before the `int` test passes.\n\n---\n\n# `issubclass` for Class Objects\n\n`issubclass(cls, parent)` answers the same question as `isinstance`, but the first argument is a class rather than an instance. It's useful when you have a class object in hand and want to check its lineage without creating an instance.\n\n\n```python\nclass Product: pass\nclass PhysicalProduct(Product): pass\nclass DigitalProduct(Product): pass\n\nprint(issubclass(PhysicalProduct, Product))\nprint(issubclass(DigitalProduct, Product))\nprint(issubclass(PhysicalProduct, DigitalProduct))\nprint(issubclass(Product, Product))\n```\n\n\nTwo details worth noting. `issubclass` returns `True` when you compare a class to itself, because by convention every class is considered a subclass of itself. And like `isinstance`, the second argument can be a tuple.\n\n\n```python\nclass GiftCard(Product): pass\n\ndef is_shippable(cls):\n return issubclass(cls, (PhysicalProduct, GiftCard))\n\nprint(is_shippable(PhysicalProduct))\nprint(is_shippable(GiftCard))\nprint(is_shippable(DigitalProduct))\n```\n\n\nA common mistake is calling `issubclass` with an instance instead of a class. The function raises a `TypeError` because it expects a class object.\n\n\n```python\nmouse = PhysicalProduct()\ntry:\n issubclass(mouse, Product)\nexcept TypeError as e:\n print(e)\n```\n\n\nUse `isinstance` for instances, `issubclass` for classes. The error message is clear about which one you reached for.\n\n---\n\n# `isinstance()` vs `type() ==`: The Comparison\n\nBoth forms check types, but they answer subtly different questions. Picking the right one matters more often than people think.\n\n\n| Aspect | `isinstance(obj, cls)` | `type(obj) == cls` |\n| ------ | ---------------------- | ------------------ |\n| Subclasses count? | Yes, returns `True` for the class and any descendant | No, must be the exact class |\n| Multiple types in one call | Yes, pass a tuple or use `\\|` (3.10+) | No, one class at a time |\n| Works with abstract base classes | Yes, supports virtual subclasses | No, ignores `register()` |\n| Idiomatic Python? | Yes, this is the standard check | Rare, used only when you need exact-type semantics |\n| Common use case | Polymorphic input validation | Strict type guards, sentinel checks |\n\n\nThe short version: reach for `isinstance` 95% of the time. Use `type(obj) == cls` only when you have a specific reason to reject subclasses (for example, when you're writing a serializer that handles each exact type differently and a subclass would need its own branch).\n\n\n```mermaid\nflowchart TD\n Q[Need to check a type?]:::orange\n Q -->|Care about subclasses?| ISINST[Use isinstance]:::cyan\n Q -->|Need exact class only?| TYPECHECK[Use type ==]:::teal\n\n ISINST --> EX1[isinstance order.product, Product
accepts PhysicalProduct, DigitalProduct]:::green\n TYPECHECK --> EX2[type item is dict
rejects OrderedDict, defaultdict]:::red\n\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe decision tree captures the rule. If you write `type(x) == list` and someone passes you a custom list subclass that should work just as well, the check rejects it for no good reason. `isinstance(x, list)` accepts it.\n\n---\n\n# Abstract Base Classes and Virtual Subclasses\n\nPython's `abc` module lets a class declare another class as a \"virtual subclass\" without actually inheriting from it. `isinstance` and `issubclass` respect those registrations, which is part of why they're more flexible than raw `type()` checks.\n\nA quick taste: `collections.abc.Sequence` is registered against `list`, `tuple`, `range`, and a few others.\n\n\n```python\nfrom collections import abc\n\nprint(isinstance([1, 2, 3], abc.Sequence))\nprint(isinstance((1, 2, 3), abc.Sequence))\nprint(isinstance(\"hello\", abc.Sequence))\nprint(isinstance({1, 2, 3}, abc.Sequence))\n```\n\n\nLists, tuples, and strings are all sequences (indexable, have a length). Sets are not. `isinstance` knows this because the standard library registered them. `type()` would have given you four useless answers (`list`, `tuple`, `str`, `set`) and forced you to write the dispatch logic by hand.\n\nThe point for this lesson is that `isinstance` and `issubclass` plug into the ABC system out of the box.\n\n---\n\n# Duck Typing vs Explicit Type Checks\n\nPython developers often quote the phrase \"duck typing\": if it walks like a duck and quacks like a duck, treat it like a duck. Translated to code, it means \"don't ask what something is, just try to use it and let it fail if the operation isn't supported\". This is the EAFP style: Easier to Ask Forgiveness than Permission.\n\n\n```python\ndef total_cart(items):\n return sum(item.price for item in items)\n```\n\n\nThis function doesn't check whether `items` is a list, or whether each item is a `Product` instance. If the loop works, it works. If `item.price` doesn't exist on some object, you'll get an `AttributeError` and know exactly what's wrong.\n\nThe opposite style is LBYL: Look Before You Leap. Check types up front, then proceed.\n\n\n```python\ndef total_cart(items):\n if not isinstance(items, list):\n raise TypeError(\"items must be a list\")\n for item in items:\n if not isinstance(item, Product):\n raise TypeError(\"each item must be a Product\")\n return sum(item.price for item in items)\n```\n\n\nWhich one is right? Most Pythonic code leans toward duck typing inside private/internal code, because it accepts more inputs and reads cleaner. A `Sequence`-like object that isn't strictly a `list` should still work. But at boundaries (public APIs, deserialized JSON, user input, anywhere a caller might pass nonsense), explicit `isinstance` checks earn their keep. A clear `TypeError` at the boundary is much easier to debug than an `AttributeError` ten function calls deep.\n\nA practical rule:\n\n- **Inside your own module**, trust the caller and use duck typing. Let exceptions propagate naturally.\n- **At public boundaries** (API endpoints, library entry points, command-line input parsing), validate types with `isinstance` and raise a clear error.\n\n\n```python\ndef add_to_cart(cart, product, quantity):\n # public boundary, validate inputs\n if not isinstance(product, Product):\n raise TypeError(\"product must be a Product instance\")\n if isinstance(quantity, bool) or not isinstance(quantity, int):\n raise TypeError(\"quantity must be an integer\")\n if quantity <= 0:\n raise ValueError(\"quantity must be positive\")\n\n # internal work, trust the inputs\n cart.append((product, quantity))\n return cart\n```\n\n\nThe check appears once, at the entry point. Everything downstream can rely on the invariant and stay clean.\n\n---\n\n# Common Patterns and Pitfalls\n\nA few patterns come up often enough to call out.\n\n**Dispatch by type.** When you have a list of mixed objects and need different handling for each kind, `isinstance` is the clean way to route them.\n\n\n```python\nclass PhysicalProduct: pass\nclass DigitalProduct: pass\n\nclass PhysicalProductImpl(PhysicalProduct):\n def __init__(self, name): self.name = name\n\nclass DigitalProductImpl(DigitalProduct):\n def __init__(self, name): self.name = name\n\ndef shipping_label(item):\n if isinstance(item, PhysicalProduct):\n return f\"Ship {item.name} via courier\"\n if isinstance(item, DigitalProduct):\n return f\"Email {item.name} download link\"\n raise TypeError(f\"Unknown product type: {type(item).__name__}\")\n\nitems = [PhysicalProductImpl(\"Wireless Mouse\"), DigitalProductImpl(\"Python Guide\")]\nfor item in items:\n print(shipping_label(item))\n```\n\n\n**Avoid long `isinstance` chains.** If you find yourself writing five or six `isinstance` branches in a function, that's a hint to use polymorphism instead. Add a method on each class and let the object decide what to do.\n\n\n```python\nclass PhysicalProduct:\n def __init__(self, name): self.name = name\n def shipping_label(self): return f\"Ship {self.name} via courier\"\n\nclass DigitalProduct:\n def __init__(self, name): self.name = name\n def shipping_label(self): return f\"Email {self.name} download link\"\n\nitems = [PhysicalProduct(\"Wireless Mouse\"), DigitalProduct(\"Python Guide\")]\nfor item in items:\n print(item.shipping_label())\n```\n\n\nSame result, less branching, and adding a new product type only requires adding a new class with a `shipping_label` method. No central function to keep updating.\n\n**Don't use `isinstance` to fake type hints.** Runtime `isinstance` checks should validate inputs, not document intent. For static type checking, use type annotations. The two work together: annotations let tools like `mypy` catch bugs before you run the code, while `isinstance` guards the runtime boundary.\n\n---\n\n# Putting It Together\n\n`isinstance` answers \"is this object a kind of X?\" by walking the inheritance chain. `issubclass` answers the same question between two classes. Both accept tuples (and `|` unions on 3.10+) to check against several options at once. Both respect Python's full type system, including abstract base classes and virtual subclasses, which is why they're preferred over raw `type(obj) == cls` checks in nearly every case.\n\nThe one gotcha to remember: `bool` is an `int`, so `isinstance(True, int)` is `True`. If that matters for your input validation, check for `bool` first.\n\nUse these checks at public boundaries where callers might pass anything. Inside trusted code, lean on duck typing instead, because Python code that accepts \"any object with the right shape\" is often more flexible and easier to read than code that demands a specific class.","pageType":"python"}

type & isinstance

Get Premium