added comments to dict.pop and MutableMapping.pop

Author: randolf-scholz

stdlib/builtins.pyi

@@ -1225,6 +1225,8 @@ class dict(MutableMapping[_KT, _VT]):
     def get(self, key: _KT, default: _VT, /) -> _VT: ...
     @overload
     def get(self, key: _KT, default: _T, /) -> _VT | _T: ...
+    # dict.pop allows arbitrary types, which matches runtime semantics.
+    # linters may choose to warn if the given type does not overlap with the key type
     @overload
     def pop(self, key: object, /) -> _VT: ...
     @overload

stdlib/typing.pyi

@@ -794,6 +794,8 @@ class MutableMapping(Mapping[_KT, _VT]):
     @abstractmethod
     def __delitem__(self, key: _KT, /) -> None: ...
     def clear(self) -> None: ...
+    # We annotate this with `Any` rather than `object` as in dict.pop, since
+    # specific implementations of `MutableMapping` may wish to restrict the type.
     @overload
     def pop(self, key: Any, /) -> _VT: ...
     @overload