pythongh-116938: Clarify documentation of dict and dict.update re…

…garding the positional argument they accept

Doc/library/stdtypes.rst

@@ -4505,13 +4505,13 @@ can be used interchangeably to index the same dictionary entry.
  ``dict([('foo', 100), ('bar', 200)])``, ``dict(foo=100, bar=200)``
 
  If no positional argument is given, an empty dictionary is created.
- If a positional argument is given and it is a mapping object, a dictionary
- is created with the same key-value pairs as the mapping object. Otherwise,
- the positional argument must be an :term:`iterable` object. Each item in
- the iterable must itself be an iterable with exactly two objects. The
- first object of each item becomes a key in the new dictionary, and the
- second object the corresponding value. If a key occurs more than once, the
- last value for that key becomes the corresponding value in the new
+ If a positional argument is given and it defines a ``keys()`` method, a
+ dictionary is created by calling ``__getitem__`` on the argument with each
+ returned key from the method. Otherwise, the positional argument must be an
+ :term:`iterable` object. Each item in the iterable must itself be an iterable
+ with exactly two objects. The first object of each item becomes a key in the new
+ dictionary, and the second object the corresponding value. If a key occurs more
+ than once, the last value for that key becomes the corresponding value in the new
  dictionary.
 
  If keyword arguments are given, the keyword arguments and their values are
@@ -4669,9 +4669,10 @@ can be used interchangeably to index the same dictionary entry.
  Update the dictionary with the key/value pairs from *other*, overwriting
  existing keys. Return ``None``.
 
- :meth:`update` accepts either another dictionary object or an iterable of
- key/value pairs (as tuples or other iterables of length two). If keyword
- arguments are specified, the dictionary is then updated with those
+ :meth:`update` accepts either another object with a ``keys()`` method
+ (in which case ``__getitem__`` is called with every key returned from the method).
+ or an iterable of key/value pairs (as tuples or other iterables of length two).
+ If keyword arguments are specified, the dictionary is then updated with those
  key/value pairs: ``d.update(red=1, blue=2)``.
 
  .. method:: values()

Misc/NEWS.d/next/Documentation/2024-10-09-21-41-36.gh-issue-116938.ChLcRx.rst

@@ -0,0 +1,2 @@
+Clarify documentation of :class:`dict` and :meth:`dict.update` regarding the
+positional argument they accept.