introduce immutable_type option for pyclasses (PyO3#5101)

* introduce `immutable_type` option for pyclasses

* allow `immutable_type` from 3.10 on the unlimited api

* fix `is_abi3_before` check

---------

Co-authored-by: David Hewitt <[email protected]>

Author: Icxolu

guide/pyclass-parameters.md

@@ -12,6 +12,7 @@
 | <span style="white-space: pre">`frozen`</span> | Declares that your pyclass is immutable. It removes the borrow checker overhead when retrieving a shared reference to the Rust struct, but disables the ability to get a mutable reference. |
 | `get_all` | Generates getters for all fields of the pyclass. |
 | `hash` | Implements `__hash__` using the `Hash` implementation of the underlying Rust datatype. |
+| `immutable_type` | Makes the type object immutable. Supported on 3.14+ with the `abi3` feature active, or 3.10+ otherwise. |
 | `mapping` |  Inform PyO3 that this class is a [`Mapping`][params-mapping], and so leave its implementation of sequence C-API slots empty. |
 | <span style="white-space: pre">`module = "module_name"`</span> |  Python code will see the class as being defined in this module. Defaults to `builtins`. |
 | <span style="white-space: pre">`name = "python_name"`</span> | Sets the name that Python sees this class as. Defaults to the name of the Rust struct. |

newsfragments/5101.added.md

@@ -0,0 +1 @@
+added `immutable_type` pyclass option (on Python 3.14+ with `abi3`, or 3.10+ otherwise) for immutable type objects

pyo3-macros-backend/src/attributes.rs

@@ -27,6 +27,7 @@ pub mod kw {
     syn::custom_keyword!(hash);
     syn::custom_keyword!(into_py_with);
     syn::custom_keyword!(item);
+    syn::custom_keyword!(immutable_type);
     syn::custom_keyword!(from_item_all);
     syn::custom_keyword!(mapping);
     syn::custom_keyword!(module);

pyo3-macros-backend/src/pyclass.rs

@@ -25,7 +25,7 @@ use crate::pymethod::{
     MethodAndSlotDef, PropertyType, SlotDef, __GETITEM__, __HASH__, __INT__, __LEN__, __REPR__,
     __RICHCMP__, __STR__,
 };
-use crate::pyversions::is_abi3_before;
+use crate::pyversions::{is_abi3_before, is_py_before};
 use crate::utils::{self, apply_renaming_rule, Ctx, LitCStr, PythonDoc};
 use crate::PyFunctionOptions;
 
@@ -71,6 +71,7 @@ pub struct PyClassPyO3Options {
     pub freelist: Option<FreelistAttribute>,
     pub frozen: Option<kw::frozen>,
     pub hash: Option<kw::hash>,
+    pub immutable_type: Option<kw::immutable_type>,
     pub mapping: Option<kw::mapping>,
     pub module: Option<ModuleAttribute>,
     pub name: Option<NameAttribute>,
@@ -94,6 +95,7 @@ pub enum PyClassPyO3Option {
     Frozen(kw::frozen),
     GetAll(kw::get_all),
     Hash(kw::hash),
+    ImmutableType(kw::immutable_type),
     Mapping(kw::mapping),
     Module(ModuleAttribute),
     Name(NameAttribute),
@@ -128,6 +130,8 @@ impl Parse for PyClassPyO3Option {
             input.parse().map(PyClassPyO3Option::GetAll)
         } else if lookahead.peek(attributes::kw::hash) {
             input.parse().map(PyClassPyO3Option::Hash)
+        } else if lookahead.peek(attributes::kw::immutable_type) {
+            input.parse().map(PyClassPyO3Option::ImmutableType)
         } else if lookahead.peek(attributes::kw::mapping) {
             input.parse().map(PyClassPyO3Option::Mapping)
         } else if lookahead.peek(attributes::kw::module) {
@@ -203,6 +207,13 @@ impl PyClassPyO3Options {
             PyClassPyO3Option::Freelist(freelist) => set_option!(freelist),
             PyClassPyO3Option::Frozen(frozen) => set_option!(frozen),
             PyClassPyO3Option::GetAll(get_all) => set_option!(get_all),
+            PyClassPyO3Option::ImmutableType(immutable_type) => {
+                ensure_spanned!(
+                    !(is_py_before(3, 10) || is_abi3_before(3, 14)),
+                    immutable_type.span() => "`immutable_type` requires Python >= 3.10 or >= 3.14 (ABI3)"
+                );
+                set_option!(immutable_type)
+            }
             PyClassPyO3Option::Hash(hash) => set_option!(hash),
             PyClassPyO3Option::Mapping(mapping) => set_option!(mapping),
             PyClassPyO3Option::Module(module) => set_option!(module),
@@ -2145,6 +2156,7 @@ impl<'a> PyClassImplsBuilder<'a> {
         let is_subclass = self.attr.options.extends.is_some();
         let is_mapping: bool = self.attr.options.mapping.is_some();
         let is_sequence: bool = self.attr.options.sequence.is_some();
+        let is_immutable_type = self.attr.options.immutable_type.is_some();
 
         ensure_spanned!(
             !(is_mapping && is_sequence),
@@ -2278,6 +2290,7 @@ impl<'a> PyClassImplsBuilder<'a> {
                 const IS_SUBCLASS: bool = #is_subclass;
                 const IS_MAPPING: bool = #is_mapping;
                 const IS_SEQUENCE: bool = #is_sequence;
+                const IS_IMMUTABLE_TYPE: bool = #is_immutable_type;
 
                 type BaseType = #base;
                 type ThreadChecker = #thread_checker;

pyo3-macros-backend/src/pyversions.rs

@@ -2,5 +2,10 @@ use pyo3_build_config::PythonVersion;
 
 pub fn is_abi3_before(major: u8, minor: u8) -> bool {
     let config = pyo3_build_config::get();
-    config.abi3 && config.version < PythonVersion { major, minor }
+    config.abi3 && !config.is_free_threaded() && config.version < PythonVersion { major, minor }
+}
+
+pub fn is_py_before(major: u8, minor: u8) -> bool {
+    let config = pyo3_build_config::get();
+    config.version < PythonVersion { major, minor }
 }

src/impl_/pyclass.rs

@@ -176,6 +176,9 @@ pub trait PyClassImpl: Sized + 'static {
     /// #[pyclass(sequence)]
     const IS_SEQUENCE: bool = false;
 
+    /// #[pyclass(immutable_type)]
+    const IS_IMMUTABLE_TYPE: bool = false;
+
     /// Base class
     type BaseType: PyTypeInfo + PyClassBaseType;
 

src/impl_/pyclass/lazy_type_object.rs

@@ -4,6 +4,10 @@ use std::{
     thread::{self, ThreadId},
 };
 
+#[cfg(Py_3_14)]
+use crate::err::error_on_minusone;
+#[cfg(Py_3_14)]
+use crate::types::PyTypeMethods;
 use crate::{
     exceptions::PyRuntimeError,
     ffi,
@@ -75,12 +79,13 @@ impl LazyTypeObjectInner {
         items_iter: PyClassItemsIter,
     ) -> PyResult<&Bound<'py, PyType>> {
         (|| -> PyResult<_> {
-            let type_object = self
-                .value
-                .get_or_try_init(py, || init(py))?
-                .type_object
-                .bind(py);
-            self.ensure_init(type_object, name, items_iter)?;
+            let PyClassTypeObject {
+                type_object,
+                is_immutable_type,
+                ..
+            } = self.value.get_or_try_init(py, || init(py))?;
+            let type_object = type_object.bind(py);
+            self.ensure_init(type_object, *is_immutable_type, name, items_iter)?;
             Ok(type_object)
         })()
         .map_err(|err| {
@@ -95,6 +100,7 @@ impl LazyTypeObjectInner {
     fn ensure_init(
         &self,
         type_object: &Bound<'_, PyType>,
+        #[allow(unused_variables)] is_immutable_type: bool,
         name: &str,
         items_iter: PyClassItemsIter,
     ) -> PyResult<()> {
@@ -181,6 +187,28 @@ impl LazyTypeObjectInner {
         // return from the function.
         let result = self.tp_dict_filled.get_or_try_init(py, move || {
             let result = initialize_tp_dict(py, type_object.as_ptr(), items);
+            #[cfg(Py_3_14)]
+            if is_immutable_type {
+                // freeze immutable types after __dict__ is initialized
+                let res = unsafe { ffi::PyType_Freeze(type_object.as_type_ptr()) };
+                error_on_minusone(py, res)?;
+            }
+            #[cfg(all(Py_3_10, not(Py_LIMITED_API), not(Py_3_14)))]
+            if is_immutable_type {
+                use crate::types::PyTypeMethods as _;
+                #[cfg(not(Py_GIL_DISABLED))]
+                unsafe {
+                    (*type_object.as_type_ptr()).tp_flags |= ffi::Py_TPFLAGS_IMMUTABLETYPE
+                };
+                #[cfg(Py_GIL_DISABLED)]
+                unsafe {
+                    (*type_object.as_type_ptr()).tp_flags.fetch_or(
+                        ffi::Py_TPFLAGS_IMMUTABLETYPE,
+                        std::sync::atomic::Ordering::Relaxed,
+                    )
+                };
+                unsafe { ffi::PyType_Modified(type_object.as_type_ptr()) };
+            }
 
             // Initialization successfully complete, can clear the thread list.
             // (No further calls to get_or_init() will try to init, on any thread.)

src/pyclass/create_type_object.rs

@@ -23,6 +23,7 @@ use std::{
 
 pub(crate) struct PyClassTypeObject {
     pub type_object: Py<PyType>,
+    pub is_immutable_type: bool,
     #[allow(dead_code)] // This is purely a cache that must live as long as the type object
     getset_destructors: Vec<GetSetDefDestructor>,
 }
@@ -40,6 +41,7 @@ where
         dealloc_with_gc: unsafe extern "C" fn(*mut ffi::PyObject),
         is_mapping: bool,
         is_sequence: bool,
+        is_immutable_type: bool,
         doc: &'static CStr,
         dict_offset: Option<ffi::Py_ssize_t>,
         weaklist_offset: Option<ffi::Py_ssize_t>,
@@ -61,6 +63,7 @@ where
                 tp_dealloc_with_gc: dealloc_with_gc,
                 is_mapping,
                 is_sequence,
+                is_immutable_type,
                 has_new: false,
                 has_dealloc: false,
                 has_getitem: false,
@@ -88,6 +91,7 @@ where
             tp_dealloc_with_gc::<T>,
             T::IS_MAPPING,
             T::IS_SEQUENCE,
+            T::IS_IMMUTABLE_TYPE,
             T::doc(py)?,
             T::dict_offset(),
             T::weaklist_offset(),
@@ -116,6 +120,7 @@ struct PyTypeBuilder {
     tp_dealloc_with_gc: ffi::destructor,
     is_mapping: bool,
     is_sequence: bool,
+    is_immutable_type: bool,
     has_new: bool,
     has_dealloc: bool,
     has_getitem: bool,
@@ -505,6 +510,7 @@ impl PyTypeBuilder {
 
         Ok(PyClassTypeObject {
             type_object,
+            is_immutable_type: self.is_immutable_type,
             getset_destructors,
         })
     }

tests/test_class_attributes.rs

@@ -1,6 +1,7 @@
 #![cfg(feature = "macros")]
 
 use pyo3::prelude::*;
+use pyo3::py_run;
 
 #[path = "../src/tests/common.rs"]
 mod common;
@@ -66,14 +67,68 @@ fn class_attributes() {
     });
 }
 
-// Ignored because heap types are not immutable:
-// https://github.com/python/cpython/blob/master/Objects/typeobject.c#L3399-L3409
 #[test]
-#[ignore]
-fn class_attributes_are_immutable() {
+fn class_attributes_mutable() {
+    #[pyclass]
+    struct Foo {}
+
+    #[pymethods]
+    impl Foo {
+        #[classattr]
+        const MY_CONST: &'static str = "foobar";
+
+        #[classattr]
+        fn a() -> i32 {
+            5
+        }
+    }
+
     Python::with_gil(|py| {
-        let foo_obj = py.get_type::<Foo>();
-        py_expect_exception!(py, foo_obj, "foo_obj.a = 6", PyTypeError);
+        let obj = py.get_type::<Foo>();
+        py_run!(py, obj, "obj.MY_CONST = 'BAZ'");
+        py_run!(py, obj, "obj.a = 42");
+        py_assert!(py, obj, "obj.MY_CONST == 'BAZ'");
+        py_assert!(py, obj, "obj.a == 42");
+    });
+}
+
+#[test]
+#[cfg(any(Py_3_14, all(Py_3_10, not(Py_LIMITED_API))))]
+fn immutable_type_object() {
+    #[pyclass(immutable_type)]
+    struct ImmutableType {}
+
+    #[pymethods]
+    impl ImmutableType {
+        #[classattr]
+        const MY_CONST: &'static str = "foobar";
+
+        #[classattr]
+        fn a() -> i32 {
+            5
+        }
+    }
+
+    #[pyclass(immutable_type)]
+    enum SimpleImmutable {
+        Variant = 42,
+    }
+
+    #[pyclass(immutable_type)]
+    enum ComplexImmutable {
+        Variant(u32),
+    }
+
+    Python::with_gil(|py| {
+        let obj = py.get_type::<ImmutableType>();
+        py_expect_exception!(py, obj, "obj.MY_CONST = 'FOOBAR'", PyTypeError);
+        py_expect_exception!(py, obj, "obj.a = 6", PyTypeError);
+
+        let obj = py.get_type::<SimpleImmutable>();
+        py_expect_exception!(py, obj, "obj.Variant = 0", PyTypeError);
+
+        let obj = py.get_type::<ComplexImmutable>();
+        py_expect_exception!(py, obj, "obj.Variant = 0", PyTypeError);
     });
 }
 

tests/test_compile_error.rs

@@ -71,6 +71,8 @@ fn test_compile_errors() {
     t.compile_fail("tests/ui/duplicate_pymodule_submodule.rs");
     #[cfg(all(not(Py_LIMITED_API), Py_3_11))]
     t.compile_fail("tests/ui/invalid_base_class.rs");
+    #[cfg(any(not(Py_3_10), all(not(Py_3_14), Py_LIMITED_API)))]
+    t.compile_fail("tests/ui/immutable_type.rs");
     t.pass("tests/ui/ambiguous_associated_items.rs");
     t.pass("tests/ui/pyclass_probe.rs");
 }