gh-141510, PEP 814: Add built-in frozendict type by vstinner · Pull Request #144757 · python/cpython

vstinner · 2026-02-12T18:21:35Z

Add TYPE_FROZENDICT to the marshal module.

Add C API functions:

PyAnyDict_Check()
PyAnyDict_CheckExact()
PyFrozenDict_Check()
PyFrozenDict_CheckExact()
PyFrozenDict_New()

Add PyFrozenDict_Type C type.

Issue: PEP 814: Add built-in frozendict type #141510

📚 Documentation preview 📚: https://cpython-previews--144757.org.readthedocs.build/

Add TYPE_FROZENDICT to the marshal module. Add C API functions: * PyAnyDict_Check() * PyAnyDict_CheckExact() * PyFrozenDict_Check() * PyFrozenDict_CheckExact() * PyFrozenDict_New() Add PyFrozenDict_Type C type.

vstinner · 2026-02-13T07:49:35Z

cc @corona10

Fix also indentation.

Doc/library/stdtypes.rst

Doc/whatsnew/3.15.rst

Lib/test/mapping_tests.py

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Objects/dictobject.c

corona10 · 2026-02-13T13:00:43Z

Objects/dictobject.c

    }

-    if (PyDict_CheckExact(d)) {
+    if (PyAnyDict_CheckExact(d)) {


Maybe same opinion with @kumaraditya303 we can avoid a lot of critical section if dict is frozen dict.

I agree, but I would prefer to make such "optimization" change in a separated PR.

corona10 · 2026-02-13T13:01:28Z

Objects/dictobject.c

 dict_length(PyObject *self)
 {
-    return FT_ATOMIC_LOAD_SSIZE_RELAXED(((PyDictObject *)self)->ma_used);
+    return GET_USED(_PyAnyDict_CAST(self));


Do we have to use atomic operation for frozendict?

No, we can skip the atomic operation for frozendict.

It uses relaxed atomic so it compiles to simple loads so avoiding it has no real benefit.

corona10 · 2026-02-13T13:02:04Z

Objects/dictobject.c

+};
+
+static PyMappingMethods frozendict_as_mapping = {
+    .mp_length = dict_length,


I think that we can make frozendict_lenth

I propose to make such optimization in a separated PR.

corona10 · 2026-02-13T13:05:55Z

Objects/dictobject.c

+
+static PyMappingMethods frozendict_as_mapping = {
+    .mp_length = dict_length,
+    .mp_subscript = dict_subscript,


Still perfer to make frozendict_subscript, but let's do it at the separate PR.

corona10

We should notice that frozendict is not subclass of dict to follow SC feedback

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Document frozendict after lazy import.

vstinner · 2026-02-13T15:02:44Z

Objects/dictobject.c

            mp->ma_values == NULL &&
-            (mp->ma_used >= (mp->ma_keys->dk_nentries * 2) / 3))
+            (mp->ma_used >= (mp->ma_keys->dk_nentries * 2) / 3) &&
+            !frozendict)


We might take this fast-path for frozendict as well. It's just a missed optimization opportunity.

@corona10: Add it to the optimization TODO list :-)

Yeah I will take a look at it

vstinner · 2026-02-13T15:07:01Z

Objects/dictobject.c

+    if (items == NULL) {
+        return -1;
+    }
+    PyObject *frozenset = PyFrozenSet_New(items);


The current implementation creates an actual frozenset object which emits surprising error messages:

>>> hash(frozendict(x=[])) Traceback (most recent call last): File "<python-input-0>", line 1, in <module> hash(frozendict(x=[])) ~~~~^^^^^^^^^^^^^^^^^^ TypeError: cannot use 'tuple' as a set element (unhashable type: 'list')

We may change the implementation later to not create an actual frozenset, but reuse frozenset hash code instead, to avoid the surprising errors.

vstinner · 2026-02-13T15:13:01Z

We should notice that frozendict is not subclass of dict to follow SC feedback

Ah right, done.

bedevere-bot · 2026-02-14T12:19:13Z

🤖 New build scheduled with the buildbot fleet by @corona10 for commit 9101b1a 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F144757%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-refleak-buildbots label again.

corona10 · 2026-02-14T12:19:43Z

Let's wait build bot to pass the refleak test :)

benediktjohannes

Nitpick: I know this does not primarily belong to the PR, but it's such a small change that a new PR wouldn't make sense for these small "typos".

benediktjohannes · 2026-02-14T14:37:03Z

Doc/library/stdtypes.rst

 | ``max(s)``               | largest item of *s*            |          |
 +--------------------------+--------------------------------+----------+

 Sequences of the same type also support comparisons.  In particular, tuples


Suggested change

Sequences of the same type also support comparisons. In particular, tuples

benediktjohannes · 2026-02-14T14:38:02Z

Doc/library/stdtypes.rst

 Sequences of the same type also support comparisons.  In particular, tuples
 and lists are compared lexicographically by comparing corresponding elements.
 This means that to compare equal, every element must compare equal and the
 two sequences must be of the same type and have the same length.  (For full


Suggested change

two sequences must be of the same type and have the same length.

(For full details see :ref:`comparisons` in the language reference.)

benediktjohannes · 2026-02-14T14:38:16Z

Doc/library/stdtypes.rst

 and lists are compared lexicographically by comparing corresponding elements.
 This means that to compare equal, every element must compare equal and the
 two sequences must be of the same type and have the same length.  (For full
 details see :ref:`comparisons` in the language reference.)


Suggested change

pythongh-141510, PEP 814: Add built-in frozendict type

bde4379

Add TYPE_FROZENDICT to the marshal module. Add C API functions: * PyAnyDict_Check() * PyAnyDict_CheckExact() * PyFrozenDict_Check() * PyFrozenDict_CheckExact() * PyFrozenDict_New() Add PyFrozenDict_Type C type.

bedevere-app bot mentioned this pull request Feb 12, 2026

PEP 814: Add built-in frozendict type #141510

Open

vstinner added 2 commits February 12, 2026 19:25

Document PyFrozenDict_Type in the C API doc

1fb7c5a

Fix test_inspect and test_doctest

fca2e5b

vstinner marked this pull request as ready for review February 13, 2026 07:30

vstinner requested review from AA-Turner, ZeroIntensity, ericsnowcurrently, markshannon, methane and rhettinger as code owners February 13, 2026 07:30

bedevere-app bot added the awaiting core review label Feb 13, 2026

Complete the documentation

99b291c

vstinner mentioned this pull request Feb 13, 2026

[WIP] gh-141510: PEP 814: Add built-in frozendict type #141508

Draft

Fix doc warnings

5e4a284

Fix also indentation.

corona10 self-requested a review February 13, 2026 10:07

hugovk reviewed Feb 13, 2026

View reviewed changes

Apply suggestions from code review

5c0c6f1

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

kumaraditya303 reviewed Feb 13, 2026

View reviewed changes

Objects/dictobject.c Show resolved Hide resolved

corona10 reviewed Feb 13, 2026

View reviewed changes

vstinner and others added 3 commits February 13, 2026 15:46

Apply suggestion from @hugovk

8d4ed14

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Move the What's New entry

c770613

Document frozendict after lazy import.

Revert _PyDict_LoadBuiltinsFromGlobals() change

6dfec48

vstinner commented Feb 13, 2026

View reviewed changes

Document that frozendict is not a dict subclass

9101b1a

corona10 added the 🔨 test-with-refleak-buildbots Test PR w/ refleak buildbots; report in status section label Feb 14, 2026

bedevere-bot removed the 🔨 test-with-refleak-buildbots Test PR w/ refleak buildbots; report in status section label Feb 14, 2026

benediktjohannes reviewed Feb 14, 2026

View reviewed changes


	Sequences of the same type also support comparisons. In particular, tuples


	two sequences must be of the same type and have the same length.
	(For full details see :ref:`comparisons` in the language reference.)

Uh oh!

Conversation

vstinner commented Feb 12, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vstinner commented Feb 13, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

corona10 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vstinner commented Feb 13, 2026

Uh oh!

bedevere-bot commented Feb 14, 2026

Uh oh!

corona10 commented Feb 14, 2026

Uh oh!

benediktjohannes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

vstinner commented Feb 12, 2026 •

edited by github-actions bot

Loading