bpo-29981: Update Index for set, dict, and generator 'comprehensions'

Doc/glossary.rst

@@ -272,6 +272,12 @@ Glossary
       keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
       Called a hash in Perl.
 
+   dictionary comprehension
+      A compact way to process all or part of the items in a sequence
+      and return a dictionary with the results. ``results = {n: n ** 2 for n in
+      range(10)}`` generates a dictionary containing key ``n`` which mapped to
+      value ``n ** 2``. See :ref:`comprehensions`.
+
    dictionary view
       The objects returned from :meth:`dict.keys`, :meth:`dict.values`, and
       :meth:`dict.items` are called dictionary views. They provide a dynamic
@@ -921,6 +927,12 @@ Glossary
       reserved for rare cases where there are large numbers of instances in a
       memory-critical application.
 
+   set comprehension
+      A compact way to process all or part of the elements in a sequence and
+      return a set with the results. ``results = {c for c in 'abracadabra' if
+      c not in 'abc'}`` generates the set of strings with ``{'r', 'd'}``.  See
+      :ref:`comprehensions`.
+
    sequence
       An :term:`iterable` which supports efficient element access using integer
       indices via the :meth:`__getitem__` special method and defines a

Doc/library/stdtypes.rst

@@ -3826,15 +3826,17 @@ another set.  The :class:`frozenset` type is immutable and :term:`hashable` ---
 its contents cannot be altered after it is created; it can therefore be used as
 a dictionary key or as an element of another set.
 
-Non-empty sets (not frozensets) can be created by placing a comma-separated list
-of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the
-:class:`set` constructor.
-
 The constructors for both classes work the same:
 
 .. class:: set([iterable])
            frozenset([iterable])
 
+   Sets can be created by several ways:
+
+   * Using a comma-separated list of elements within braces: ``{'jack', 'sjoerd'}``
+   * Using a set comprehension: ``{c for c in 'abracadabra' if c not in 'abc'}``
+   * Using the type constructor: ``set()``, ``set('foobar')``, ``set(['a', 'b', 'foo'])``
+
    Return a new set or frozenset object whose elements are taken from
    *iterable*.  The elements of a set must be :term:`hashable`.  To
    represent sets of sets, the inner sets must be :class:`frozenset`
@@ -4024,14 +4026,18 @@ then they can be used interchangeably to index the same dictionary entry.  (Note
 however, that since computers store floating-point numbers as approximations it
 is usually unwise to use them as dictionary keys.)
 
-Dictionaries can be created by placing a comma-separated list of ``key: value``
-pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
-'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor.
-
 .. class:: dict(**kwarg)
            dict(mapping, **kwarg)
            dict(iterable, **kwarg)
 
+   Dictionaries can be created in several ways:
+
+   * Using a comma-separated list of ``key: value`` pairs within braces:
+     ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 'jack', 4127: 'sjoerd'}``
+   * Using a dict comprehension: ``{}``, ``{x: x ** 2 for x in range(10)}``
+   * Using the type constructor: ``dict()``,
+     ``dict([('foo', 100), ('bar', 200)])``, ``dict(foo=100, bar=200)``
+
    Return a new dictionary initialized from an optional positional argument
    and a possibly empty set of keyword arguments.
 

Doc/reference/expressions.rst

@@ -160,6 +160,8 @@ ambiguities and allow common typos to pass uncaught.
 Displays for lists, sets and dictionaries
 -----------------------------------------
 
+.. index:: single: comprehensions
+
 For constructing a list, a set or a dictionary Python provides special syntax
 called "displays", each of them in two flavors:
 
@@ -227,8 +229,10 @@ the list is constructed from the elements resulting from the comprehension.
 Set displays
 ------------
 
-.. index:: pair: set; display
-           object: set
+.. index::
+   pair: set; display
+   pair: set; comprehensions
+   object: set
 
 A set display is denoted by curly braces and distinguishable from dictionary
 displays by the lack of colons separating keys and values:
@@ -251,9 +255,11 @@ dictionary.
 Dictionary displays
 -------------------
 
-.. index:: pair: dictionary; display
-           key, datum, key/datum pair
-           object: dictionary
+.. index::
+   pair: dictionary; display
+   pair: dictionary; comprehensions
+   key, datum, key/datum pair
+   object: dictionary
 
 A dictionary display is a possibly empty series of key/datum pairs enclosed in
 curly braces:
@@ -302,8 +308,10 @@ prevails.
 Generator expressions
 ---------------------
 
-.. index:: pair: generator; expression
-           object: generator
+.. index::
+   pair: generator; expression
+   pair: generator; comprehensions
+   object: generator
 
 A generator expression is a compact generator notation in parentheses: