feat: introduce stack-allocated `PyBuffer` by winstxnhdw · Pull Request #5894 · PyO3/pyo3

winstxnhdw · 2026-03-19T10:10:14Z

Summary

This PR implements a pinned stack-allocated PyUntypedBuffer variant, PyUntypedBufferView.

src/buffer.rs

davidhewitt

Thanks very much for this. Various thoughts around the accessor methods.

Also, out of scope for this PR, but I keep wondering if we should provide iterators for these structures. Especially with the strides / suboffsets etc, it's not necessarily trivial to get this right.

src/buffer.rs

davidhewitt · 2026-03-19T21:28:15Z

src/buffer.rs

+    /// Gets the size of a single element, in bytes.
+    #[inline]
+    pub fn item_size(&self) -> usize {
+        self.raw.itemsize as usize


Interesting note from the Python docs for itemsize

If shape is NULL as a result of a PyBUF_SIMPLE or a PyBUF_WRITABLE request, the consumer must disregard itemsize and assume itemsize == 1.

I am unsure whether it's better to have a corresponding check for shape here and return 1 if needed, or to return None if shape is None, or to just keep the implementation as-is and document this for users.

I am in favour of returning 1. Also, instead of doing the NULL check inside the method, we could probably do it in with() instead so that the check is only done once.

winstxnhdw · 2026-03-20T16:47:05Z

Also, out of scope for this PR, but I keep wondering if we should provide iterators for these structures. Especially with the strides / suboffsets etc, it's not necessarily trivial to get this right.

Yes, I think it would definitely be useful as well. I am not yet sure how this would look like though.

davidhewitt

Thanks for the continued work here, looking great!

Implementing Drop directly on PyUntypedBufferView is functionally equivalent to what I had in mind from the "drop guard", so gets a 👍 from me.

Afraid I had quite a few more thoughts around some of the edge cases (plus some ideas we can probably ignore). Hopefully helps us get to the right eventual abstraction!

src/buffer.rs

codspeed-hq · 2026-03-24T18:46:30Z

Merging this PR will not alter performance

✅ 105 untouched benchmarks
⏩ 1 skipped benchmark¹

_{Comparing winstxnhdw:feat/stacked-pybuffer (c1872f3) with main (cd87dcf)}

1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

winstxnhdw · 2026-03-30T10:05:32Z

src/buffer.rs

 impl_element!(f64, Float);

+/// Sealed marker for buffer field availability. Either [`Known`] or [`Unknown`].
+mod buffer_info {


I wonder if this should be moved to another file or moved to the top level.

We actually already have pyo3::pyclass::boolean_struct::True / False which could potentially be deduplicated with these types.

It might be possible to also use const FORMAT: bool etc as const-generics instead of types. Not sure if that offers any practical benefit here. I think it's not possible to provide defaults for const generics, so it might work out strictly worse I guess?

It might be possible to also use const FORMAT: bool etc as const-generics instead of types.

You're right. It works, and it's a lot cleaner. It's possible to set defaults for const generics.

davidhewitt

Very cool!

After reading through this implementation a couple of times, I really like the expressiveness this gives in the type system. I have some ideas which might refine it further (see BufferFlags struct idea).

Main concern is about generic code bloat from explosion of generic parameters. I am unsure if there's a way that we can mitigate that at all.

davidhewitt · 2026-03-31T08:22:48Z

src/buffer.rs

 impl_element!(f64, Float);

+/// Sealed marker for buffer field availability. Either [`Known`] or [`Unknown`].
+mod buffer_info {


We actually already have pyo3::pyclass::boolean_struct::True / False which could potentially be deduplicated with these types.

It might be possible to also use const FORMAT: bool etc as const-generics instead of types. Not sure if that offers any practical benefit here. I think it's not possible to provide defaults for const generics, so it might work out strictly worse I guess?

davidhewitt · 2026-03-31T08:38:28Z

src/buffer.rs

+impl<Format: FieldInfo, Stride: FieldInfo> PyUntypedBufferView<Format, Known, Stride> {
+    /// Returns the shape array. `shape[i]` is the length of dimension `i`.
+    ///
+    /// Despite Python using an array of signed integers, the values are guaranteed to be
+    /// non-negative. However, dimensions of length 0 are possible and might need special
+    /// attention.
+    #[inline]
+    pub fn shape(&self) -> &[usize] {
+        debug_assert!(!self.raw.shape.is_null());
+        unsafe { slice::from_raw_parts(self.raw.shape.cast(), self.raw.ndim as usize) }
+    }
+}


I think it's potentially also valid to have PyUntypedBufferView<Format, Unknown, Stride> implement a shape() accessor which returns Option<&[usize]>. I am unsure if that's of any practical value, it seems to me that it would be expected to always return None.

(Maybe similar observation for format / stride parameters.)

I can't see this being useful, and I can't think of a good way to implement this. I am assuming this is necessary for someone who wants to resolve the flags dynamically at runtime? I don’t think it’s worth supporting that. Such users should just request for all the flags.

davidhewitt · 2026-03-31T08:40:57Z

src/buffer.rs

+#[repr(transparent)]
+pub struct PyBufferView<
+    T,
+    Format: FieldInfo = Known,


I suppose the typed buffer view always needs to know format, this parameter might not be necessary (however I guess is useful for consistency).

We'd have to add another flag type, which isn't worth it imo.

src/buffer.rs

davidhewitt · 2026-03-31T09:04:10Z

src/buffer.rs

+    /// Attempt to interpret this untyped view as containing elements of type `T`.
+    pub fn as_typed<T: Element>(&self) -> PyResult<&PyBufferView<T, Known, Shape, Stride>> {
+        self.ensure_compatible_with::<T>()?;
+        // SAFETY: PyBufferView<T, ..> is repr(transparent) around PyUntypedBufferView<..>
+        let typed = unsafe {
+            NonNull::from(self)
+                .cast::<PyBufferView<T, Known, Shape, Stride>>()
+                .as_ref()
+        };
+
+        Ok(typed)
+    }
+
+    fn ensure_compatible_with<T: Element>(&self) -> PyResult<()> {
+        let name = std::any::type_name::<T>();
+
+        if mem::size_of::<T>() != self.item_size() || !T::is_compatible_format(self.format()) {
+            return Err(PyBufferError::new_err(format!(
+                "buffer contents are not compatible with {name}"
+            )));
+        }
+
+        if self.raw.buf.align_offset(mem::align_of::<T>()) != 0 {
+            return Err(PyBufferError::new_err(format!(
+                "buffer contents are insufficiently aligned for {name}"
+            )));
+        }
+
+        Ok(())
+    }


One downside of the high numbers of generic parameters is that these methods are monomorphised many times over during codegen. We might want to have fn inner internal methods which are only generic on T for these larger methods. Small ones probably aren't worth applying such complexity for, I don't have a good instinct for a cut-off threshold on that.

Most of the methods are pretty short. I guess ensure_compatible_with is a good candidate?

src/buffer.rs

davidhewitt · 2026-03-31T09:20:15Z

Thanks for all of this - would be interested to see what you think of these suggestions (none are mandatory, I'm just pushing out ideas of what I think I like, which may not be to others' taste!)

davidhewitt · 2026-03-31T13:35:31Z

#5870 has now merged, we'll want to add a similar API here.

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

winstxnhdw · 2026-04-07T21:38:27Z

Sorry for the delay. I've been a little burnt out from school + work. I've adapted your suggestions and modified them to be what I think is appropriate.

Also, if you do PyBufferFlags::simple().full(), you won't be able to append let's say format() on it anymore because full() already implies format(). Just a nice DX win that I haven't really seen in other libraries like reqwest or tokio.

winstxnhdw commented Mar 19, 2026

View reviewed changes

src/buffer.rs Outdated Show resolved Hide resolved

davidhewitt reviewed Mar 19, 2026

View reviewed changes

davidhewitt reviewed Mar 22, 2026

View reviewed changes

winstxnhdw force-pushed the feat/stacked-pybuffer branch 3 times, most recently from 5430e96 to 48b5fdd Compare March 22, 2026 18:11

winstxnhdw force-pushed the feat/stacked-pybuffer branch from b4f1eab to dd63129 Compare March 27, 2026 15:03

winstxnhdw commented Mar 30, 2026

View reviewed changes

winstxnhdw requested a review from davidhewitt March 30, 2026 10:09

davidhewitt reviewed Mar 31, 2026

View reviewed changes

winstxnhdw and others added 8 commits April 8, 2026 01:56

feat: introduce stack-allocated PyBuffer

ada6209

docs: update CHANGELOG

498b803

refactor: apply suggestions

857f5aa

refactor: use assume_init

8180360

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

refactor: apply some suggestions

e6dca4c

fix: handle PyBUF_WRITABLE

6a823e1

refactor: encode compile-time buffer field availability

63ffa11

style: clean up

b239797

winstxnhdw force-pushed the feat/stacked-pybuffer branch from dd63129 to 5d3c801 Compare April 7, 2026 17:59

tests: extend coverage

c9e582a

winstxnhdw force-pushed the feat/stacked-pybuffer branch from 5d3c801 to c9e582a Compare April 7, 2026 18:07

winstxnhdw added 2 commits April 8, 2026 02:11

chore: add obj API

35aec71

refactor: use PyBufferFlags

48a2bd0

winstxnhdw force-pushed the feat/stacked-pybuffer branch 3 times, most recently from a462497 to fcb9203 Compare April 7, 2026 21:25

feat: add flag builder

c1872f3

winstxnhdw force-pushed the feat/stacked-pybuffer branch from fcb9203 to c1872f3 Compare April 7, 2026 21:31

winstxnhdw requested a review from davidhewitt April 9, 2026 06:39

Conversation

winstxnhdw commented Mar 19, 2026

Summary

Uh oh!

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

winstxnhdw commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codspeed-hq bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidhewitt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

winstxnhdw Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davidhewitt commented Mar 31, 2026

Uh oh!

davidhewitt commented Mar 31, 2026

Uh oh!

winstxnhdw commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

winstxnhdw commented Mar 20, 2026 •

edited

Loading

codspeed-hq bot commented Mar 24, 2026 •

edited

Loading

winstxnhdw Apr 7, 2026 •

edited

Loading

winstxnhdw commented Apr 7, 2026 •

edited

Loading