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

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

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

Trait Implementations

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

👎Deprecated since 0.23.0: renamed to PyTypeInfo::is_type_of

Deprecated name for PyTypeInfo::is_type_of.

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

Returns the safe abstraction over the type object.

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

👎Deprecated since 0.23.0: renamed to PyTypeInfo::type_object

Deprecated name for PyTypeInfo::type_object.

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

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

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

Checks if object is an instance of this type.

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

👎Deprecated since 0.23.0: renamed to PyTypeInfo::is_exact_type_of

Deprecated name for PyTypeInfo::is_exact_type_of.

impl DerefToPyAny for PyBytes