Introduce Mapping-like protocols

[srittau]

typing.Mapping is not a protocol, which has caused problems in the past.
(E.g. #3569, see also #3576.) This
introduces a few narrow protocols to _typeshed.pyi that can be used in
place of Mapping.

Not all uses of Mapping can be replaced. For example, cgi.FieldStorage
explictly checks whether the supplied headers argument is a Mapping
instance.

[JelleZijlstra]

See python/typing#273 and #550 for some previous discussion on the variance of Mapping (not directly relevant here).

[Akuli]

For example, TopologicalSorter.__init__ takes a mapping and only uses the .items() method. What happens if it's changed to instead loop over the mapping to get the keys and call __getitem__ to get the values in a future version of Python? Then requiring SupportsItems instead of Mapping will be incorrect. The documentation says that the argument should be "a mapping", rather than saying "an object with .items()".

[srittau]

If the implementation changes, the stubs need to change as well. We tend to follow implementation, not documentation in typeshed.

[torstenrudolf]

is there a way I can use the SupportsGetItem in type annotations in my code? I cannot figure out how to import it.

[hauntsaninja]

Look at the comment at the top of the file :-)