diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index c8dcaef80188cd..fb4f8da503fde8 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -1346,7 +1346,14 @@ attribute. A real dictionary used to store the contents of the :class:`UserDict` class. + :class:`!UserDict` instances also override the following method: + .. method:: popitem + + Remove and return a ``(key, value)`` pair from the wrapped dictionary. Pairs are + returned in in the same order as ``data.popitem()``. (For the default + :meth:`dict.popitem`, this order is :abbr:`LIFO (last-in, first-out)`.) If the + dictionary is empty, raises a :exc:`KeyError`. :class:`UserList` objects ------------------------- diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index febab521629228..20f1e728733fec 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -1253,6 +1253,20 @@ def copy(self): c.update(self) return c + + # This method has a default implementation in MutableMapping, but dict's + # equivalent is last-in, first-out instead of first-in, first-out. + def popitem(self): + """Remove and return a (key, value) pair as a 2-tuple. + + Removes pairs in the same order as the wrapped mapping's popitem() + method. For dict objects (the default), that order is last-in, + first-out (LIFO). + Raises KeyError if the UserDict is empty. + """ + return self.data.popitem() + + @classmethod def fromkeys(cls, iterable, value=None): d = cls() diff --git a/Misc/NEWS.d/next/Library/2026-04-01-07-10-49.gh-issue-147957.QXf5Xx.rst b/Misc/NEWS.d/next/Library/2026-04-01-07-10-49.gh-issue-147957.QXf5Xx.rst new file mode 100644 index 00000000000000..4a0e15d01c72b6 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-04-01-07-10-49.gh-issue-147957.QXf5Xx.rst @@ -0,0 +1 @@ +Guarantees that :meth:`collections.UserDict.popitem` will pop in the same order as the wrapped dictionary rather than an arbitrary order.