Search code examples
pythonpython-typing

How to find the exact function annotations of Python's builtin `collections.abc` Protocol types?


Python's standard library comes with a bunch of Protocol types in collections.abc like Sequence, Mapping, or Iterable. The documentation contains a nice overview here.

What the documentation is missing though is exact type annotations of these methods. Take for instance the __reversed__ method. I would like to see its exact type signature. Does it for instance return a -> Iterator[T] or is it Iterable[T].

How can I quickly look up these type signatures? Trying to following the types in the IDE seems to lead to a dead-end due to a bunch of re-export barriers.


Solution

  • The best way I have found is to go straight to typeshed/stdlib/typing.pyi, and look up the signatures from there.


    I'll add a few more details, because I always get confuse by that import/re-export.

    collections.abc

    collections/__init__.py actually imports a top-level, private module import _collections_abc and patches it into _sys.modules['collections.abc'] = _collections_abc, see here.

    This is probably what makes IDE struggle with following these types.

    typeshed/stdlib/_collections_abc.pyi

    On the typeshed side that module is typed in typeshed/stdlib/typing.pyi

    However, that module actually contains a bunch of re-export from typing import (...), i.e., it doesn't really contain the actual type definitions itself.

    This finally leads (back?) to typeshed/stdlib/typing.pyi, which contains the actual type definitions.


    The direction how the types are delegated is kind of funny, because at runtime, the aliasing goes the other way around: typing.py contains aliases pointing towards collections.abc here.