Embrace the frozen set

Doc/glossary.rst

@@ -1138,6 +1138,12 @@ Glossary
       c not in 'abc'}`` generates the set of strings ``{'r', 'd'}``.  See
       :ref:`comprehensions`.
 
+   frozen set comprehension
+      A compact way to process all or part of the elements in an iterable and
+      return a frozen set with the results. ``results = {{c for c in 'abracadabra'
+      if c not in 'abc'}}`` generates the frozen 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.

Doc/library/ast.rst

@@ -362,6 +362,21 @@ Literals
                     Constant(value=2),
                     Constant(value=3)]))
 
+.. class:: FrozenSet(elts)
+
+   A frozen set. ``elts`` holds a list of nodes representing the frozen set's elements.
+
+   .. doctest::
+
+        >>> print(ast.dump(ast.parse('{{1, 2, 3}}', mode='eval'), indent=4))
+        Expression(
+            body=FrozenSet(
+                elts=[
+                    Constant(value=1),
+                    Constant(value=2),
+                    Constant(value=3)]))
+
+   .. versionadded:: 3.14
 
 .. class:: Dict(keys, values)
 
@@ -723,12 +738,14 @@ Comprehensions
 
 .. class:: ListComp(elt, generators)
            SetComp(elt, generators)
+           FrozenSetComp(elt, generators)
            GeneratorExp(elt, generators)
            DictComp(key, value, generators)
 
-   List and set comprehensions, generator expressions, and dictionary
-   comprehensions. ``elt`` (or ``key`` and ``value``) is a single node
-   representing the part that will be evaluated for each item.
+   List and (frozen) set comprehensions, generator expressions, and
+   dictionary comprehensions. ``elt`` (or ``key`` and ``value``) is
+   a single node representing the part that will be evaluated for
+   each item.
 
    ``generators`` is a list of :class:`comprehension` nodes.
 
@@ -774,6 +791,21 @@ Comprehensions
                         target=Name(id='x', ctx=Store()),
                         iter=Name(id='numbers', ctx=Load()),
                         is_async=0)]))
+        >>> print(ast.dump(
+        ...     ast.parse('{{x for x in numbers}}', mode='eval'),
+        ...     indent=4,
+        ... ))
+        Expression(
+            body=FrozenSetComp(
+                elt=Name(id='x', ctx=Load()),
+                generators=[
+                    comprehension(
+                        target=Name(id='x', ctx=Store()),
+                        iter=Name(id='numbers', ctx=Load()),
+                        is_async=0)]))
+
+   .. versionadded:: 3.14
+        ``FrozenSetComp``
 
 
 .. class:: comprehension(target, iter, ifs, is_async)
@@ -2233,6 +2265,9 @@ and classes for traversing abstract syntax trees:
    .. versionchanged:: 3.10
       For string inputs, leading spaces and tabs are now stripped.
 
+   .. versionchanged:: 3.14
+      Now supports creating empty frozen sets with ``'frozenset()'``.
+
 
 .. function:: get_docstring(node, clean=True)
 

Doc/library/dis.rst

@@ -800,7 +800,7 @@ not have to be) the original ``STACK[-2]``.
       item = STACK.pop()
       set.add(STACK[-i], item)
 
-   Used to implement set comprehensions.
+   Used to implement (frozen) set comprehensions.
 
 
 .. opcode:: LIST_APPEND (i)
@@ -1120,6 +1120,13 @@ iterations of the loop.
    Works as :opcode:`BUILD_TUPLE`, but creates a set.
 
 
+.. opcode:: BUILD_FROZENSET (count)
+
+   Works as :opcode:`BUILD_TUPLE`, but creates a frozen set.
+
+   .. versionadded:: 3.14
+
+
 .. opcode:: BUILD_MAP (count)
 
    Pushes a new dictionary object onto the stack.  Pops ``2 * count`` items
@@ -1167,7 +1174,7 @@ iterations of the loop.
       seq = STACK.pop()
       set.update(STACK[-i], seq)
 
-   Used to build sets.
+   Used to build (frozen) sets.
 
    .. versionadded:: 3.9
 

Doc/library/stdtypes.rst

@@ -58,8 +58,8 @@ objects considered false:
 * zero of any numeric type: ``0``, ``0.0``, ``0j``, ``Decimal(0)``,
   ``Fraction(0, 1)``
 
-* empty sequences and collections: ``''``, ``()``, ``[]``, ``{}``, ``set()``,
-  ``range(0)``
+* empty sequences and collections: ``''``, ``()``, ``[]``, ``{}``, ``{/}``,
+  ``{{/}}``, ``range(0)``
 
 .. index::
    pair: operator; or
@@ -4247,9 +4247,10 @@ 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.
+Non-empty sets can be created by placing a comma-separated list of elements
+within braces (or double braces for frozen sets), for example: ``{'jack', 'sjoerd'}``
+and ``{{'jack', 'sjoerd'}}`` in addition to the :class:`set` and :class:`frozenset`
+constructors.
 
 The constructors for both classes work the same:
 
@@ -4264,10 +4265,19 @@ The constructors for both classes work the same:
 
    Sets can be created by several means:
 
+   * Use a slash within braces for an empty set: ``{/}``
    * 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'])``
 
+   You can do the same for frozen sets:
+
+   * Use a slash within double braces for an empty set: ``{{/}}``
+   * Use a comma-separated list of elements within double braces: ``{{'jack', 'sjoerd'}}``
+   * Use a frozen set comprehension: ``{{c for c in 'abracadabra' if c not in 'abc'}}``
+   * Use the type constructor: ``frozenset()``, ``frozenset('foobar')``,
+     ``frozenset(['a', 'b', 'foo'])``
+
    Instances of :class:`set` and :class:`frozenset` provide the following
    operations:
 

Doc/reference/expressions.rst

@@ -57,7 +57,7 @@ also categorized syntactically as atoms.  The syntax for atoms is:
 .. productionlist:: python-grammar
    atom: `identifier` | `literal` | `enclosure`
    enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display`
-            : | `generator_expression` | `yield_atom`
+            : | `frozenset_display` | `generator_expression` | `yield_atom`
 
 
 .. _atom-identifiers:
@@ -161,13 +161,13 @@ ambiguities and allow common typos to pass uncaught.
 
 .. _comprehensions:
 
-Displays for lists, sets and dictionaries
------------------------------------------
+Displays for lists, (frozen) 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:
+For constructing a list, a (frozen) set or a dictionary Python provides special
+syntax called "displays", each of them in two flavors:
 
 * either the container contents are listed explicitly, or
 
@@ -278,16 +278,44 @@ A set display is denoted by curly braces and distinguishable from dictionary
 displays by the lack of colons separating keys and values:
 
 .. productionlist:: python-grammar
-   set_display: "{" (`starred_list` | `comprehension`) "}"
+   set_display: "{" (`starred_list` | "/" | `comprehension`) "}"
 
 A set display yields a new mutable set object, the contents being specified by
 either a sequence of expressions or a comprehension.  When a comma-separated
 list of expressions is supplied, its elements are evaluated from left to right
 and added to the set object.  When a comprehension is supplied, the set is
 constructed from the elements resulting from the comprehension.
 
-An empty set cannot be constructed with ``{}``; this literal constructs an empty
-dictionary.
+An empty set is constructed with ``{/}``, not ``{}``; the latter constructs an
+empty dictionary.
+
+
+.. _frozenset:
+
+Frozen set displays
+-------------------
+
+.. index::
+   pair: frozenset; display
+   pair: frozenset; comprehensions
+   pair: object; frozenset
+   single: {{}} (double curly brackets); frozenset expression
+   single: , (comma); expression list
+
+A frozen set display is denoted by double curly braces:
+
+.. productionlist:: python-grammar
+   frozenset_display: "{{" (`starred_list` | "/" | `comprehension`) "}}"
+
+A frozen set display yields a new immutable set object, the contents being
+specified by either a sequence of expressions or a comprehension.  When a
+comma-separated list of expressions is supplied, its elements are evaluated
+from left to right and added to the frozenset object.  When a comprehension
+is supplied, the frozen set is constructed from the elements resulting from
+the comprehension.
+
+An empty frozen set is constructed with ``{{/}}``, not ``{{}}``; the latter is
+reserved for an empty frozen dictionary.
 
 
 .. _dict:
@@ -333,8 +361,8 @@ earlier dict items and earlier dictionary unpackings.
 .. versionadded:: 3.5
    Unpacking into dictionary displays, originally proposed by :pep:`448`.
 
-A dict comprehension, in contrast to list and set comprehensions, needs two
-expressions separated with a colon followed by the usual "for" and "if" clauses.
+A dict comprehension, in contrast to list and (frozen) set comprehensions, needs
+two expressions separated with a colon followed by the usual "for" and "if" clauses.
 When the comprehension is run, the resulting key and value elements are inserted
 in the new dictionary in the order they are produced.
 

Doc/tutorial/datastructures.rst

@@ -451,7 +451,7 @@ eliminating duplicate entries.  Set objects also support mathematical operations
 like union, intersection, difference, and symmetric difference.
 
 Curly braces or the :func:`set` function can be used to create sets.  Note: to
-create an empty set you have to use ``set()``, not ``{}``; the latter creates an
+create an empty set you have to use ``{/}``, not ``{}``; the latter creates an
 empty dictionary, a data structure that we discuss in the next section.
 
 Here is a brief demonstration::
@@ -486,6 +486,26 @@ are also supported::
    >>> a
    {'r', 'd'}
 
+Frozen sets
+-----------
+
+Frozen sets are :term:`immutable` sets and can be used for constants. Double
+curly braces or the :func:`frozenset` function can be used to create them::
+
+   >>> {{1, 2, 3}}
+   {{1, 2, 3}}
+   >>> frozenset('foobar')
+   {{'f', 'r', 'a', 'b', 'o'}}
+
+.. note::
+   To create an empty frozen set you have to use ``{{/}}``, not ``{{}}``; the
+   latter is reserved for an empty frozen dictionary.
+
+Like sets, comprehensions are also supported::
+
+   >>> a = {{x for x in 'abracadabra' if x not in 'abc'}}
+   >>> a
+   {{'r', 'd'}}
 
 .. _tut-dictionaries:
 

Grammar/python.gram

@@ -844,6 +844,7 @@ atom[expr_ty]:
     | NUMBER
     | &'(' (tuple | group | genexp)
     | &'[' (list | listcomp)
+    | &('{' '{') !invalid_frozenset (frozenset | frozensetcomp)
     | &'{' (dict | set | dictcomp | setcomp)
     | '...' { _PyAST_Constant(Py_Ellipsis, NULL, EXTRA) }
 
@@ -937,7 +938,17 @@ tuple[expr_ty]:
     | '(' a=[y=star_named_expression ',' z=[star_named_expressions] { _PyPegen_seq_insert_in_front(p, y, z) } ] ')' {
         _PyAST_Tuple(a, Load, EXTRA) }
 
-set[expr_ty]: '{' a=star_named_expressions '}' { _PyAST_Set(a, EXTRA) }
+set[expr_ty]:
+    | '{' a=star_named_expressions '}' { _PyAST_Set(a, EXTRA) }
+    | '{' '/' '}' { _PyAST_Set(NULL, EXTRA) }
+
+frozenset[expr_ty]:
+    | '{' '{' a=star_named_expressions '}' '}' { _PyAST_FrozenSet(a, EXTRA) }
+    | '{' '{' '/' '}' '}' { _PyAST_FrozenSet(NULL, EXTRA) }
+
+invalid_frozenset:
+    | '{' '{' ~ invalid_frozenset '}' '}'
+    | (dict | set | dictcomp | setcomp)
 
 # Dicts
 # -----
@@ -980,6 +991,10 @@ setcomp[expr_ty]:
     | '{' a=named_expression b=for_if_clauses '}' { _PyAST_SetComp(a, b, EXTRA) }
     | invalid_comprehension
 
+frozensetcomp[expr_ty]:
+    | '{' '{' a=named_expression b=for_if_clauses '}' '}' { _PyAST_FrozenSetComp(a, b, EXTRA) }
+    | invalid_comprehension
+
 genexp[expr_ty]:
     | '(' a=( assignment_expression | expression !':=') b=for_if_clauses ')' { _PyAST_GeneratorExp(a, b, EXTRA) }
     | invalid_comprehension
@@ -1227,12 +1242,12 @@ invalid_del_stmt:
 invalid_block:
     | NEWLINE !INDENT { RAISE_INDENTATION_ERROR("expected an indented block") }
 invalid_comprehension:
-    | ('[' | '(' | '{') a=starred_expression for_if_clauses {
+    | ('[' | '(' | '{' | '{' '{') a=starred_expression for_if_clauses {
         RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "iterable unpacking cannot be used in comprehension") }
-    | ('[' | '{') a=star_named_expression ',' b=star_named_expressions for_if_clauses {
+    | ('[' | '{' | '{' '{') a=star_named_expression ',' b=star_named_expressions for_if_clauses {
         RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, PyPegen_last_item(b, expr_ty),
         "did you forget parentheses around the comprehension target?") }
-    | ('[' | '{') a=star_named_expression b=',' for_if_clauses {
+    | ('[' | '{' | '{' '{') a=star_named_expression b=',' for_if_clauses {
         RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "did you forget parentheses around the comprehension target?") }
 invalid_dict_comprehension:
     | '{' a='**' bitwise_or for_if_clauses '}' {