PySubclass

youknowone · Dec 14, 2025 · Dec 14, 2025 · Dec 5, 2025 · Dec 6, 2025 · Dec 14, 2025
commit e05cf537809d715464874cbea62929ecc95c5c5a
diff --git a/crates/derive-impl/src/pyclass.rs b/crates/derive-impl/src/pyclass.rs
@@ -350,6 +350,18 @@ fn generate_class_def(
                 false
             }
     });
+    // Check if the type has #[repr(transparent)] - only then we can safely
+    // generate PySubclass impl (requires same memory layout as base type)
+    let is_repr_transparent = attrs.iter().any(|attr| {
+        attr.path().is_ident("repr")
+            && if let Ok(Meta::List(l)) = attr.parse_meta() {
+                l.nested
+                    .into_iter()
+                    .any(|n| n.get_ident().is_some_and(|p| p == "transparent"))
+            } else {
+                false
+            }
+    });
     if base.is_some() && is_pystruct {
         bail_span!(ident, "PyStructSequence cannot have `base` class attr",);
     }
@@ -379,12 +391,40 @@ fn generate_class_def(
         }
     });
 
-    let base_or_object = if let Some(base) = base {
+    let base_or_object = if let Some(ref base) = base {
         quote! { #base }
     } else {
         quote! { ::rustpython_vm::builtins::PyBaseObject }
     };
 
+    // Generate PySubclass impl for #[repr(transparent)] types with base class
+    // (tuple struct assumed, so &self.0 works)
+    let subclass_impl = if !is_pystruct && is_repr_transparent {
+        base.as_ref().map(|typ| {
+            quote! {
+                impl ::rustpython_vm::class::PySubclass for #ident {
+                    type Base = #typ;
+
+                    #[inline]
+                    fn as_base(&self) -> &Self::Base {
+                        &self.0
+                    }
+                }
+            }
+        })
+    } else {
+        None
+    };
+
+    // Generate PySubclassTransparent marker for #[repr(transparent)] types
+    let transparent_impl = if !is_pystruct && is_repr_transparent && base.is_some() {
+        Some(quote! {
+            impl ::rustpython_vm::class::PySubclassTransparent for #ident {}
+        })
+    } else {
+        None
+    };
+
     let tokens = quote! {
         impl ::rustpython_vm::class::PyClassDef for #ident {
             const NAME: &'static str = #name;
@@ -409,6 +449,9 @@ fn generate_class_def(
 
             #base_class
         }
+
+        #subclass_impl
+        #transparent_impl
     };
     Ok(tokens)
 }
@@ -430,7 +473,7 @@ pub(crate) fn impl_pyclass(attr: PunctuatedNestedMeta, item: Item) -> Result<Tok
         ident,
         &class_name,
         module_name.as_deref(),
-        base,
+        base.clone(),
         metaclass,
         unhashable,
         attrs,
@@ -485,19 +528,46 @@ pub(crate) fn impl_pyclass(attr: PunctuatedNestedMeta, item: Item) -> Result<Tok
         }
     };
 
-    let impl_payload = if let Some(ctx_type_name) = class_meta.ctx_name()? {
-        let ctx_type_ident = Ident::new(&ctx_type_name, ident.span()); // FIXME span
+    // Generate PyPayload impl based on whether base exists
+    #[allow(clippy::collapsible_else_if)]
+    let impl_payload = if let Some(base_type) = &base {
+        let class_fn = if let Some(ctx_type_name) = class_meta.ctx_name()? {
+            let ctx_type_ident = Ident::new(&ctx_type_name, ident.span());
+            quote! { ctx.types.#ctx_type_ident }
+        } else {
+            quote! { <Self as ::rustpython_vm::class::StaticType>::static_type() }
+        };
 
-        // We need this to make extend mechanism work:
         quote! {
             impl ::rustpython_vm::PyPayload for #ident {
+                #[inline]
+                fn payload_type_id() -> ::std::any::TypeId {
+                    <#base_type as ::rustpython_vm::PyPayload>::payload_type_id()
+                }
+
+                #[inline]
+                fn validate_downcastable_from(obj: &::rustpython_vm::PyObject) -> bool {
+                    <Self as ::rustpython_vm::class::PyClassDef>::BASICSIZE <= obj.class().slots.basicsize && obj.class().fast_issubclass(<Self as ::rustpython_vm::class::StaticType>::static_type())
+                }
+
                 fn class(ctx: &::rustpython_vm::vm::Context) -> &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType> {
-                    ctx.types.#ctx_type_ident
+                    #class_fn
                 }
             }
         }
     } else {
-        quote! {}
+        if let Some(ctx_type_name) = class_meta.ctx_name()? {
+            let ctx_type_ident = Ident::new(&ctx_type_name, ident.span());
+            quote! {
+                impl ::rustpython_vm::PyPayload for #ident {
+                    fn class(ctx: &::rustpython_vm::vm::Context) -> &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType> {
+                        ctx.types.#ctx_type_ident
+                    }
+                }
+            }
+        } else {
+            quote! {}
+        }
     };
 
     let empty_impl = if let Some(attrs) = class_meta.impl_attrs()? {
@@ -536,26 +606,6 @@ pub(crate) fn impl_pyexception(attr: PunctuatedNestedMeta, item: Item) -> Result
     let class_name = class_meta.class_name()?;
 
     let base_class_name = class_meta.base()?;
-    let impl_payload = if let Some(ctx_type_name) = class_meta.ctx_name()? {
-        let ctx_type_ident = Ident::new(&ctx_type_name, ident.span()); // FIXME span
-
-        // We need this to make extend mechanism work:
-        quote! {
-            impl ::rustpython_vm::PyPayload for #ident {
-                fn class(ctx: &::rustpython_vm::vm::Context) -> &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType> {
-                    ctx.exceptions.#ctx_type_ident
-                }
-            }
-        }
-    } else {
-        quote! {
-            impl ::rustpython_vm::PyPayload for #ident {
-                fn class(_ctx: &::rustpython_vm::vm::Context) -> &'static ::rustpython_vm::Py<::rustpython_vm::builtins::PyType> {
-                    <Self as ::rustpython_vm::class::StaticType>::static_type()
-                }
-            }
-        }
-    };
     let impl_pyclass = if class_meta.has_impl()? {
         quote! {
             #[pyexception]
@@ -568,7 +618,6 @@ pub(crate) fn impl_pyexception(attr: PunctuatedNestedMeta, item: Item) -> Result
     let ret = quote! {
         #[pyclass(module = false, name = #class_name, base = #base_class_name)]
         #item
-        #impl_payload
         #impl_pyclass
     };
     Ok(ret)

diff --git a/crates/vm/src/builtins/bool.rs b/crates/vm/src/builtins/bool.rs
@@ -1,8 +1,7 @@
 use super::{PyInt, PyStrRef, PyType, PyTypeRef};
 use crate::common::format::FormatSpec;
 use crate::{
-    AsObject, Context, Py, PyObject, PyObjectRef, PyPayload, PyResult, TryFromBorrowedObject,
-    VirtualMachine,
+    AsObject, Context, Py, PyObject, PyObjectRef, PyResult, TryFromBorrowedObject, VirtualMachine,
     class::PyClassImpl,
     convert::{IntoPyException, ToPyObject, ToPyResult},
     function::{FuncArgs, OptionalArg},
@@ -81,15 +80,9 @@ impl PyObjectRef {
     }
 }
 
-#[pyclass(name = "bool", module = false, base = PyInt)]
-pub struct PyBool;
-
-impl PyPayload for PyBool {
-    #[inline]
-    fn class(ctx: &Context) -> &'static Py<PyType> {
-        ctx.types.bool_type
-    }
-}
+#[pyclass(name = "bool", module = false, base = PyInt, ctx = "bool_type")]
+#[repr(transparent)]
+pub struct PyBool(pub PyInt);
 
 impl Debug for PyBool {
     fn fmt(&self, _f: &mut Formatter<'_>) -> std::fmt::Result {

diff --git a/crates/vm/src/class.rs b/crates/vm/src/class.rs
@@ -171,3 +171,31 @@ pub trait PyClassImpl: PyClassDef {
         slots
     }
 }
+
+/// Trait for Python subclasses that can provide a reference to their base type.
+///
+/// This trait is automatically implemented by the `#[pyclass]` macro when
+/// `base = SomeType` is specified. It provides safe reference access to the
+/// base type's payload.
+///
+/// For subclasses with `#[repr(transparent)]`, see also [`PySubclassTransparent`]
+/// which enables ownership transfer via `into_base()`.
+pub trait PySubclass: crate::PyPayload {
+    type Base: crate::PyPayload;
+
+    /// Returns a reference to the base type's payload.
+    fn as_base(&self) -> &Self::Base;
+}
+
+/// Marker trait for `#[repr(transparent)]` subclasses.
+///
+/// This trait enables ownership transfer from `PyRef<Self>` to `PyRef<Self::Base>`
+/// via the `into_base_ref()` method. Only types with identical memory layout to their
+/// base type (i.e., `#[repr(transparent)]` newtypes) should implement this trait.
+///
+/// # Safety
+///
+/// Implementors must ensure:
+/// - The type uses `#[repr(transparent)]` with the Base type as the only field
+/// - Memory layout is identical to the Base type
+pub trait PySubclassTransparent: PySubclass {}
diff --git a/crates/vm/src/object/core.rs b/crates/vm/src/object/core.rs
@@ -1070,6 +1070,19 @@ impl<T: PyPayload + std::fmt::Debug> PyRef<T> {
     }
 }
 
+impl<T: crate::class::PySubclassTransparent + std::fmt::Debug> PyRef<T>
+where
+    T::Base: std::fmt::Debug,
+{
+    /// Converts this reference to the base type (ownership transfer).
+    /// Only available for `#[repr(transparent)]` types.
+    #[inline]
+    pub fn into_base_ref(self) -> PyRef<T::Base> {
+        // SAFETY: #[repr(transparent)] guarantees same memory layout
+        unsafe { std::mem::transmute(self) }
+    }
+}
-impl<T: crate::class::PySubclass + std::fmt::Debug> PyRef<T>
-where
-    T::Base: std::fmt::Debug,
-{
-    /// Converts this reference to the base type (ownership transfer).
-    /// # Safety
-    /// T and T::Base must have compatible layouts in size_of::<T::Base>() bytes.
-    #[inline]
-    pub fn into_base(self) -> PyRef<T::Base> {
-        let obj: PyObjectRef = self.into();
-        match obj.downcast() {
-            Ok(base_ref) => base_ref,
-            Err(_) => unsafe { std::hint::unreachable_unchecked() },
-        }
-    }
-    #[inline]
-    pub fn upcast<U: PyPayload + StaticType>(self) -> PyRef<U>
-    where
-        T: StaticType,
-    {
-        debug_assert!(T::static_type().is_subtype(U::static_type()));
-        let obj: PyObjectRef = self.into();
-        match obj.downcast::<U>() {
-            Ok(upcast_ref) => upcast_ref,
-            Err(_) => unsafe { std::hint::unreachable_unchecked() },
-        }
-    }
-}
+impl<T: crate::class::PySubclass + std::fmt::Debug> PyRef<T>
+where
+    T::Base: std::fmt::Debug,
+{
+    /// Converts this reference to the base type (ownership transfer).
+    /// # Safety
+    /// T and T::Base must have compatible layouts in size_of::<T::Base>() bytes.
+    #[inline]
+    pub fn into_base(self) -> PyRef<T::Base> {
+        let obj: PyObjectRef = self.into();
+        match obj.downcast() {
+            Ok(base_ref) => base_ref,
+            Err(_) => unreachable!("PySubclass invariant violated: into_base downcast failed"),
+        }
+    }
+    #[inline]
+    pub fn upcast<U: PyPayload + StaticType>(self) -> PyRef<U>
+    where
+        T: StaticType,
+    {
+        debug_assert!(T::static_type().is_subtype(U::static_type()));
+        let obj: PyObjectRef = self.into();
+        match obj.downcast::<U>() {
+            Ok(upcast_ref) => upcast_ref,
+            Err(_) => unreachable!("PySubclass invariant violated: upcast to {} failed", std::any::type_name::<U>()),
+        }
+    }
+}
-impl<T: crate::class::PySubclass + std::fmt::Debug> PyRef<T>
-where
-    T::Base: std::fmt::Debug,
-{
-    /// Converts this reference to the base type (ownership transfer).
-    /// # Safety
-    /// T and T::Base must have compatible layouts in size_of::<T::Base>() bytes.
-    #[inline]
-    pub fn into_base(self) -> PyRef<T::Base> {
-        let obj: PyObjectRef = self.into();
-        match obj.downcast() {
-            Ok(base_ref) => base_ref,
-            Err(_) => unsafe { std::hint::unreachable_unchecked() },
-        }
-    }
-    #[inline]
-    pub fn upcast<U: PyPayload + StaticType>(self) -> PyRef<U>
-    where
-        T: StaticType,
-    {
-        debug_assert!(T::static_type().is_subtype(U::static_type()));
-        let obj: PyObjectRef = self.into();
-        match obj.downcast::<U>() {
-            Ok(upcast_ref) => upcast_ref,
-            Err(_) => unsafe { std::hint::unreachable_unchecked() },
-        }
-    }
-}
+impl<T: crate::class::PySubclass + std::fmt::Debug> PyRef<T>
+where
+    T::Base: std::fmt::Debug,
+{
+    /// Converts this reference to the base type (ownership transfer).
+    /// # Safety
+    /// T and T::Base must have compatible layouts in size_of::<T::Base>() bytes.
+    #[inline]
+    pub fn into_base(self) -> PyRef<T::Base> {
+        let obj: PyObjectRef = self.into();
+        match obj.downcast() {
+            Ok(base_ref) => base_ref,
+            Err(_) => unreachable!("PySubclass invariant violated: into_base downcast failed"),
+        }
+    }
+    #[inline]
+    pub fn upcast<U: PyPayload + StaticType>(self) -> PyRef<U>
+    where
+        T: StaticType,
+    {
+        debug_assert!(T::static_type().is_subtype(U::static_type()));
+        let obj: PyObjectRef = self.into();
+        match obj.downcast::<U>() {
+            Ok(upcast_ref) => upcast_ref,
+            Err(_) => unreachable!("PySubclass invariant violated: upcast to {} failed", std::any::type_name::<U>()),
+        }
+    }
+}
+
 impl<T> Borrow<PyObject> for PyRef<T>
 where
     T: PyPayload,

diff --git a/crates/vm/src/object/payload.rs b/crates/vm/src/object/payload.rs
@@ -16,6 +16,15 @@ cfg_if::cfg_if! {
     }
 }
 
+#[cold]
+pub(crate) fn cold_downcast_type_error(
+    vm: &VirtualMachine,
+    class: &Py<PyType>,
+    obj: &PyObject,
+) -> PyBaseExceptionRef {
+    vm.new_downcast_type_error(class, obj)
+}
+
 pub trait PyPayload: MaybeTraverse + PyThreadingConstraint + Sized + 'static {
     #[inline]
     fn payload_type_id() -> std::any::TypeId {
@@ -38,17 +47,8 @@ pub trait PyPayload: MaybeTraverse + PyThreadingConstraint + Sized + 'static {
             return Ok(());
         }
 
-        #[cold]
-        fn raise_downcast_type_error(
-            vm: &VirtualMachine,
-            class: &Py<PyType>,
-            obj: &PyObject,
-        ) -> PyBaseExceptionRef {
-            vm.new_downcast_type_error(class, obj)
-        }
-
         let class = Self::class(&vm.ctx);
-        Err(raise_downcast_type_error(vm, class, obj))
+        Err(cold_downcast_type_error(vm, class, obj))
     }
 
     fn class(ctx: &Context) -> &'static Py<PyType>;

diff --git a/crates/vm/src/stdlib/ctypes/array.rs b/crates/vm/src/stdlib/ctypes/array.rs
@@ -23,7 +23,7 @@ use rustpython_vm::stdlib::ctypes::base::PyCData;
 /// PyCArrayType - metatype for Array types
 /// CPython stores array info (type, length) in StgInfo via type_data
 #[pyclass(name = "PyCArrayType", base = PyType, module = "_ctypes")]
-#[derive(Debug, Default, PyPayload)]
+#[derive(Debug, Default)]
 pub struct PyCArrayType {}
 
 /// Create a new Array type with StgInfo stored in type_data (CPython style)
@@ -235,7 +235,6 @@ impl AsNumber for PyCArrayType {
     metaclass = "PyCArrayType",
     module = "_ctypes"
 )]
-#[derive(PyPayload)]
 pub struct PyCArray {
     /// Element type - can be a simple type (c_int) or an array type (c_int * 5)
     pub(super) typ: PyRwLock<PyObjectRef>,

diff --git a/crates/vm/src/stdlib/ctypes/base.rs b/crates/vm/src/stdlib/ctypes/base.rs
@@ -228,7 +228,7 @@ impl PyCData {
 }
 
 #[pyclass(module = "_ctypes", name = "PyCSimpleType", base = PyType)]
-#[derive(Debug, PyPayload, Default)]
+#[derive(Debug, Default)]
 pub struct PyCSimpleType {}
 
 #[pyclass(flags(BASETYPE), with(AsNumber))]
@@ -411,7 +411,6 @@ impl AsNumber for PyCSimpleType {
     base = PyCData,
     metaclass = "PyCSimpleType"
 )]
-#[derive(PyPayload)]
 pub struct PyCSimple {
     pub _type_: String,
     pub value: AtomicCell<PyObjectRef>,

diff --git a/crates/vm/src/stdlib/ctypes/field.rs b/crates/vm/src/stdlib/ctypes/field.rs
@@ -8,7 +8,7 @@ use super::structure::PyCStructure;
 use super::union::PyCUnion;
 
 #[pyclass(name = "PyCFieldType", base = PyType, module = "_ctypes")]
-#[derive(PyPayload, Debug)]
+#[derive(Debug)]
 pub struct PyCFieldType {
     #[allow(dead_code)]
     pub(super) inner: PyCField,

diff --git a/crates/vm/src/stdlib/ctypes/function.rs b/crates/vm/src/stdlib/ctypes/function.rs
@@ -162,7 +162,6 @@ impl ReturnType for PyNone {
 }
 
 #[pyclass(module = "_ctypes", name = "CFuncPtr", base = PyCData)]
-#[derive(PyPayload)]
 pub struct PyCFuncPtr {
     pub name: PyRwLock<Option<String>>,
     pub ptr: PyRwLock<Option<CodePtr>>,

diff --git a/crates/vm/src/stdlib/ctypes/pointer.rs b/crates/vm/src/stdlib/ctypes/pointer.rs
@@ -9,7 +9,7 @@ use crate::types::{AsNumber, Constructor};
 use crate::{AsObject, Py, PyObjectRef, PyPayload, PyResult, VirtualMachine};
 
 #[pyclass(name = "PyCPointerType", base = PyType, module = "_ctypes")]
-#[derive(PyPayload, Debug, Default)]
+#[derive(Debug, Default)]
 pub struct PyCPointerType {}
 
 #[pyclass(flags(IMMUTABLETYPE), with(AsNumber))]
@@ -60,7 +60,7 @@ impl AsNumber for PyCPointerType {
     metaclass = "PyCPointerType",
     module = "_ctypes"
 )]
-#[derive(Debug, PyPayload)]
+#[derive(Debug)]
 pub struct PyCPointer {
     contents: PyRwLock<PyObjectRef>,
 }

diff --git a/crates/vm/src/stdlib/ctypes/structure.rs b/crates/vm/src/stdlib/ctypes/structure.rs
@@ -15,7 +15,7 @@ use std::fmt::Debug;
 
 /// PyCStructType - metaclass for Structure
 #[pyclass(name = "PyCStructType", base = PyType, module = "_ctypes")]
-#[derive(Debug, PyPayload, Default)]
+#[derive(Debug, Default)]
 pub struct PyCStructType {}
 
 impl Constructor for PyCStructType {
@@ -218,7 +218,6 @@ pub struct FieldInfo {
     base = PyCData,
     metaclass = "PyCStructType"
 )]
-#[derive(PyPayload)]
 pub struct PyCStructure {
     /// Common CDataObject for memory buffer
     pub(super) cdata: PyRwLock<CDataObject>,

diff --git a/crates/vm/src/stdlib/ctypes/union.rs b/crates/vm/src/stdlib/ctypes/union.rs
@@ -13,7 +13,7 @@ use rustpython_common::lock::PyRwLock;
 
 /// PyCUnionType - metaclass for Union
 #[pyclass(name = "UnionType", base = PyType, module = "_ctypes")]
-#[derive(Debug, PyPayload, Default)]
+#[derive(Debug, Default)]
 pub struct PyCUnionType {}
 
 impl Constructor for PyCUnionType {
@@ -121,7 +121,6 @@ impl PyCUnionType {}
 
 /// PyCUnion - base class for Union
 #[pyclass(module = "_ctypes", name = "Union", base = PyCData, metaclass = "PyCUnionType")]
-#[derive(PyPayload)]
 pub struct PyCUnion {
     /// Common CDataObject for memory buffer
     pub(super) cdata: PyRwLock<CDataObject>,