Skip to main content

pyo3/conversions/
bytes.rs

1#![cfg(feature = "bytes")]
2
3//! Conversions to and from [bytes](https://docs.rs/bytes/latest/bytes/)'s [`Bytes`].
4//!
5//! This is useful for efficiently converting Python's `bytes` types efficiently.
6//! While `bytes` will be directly borrowed, converting from `bytearray` will result in a copy.
7//!
8//! When converting `Bytes` back into Python, this will do a copy, just like `&[u8]` and `Vec<u8>`.
9//!
10//! # When to use `Bytes`
11//!
12//! Unless you specifically need [`Bytes`] for ref-counted ownership and sharing,
13//! you may find that using `&[u8]`, `Vec<u8>`, [`Bound<PyBytes>`], or [`PyBackedBytes`]
14//! is simpler for most use cases.
15//!
16//! # Setup
17//!
18//! To use this feature, add in your **`Cargo.toml`**:
19//!
20//! ```toml
21//! [dependencies]
22//! bytes = "1.10"
23#![doc = concat!("pyo3 = { version = \"", env!("CARGO_PKG_VERSION"),  "\", features = [\"bytes\"] }")]
24//! ```
25//!
26//! Note that you must use compatible versions of bytes and PyO3.
27//!
28//! # Example
29//!
30//! Rust code to create functions which return `Bytes` or take `Bytes` as arguments:
31//!
32//! ```rust,no_run
33//! use pyo3::prelude::*;
34//! use bytes::Bytes;
35//!
36//! #[pyfunction]
37//! fn get_message_bytes() -> Bytes {
38//!     Bytes::from_static(b"Hello Python!")
39//! }
40//!
41//! #[pyfunction]
42//! fn num_bytes(bytes: Bytes) -> usize {
43//!     bytes.len()
44//! }
45//!
46//! #[pymodule]
47//! # #[pyo3(name = "example_bytes")]
48//! fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
49//!     m.add_function(wrap_pyfunction!(get_message_bytes, m)?)?;
50//!     m.add_function(wrap_pyfunction!(num_bytes, m)?)?;
51//!     Ok(())
52//! }
53//! ```
54//!
55//! Python code that calls these functions:
56//!
57//! ```python
58//! from my_module import get_message_bytes, num_bytes
59//!
60//! message = get_message_bytes()
61//! assert message == b"Hello Python!"
62//!
63//! size = num_bytes(message)
64//! assert size == 13
65//! ```
66use bytes::Bytes;
67
68#[cfg(feature = "experimental-inspect")]
69use crate::PyTypeInfo;
70use crate::conversion::IntoPyObject;
71#[cfg(feature = "experimental-inspect")]
72use crate::inspect::PyStaticExpr;
73use crate::instance::Bound;
74#[allow(unused_imports, reason = "used to build docs")]
75use crate::platform::prelude::*;
76use crate::pybacked::PyBackedBytes;
77use crate::types::PyBytes;
78use crate::{Borrowed, CastError, FromPyObject, PyAny, PyErr, Python};
79
80impl<'a, 'py> FromPyObject<'a, 'py> for Bytes {
81    type Error = CastError<'a, 'py>;
82
83    #[cfg(feature = "experimental-inspect")]
84    const INPUT_TYPE: PyStaticExpr = PyBackedBytes::INPUT_TYPE;
85
86    fn extract(obj: Borrowed<'a, 'py, PyAny>) -> Result<Self, Self::Error> {
87        Ok(Bytes::from_owner(obj.extract::<PyBackedBytes>()?))
88    }
89}
90
91impl<'py> IntoPyObject<'py> for Bytes {
92    type Target = PyBytes;
93    type Output = Bound<'py, Self::Target>;
94    type Error = PyErr;
95
96    #[cfg(feature = "experimental-inspect")]
97    const OUTPUT_TYPE: PyStaticExpr = PyBytes::TYPE_HINT;
98
99    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
100        Ok(PyBytes::new(py, &self))
101    }
102}
103
104impl<'py> IntoPyObject<'py> for &Bytes {
105    type Target = PyBytes;
106    type Output = Bound<'py, Self::Target>;
107    type Error = PyErr;
108
109    #[cfg(feature = "experimental-inspect")]
110    const OUTPUT_TYPE: PyStaticExpr = PyBytes::TYPE_HINT;
111
112    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
113        Ok(PyBytes::new(py, self))
114    }
115}
116
117#[cfg(test)]
118mod tests {
119    use super::*;
120    use crate::Python;
121    use crate::types::{PyAnyMethods, PyByteArray, PyByteArrayMethods, PyBytes};
122
123    #[test]
124    fn test_bytes() {
125        Python::attach(|py| {
126            let py_bytes = PyBytes::new(py, b"foobar");
127            let bytes: Bytes = py_bytes.extract().unwrap();
128            assert_eq!(&*bytes, b"foobar");
129
130            let bytes = Bytes::from_static(b"foobar").into_pyobject(py).unwrap();
131            assert!(bytes.is_instance_of::<PyBytes>());
132        });
133    }
134
135    #[test]
136    fn test_bytearray() {
137        Python::attach(|py| {
138            let py_bytearray = PyByteArray::new(py, b"foobar");
139            let bytes: Bytes = py_bytearray.extract().unwrap();
140            assert_eq!(&*bytes, b"foobar");
141
142            // Editing the bytearray should not change extracted Bytes
143            // SAFETY: the slice is dropped within this statement without running any Python code,
144            // and `bytes` holds a copy of the data, so the buffer is not aliased
145            unsafe { py_bytearray.as_bytes_mut()[0] = b'x' };
146            assert_eq!(&bytes, "foobar");
147            assert_eq!(&py_bytearray.extract::<Vec<u8>>().unwrap(), b"xoobar");
148        });
149    }
150}