Struct numpy::borrow::PyReadwriteArray

source · [−]
#[repr(C)]
pub struct PyReadwriteArray<'py, T, D>where
    T: Element,
    D: Dimension,{ /* private fields */ }
Expand description

Read-write borrow of an array.

An instance of this type ensures that there are no instances of PyReadonlyArray and no other instances of PyReadwriteArray, i.e. that only a single exclusive reference into the interior of the array can be created safely.

See the module-level documentation for more.

Implementations

Provides a mutable array view of the interior of the NumPy array.

Provide a mutable slice view of the interior of the NumPy array if it is contiguous.

Provide a mutable reference to an element of the NumPy array if the index is within bounds.

Extends or truncates the dimensions of an array.

Safe wrapper for PyArray::resize.

Example
use numpy::PyArray;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray = PyArray::arange(py, 0, 10, 1);
    assert_eq!(pyarray.len(), 10);

    let pyarray = pyarray.readwrite();
    let pyarray = pyarray.resize(100).unwrap();
    assert_eq!(pyarray.len(), 100);
});

Methods from Deref<Target = PyReadonlyArray<'py, T, D>>

Provides an immutable array view of the interior of the NumPy array.

Provide an immutable slice view of the interior of the NumPy array if it is contiguous.

Provide an immutable reference to an element of the NumPy array if the index is within bounds.

Methods from Deref<Target = PyArray<T, D>>

Returns a raw pointer to the underlying PyArrayObject.

Returns the dtype of the array.

See also ndarray.dtype and PyArray_DTYPE.

Example
use numpy::{dtype, PyArray};
use pyo3::Python;

Python::with_gil(|py| {
   let array = PyArray::from_vec(py, vec![1_i32, 2, 3]);

   assert!(array.dtype().is_equiv_to(dtype::<i32>(py)));
});

Returns true if the internal data of the array is contiguous, indepedently of whether C-style/row-major or Fortran-style/column-major.

Example
use numpy::PyArray1;
use pyo3::{types::IntoPyDict, Python};

Python::with_gil(|py| {
    let array = PyArray1::arange(py, 0, 10, 1);
    assert!(array.is_contiguous());

    let view = py
        .eval("array[::2]", None, Some([("array", array)].into_py_dict(py)))
        .unwrap()
        .downcast::<PyArray1<i32>>()
        .unwrap();
    assert!(!view.is_contiguous());
});

Returns true if the internal data of the array is Fortran-style/column-major contiguous.

Returns true if the internal data of the array is C-style/row-major contiguous.

Turn &PyArray<T,D> into Py<PyArray<T,D>>, i.e. a pointer into Python’s heap which is independent of the GIL lifetime.

This method can be used to avoid lifetime annotations of function arguments or return values.

Example
use numpy::PyArray1;
use pyo3::{Py, Python};

let array: Py<PyArray1<f64>> = Python::with_gil(|py| {
    PyArray1::zeros(py, 5, false).to_owned()
});

Python::with_gil(|py| {
    assert_eq!(array.as_ref(py).readonly().as_slice().unwrap(), [0.0; 5]);
});

Returns the number of dimensions of the array.

See also ndarray.ndim and PyArray_NDIM.

Example
use numpy::PyArray3;
use pyo3::Python;

Python::with_gil(|py| {
    let arr = PyArray3::<f64>::zeros(py, [4, 5, 6], false);

    assert_eq!(arr.ndim(), 3);
});

Returns a slice indicating how many bytes to advance when iterating along each axis.

See also ndarray.strides and PyArray_STRIDES.

Example
use numpy::PyArray3;
use pyo3::Python;

Python::with_gil(|py| {
    let arr = PyArray3::<f64>::zeros(py, [4, 5, 6], false);

    assert_eq!(arr.strides(), &[240, 48, 8]);
});

Returns a slice which contains dimmensions of the array.

See also [ndarray.shape][ndaray-shape] and PyArray_DIMS.

Example
use numpy::PyArray3;
use pyo3::Python;

Python::with_gil(|py| {
    let arr = PyArray3::<f64>::zeros(py, [4, 5, 6], false);

    assert_eq!(arr.shape(), &[4, 5, 6]);
});

Calculates the total number of elements in the array.

Returns true if the there are no elements in the array.

Returns a pointer to the first element of the array.

Same as shape, but returns D insead of &[usize].

Returns an immutable view of the internal data as a slice.

Safety

Calling this method is undefined behaviour if the underlying array is aliased mutably by other instances of PyArray or concurrently modified by Python or other native code.

Please consider the safe alternative PyReadonlyArray::as_slice.

Returns a mutable view of the internal data as a slice.

Safety

Calling this method is undefined behaviour if the underlying array is aliased immutably or mutably by other instances of PyArray or concurrently modified by Python or other native code.

Please consider the safe alternative PyReadwriteArray::as_slice_mut.

Get a reference of the specified element if the given index is valid.

Safety

Calling this method is undefined behaviour if the underlying array is aliased mutably by other instances of PyArray or concurrently modified by Python or other native code.

Consider using safe alternatives like PyReadonlyArray::get.

Example
use numpy::PyArray;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();

    assert_eq!(unsafe { *pyarray.get([1, 0, 3]).unwrap() }, 11);
});

Same as get, but returns Option<&mut T>.

Safety

Calling this method is undefined behaviour if the underlying array is aliased immutably or mutably by other instances of PyArray or concurrently modified by Python or other native code.

Consider using safe alternatives like PyReadwriteArray::get_mut.

Example
use numpy::PyArray;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();

    unsafe {
        *pyarray.get_mut([1, 0, 3]).unwrap() = 42;
    }

    assert_eq!(unsafe { *pyarray.get([1, 0, 3]).unwrap() }, 42);
});

Get an immutable reference of the specified element, without checking the given index.

See NpyIndex for what types can be used as the index.

Safety

Passing an invalid index is undefined behavior. The element must also have been initialized and all other references to it is must also be shared.

See PyReadonlyArray::get for a safe alternative.

Example
use numpy::PyArray;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();

    assert_eq!(unsafe { *pyarray.uget([1, 0, 3]) }, 11);
});

Same as uget, but returns &mut T.

Safety

Passing an invalid index is undefined behavior. The element must also have been initialized and other references to it must not exist.

See PyReadwriteArray::get_mut for a safe alternative.

Same as uget, but returns *mut T.

Safety

Passing an invalid index is undefined behavior.

Get a copy of the specified element in the array.

See NpyIndex for what types can be used as the index.

Example
use numpy::PyArray;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();

    assert_eq!(pyarray.get_owned([1, 0, 3]), Some(11));
});

Turn an array with fixed dimensionality into one with dynamic dimensionality.

Returns a copy of the internal data of the array as a Vec.

Fails if the internal array is not contiguous. See also as_slice.

Example
use numpy::PyArray2;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray= py
        .eval("__import__('numpy').array([[0, 1], [2, 3]], dtype='int64')", None, None)
        .unwrap()
        .downcast::<PyArray2<i64>>()
        .unwrap();

    assert_eq!(pyarray.to_vec().unwrap(), vec![0, 1, 2, 3]);
});

Get an immutable borrow of the NumPy array

Get an immutable borrow of the NumPy array

Panics

Panics if the allocation backing the array is currently mutably borrowed.

For a non-panicking variant, use try_readonly.

Get a mutable borrow of the NumPy array

Get a mutable borrow of the NumPy array

Panics

Panics if the allocation backing the array is currently borrowed or if the array is flagged as not writeable.

For a non-panicking variant, use try_readwrite.

Returns an ArrayView of the internal array.

See also PyReadonlyArray::as_array.

Safety

The existence of an exclusive reference to the internal data, e.g. &mut [T] or ArrayViewMut, implies undefined behavior.

Returns an ArrayViewMut of the internal array.

See also PyReadwriteArray::as_array_mut.

Safety

The existence of another reference to the internal data, e.g. &[T] or ArrayView, implies undefined behavior.

Returns the internal array as RawArrayView enabling element access via raw pointers

Returns the internal array as RawArrayViewMut enabling element access via raw pointers

Get a copy of the array as an ndarray::Array.

Example
use numpy::PyArray;
use ndarray::array;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray = PyArray::arange(py, 0, 4, 1).reshape([2, 2]).unwrap();

    assert_eq!(
        pyarray.to_owned_array(),
        array![[0, 1], [2, 3]]
    )
});

Get the single element of a zero-dimensional array.

See inner for an example.

Copies self into other, performing a data type conversion if necessary.

See also PyArray_CopyInto.

Example
use numpy::PyArray;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray_f = PyArray::arange(py, 2.0, 5.0, 1.0);
    let pyarray_i = unsafe { PyArray::<i64, _>::new(py, [3], false) };

    assert!(pyarray_f.copy_to(pyarray_i).is_ok());

    assert_eq!(pyarray_i.readonly().as_slice().unwrap(), &[2, 3, 4]);
});

Cast the PyArray<T> to PyArray<U>, by allocating a new array.

See also PyArray_CastToType.

Example
use numpy::PyArray;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray_f = PyArray::arange(py, 2.0, 5.0, 1.0);

    let pyarray_i = pyarray_f.cast::<i32>(false).unwrap();

    assert_eq!(pyarray_i.readonly().as_slice().unwrap(), &[2, 3, 4]);
});

Construct a new array which has same values as self, but has different dimensions specified by dims and a possibly different memory order specified by order.

See also numpy.reshape and PyArray_Newshape.

Example
use numpy::{npyffi::NPY_ORDER, PyArray};
use pyo3::Python;
use ndarray::array;

Python::with_gil(|py| {
    let array =
        PyArray::from_iter(py, 0..9).reshape_with_order([3, 3], NPY_ORDER::NPY_FORTRANORDER).unwrap();

    assert_eq!(array.readonly().as_array(), array![[0, 3, 6], [1, 4, 7], [2, 5, 8]]);
    assert!(array.is_fortran_contiguous());

    assert!(array.reshape([5]).is_err());
});

Special case of reshape_with_order which keeps the memory order the same.

Extends or truncates the dimensions of an array.

This method works only on contiguous arrays. Missing elements will be initialized as if calling zeros.

See also ndarray.resize and PyArray_Resize.

Safety

There should be no outstanding references (shared or exclusive) into the array as this method might re-allocate it and thereby invalidate all pointers into it.

Example
use numpy::PyArray;
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray = PyArray::<f64, _>::zeros(py, (10, 10), false);
    assert_eq!(pyarray.shape(), [10, 10]);

    unsafe {
        pyarray.resize((100, 100)).unwrap();
    }
    assert_eq!(pyarray.shape(), [100, 100]);
});

Methods from Deref<Target = PyAny>

Converts this PyAny to a concrete Python type.

Examples
use pyo3::prelude::*;
use pyo3::types::{PyAny, PyDict, PyList};

Python::with_gil(|py| {
    let dict = PyDict::new(py);
    assert!(dict.is_instance_of::<PyAny>().unwrap());
    let any: &PyAny = dict.as_ref();
    assert!(any.downcast::<PyDict>().is_ok());
    assert!(any.downcast::<PyList>().is_err());
});

Returns whether self and other point to the same object. To compare the equality of two objects (the == operator), use eq.

This is equivalent to the Python expression self is other.

Determines whether this object has the given attribute.

This is equivalent to the Python expression hasattr(self, attr_name).

To avoid repeated temporary allocations of Python strings, the [intern!] macro can be used to intern attr_name.

Retrieves an attribute value.

This is equivalent to the Python expression self.attr_name.

To avoid repeated temporary allocations of Python strings, the [intern!] macro can be used to intern attr_name.

Example: intern!ing the attribute name
#[pyfunction]
fn version(sys: &PyModule) -> PyResult<&PyAny> {
    sys.getattr(intern!(sys.py(), "version"))
}

Sets an attribute value.

This is equivalent to the Python expression self.attr_name = value.

To avoid repeated temporary allocations of Python strings, the [intern!] macro can be used to intern name.

Example: intern!ing the attribute name
#[pyfunction]
fn set_answer(ob: &PyAny) -> PyResult<()> {
    ob.setattr(intern!(ob.py(), "answer"), 42)
}

Deletes an attribute.

This is equivalent to the Python statement del self.attr_name.

To avoid repeated temporary allocations of Python strings, the [intern!] macro can be used to intern attr_name.

Returns an Ordering between self and other.

This is equivalent to the following Python code:

if self == other:
    return Equal
elif a < b:
    return Less
elif a > b:
    return Greater
else:
    raise TypeError("PyAny::compare(): All comparisons returned false")
Examples
use pyo3::prelude::*;
use pyo3::types::PyFloat;
use std::cmp::Ordering;

Python::with_gil(|py| -> PyResult<()> {
    let a = PyFloat::new(py, 0_f64);
    let b = PyFloat::new(py, 42_f64);
    assert_eq!(a.compare(b)?, Ordering::Less);
    Ok(())
})?;

It will return PyErr for values that cannot be compared:

use pyo3::prelude::*;
use pyo3::types::{PyFloat, PyString};

Python::with_gil(|py| -> PyResult<()> {
    let a = PyFloat::new(py, 0_f64);
    let b = PyString::new(py, "zero");
    assert!(a.compare(b).is_err());
    Ok(())
})?;

Tests whether two Python objects obey a given CompareOp.

lt, le, eq, ne, gt and ge are the specialized versions of this function.

Depending on the value of compare_op, this is equivalent to one of the following Python expressions:

compare_opPython expression
CompareOp::Eqself == other
CompareOp::Neself != other
CompareOp::Ltself < other
CompareOp::Leself <= other
CompareOp::Gtself > other
CompareOp::Geself >= other
Examples
use pyo3::class::basic::CompareOp;
use pyo3::prelude::*;
use pyo3::types::PyInt;

Python::with_gil(|py| -> PyResult<()> {
    let a: &PyInt = 0_u8.into_py(py).into_ref(py).downcast()?;
    let b: &PyInt = 42_u8.into_py(py).into_ref(py).downcast()?;
    assert!(a.rich_compare(b, CompareOp::Le)?.is_true()?);
    Ok(())
})?;

Tests whether this object is less than another.

This is equivalent to the Python expression self < other.

Tests whether this object is less than or equal to another.

This is equivalent to the Python expression self <= other.

Tests whether this object is equal to another.

This is equivalent to the Python expression self == other.

Tests whether this object is not equal to another.

This is equivalent to the Python expression self != other.

Tests whether this object is greater than another.

This is equivalent to the Python expression self > other.

Tests whether this object is greater than or equal to another.

This is equivalent to the Python expression self >= other.

Determines whether this object appears callable.

This is equivalent to Python’s callable() function.

Examples
use pyo3::prelude::*;

Python::with_gil(|py| -> PyResult<()> {
    let builtins = PyModule::import(py, "builtins")?;
    let print = builtins.getattr("print")?;
    assert!(print.is_callable());
    Ok(())
})?;

This is equivalent to the Python statement assert callable(print).

Note that unless an API needs to distinguish between callable and non-callable objects, there is no point in checking for callability. Instead, it is better to just do the call and handle potential exceptions.

Calls the object.

This is equivalent to the Python expression self(*args, **kwargs).

Examples
use pyo3::prelude::*;
use pyo3::types::PyDict;

const CODE: &str = r#"
def function(*args, **kwargs):
    assert args == ("hello",)
    assert kwargs == {"cruel": "world"}
    return "called with args and kwargs"
"#;

Python::with_gil(|py| {
    let module = PyModule::from_code(py, CODE, "", "")?;
    let fun = module.getattr("function")?;
    let args = ("hello",);
    let kwargs = PyDict::new(py);
    kwargs.set_item("cruel", "world")?;
    let result = fun.call(args, Some(kwargs))?;
    assert_eq!(result.extract::<&str>()?, "called with args and kwargs");
    Ok(())
})

Calls the object without arguments.

This is equivalent to the Python expression self().

Examples
use pyo3::prelude::*;

Python::with_gil(|py| -> PyResult<()> {
    let module = PyModule::import(py, "builtins")?;
    let help = module.getattr("help")?;
    help.call0()?;
    Ok(())
})?;

This is equivalent to the Python expression help().

Calls the object with only positional arguments.

This is equivalent to the Python expression self(*args).

Examples
use pyo3::prelude::*;

const CODE: &str = r#"
def function(*args, **kwargs):
    assert args == ("hello",)
    assert kwargs == {}
    return "called with args"
"#;

Python::with_gil(|py| {
    let module = PyModule::from_code(py, CODE, "", "")?;
    let fun = module.getattr("function")?;
    let args = ("hello",);
    let result = fun.call1(args)?;
    assert_eq!(result.extract::<&str>()?, "called with args");
    Ok(())
})

Calls a method on the object.

This is equivalent to the Python expression self.name(*args, **kwargs).

To avoid repeated temporary allocations of Python strings, the [intern!] macro can be used to intern name.

Examples
use pyo3::prelude::*;
use pyo3::types::PyDict;

const CODE: &str = r#"
class A:
    def method(self, *args, **kwargs):
        assert args == ("hello",)
        assert kwargs == {"cruel": "world"}
        return "called with args and kwargs"
a = A()
"#;

Python::with_gil(|py| {
    let module = PyModule::from_code(py, CODE, "", "")?;
    let instance = module.getattr("a")?;
    let args = ("hello",);
    let kwargs = PyDict::new(py);
    kwargs.set_item("cruel", "world")?;
    let result = instance.call_method("method", args, Some(kwargs))?;
    assert_eq!(result.extract::<&str>()?, "called with args and kwargs");
    Ok(())
})

Calls a method on the object without arguments.

This is equivalent to the Python expression self.name().

To avoid repeated temporary allocations of Python strings, the [intern!] macro can be used to intern name.

Examples
use pyo3::prelude::*;

const CODE: &str = r#"
class A:
    def method(self, *args, **kwargs):
        assert args == ()
        assert kwargs == {}
        return "called with no arguments"
a = A()
"#;

Python::with_gil(|py| {
    let module = PyModule::from_code(py, CODE, "", "")?;
    let instance = module.getattr("a")?;
    let result = instance.call_method0("method")?;
    assert_eq!(result.extract::<&str>()?, "called with no arguments");
    Ok(())
})

Calls a method on the object with only positional arguments.

This is equivalent to the Python expression self.name(*args).

To avoid repeated temporary allocations of Python strings, the [intern!] macro can be used to intern name.

Examples
use pyo3::prelude::*;

const CODE: &str = r#"
class A:
    def method(self, *args, **kwargs):
        assert args == ("hello",)
        assert kwargs == {}
        return "called with args"
a = A()
"#;

Python::with_gil(|py| {
    let module = PyModule::from_code(py, CODE, "", "")?;
    let instance = module.getattr("a")?;
    let args = ("hello",);
    let result = instance.call_method1("method", args)?;
    assert_eq!(result.extract::<&str>()?, "called with args");
    Ok(())
})

Returns whether the object is considered to be true.

This is equivalent to the Python expression bool(self).

Returns whether the object is considered to be None.

This is equivalent to the Python expression self is None.

Returns true if the sequence or mapping has a length of 0.

This is equivalent to the Python expression len(self) == 0.

Gets an item from the collection.

This is equivalent to the Python expression self[key].

Sets a collection item value.

This is equivalent to the Python expression self[key] = value.

Deletes an item from the collection.

This is equivalent to the Python expression del self[key].

Takes an object and returns an iterator for it.

This is typically a new iterator but if the argument is an iterator, this returns itself.

Returns the Python type object for this object’s type.

Returns the Python type pointer for this object.

Casts self to a concrete Python object type.

This can cast only to native Python types, not types implemented in Rust.

Extracts some type from the Python object.

This is a wrapper function around FromPyObject::extract().

Returns the reference count for the Python object.

Computes the “repr” representation of self.

This is equivalent to the Python expression repr(self).

Computes the “str” representation of self.

This is equivalent to the Python expression str(self).

Retrieves the hash code of self.

This is equivalent to the Python expression hash(self).

Returns the length of the sequence or mapping.

This is equivalent to the Python expression len(self).

Returns the list of attributes of this object.

This is equivalent to the Python expression dir(self).

Checks whether this object is an instance of type ty.

This is equivalent to the Python expression isinstance(self, ty).

Checks whether this object is an instance of type T.

This is equivalent to the Python expression isinstance(self, T), if the type T is known at compile time.

Determines if self contains value.

This is equivalent to the Python expression value in self.

Returns a GIL marker constrained to the lifetime of this type.

Return a proxy object that delegates method calls to a parent or sibling class of type.

This is equivalent to the Python expression super()

Trait Implementations

Formats the value using the given formatter. Read more
The resulting type after dereferencing.
Dereferences the value.
Executes the destructor for this type. Read more
Extracts Self from the source PyObject.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.