docs/library: Document OrderedDict.popitem()'s CPython differences.

Fixes issue #18370.

Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com>

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/library/collections.rst b/docs/library/collections.rst
index 6a23e456c..f973e521e 100644
--- a/docs/library/collections.rst
+++ b/docs/library/collections.rst
@@ -101,3 +101,19 @@ Classes
         a 2
         w 5
         b 3
+
+    .. method:: OrderedDict.popitem()
+
+        Remove and return a (key, value) pair from the dictionary.
+        Pairs are returned in LIFO order.
+
+        .. admonition:: Difference to CPython
+            :class: attention
+
+            ``OrderedDict.popitem()`` does not support the ``last=False`` argument and
+            will always remove and return the last item if present.
+
+            A workaround for this is to use ``pop(<first_key>)`` to remove the first item::
+
+                first_key = next(iter(d))
+                d.pop(first_key)