bpo-29981: Add examples and update index for set, dict, and generator comprehensions'(GH-20272)
Co-authored-by: Rémi Lapeyre <remi.lapeyre@henki.fr>
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 9fdbdb1..4f0654b 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -308,6 +308,12 @@
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 elements in an iterable and
+ return a dictionary with the results. ``results = {n: n ** 2 for n in
+ range(10)}`` generates a dictionary containing key ``n`` 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
@@ -1026,6 +1032,12 @@
interface can be registered explicitly using
:func:`~abc.register`.
+ set comprehension
+ A compact way to process all or part of the elements in an iterable and
+ return a set with the results. ``results = {c for c in 'abracadabra' if
+ c not in 'abc'}`` generates the set of strings ``{'r', 'd'}``. See
+ :ref:`comprehensions`.
+
single dispatch
A form of :term:`generic function` dispatch where the implementation is
chosen based on the type of a single argument.
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 2fc7a61..c74d164 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -4140,6 +4140,12 @@
objects. If *iterable* is not specified, a new empty set is
returned.
+ Sets can be created by several means:
+
+ * Use a comma-separated list of elements within braces: ``{'jack', 'sjoerd'}``
+ * Use a set comprehension: ``{c for c in 'abracadabra' if c not in 'abc'}``
+ * Use the type constructor: ``set()``, ``set('foobar')``, ``set(['a', 'b', 'foo'])``
+
Instances of :class:`set` and :class:`frozenset` provide the following
operations:
@@ -4332,6 +4338,14 @@
Return a new dictionary initialized from an optional positional argument
and a possibly empty set of keyword arguments.
+ Dictionaries can be created by several means:
+
+ * Use a comma-separated list of ``key: value`` pairs within braces:
+ ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 'jack', 4127: 'sjoerd'}``
+ * Use a dict comprehension: ``{}``, ``{x: x ** 2 for x in range(10)}``
+ * Use the type constructor: ``dict()``,
+ ``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,
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index b68c298..81dd6fc 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -162,6 +162,8 @@
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:
@@ -260,6 +262,7 @@
.. index::
pair: set; display
+ pair: set; comprehensions
object: set
single: {} (curly brackets); set expression
single: , (comma); expression list
@@ -287,6 +290,7 @@
.. index::
pair: dictionary; display
+ pair: dictionary; comprehensions
key, datum, key/datum pair
object: dictionary
single: {} (curly brackets); dictionary expression
diff --git a/Misc/ACKS b/Misc/ACKS
index 404f70e..5285693 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -382,6 +382,7 @@
Jason Curtis
Hakan Celik
Paul Dagnelie
+Florian Dahlitz
Lisandro Dalcin
Darren Dale
Andrew Dalke