devela::_dep::pyo3::types

Struct PyBytes

pub struct PyBytes(/* private fields */);

Available on crate features dep_pyo3 and std only.

Expand description

Represents a Python bytes object.

This type is immutable.

Values of this type are accessed via PyO3’s smart pointers, e.g. as Py<PyBytes> or Bound<'py, PyBytes>.

For APIs available on bytes objects, see the PyBytesMethods trait which is implemented for Bound<'py, PyBytes>.

§Equality

For convenience, Bound<'py, PyBytes> implements PartialEq<[u8]> to allow comparing the data in the Python bytes to a Rust [u8] byte slice.

This is not always the most appropriate way to compare Python bytes, as Python bytes subclasses may have different equality semantics. In situations where subclasses overriding equality might be relevant, use PyAnyMethods::eq, at cost of the additional overhead of a Python method call.

use pyo3::types::PyBytes;

let py_bytes = PyBytes::new(py, b"foo".as_slice());
// via PartialEq<[u8]>
assert_eq!(py_bytes, b"foo".as_slice());

// via Python equality
let other = PyBytes::new(py, b"foo".as_slice());
assert!(py_bytes.as_any().eq(other).unwrap());

// Note that `eq` will convert its argument to Python using `IntoPyObject`.
// Byte collections are specialized, so that the following slice will indeed
// convert into a `bytes` object and not a `list`:
assert!(py_bytes.as_any().eq(b"foo".as_slice()).unwrap());

Implementations§

§

impl PyBytes

pub fn new<'p>(py: Python<'p>, s: &[u8]) -> Bound<'p, PyBytes>

Creates a new Python bytestring object. The bytestring is initialized by copying the data from the &[u8].

Panics if out of memory.

pub fn new_bound<'p>(py: Python<'p>, s: &[u8]) -> Bound<'p, PyBytes>

👎Deprecated since 0.23.0: renamed to PyBytes::new

Deprecated name for PyBytes::new.

pub fn new_with<F>( py: Python<'_>, len: usize, init: F, ) -> Result<Bound<'_, PyBytes>, PyErr> ⓘ
where F: FnOnce(&mut [u8]) -> Result<(), PyErr>,

Creates a new Python bytes object with an init closure to write its contents. Before calling init the bytes’ contents are zero-initialised.

If Python raises a MemoryError on the allocation, new_with will return it inside Err.
If init returns Err(e), new_with will return Err(e).
If init returns Ok(()), new_with will return Ok(&PyBytes).

§Examples

use pyo3::{prelude::*, types::PyBytes};

Python::with_gil(|py| -> PyResult<()> {
    let py_bytes = PyBytes::new_with(py, 10, |bytes: &mut [u8]| {
        bytes.copy_from_slice(b"Hello Rust");
        Ok(())
    })?;
    let bytes: &[u8] = py_bytes.extract()?;
    assert_eq!(bytes, b"Hello Rust");
    Ok(())
})

pub fn new_bound_with<F>( py: Python<'_>, len: usize, init: F, ) -> Result<Bound<'_, PyBytes>, PyErr> ⓘ
where F: FnOnce(&mut [u8]) -> Result<(), PyErr>,

👎Deprecated since 0.23.0: renamed to PyBytes::new_with

Deprecated name for PyBytes::new_with.

pub unsafe fn from_ptr( py: Python<'_>, ptr: *const u8, len: usize, ) -> Bound<'_, PyBytes>

Creates a new Python byte string object from a raw pointer and length.

Panics if out of memory.

§Safety

This function dereferences the raw pointer ptr as the leading pointer of a slice of length len. As with std::slice::from_raw_parts, this is unsafe.

pub unsafe fn bound_from_ptr( py: Python<'_>, ptr: *const u8, len: usize, ) -> Bound<'_, PyBytes>

👎Deprecated since 0.23.0: renamed to PyBytes::from_ptr

Deprecated name for PyBytes::from_ptr.

§Safety

This function dereferences the raw pointer ptr as the leading pointer of a slice of length len. As with std::slice::from_raw_parts, this is unsafe.