Add protocols `SequenceLike` and `MappingLike` by srittau · Pull Request #15152 · python/typeshed · GitHub

Sequence and Mapping are commonly used in argument types. This can
be problematic, since they are not protocols, making it impossible to
safely duck type or mock them. Also, not all sequence- or mapping-like
types derive from these ABCs at runtime, although in typeshed we often
pretend they do. Ideally we'd be able to avoid this discrepancy in the
far future. Finally, the ABCs sometimes make more API promises than
their sub-classes fulfill. For example, Mapping arguments are
keyword-or-positional, while its most important subtype dict only
accepts positional arguments. These protocols have tighter guarantees.

SequenceLike contains most, MappingLike all methods from their
respective types, making them an easy substitute in argument types.

`Sequence` and `Mapping` are commonly used in argument types. This can be problematic, since they are not protocols, making it impossible to safely duck type or mock them. Also, not all sequence- or mapping-like types derive from these ABCs at runtime, although in typeshed we often pretend they do. Ideally we'd be able to avoid this discrepancy in the far future. Finally, the ABCs sometimes make more API promises than their sub-classes fulfill. For example, `Mapping` arguments are keyword-or-positional, while its most important subtype `dict` only accepts positional arguments. These protocols have tighter guarantees. `SequenceLike` contains most, `MappingLike` all methods from their respective types, making them an easy substitute in argument types.

Why should we use these rather than more precise protocols like SupportsGetItem?

For convenience. I still think using the more precise protocols is the better option in 90% of cases, but sometimes this would be inconvenient, especially as long as we don't have easy protocol composition (via intersections). See also the large amount of Mapping and Sequence annotations we still have, which could easily be replaced with these protocols for now, and refined later.

Also, cf. PyCQA/flake8-pyi#525

Yea this seems useful, and I like the NumPy-esque naming :)

Speaking of NumPy, I left a suggestion that would make np.ndarray assignable to SequenceLike.

MappingLike currently lacks __iter__, is that intentional?

MappingLike currently lacks __iter__, is that intentional?

Good catch, added.

Actually, we need to be careful with such protocols, because match-case relies on collections.abc.Mapping and collections.abc.Sequence subclassing: (see: https://peps.python.org/pep-0634/#sequence-patterns and https://peps.python.org/pep-0634/#mapping-patterns)

For a sequence pattern to succeed the subject must be a sequence, where being a sequence is defined as its class being one of the following:

a class that inherits from collections.abc.Sequence

a Python class that has been registered as a collections.abc.Sequence

a builtin class that has its Py_TPFLAGS_SEQUENCE bit set

a class that inherits from any of the above (including classes defined before a parent’s Sequence registration)

So if the implementation uses match-case, one cannot safely replace argument Mapping with MappingLike and Sequencewith SequenceLike arguments.

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

srittau and others added 2 commits December 19, 2025 18:35

[pre-commit.ci] auto fixes from pre-commit.com hooks

cf4ac68

srittau mentioned this pull request Dec 19, 2025

Fully typed setuptools setup method #15146

Merged