bpo-36715: Add usage note for dict.fromkeys() (GH-12974)

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index aeecdbb24a57b1fbd05be5e5aa16a2fb40e19f24..0a6bb149075f47407a08eb7ab7b909b7f257db04 100644 (file)
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -4254,7 +4254,10 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
       Create a new dictionary with keys from *iterable* and values set to *value*.
 
       :meth:`fromkeys` is a class method that returns a new dictionary. *value*
-      defaults to ``None``.
+      defaults to ``None``.  All of the values refer to just a single instance,
+      so it generally doesn't make sense for *value* to be a mutable object
+      such as an empty list.  To get distinct values, use a :ref:`dict
+      comprehension <dict>` instead.
 
    .. method:: get(key[, default])