Trait PyListMethods

pub trait PyListMethods<'py>: Sealed {
    // Required methods
    fn len(&self) -> usize;
    fn is_empty(&self) -> bool;
    fn as_sequence(&self) -> &Bound<'py, PySequence>;
    fn into_sequence(self) -> Bound<'py, PySequence>;
    fn get_item(&self, index: usize) -> PyResult<Bound<'py, PyAny>>;
    unsafe fn get_item_unchecked(&self, index: usize) -> Bound<'py, PyAny>;
    fn get_slice(&self, low: usize, high: usize) -> Bound<'py, PyList>;
    fn set_item<I>(&self, index: usize, item: I) -> PyResult<()>
       where I: IntoPyObject<'py>;
    fn del_item(&self, index: usize) -> PyResult<()>;
    fn set_slice(
        &self,
        low: usize,
        high: usize,
        seq: &Bound<'_, PyAny>,
    ) -> PyResult<()>;
    fn del_slice(&self, low: usize, high: usize) -> PyResult<()>;
    fn append<I>(&self, item: I) -> PyResult<()>
       where I: IntoPyObject<'py>;
    fn insert<I>(&self, index: usize, item: I) -> PyResult<()>
       where I: IntoPyObject<'py>;
    fn contains<V>(&self, value: V) -> PyResult<bool>
       where V: IntoPyObject<'py>;
    fn index<V>(&self, value: V) -> PyResult<usize>
       where V: IntoPyObject<'py>;
    fn iter(&self) -> BoundListIterator<'py> ;
    fn locked_for_each<F>(&self, closure: F) -> PyResult<()>
       where F: Fn(Bound<'py, PyAny>) -> PyResult<()>;
    fn sort(&self) -> PyResult<()>;
    fn reverse(&self) -> PyResult<()>;
    fn to_tuple(&self) -> Bound<'py, PyTuple>;
}

Implementation of functionality for PyList.

These methods are defined for the Bound<'py, PyList> smart pointer, so to use method call syntax these methods are separated into a trait, because stable Rust does not yet support arbitrary_self_types.

Required Methods

fn len(&self) -> usize

Returns the length of the list.

fn is_empty(&self) -> bool

Checks if the list is empty.

fn as_sequence(&self) -> &Bound<'py, PySequence>

Returns self cast as a PySequence.

fn into_sequence(self) -> Bound<'py, PySequence>

Returns self cast as a PySequence.

fn get_item(&self, index: usize) -> PyResult<Bound<'py, PyAny>>

Gets the list item at the specified index.

Example

use pyo3::{prelude::*, types::PyList};
Python::with_gil(|py| {
    let list = PyList::new(py, [2, 3, 5, 7]).unwrap();
    let obj = list.get_item(0);
    assert_eq!(obj.unwrap().extract::<i32>().unwrap(), 2);
});

unsafe fn get_item_unchecked(&self, index: usize) -> Bound<'py, PyAny>

Gets the list item at the specified index. Undefined behavior on bad index. Use with caution.

Safety

Caller must verify that the index is within the bounds of the list. On the free-threaded build, caller must verify they have exclusive access to the list via a lock or by holding the innermost critical section on the list.

fn get_slice(&self, low: usize, high: usize) -> Bound<'py, PyList>

Takes the slice self[low:high] and returns it as a new list.

Indices must be nonnegative, and out-of-range indices are clipped to self.len().

fn set_item<I>(&self, index: usize, item: I) -> PyResult<()>

where I: IntoPyObject<'py>,

Sets the item at the specified index.

Raises IndexError if the index is out of range.

fn del_item(&self, index: usize) -> PyResult<()>

Deletes the indexth element of self.

This is equivalent to the Python statement del self[i].

fn set_slice( &self, low: usize, high: usize, seq: &Bound<'_, PyAny>, ) -> PyResult<()>

Assigns the sequence seq to the slice of self from low to high.

This is equivalent to the Python statement self[low:high] = v.

fn del_slice(&self, low: usize, high: usize) -> PyResult<()>

Deletes the slice from low to high from self.

This is equivalent to the Python statement del self[low:high].

fn append<I>(&self, item: I) -> PyResult<()>

where I: IntoPyObject<'py>,

Appends an item to the list.

fn insert<I>(&self, index: usize, item: I) -> PyResult<()>

where I: IntoPyObject<'py>,

Inserts an item at the specified index.

If index >= self.len(), inserts at the end.

fn contains<V>(&self, value: V) -> PyResult<bool>

where V: IntoPyObject<'py>,

Determines if self contains value.

This is equivalent to the Python expression value in self.

fn index<V>(&self, value: V) -> PyResult<usize>

where V: IntoPyObject<'py>,

Returns the first index i for which self[i] == value.

This is equivalent to the Python expression self.index(value).

fn iter(&self) -> BoundListIterator<'py>

Returns an iterator over this list’s items.

fn locked_for_each<F>(&self, closure: F) -> PyResult<()>

where F: Fn(Bound<'py, PyAny>) -> PyResult<()>,

Iterates over the contents of this list while holding a critical section on the list. This is useful when the GIL is disabled and the list is shared between threads. It is not guaranteed that the list will not be modified during iteration when the closure calls arbitrary Python code that releases the critical section held by the iterator. Otherwise, the list will not be modified during iteration.

This is equivalent to for_each if the GIL is enabled.

fn sort(&self) -> PyResult<()>

Sorts the list in-place. Equivalent to the Python expression l.sort().

fn reverse(&self) -> PyResult<()>

Reverses the list in-place. Equivalent to the Python expression l.reverse().

fn to_tuple(&self) -> Bound<'py, PyTuple>

Return a new tuple containing the contents of the list; equivalent to the Python expression tuple(list).

This method is equivalent to self.as_sequence().to_tuple() and faster than PyTuple::new(py, this_list).

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'py> PyListMethods<'py> for Bound<'py, PyList>