Make Mapping/MutableMapping params positional-only (#5772)

These are positional-only on dict, so it makes sense to mark them as positional-only in these base classes too.

Fixes #5771

Author: JelleZijlstra

stdlib/collections/__init__.pyi

@@ -41,9 +41,9 @@ class UserDict(MutableMapping[_KT, _VT]):
     def __delitem__(self, key: _KT) -> None: ...
     def __iter__(self) -> Iterator[_KT]: ...
     def __contains__(self, key: object) -> bool: ...
-    def copy(self: _S) -> _S: ...
+    def copy(self: Self) -> Self: ...
     @classmethod
-    def fromkeys(cls: Type[_S], iterable: Iterable[_KT], value: _VT | None = ...) -> _S: ...
+    def fromkeys(cls: Type[Self], iterable: Iterable[_KT], value: _VT | None = ...) -> Self: ...
 
 class UserList(MutableSequence[_T]):
     data: list[_T]
@@ -208,7 +208,7 @@ class Counter(Dict[_T, int], Generic[_T]):
     def __init__(self, __mapping: Mapping[_T, int]) -> None: ...
     @overload
     def __init__(self, __iterable: Iterable[_T]) -> None: ...
-    def copy(self: _S) -> _S: ...
+    def copy(self: Self) -> Self: ...
     def elements(self) -> Iterator[_T]: ...
     def most_common(self, n: int | None = ...) -> list[tuple[_T, int]]: ...
     @classmethod
@@ -256,7 +256,7 @@ class _OrderedDictValuesView(dict_values[_KT_co, _VT_co], Reversible[_VT_co], Ge
 class OrderedDict(Dict[_KT, _VT], Reversible[_KT], Generic[_KT, _VT]):
     def popitem(self, last: bool = ...) -> tuple[_KT, _VT]: ...
     def move_to_end(self, key: _KT, last: bool = ...) -> None: ...
-    def copy(self: _S) -> _S: ...
+    def copy(self: Self) -> Self: ...
     def __reversed__(self) -> Iterator[_KT]: ...
     def keys(self) -> _OrderedDictKeysView[_KT, _VT]: ...
     def items(self) -> _OrderedDictItemsView[_KT, _VT]: ...
@@ -296,3 +296,8 @@ class ChainMap(MutableMapping[_KT, _VT], Generic[_KT, _VT]):
     def __iter__(self) -> Iterator[_KT]: ...
     def __len__(self) -> int: ...
     def __missing__(self, key: _KT) -> _VT: ...  # undocumented
+    def setdefault(self, key: _KT, default: _VT = ...) -> _VT: ...
+    @overload
+    def pop(self, key: _KT) -> _VT: ...
+    @overload
+    def pop(self, key: _KT, default: _VT | _T = ...) -> _VT | _T: ...

stdlib/typing.pyi

@@ -431,29 +431,29 @@ class Mapping(Collection[_KT], Generic[_KT, _VT_co]):
     # TODO: We wish the key type could also be covariant, but that doesn't work,
     # see discussion in https://github.com/python/typing/pull/273.
     @abstractmethod
-    def __getitem__(self, k: _KT) -> _VT_co: ...
+    def __getitem__(self, __k: _KT) -> _VT_co: ...
     # Mixin methods
     @overload
     def get(self, key: _KT) -> _VT_co | None: ...
     @overload
-    def get(self, key: _KT, default: _VT_co | _T) -> _VT_co | _T: ...
+    def get(self, __key: _KT, __default: _VT_co | _T) -> _VT_co | _T: ...
     def items(self) -> ItemsView[_KT, _VT_co]: ...
     def keys(self) -> KeysView[_KT]: ...
     def values(self) -> ValuesView[_VT_co]: ...
-    def __contains__(self, o: object) -> bool: ...
+    def __contains__(self, __o: object) -> bool: ...
 
 class MutableMapping(Mapping[_KT, _VT], Generic[_KT, _VT]):
     @abstractmethod
-    def __setitem__(self, k: _KT, v: _VT) -> None: ...
+    def __setitem__(self, __k: _KT, __v: _VT) -> None: ...
     @abstractmethod
-    def __delitem__(self, v: _KT) -> None: ...
+    def __delitem__(self, __v: _KT) -> None: ...
     def clear(self) -> None: ...
     @overload
-    def pop(self, key: _KT) -> _VT: ...
+    def pop(self, __key: _KT) -> _VT: ...
     @overload
-    def pop(self, key: _KT, default: _VT | _T = ...) -> _VT | _T: ...
+    def pop(self, __key: _KT, __default: _VT | _T = ...) -> _VT | _T: ...
     def popitem(self) -> tuple[_KT, _VT]: ...
-    def setdefault(self, key: _KT, default: _VT = ...) -> _VT: ...
+    def setdefault(self, __key: _KT, __default: _VT = ...) -> _VT: ...
     # 'update' used to take a Union, but using overloading is better.
     # The second overloaded type here is a bit too general, because
     # Mapping[Tuple[_KT, _VT], W] is a subclass of Iterable[Tuple[_KT, _VT]],

stdlib/weakref.pyi

@@ -42,6 +42,11 @@ class WeakValueDictionary(MutableMapping[_KT, _VT]):
     def items(self) -> Iterator[tuple[_KT, _VT]]: ...  # type: ignore
     def itervaluerefs(self) -> Iterator[KeyedRef[_KT, _VT]]: ...
     def valuerefs(self) -> list[KeyedRef[_KT, _VT]]: ...
+    def setdefault(self, key: _KT, default: _VT = ...) -> _VT: ...
+    @overload
+    def pop(self, key: _KT) -> _VT: ...
+    @overload
+    def pop(self, key: _KT, default: _VT | _T = ...) -> _VT | _T: ...
 
 class KeyedRef(ref[_T], Generic[_KT, _T]):
     key: _KT
@@ -67,6 +72,11 @@ class WeakKeyDictionary(MutableMapping[_KT, _VT]):
     def values(self) -> Iterator[_VT]: ...  # type: ignore
     def items(self) -> Iterator[tuple[_KT, _VT]]: ...  # type: ignore
     def keyrefs(self) -> list[ref[_KT]]: ...
+    def setdefault(self, key: _KT, default: _VT = ...) -> _VT: ...
+    @overload
+    def pop(self, key: _KT) -> _VT: ...
+    @overload
+    def pop(self, key: _KT, default: _VT | _T = ...) -> _VT | _T: ...
 
 class finalize:
     def __init__(self, __obj: object, __func: Callable[..., Any], *args: Any, **kwargs: Any) -> None: ...

tests/stubtest_allowlists/py310.txt

@@ -13,6 +13,16 @@ _collections_abc.Generator.throw
 _collections_abc.ItemsView.__reversed__
 _collections_abc.KeysView.__reversed__
 _collections_abc.ValuesView.__reversed__
+
+# These are not positional-only at runtime, but we treat them
+# as positional-only to match dict.
+_collections_abc.Mapping.__getitem__
+_collections_abc.Mapping.__contains__
+_collections_abc.MutableMapping.__delitem__
+_collections_abc.MutableMapping.__setitem__
+_collections_abc.MutableMapping.pop
+_collections_abc.MutableMapping.setdefault
+
 _dummy_thread
 ast.Bytes.__new__
 ast.Ellipsis.__new__