Opaque Object Layout #4678

mbway · 2024-11-02T22:40:46Z

This PR introduces the capability to inherit from classes where the exact layout/size is not known using the mechanism described in PEP 697. This allows inheriting from type in order to create metaclasses. These metaclasses cannot yet be used with pyo3 classes (i.e. #[pyclass(metaclass=Foo)]) but this should be a possibility in future. It may also be possible in future for pyo3 classes to extend builtin classes using the limited API and to potentially extend imported classes (eg enum.EnumType).

This PR supersedes my first attempt at creating metaclasses: #4621. Previously I was using the normal class layout which relies on the exact layout of every base class to be known. For type the base structure is ffi::PyHeapTypeObject. The contents of this structure are intended to be private (even for the 'unlimited' API) and so an alternative mechanism is required (PEP 697).

Instead of nesting each base class at the beginning of the derived class in memory, objects created with PEP 697 only require knowledge of how much additional memory the derived class requires and the address of this section of memory is accessed via PyObject_GetTypeData. The PEP 697 mechanism could potentially be used to inherit from other builtins when only the 'limited' API is available however many of these builtins also store items (eg list, set) which introduces more complications, so this PR focuses on inheriting from PyType only.

This PR is a proof of concept but I am sure that some of the decisions I made aren't the best so feedback is welcome. The current design is as follows:

Before this PR the only possible layout was the 'static' layout where the size of the base class is known. This layout was described by PyClassObject<T> (now renamed to PyStaticClassObject). This PR introduces hides the details of the static layout behind a trait InternalPyClassObjectLayout so that other layouts are possible.

Before this PR: PyClassObject<T> was used to obtain the exact layout of T: PyClassImpl assuming that layout is the 'static' layout. This PR introduces PyClassImpl::Layout so that a pyclass declares its layout. The pyclass uses PyTypeInfo::Layout to set T::Layout. Each base type declares either PyTypeInfo::Layout = PyStaticClassObject or PyTypeInfo::Layout = PyVariableClassObject.

Potential Improvements

Some questions still remain:

how best to handle initialisation (see below)
- using the __init__ approach, how to initialise super classes?
- using the __init__ approach, how to restrict return value to () or PyResult<()>?
how to handle subclassing variable sized pyclasses
- I tried writing some unit tests that inherited from type -> MyMetaclass -> MySubMetaclass but I think there are some outstanding problems. I also am not sure how to prevent users from doing this so I have left it for now.
  - problems encountered: setattr works without using #[pyclass(dict)] but the set values aren't accessible in the subclass
  - values are not as expected after initialisation, perhaps only the subclass data is getting initialised?
for some reason using setattr on a class extending type does not fail, unlike on a class extending object. I'm not sure if this means type has __dict__ already?

Initialisation

I'm not sure what the best way is to handle initialisation. tp_new cannot be used with metaclasses (source) however the best semantics of __init__ aren't clear. For now I am requiring that metaclasses implement Default which allows the struct to be initialised before __init__ is called (but this is a hack and may have issues properly initialising superclasses). There are runtime checks when a class is constructed that metaclasses do not define #[new] and do define __init__. This should be sufficient to ensure that users cannot create a struct with uninitialized memory.

An alternative to using __init__ could be to repurpose #[new] to wrap it and assign it to tp_init instead in the case of a metaclass but that would be more complex to implement.

This allows for variable sized base classes in future by using negative basicsize values.

Variable sized base classes require the use of relative offsets

…yout

Metaclasses cannot define `__new__` so `__init__` is the only alternative.

mbway · 2024-11-03T12:24:47Z

I didn't realise I was going to hit the issue that the minimum supported rust version of pyo3 (1.63) doesn't support generic associated types which I'm using for type Layout<T: PyClassImpl>: InternalPyClassObjectLayout<T>;.

Rust 1.65 (the first with GAT support) was released on 2022-11-03 and python 3.12 (the first version to allow extending variable sized base classes) was released on 2023-10-02.

I'm going to bump the MSRV to 1.65 but I'm open to other suggestions that avoid requiring GATs. I checked the MSRV requirements according to Contributing.md and from what I can see Debian stable ships 1.63 so this is going to be a problem.

Debian bookworm is supported until June 2026 which seems like a long time to wait...

mejrs · 2024-11-03T18:27:34Z

I'm going to bump the MSRV to 1.65

You can't do that unfortunately. Our msrv policy is at https://github.com/PyO3/pyo3/blob/main/Contributing.md#python-and-rust-version-support-policy

What you can do is to feature gate this and only enable the functionality on Rust 1.65 and up, or figure out a way to do it without gats.

mbway · 2024-11-03T18:35:07Z

What you can do is to feature gate this and only enable the functionality on Rust 1.65 and up

That sounds good to me. Do you mean introduce a feature like variable_base_types that has a different MSRV? How would I go about doing that?

Would it be sufficient to introduce the feature and have it disabled by default?

mejrs · 2024-11-03T19:02:24Z

A feature is one way to do it, a cfg that is automatically enabled when the build script detects it's on rust 1.65+ is another method. Both have pros and cons as far as user experience goes, so it's best to have a solution that doesn't need them. The layout code is also reasonably complex, so I'd rather not mix conditional compilation into it if possible.

mbway · 2024-11-03T20:33:01Z

The design currently revolves around the #[pyclass] macro being able to fill out the Layout entry like so

type Layout = <#cls as #pyo3_path::PyTypeInfo>::Layout<Self>;

This way the layout is set generically in the base types like PyAny and PyType and inherited from there.

The ways I can currently see around this are:

continue using GAT and feature gate the functionality
- when disabled, hard code to the static layout and catch any discrepancy at construction? Better designs are probably possible but this would be simple to implement.
use a mechanism like PyClass::Frozen and instead of T::Layout have PyClassLayout<T> be a single struct containing the functionality that selects between implementations at runtime by observing T::VariableSized::VALUE. This of course has some runtime overhead.
use some trait magic to have a marker trait like IsStaticType that is inherited from the base type and again there is a single PyClassLayout<T> that implements the functionality but the functionality is selected at compile time using the marker traits. Unfortunately I'm not sure how to achieve this. Below is my attempt
- related to this approach, have a single marker IsVariableType and an implementation with and without this marker. Unfortunately this requires specialisation which isn't stable yet

I'm going to implement (1) for now because the steps seem clearest, so this PR can be in a state where it could hypothetically be merged, then I'm open to suggestions if someone finds a way around the limitations I'm running into.

Attempt 1

The problem here is that the static and variable markers aren't known to be disjoint, so they conflict.

trait IsStaticType {}
trait IsVariableType {}

struct PyAny;
impl IsStaticType for PyAny {}
struct PyType;
impl IsVariableType for PyType {}

struct Layout<T> { _data: PhantomData<T> }

trait LayoutMethods {
    fn access_data();
}

impl<T: IsStaticType> LayoutMethods for Layout<T> {
    fn access_data() {
        println!("hi from static");
    }
}

impl<T: IsVariableType> LayoutMethods for Layout<T> {  // ERROR: conflicting implementations
    fn access_data() {
        println!("hi from variable");
    }
}

Attempt 2

The problem here is that <MyClass as LayoutMethods>::access_data() panics, and while <MyClass as StaticLayout>::access_data() compiles and <MyClass as VariableLayout>::access_data() does not, it doesn't solve the problem of being able to use the layout without specifying which it is.

trait LayoutMethods {
    fn access_data() {
        panic!("unknown layout")
    }
}

impl<T: PyClassImpl> LayoutMethods for T {}

trait StaticLayout: Sized + 'static + LayoutMethods {
    fn access_data() {
        println!("hi from static");
    }
}
impl<T, B> StaticLayout for T
where
    T: PyClassImpl<BaseType = B> + 'static,
    B: StaticLayout,
{ }

trait VariableLayout: Sized + 'static + LayoutMethods {
    fn access_data() {
        println!("hi from variable");
    }
}
impl<T, B> VariableLayout for T
where
    T: PyClassImpl<BaseType = B> + 'static,
    B: VariableLayout,
{ }

trait PyClassImpl { type BaseType; }

struct PyAny;
impl LayoutMethods for PyAny {}
impl StaticLayout for PyAny {}

struct PyType;
impl LayoutMethods for PyType {}
impl VariableLayout for PyType {}

struct MyClass {}
impl PyClassImpl for MyClass {
    type BaseType = PyAny;
}

Before this change, classes inheriting the base object was a special case where `object.__new__` is not called, and inheriting from other base classes requires use of the unlimited API. Previously this was not very limiting, but with <PyO3#4678> it will be possible to inherit from native base classes with the limited API and possibly from dynamically imported native base classes which may require `__new__` arguments to reach them.

mbway · 2025-02-18T10:32:55Z

Hi @davidhewitt , just wondering if anyone has capacity to start looking at these changes, starting with #4798 . I see the project has been quiet since January so there aren't many conflicts yet. I can start breaking this PR into smaller ones if you are happy with the overall approach.

I'm also happy to answer any questions if something isn't clear :)

davidhewitt · 2025-02-19T10:39:07Z

My sincerest apologies for the delay, I have had a massive backlog build up due to family commitments. I have new childcare support starting from March (so just a couple weeks away now) and the intention is to work long days Fridays to burn the backlog down.

I'll aim to get to this on either the first or second Friday on March (please do ping me to remind, the backlog is long!)

mejrs

This is by no means an exhaustive review but these jumped out to me initially.

pyo3-macros-backend/src/pyclass.rs

src/impl_/pyclass.rs

src/pycell.rs

mejrs · 2025-02-20T12:14:53Z

src/pycell/layout.rs

+    #[repr(C)]
+    pub struct InvalidStaticLayout;
+
+    /// This is valid insofar as casting a `*mut ffi::PyObject` to `*mut InvalidStaticLayout` is valid
+    /// since `InvalidStaticLayout` has no fields to read.
+    unsafe impl<T> PyLayout<T> for InvalidStaticLayout {}


Is this just from stopping people from not declaring an opaque layout when inheriting from PyType? It appears to me like it would be better to have another trait for this.

yes. When defining a PyClassBaseType implementation for a type, a value for StaticLayout is required. For types where a static layout is not possible (such as PyType) this value can be provided which panics if it is actually used with the static layout accessors. I have added PyStaticLayout::IS_VALID to make this clearer.

Can you elaborate on the alternative you have in mind?

mejrs · 2025-04-13T21:30:50Z

Apologies for the pings, but this is one of the things I'd like to see progress on :)

@mbway are you available to address the feedback and/or resolve the merge conflicts?

@davidhewitt Can you do that review?

mbway · 2025-04-14T10:15:30Z

I can try to find some time to bring things up to date. Since everyone seems on board with having the feature I can start breaking this big PR down as I expect you don't want to merge it all in one go?

The first part is #4798

mbway · 2025-04-14T22:38:00Z

I have brought this PR and #4798 up to date and addressed the comments. There are CI failures though so more work is needed, but they should be in a better state to review.

mbway · 2025-04-18T14:34:42Z

both PRs should be ready for review now. All tests are passing, only the code coverage is still failing. That will be very tricky to overcome I think.

mbway · 2025-08-20T15:41:47Z

@davidhewitt is your backlog looking any better now? If you plan to review you can ping me whenever so I can bring everything up to date (can't guarantee a quick response but I'll make sure to do it)

davidhewitt · 2025-08-20T18:43:47Z

Yes, I am moving through reviews much faster now. Sorry I missed that this was in a condition where it was waiting for me 🙈

Which PR would you like me to start with? Given the scale of the conflicts, it might make sense for me to give this a first pass before you invest time into fixing up.

mbway · 2025-08-20T18:51:21Z

#4798 is still a good place to start I think as it's much smaller and self-contained. Feel free to take a look at this PR as well if you want, I think that would be useful, but I think it's probably best to break it up further to get it merged. I didn't want to break off the next part until #4798 is in. Also #4951 (not mine) would be useful because I added basic __init__ support in this PR (required for defining metaclasses) but it's just a proof of concept as it's quite limited.

davidhewitt

Thanks for this (massive) PR, and sorry I've taken so long to come around to reading it.

Assuming there is no significant performance cost, I might be tempted to fully move towards using the opaque layout on 3.12 for simplicity. Otherwise I guess we just do it for types inheriting from bases of unknown size. Given your code here already made it optional, maybe there's no point to have the "simpler" option.

I think this PR probably can be split in three:

__init__ support (possibly to be replaced by #4951 as you noted)
opaque layout
support for inheriting from type and the metaclass documentation

... maybe let's start by converging on a design for __init__ which meets all the use cases, and then we can circle back here?

davidhewitt · 2025-09-21T19:07:42Z

guide/src/class/protocols.md

+  - `__init__(<self>, ...) -> ()` - the arguments can be defined as for
+    normal `pymethods`. The pyclass struct must implement `Default`.
+    If the class defines `__new__` and `__init__` the values set in
+    `__new__` are overridden by `Default` before `__init__` is called.


Hmm the fact that __new__ gets overwritten seems unfortunate. I will have a think what alternatives we have here (e.g. friendly compile error etc.)

davidhewitt · 2025-09-21T19:10:49Z

guide/pyclass-parameters.md

 | `subclass` | Allows other Python classes and `#[pyclass]` to inherit from this class. Enums cannot be subclassed. |
 | `unsendable` | Required if your struct is not [`Send`][params-3]. Rather than using `unsendable`, consider implementing your struct in a thread-safe way by e.g. substituting [`Rc`][params-4] with [`Arc`][params-5]. By using `unsendable`, your class will panic when accessed by another thread. Also note the Python's GC is multi-threaded and while unsendable classes will not be traversed on foreign threads to avoid UB, this can lead to memory leaks. |
 | `weakref` | Allows this class to be [weakly referenceable][params-6]. |
+| `opaque` | Forces the use of the 'opaque layout' ([PEP 697](https://peps.python.org/pep-0697/)) for this class and any subclasses that extend it. Primarily used for internal testing. |


I wonder if we should consider always using this on 3.12+, rather than having it as an option? (Might depend on the performance cost of doing so.)

I think it might require us to use managed dict & weakref on 3.12+ so that we don't know the exact object layout. The benefit is it might clean up a lot of PyO3's coupling to Python internals. I may try do that in the coming days.

davidhewitt · 2025-09-21T19:22:31Z

src/types/mod.rs

+/// Implement methods for obtaining the type object associated with a native type.
+/// These methods are referred to in `pyobject_native_type_info` for implementing `PyTypeInfo`.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! pyobject_native_type_object_methods {


I might need explaining as to the rationale of this bit.

davidhewitt · 2025-11-18T13:15:46Z

It looks like #4951 is set to merge, which might unblock this PR moving forward.

mbway · 2025-11-18T13:23:51Z

Thanks. I've been keeping an eye on it. I should have some time soon to revive these PRs

mbway added 16 commits November 2, 2024 16:14

Provide basicsize from PyClassObject instead of directly using size_of

8942b70

This allows for variable sized base classes in future by using negative basicsize values.

Hide PyClassObject details incompatible with variable sizing.

dda77a8

specify absolute or relative offsets.

b59fe48

Variable sized base classes require the use of relative offsets

use trait for accessing object layout

d9bb2e8

classes specify their structure rather than hard coding the static la…

54fb8a9

…yout

types specify their layouts

043b2aa

variable size class layout using PEP-697

e598701

allow definition of __init__ methods

8395b8d

Metaclasses cannot define `__new__` so `__init__` is the only alternative.

add metaclass example to the guide

4837953

make class initialization not dependent on the static layout

2132c27

handle deallocation for variable layout

5f14dd9

populate using Default before init to avoid data being uninitialized

71e6198

finish implementation of Offset handling

37f8509

small fixes and tidying

78b2f9b

add news fragment

eac629e

small fix to guide

d0961fe

mbway marked this pull request as draft November 2, 2024 23:01

fix some tests and linting errors

5499d10

mbway force-pushed the variable_sized_base_types branch from 4ce2db0 to 401af6c Compare November 3, 2024 15:52

add instructions to Contributing.md

ccce96d

mbway force-pushed the variable_sized_base_types branch 2 times, most recently from 7820766 to de2c2a3 Compare November 3, 2024 17:28

wrap PyClassObjectContents to prevent it from leaking outside pyo3

426b218

mbway force-pushed the variable_sized_base_types branch from de2c2a3 to 426b218 Compare November 3, 2024 17:29

improved docs

0d08681

mejrs reviewed Feb 20, 2025

View reviewed changes

mbway mentioned this pull request Apr 6, 2025

Extend PyType to create metaclasses #4621

Closed

mbway added 4 commits April 14, 2025 22:45

address comments

290776d

Merge branch 'main' into variable_sized_base_types

8fcd5b0

fix uses of unsafe

34afe2d

formatting

370fa76

mbway force-pushed the variable_sized_base_types branch 4 times, most recently from 593cff8 to 14513d6 Compare April 18, 2025 12:57

fixes

61bc306

mbway force-pushed the variable_sized_base_types branch from 14513d6 to 61bc306 Compare April 18, 2025 13:32

mbway mentioned this pull request Apr 20, 2025

Implement #[init] method attribute in #[pymethods] #4951

Merged

davidhewitt removed this from the 0.24 milestone Jul 25, 2025

davidhewitt reviewed Sep 21, 2025

View reviewed changes

davidhewitt mentioned this pull request Nov 28, 2025

fix FFI definition of PyDictObject on PyPy #5653

Merged

This was referenced Dec 12, 2025

Using PyList as a baseclass #5164

Open

implement exception introspection #5666

Closed

Opaque Object Layout #4678

Are you sure you want to change the base?

Opaque Object Layout #4678

Uh oh!

Conversation

mbway commented Nov 2, 2024

Potential Improvements

Initialisation

Uh oh!

mbway commented Nov 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mejrs commented Nov 3, 2024

Uh oh!

mbway commented Nov 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mejrs commented Nov 3, 2024

Uh oh!

mbway commented Nov 3, 2024

Uh oh!

mbway commented Feb 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidhewitt commented Feb 19, 2025

Uh oh!

mejrs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mejrs Feb 20, 2025

Choose a reason for hiding this comment

Uh oh!

mbway Apr 14, 2025

Choose a reason for hiding this comment

Uh oh!

mejrs commented Apr 13, 2025

Uh oh!

mbway commented Apr 14, 2025

Uh oh!

mbway commented Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mbway commented Apr 18, 2025

Uh oh!

mbway commented Aug 20, 2025

Uh oh!

davidhewitt commented Aug 20, 2025

Uh oh!

mbway commented Aug 20, 2025

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

davidhewitt Sep 21, 2025

Choose a reason for hiding this comment

Uh oh!

davidhewitt Sep 21, 2025

Choose a reason for hiding this comment

Uh oh!

davidhewitt Sep 21, 2025

Choose a reason for hiding this comment

Uh oh!

davidhewitt commented Nov 18, 2025

Uh oh!

mbway commented Nov 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mbway commented Nov 3, 2024 •

edited

Loading

mbway commented Nov 3, 2024 •

edited

Loading

mbway commented Feb 18, 2025 •

edited

Loading

mbway commented Apr 14, 2025 •

edited

Loading