Struct PyBytes

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

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_with<F>( py: Python<'_>, len: usize, init: F, ) -> PyResult<Bound<'_, PyBytes>>

where F: FnOnce(&mut [u8]) -> PyResult<()>,

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 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.

Trait Implementations

impl PyTypeInfo for PyBytes

const NAME: &'static str = "PyBytes"

Class name.

const MODULE: Option<&'static str>

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn is_type_of(obj: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.

impl DerefToPyAny for PyBytes