Add PyGcTraversable derive

Cargo.toml

@@ -346,6 +346,10 @@ required-features = ["macros"]
 name = "test_gc"
 required-features = ["macros"]
 
+[[test]]
+name = "test_pygcintegration"
+required-features = ["macros"]
+
 [[test]]
 name = "test_getter_setter"
 required-features = ["macros"]

newsfragments/6330.added.md

@@ -0,0 +1 @@
+Add `PyGcTraversable` and `#[derive(PyGcTraversable)]` for opt-in GC traversal derivation, including field-level `#[pyo3(gc = false)]` support and a `PyGcOpaque<T>` wrapper for explicit traversal opt-out in recursion breakpoints.

pyo3-macros-backend/src/attributes.rs

@@ -50,6 +50,7 @@ pub mod kw {
     syn::custom_keyword!(unsendable);
     syn::custom_keyword!(weakref);
     syn::custom_keyword!(generic);
+    syn::custom_keyword!(gc);
     syn::custom_keyword!(gil_used);
     syn::custom_keyword!(warn);
     syn::custom_keyword!(message);
@@ -392,6 +393,7 @@ pub type FromPyWithAttribute = KeywordAttribute<kw::from_py_with, ExprPath>;
 pub type IntoPyWithAttribute = KeywordAttribute<kw::into_py_with, ExprPath>;
 
 pub type DefaultAttribute = OptionalKeywordAttribute<Token![default], Expr>;
+pub type GcAttribute = KeywordAttribute<kw::gc, LitBool>;
 
 /// For specifying the path to the pyo3 crate.
 pub type CrateAttribute = KeywordAttribute<Token![crate], LitStrValue<Path>>;

pyo3-macros-backend/src/derive_attributes.rs

@@ -1,7 +1,7 @@
-use crate::attributes::{
-    self, get_pyo3_options, CrateAttribute, DefaultAttribute, FromPyWithAttribute,
-    IntoPyWithAttribute, RenameAllAttribute,
-};
+use crate::attributes::{
+    self, get_pyo3_options, CrateAttribute, DefaultAttribute, FromPyWithAttribute,
+    IntoPyWithAttribute, RenameAllAttribute,
+};
 use proc_macro2::Span;
 use syn::parse::{Parse, ParseStream};
 use syn::spanned::Spanned;
@@ -111,12 +111,12 @@ impl FieldGetter {
     }
 }
 
-pub enum FieldAttribute {
-    Getter(FieldGetter),
-    FromPyWith(FromPyWithAttribute),
-    IntoPyWith(IntoPyWithAttribute),
-    Default(DefaultAttribute),
-}
+pub enum FieldAttribute {
+    Getter(FieldGetter),
+    FromPyWith(FromPyWithAttribute),
+    IntoPyWith(IntoPyWithAttribute),
+    Default(DefaultAttribute),
+}
 
 impl Parse for FieldAttribute {
     fn parse(input: ParseStream<'_>) -> Result<Self> {
@@ -159,21 +159,21 @@ impl Parse for FieldAttribute {
             input.parse().map(Self::FromPyWith)
         } else if lookahead.peek(attributes::kw::into_py_with) {
             input.parse().map(FieldAttribute::IntoPyWith)
-        } else if lookahead.peek(Token![default]) {
-            input.parse().map(Self::Default)
-        } else {
-            Err(lookahead.error())
-        }
+        } else if lookahead.peek(Token![default]) {
+            input.parse().map(Self::Default)
+        } else {
+            Err(lookahead.error())
+        }
     }
 }
 
 #[derive(Clone, Debug, Default)]
-pub struct FieldAttributes {
-    pub getter: Option<FieldGetter>,
-    pub from_py_with: Option<FromPyWithAttribute>,
-    pub into_py_with: Option<IntoPyWithAttribute>,
-    pub default: Option<DefaultAttribute>,
-}
+pub struct FieldAttributes {
+    pub getter: Option<FieldGetter>,
+    pub from_py_with: Option<FromPyWithAttribute>,
+    pub into_py_with: Option<IntoPyWithAttribute>,
+    pub default: Option<DefaultAttribute>,
+}
 
 impl FieldAttributes {
     /// Extract the field attributes.
@@ -208,10 +208,10 @@ impl FieldAttributes {
             FieldAttribute::Getter(getter) => {
                 set_option!(getter, "only one of `attribute` or `item` can be provided")
             }
-            FieldAttribute::FromPyWith(from_py_with) => set_option!(from_py_with),
-            FieldAttribute::IntoPyWith(into_py_with) => set_option!(into_py_with),
-            FieldAttribute::Default(default) => set_option!(default),
-        }
-        Ok(())
-    }
-}
+            FieldAttribute::FromPyWith(from_py_with) => set_option!(from_py_with),
+            FieldAttribute::IntoPyWith(into_py_with) => set_option!(into_py_with),
+            FieldAttribute::Default(default) => set_option!(default),
+        }
+        Ok(())
+    }
+}

pyo3-macros-backend/src/lib.rs

@@ -23,6 +23,7 @@ mod params;
 mod py_expr;
 mod pyclass;
 mod pyfunction;
+mod pygcintegration;
 mod pyimpl;
 mod pymethod;
 mod quotes;
@@ -32,5 +33,6 @@ pub use intopyobject::build_derive_into_pyobject;
 pub use module::{pymodule_function_impl, pymodule_module_impl, PyModuleOptions};
 pub use pyclass::{build_py_class, build_py_enum, PyClassArgs};
 pub use pyfunction::{build_py_function, PyFunctionOptions};
+pub use pygcintegration::build_derive_py_gc_integration;
 pub use pyimpl::{build_py_methods, PyClassMethodsType};
 pub use utils::get_doc;