Improve performance of isinstance() for misses and improve documentation #159580

Feature or enhancement

When isinstance(obj, cls) fails the PyObject_TypeCheck() test, object_isinstance() looks up obj.__class__ through the full attribute machinery to handle proxies that override __class__. For ordinary objects that lookup resolves to object's own __class__ getset descriptor, so it calls the getset, type-checks, increfs the type, compares it to Py_TYPE(obj) and decrefs it again, all to confirm what was already known.

This PR checks whether __class__ resolves to object's getset descriptor for a type that uses generic attribute lookup. If so the answer is False without any call. Every isinstance() call that returns False with an exact type as the second argument benefits, including each non-matching entry of a tuple of types, which is the common isinstance(o, (str, int, float, ...)) dispatch pattern.

The isinstance() documentation now states that a __class__ attribute differing from type(object) is also consulted, which was undocumented.

Benchmarks

Running isinstance(point, Other) with point a dataclass

On the free-threaded build the gain is larger under contention. On main the __class__ lookup returns a new reference to the instance's type, so when the instance is of a heap type (any Python class) every thread does an atomic incref/decref on the shared type object. The fast path takes no reference.

dataclasses.is_dataclass(point), whose first step is a failing isinstance(obj, type):

import time, threading, dataclasses

@dataclasses.dataclass
class Point:
    x: int
    y: int

class Other:
    pass

is_dataclass = dataclasses.is_dataclass
WORK = 100_000

def case_micro():
    pt = Point(1, 2)          # per-thread instance; the shared object is the type
    for _ in range(WORK):
        isinstance(pt, Other)

def case_is_dataclass():
    pt = Point(1, 2)
    for _ in range(WORK):
        is_dataclass(pt)

def run(fn, nthreads):
    ts = [threading.Thread(target=fn) for _ in range(nthreads)]
    t0 = time.perf_counter()
    for t in ts: t.start()
    for t in ts: t.join()
    return time.perf_counter() - t0

for name, fn in (("isinstance(dc, Other)", case_micro), ("is_dataclass(dc)", case_is_dataclass)):
    for n in (1, 2, 4, 8):
        print(name, n, f"{min(run(fn, n) for _ in range(3)) * 1e3:.1f} ms")

import pyperf

runner = pyperf.Runner()
runner.timeit("isinstance(1, int)  (exact hit, control)", "isinstance(x, int)", setup="x = 1")
runner.timeit("isinstance(1, str)  (False)", "isinstance(x, str)", setup="x = 1")
runner.timeit("isinstance(obj, Other)  (False)", "isinstance(c, D)",
              setup="C = type('C', (), {}); D = type('D', (), {}); c = C()")
runner.timeit("isinstance(1, (str, bytes, float))  (3 misses)", "isinstance(x, (str, bytes, float))", setup="x = 1")
runner.timeit("isinstance(1, (str, int))  (miss, hit)", "isinstance(x, (str, int))", setup="x = 1")

Has this already been discussed elsewhere?

No discussion on the optimization, but the behavior of ininstance has been discussed a lot:

• isinstance is calling ob.__getattribute__ as a fallback instead of object.__class__.__get__ #76864: proposal to bypass __getattribute__ for the __class__ lookup; rejected, overridden __getattribute__ must stay honoured (this PR keeps it).
• Fix documentation for __instancecheck__ #79264, Overzealous Optimization For isinstance #144873: the exact-type shortcut skips __instancecheck__ by design; doc PR gh-144873: Document isinstance Edge Case #144997.
• isinstance check against collection.abc classes fails if value has no __class__ #153772 / gh-153772: Make abc isinstance() tolerate instances without __class__ #154149: abc isinstance falls back to type(obj) when __class__ is unavailable, matching the built-in.
• Poor thread scaling when constructing instances or accessing attributes #139103, Free-threading scalability issue in ABC isinstance checking #157526: free-threading scaling reports with the same refcount-contention cause.
• Documenting isinstance behavior with faked __class__ (Discourse, 2026): the doc change in this PR covers that request.

Linked PRs

• gh-159580: Improve performance of isinstance() for misses and improve documentation #159581