Typing: Document performance pitfalls of protocols decorated with @runtime_checkable

[AlexWaygood]

Documentation

The following two calls look similar, but the second is dramatically slow compared to the first:

from typing import SupportsInt

isinstance(3, int)
isinstance(3, SupportsInt)

The reason for the slowness is because of _ProtocolMeta.__instancecheck__, which makes calling isinstance() against any runtime-checkable protocol pretty slow. It's possible we can find ways of optimising _ProtocolMeta.__instancecheck__, but whatever we do, it is likely to remain substantially slower to call isinstance() against runtime-checkable protocols than it is to call isinstance() against "normal" classes. This is often pretty surprising for users, so one of the consensus points in python/typing#1363 was that this should be better documented.

Linked PRs

• gh-102936: typing: document performance pitfalls of protocols decorated with @runtime_checkable #102937
• [3.11] gh-102936: typing: document performance pitfalls of protocols decorated with @runtime_checkable (GH-102937) #102963
• [3.10] gh-102936: typing: document performance pitfalls of protocols decorated with @runtime_checkable (GH-102937) #102964