Proposed code changes for [PEP XXX](link).

Author: matajoh

.gitignore

@@ -179,3 +179,5 @@ CLAUDE.local.md
 #### main branch only stuff below this line, things to backport go above. ####
 # main branch only: ABI files are not checked/maintained.
 Doc/data/python*.abi
+# Ignore the build directory.
+build*

Include/Python.h

@@ -145,6 +145,7 @@
 #include "fileutils.h"
 #include "cpython/pyfpe.h"
 #include "cpython/tracemalloc.h"
+#include "immutability.h"
 
 // Restore warning filter
 #ifdef _MSC_VER

Include/cpython/immutability.h

@@ -0,0 +1,8 @@
+#ifndef Py_CPYTHON_IMMUTABLE_H
+#  error "this header file must not be included directly"
+#endif
+
+PyAPI_DATA(PyTypeObject) _PyNotFreezable_Type;
+
+PyAPI_FUNC(int) _PyImmutability_Freeze(PyObject*);
+PyAPI_FUNC(int) _PyImmutability_RegisterFreezable(PyTypeObject*);

Include/cpython/listobject.h

@@ -44,6 +44,7 @@ PyList_SET_ITEM(PyObject *op, Py_ssize_t index, PyObject *value) {
     PyListObject *list = _PyList_CAST(op);
     assert(0 <= index);
     assert(index < list->allocated);
+    // TODO(Immutable): Add assert to check if the list is immutable
     list->ob_item[index] = value;
 }
 #define PyList_SET_ITEM(op, index, value) \

Include/cpython/object.h

@@ -291,6 +291,7 @@ typedef struct _heaptypeobject {
 PyAPI_FUNC(const char *) _PyType_Name(PyTypeObject *);
 PyAPI_FUNC(PyObject *) _PyType_Lookup(PyTypeObject *, PyObject *);
 PyAPI_FUNC(PyObject *) _PyType_LookupRef(PyTypeObject *, PyObject *);
+PyAPI_FUNC(int) _PyType_HasExtensionSlots(PyTypeObject *);
 PyAPI_FUNC(PyObject *) PyType_GetDict(PyTypeObject *);
 
 PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int);

Include/descrobject.h

@@ -84,6 +84,7 @@ struct PyMemberDef {
 #define Py_AUDIT_READ          2 // Added in 3.10, harmless no-op before that
 #define _Py_WRITE_RESTRICTED   4 // Deprecated, no-op. Do not reuse the value.
 #define Py_RELATIVE_OFFSET     8
+// TODO(Immutable): Could use this to mark members as needing a lock.
 
 PyAPI_FUNC(PyObject *) PyMember_GetOne(const char *, PyMemberDef *);
 PyAPI_FUNC(int) PyMember_SetOne(char *, PyMemberDef *, PyObject *);

Include/dictobject.h

@@ -23,7 +23,8 @@ PyAPI_FUNC(PyObject *) PyDict_GetItem(PyObject *mp, PyObject *key);
 PyAPI_FUNC(PyObject *) PyDict_GetItemWithError(PyObject *mp, PyObject *key);
 PyAPI_FUNC(int) PyDict_SetItem(PyObject *mp, PyObject *key, PyObject *item);
 PyAPI_FUNC(int) PyDict_DelItem(PyObject *mp, PyObject *key);
-PyAPI_FUNC(void) PyDict_Clear(PyObject *mp);
+// Note(Immutable): If dictionary is immutable, then clear can fail. Had to change signature here!
+PyAPI_FUNC(int) PyDict_Clear(PyObject *mp);
 PyAPI_FUNC(int) PyDict_Next(
     PyObject *mp, Py_ssize_t *pos, PyObject **key, PyObject **value);
 PyAPI_FUNC(PyObject *) PyDict_Keys(PyObject *mp);

Include/immutability.h

@@ -0,0 +1,19 @@
+#ifndef Py_IMMUTABILITY_H
+#define Py_IMMUTABILITY_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+#ifndef Py_LIMITED_API
+#  define Py_CPYTHON_IMMUTABLE_H
+#  include "cpython/immutability.h"
+#  undef Py_CPYTHON_IMMUTABLE_H
+#endif
+
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* !Py_IMMUTABILITY_H */

Include/internal/pycore_cell.h

@@ -16,21 +16,30 @@ extern "C" {
 // Sets the cell contents to `value` and return previous contents. Steals a
 // reference to `value`.
 static inline PyObject *
-PyCell_SwapTakeRef(PyCellObject *cell, PyObject *value)
+PyCell_SwapTakeRef(PyCellObject *cell, PyObject *value, int* result)
 {
-    PyObject *old_value;
+    PyObject *old_value = NULL;
+    *result = 0;
     Py_BEGIN_CRITICAL_SECTION(cell);
-    old_value = cell->ob_ref;
-    FT_ATOMIC_STORE_PTR_RELEASE(cell->ob_ref, value);
+    if(Py_CHECKWRITE(cell)){
+        old_value = cell->ob_ref;
+        FT_ATOMIC_STORE_PTR_RELEASE(cell->ob_ref, value);
+    }
+    else {
+        *result = -1;
+        Py_XDECREF(value);
+    }
     Py_END_CRITICAL_SECTION();
     return old_value;
 }
 
-static inline void
+static inline int
 PyCell_SetTakeRef(PyCellObject *cell, PyObject *value)
 {
-    PyObject *old_value = PyCell_SwapTakeRef(cell, value);
+    int result = 0;
+    PyObject *old_value = PyCell_SwapTakeRef(cell, value, &result);
     Py_XDECREF(old_value);
+    return result;
 }
 
 // Gets the cell contents. Returns a new reference.

Include/internal/pycore_ceval.h

@@ -267,6 +267,7 @@ PyAPI_FUNC(int) _PyEval_ExceptionGroupMatch(_PyInterpreterFrame *, PyObject* exc
 PyAPI_FUNC(void) _PyEval_FormatAwaitableError(PyThreadState *tstate, PyTypeObject *type, int oparg);
 PyAPI_FUNC(void) _PyEval_FormatExcCheckArg(PyThreadState *tstate, PyObject *exc, const char *format_str, PyObject *obj);
 PyAPI_FUNC(void) _PyEval_FormatExcUnbound(PyThreadState *tstate, PyCodeObject *co, int oparg);
+PyAPI_FUNC(void) _PyEval_FormatExcNotWriteable(PyThreadState *tstate, PyCodeObject *co, int oparg);
 PyAPI_FUNC(void) _PyEval_FormatKwargsError(PyThreadState *tstate, PyObject *func, PyObject *kwargs);
 PyAPI_FUNC(PyObject *) _PyEval_ImportFrom(PyThreadState *, PyObject *, PyObject *);
 PyAPI_FUNC(PyObject *) _PyEval_ImportName(PyThreadState *, _PyInterpreterFrame *, PyObject *, PyObject *, PyObject *);