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;
68#[cfg(feature = "experimental-inspect")]
69use crate::inspect::PyStaticExpr;
70use crate::instance::Bound;
71use crate::pybacked::PyBackedBytes;
72use crate::types::PyBytes;
73#[cfg(feature = "experimental-inspect")]
74use crate::PyTypeInfo;
75use crate::{Borrowed, CastError, FromPyObject, PyAny, PyErr, Python};
76
77impl<'a, 'py> FromPyObject<'a, 'py> for Bytes {
78    type Error = CastError<'a, 'py>;
79
80    #[cfg(feature = "experimental-inspect")]
81    const INPUT_TYPE: PyStaticExpr = PyBackedBytes::INPUT_TYPE;
82
83    fn extract(obj: Borrowed<'a, 'py, PyAny>) -> Result<Self, Self::Error> {
84        Ok(Bytes::from_owner(obj.extract::<PyBackedBytes>()?))
85    }
86}
87
88impl<'py> IntoPyObject<'py> for Bytes {
89    type Target = PyBytes;
90    type Output = Bound<'py, Self::Target>;
91    type Error = PyErr;
92
93    #[cfg(feature = "experimental-inspect")]
94    const OUTPUT_TYPE: PyStaticExpr = PyBytes::TYPE_HINT;
95
96    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
97        Ok(PyBytes::new(py, &self))
98    }
99}
100
101impl<'py> IntoPyObject<'py> for &Bytes {
102    type Target = PyBytes;
103    type Output = Bound<'py, Self::Target>;
104    type Error = PyErr;
105
106    #[cfg(feature = "experimental-inspect")]
107    const OUTPUT_TYPE: PyStaticExpr = PyBytes::TYPE_HINT;
108
109    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {
110        Ok(PyBytes::new(py, self))
111    }
112}
113
114#[cfg(test)]
115mod tests {
116    use super::*;
117    use crate::types::{PyAnyMethods, PyByteArray, PyByteArrayMethods, PyBytes};
118    use crate::Python;
119
120    #[test]
121    fn test_bytes() {
122        Python::attach(|py| {
123            let py_bytes = PyBytes::new(py, b"foobar");
124            let bytes: Bytes = py_bytes.extract().unwrap();
125            assert_eq!(&*bytes, b"foobar");
126
127            let bytes = Bytes::from_static(b"foobar").into_pyobject(py).unwrap();
128            assert!(bytes.is_instance_of::<PyBytes>());
129        });
130    }
131
132    #[test]
133    fn test_bytearray() {
134        Python::attach(|py| {
135            let py_bytearray = PyByteArray::new(py, b"foobar");
136            let bytes: Bytes = py_bytearray.extract().unwrap();
137            assert_eq!(&*bytes, b"foobar");
138
139            // Editing the bytearray should not change extracted Bytes
140            unsafe { py_bytearray.as_bytes_mut()[0] = b'x' };
141            assert_eq!(&bytes, "foobar");
142            assert_eq!(&py_bytearray.extract::<Vec<u8>>().unwrap(), b"xoobar");
143        });
144    }
145}
pyo3/conversions/bytes.rs

pyo3/conversions/
bytes.rs
