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//! fn my_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
48//!     m.add_function(wrap_pyfunction!(get_message_bytes, m)?)?;
49//!     m.add_function(wrap_pyfunction!(num_bytes, m)?)?;
50//!     Ok(())
51//! }
52//! ```
53//!
54//! Python code that calls these functions:
55//!
56//! ```python
57//! from my_module import get_message_bytes, num_bytes
58//!
59//! message = get_message_bytes()
60//! assert message == b"Hello Python!"
61//!
62//! size = num_bytes(message)
63//! assert size == 13
64//! ```
65use bytes::Bytes;
66
67use crate::conversion::IntoPyObject;
68use crate::instance::Bound;
69use crate::pybacked::PyBackedBytes;
70use crate::types::PyBytes;
71use crate::{Borrowed, CastError, FromPyObject, PyAny, PyErr, Python};
72
73impl<'a, 'py> FromPyObject<'a, 'py> for Bytes {
74    type Error = CastError<'a, 'py>;
75
76    fn extract(obj: Borrowed<'a, 'py, PyAny>) -> Result<Self, Self::Error> {
77        Ok(Bytes::from_owner(obj.extract::<PyBackedBytes>()?))
78    }
79}
80
81impl<'py> IntoPyObject<'py> for Bytes {
82    type Target = PyBytes;
83    type Output = Bound<'py, Self::Target>;
84    type Error = PyErr;
85
86    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
87        Ok(PyBytes::new(py, &self))
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    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
97        Ok(PyBytes::new(py, self))
98    }
99}
100
101#[cfg(test)]
102mod tests {
103    use super::*;
104    use crate::types::{PyAnyMethods, PyByteArray, PyByteArrayMethods, PyBytes};
105    use crate::Python;
106
107    #[test]
108    fn test_bytes() {
109        Python::attach(|py| {
110            let py_bytes = PyBytes::new(py, b"foobar");
111            let bytes: Bytes = py_bytes.extract().unwrap();
112            assert_eq!(&*bytes, b"foobar");
113
114            let bytes = Bytes::from_static(b"foobar").into_pyobject(py).unwrap();
115            assert!(bytes.is_instance_of::<PyBytes>());
116        });
117    }
118
119    #[test]
120    fn test_bytearray() {
121        Python::attach(|py| {
122            let py_bytearray = PyByteArray::new(py, b"foobar");
123            let bytes: Bytes = py_bytearray.extract().unwrap();
124            assert_eq!(&*bytes, b"foobar");
125
126            // Editing the bytearray should not change extracted Bytes
127            unsafe { py_bytearray.as_bytes_mut()[0] = b'x' };
128            assert_eq!(&bytes, "foobar");
129            assert_eq!(&py_bytearray.extract::<Vec<u8>>().unwrap(), b"xoobar");
130        });
131    }
132}
pyo3/conversions/bytes.rs

pyo3/conversions/
bytes.rs
