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_bound(py, b"foo".as_slice());
// via PartialEq<[u8]>
assert_eq!(py_bytes, b"foo".as_slice());

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

// Note that `eq` will convert it's argument to Python using `ToPyObject`,
// so the following does not compare equal since the slice will convert into a
// `list`, not a `bytes` object.
assert!(!py_bytes.as_any().eq(b"foo".as_slice()).unwrap());

Implementations

impl PyBytes

pub fn new_bound<'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_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_bound_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 bound_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 AsPyPointer for PyBytes

fn as_ptr(&self) -> *mut PyObject

Gets the underlying FFI pointer, returns a borrowed pointer.

impl AsRef<PyAny> for PyBytes

fn as_ref(&self) -> &PyAny

Converts this type into a shared reference of the (usually inferred) input type.

impl Deref for PyBytes

type Target = PyAny

The resulting type after dereferencing.

fn deref(&self) -> &PyAny

Dereferences the value.

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_bound(obj: &Bound<'_, PyAny>) -> bool

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

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

Returns the safe abstraction over the type object.

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

Checks if object is an instance of this type.

impl DerefToPyAny for PyBytes