@@ -173,17 +173,30 @@ pub trait PyClassImpl: PyClassDef {
173173 }
174174}
175175
176- /// Marker trait for Python subclasses with `#[repr(transparent)]` newtype pattern .
176+ /// Trait for Python subclasses that can provide a reference to their base type .
177177///
178178/// This trait is automatically implemented by the `#[pyclass]` macro when
179- /// `base = SomeType` is specified. It enables type-safe conversion between
180- /// `PyRef<Subclass>` and `PyRef<Base>`.
179+ /// `base = SomeType` is specified. It provides safe reference access to the
180+ /// base type's payload.
181+ ///
182+ /// For subclasses with `#[repr(transparent)]`, see also [`PySubclassTransparent`]
183+ /// which enables ownership transfer via `into_base()`.
184+ pub trait PySubclass : crate :: PyPayload {
185+ type Base : crate :: PyPayload ;
186+
187+ /// Returns a reference to the base type's payload.
188+ fn as_base ( & self ) -> & Self :: Base ;
189+ }
190+
191+ /// Marker trait for `#[repr(transparent)]` subclasses.
192+ ///
193+ /// This trait enables ownership transfer from `PyRef<Self>` to `PyRef<Self::Base>`
194+ /// via the `into_base_ref()` method. Only types with identical memory layout to their
195+ /// base type (i.e., `#[repr(transparent)]` newtypes) should implement this trait.
181196///
182197/// # Safety
183198///
184199/// Implementors must ensure:
185200/// - The type uses `#[repr(transparent)]` with the Base type as the only field
186201/// - Memory layout is identical to the Base type
187- pub trait PySubclass : crate :: PyPayload {
188- type Base : crate :: PyPayload ;
189- }
202+ pub trait PySubclassTransparent : PySubclass { }
0 commit comments