Struct pyo3::prelude::PyModule

#[repr(transparent)]
pub struct PyModule(_);

Represents a Python module object.

Implementations

impl PyModule

pub fn new<'p>(py: Python<'p>, name: &str) -> PyResult<&'p PyModule>

Creates a new module object with the __name__ attribute set to name.

pub fn import<'p>(py: Python<'p>, name: &str) -> PyResult<&'p PyModule>

Imports the Python module with the specified name.

pub fn from_code<'p>(
    py: Python<'p>,
    code: &str,
    file_name: &str,
    module_name: &str
) -> PyResult<&'p PyModule>

Loads the Python code specified into a new module.

code is the raw Python you want to load into the module. file_name is the file name to associate with the module (this is used when Python reports errors, for example). module_name is the name to give the module.

pub fn dict(&self) -> &PyDict

Return the dictionary object that implements module’s namespace; this object is the same as the __dict__ attribute of the module object.

pub fn index(&self) -> PyResult<&PyList>

Return the index (__all__) of the module, creating one if needed.

pub fn name(&self) -> PyResult<&str>

Returns the module’s name.

May fail if the module does not have a __name__ attribute.

pub fn filename(&self) -> PyResult<&str>

Returns the module’s filename.

May fail if the module does not have a __file__ attribute.

pub fn call(
    &self,
    name: &str,
    args: impl IntoPy<Py<PyTuple>>,
    kwargs: Option<&PyDict>
) -> PyResult<&PyAny>

Calls a function in the module.

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

pub fn call1(
    &self,
    name: &str,
    args: impl IntoPy<Py<PyTuple>>
) -> PyResult<&PyAny>

Calls a function in the module with only positional arguments.

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

pub fn call0(&self, name: &str) -> PyResult<&PyAny>

Calls a function in the module without arguments.

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

pub fn get(&self, name: &str) -> PyResult<&PyAny>

Gets a member from the module.

This is equivalent to the Python expression module.name.

pub fn add<V>(&self, name: &str, value: V) -> PyResult<()> where
    V: IntoPy<PyObject>, 

Adds a member to the module.

This is a convenience function which can be used from the module’s initialization function.

pub fn add_class<T>(&self) -> PyResult<()> where
    T: PyClass, 

Adds a new extension type to the module.

This is a convenience function that initializes the class, sets new_type.__module__ to this module’s name, and adds the type to this module.

pub fn add_wrapped<'a, T>(
    &'a self,
    wrapper: &impl Fn(Python<'a>) -> T
) -> PyResult<()> where
    T: IntoPyCallbackOutput<PyObject>, 

Adds a function or a (sub)module to a module, using the functions name as name.

Use this together with the#[pyfunction] and wrap_pyfunction! or #[pymodule] and wrap_pymodule!.

use pyo3::prelude::*;
#[pymodule]
fn utils(_py: Python, _module: &PyModule) -> PyResult<()> {
    Ok(())
}

#[pyfunction]
fn double(x: usize) -> usize {
    x * 2
}
#[pymodule]
fn top_level(_py: Python, module: &PyModule) -> PyResult<()> {
    module.add_wrapped(pyo3::wrap_pymodule!(utils))?;
    module.add_wrapped(pyo3::wrap_pyfunction!(double))
}

You can also add a function with a custom name using add:

m.add("also_double", wrap_pyfunction!(double)(m)?)?;

This function will be deprecated in the next release. Please use the specific PyModule::add_function and PyModule::add_submodule functions instead.

pub fn add_submodule(&self, module: &PyModule) -> PyResult<()>

Add a submodule to a module.

Use this together with #[pymodule] and wrap_pymodule!.

use pyo3::prelude::*;

fn init_utils(module: &PyModule) -> PyResult<()> {
    module.add("super_useful_constant", "important")
}
#[pymodule]
fn top_level(py: Python, module: &PyModule) -> PyResult<()> {
    let utils = PyModule::new(py, "utils")?;
    init_utils(utils)?;
    module.add_submodule(utils)
}

pub fn add_function<'a>(&'a self, fun: &'a PyCFunction) -> PyResult<()>

Add a function to a module.

Use this together with the#[pyfunction] and wrap_pyfunction!.

use pyo3::prelude::*;
#[pyfunction]
fn double(x: usize) -> usize {
    x * 2
}
#[pymodule]
fn double_mod(_py: Python, module: &PyModule) -> PyResult<()> {
    module.add_function(pyo3::wrap_pyfunction!(double, module)?)
}

You can also add a function with a custom name using add:

use pyo3::prelude::*;
#[pyfunction]
fn double(x: usize) -> usize {
    x * 2
}
#[pymodule]
fn double_mod(_py: Python, module: &PyModule) -> PyResult<()> {
    module.add("also_double", pyo3::wrap_pyfunction!(double, module)?)
}

Methods from Deref<Target = PyAny>

pub fn downcast<T>(&self) -> Result<&T, PyDowncastError<'_>> where
    for<'py> T: PyTryFrom<'py>, 

Convert this PyAny to a concrete Python type.

pub fn hasattr<N>(&self, attr_name: N) -> PyResult<bool> where
    N: ToPyObject, 

Determines whether this object has the given attribute.

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

pub fn getattr<N>(&self, attr_name: N) -> PyResult<&PyAny> where
    N: ToPyObject, 

Retrieves an attribute value.

This is equivalent to the Python expression self.attr_name.

pub fn setattr<N, V>(&self, attr_name: N, value: V) -> PyResult<()> where
    N: ToBorrowedObject,
    V: ToBorrowedObject, 

Sets an attribute value.

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

pub fn delattr<N>(&self, attr_name: N) -> PyResult<()> where
    N: ToPyObject, 

Deletes an attribute.

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

pub fn compare<O>(&self, other: O) -> PyResult<Ordering> where
    O: ToPyObject, 

Compares two Python objects.

This is equivalent to:

if self == other:
    return Equal
elif a < b:
    return Less
elif a > b:
    return Greater
else:
    raise TypeError("PyAny::compare(): All comparisons returned false")

pub fn rich_compare<O>(
    &self,
    other: O,
    compare_op: CompareOp
) -> PyResult<&PyAny> where
    O: ToPyObject, 

Compares two Python objects.

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

• CompareOp::Eq: self == other
• CompareOp::Ne: self != other
• CompareOp::Lt: self < other
• CompareOp::Le: self <= other
• CompareOp::Gt: self > other
• CompareOp::Ge: self >= other

pub fn is_callable(&self) -> bool

Determines whether this object is callable.

pub fn call(
    &self,
    args: impl IntoPy<Py<PyTuple>>,
    kwargs: Option<&PyDict>
) -> PyResult<&PyAny>

Calls the object.

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

pub fn call0(&self) -> PyResult<&PyAny>

Calls the object without arguments.

This is equivalent to the Python expression self().

pub fn call1(&self, args: impl IntoPy<Py<PyTuple>>) -> PyResult<&PyAny>

Calls the object with only positional arguments.

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

pub fn call_method(
    &self,
    name: &str,
    args: impl IntoPy<Py<PyTuple>>,
    kwargs: Option<&PyDict>
) -> PyResult<&PyAny>

Calls a method on the object.

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

Example

use pyo3::types::IntoPyDict;

let gil = Python::acquire_gil();
let py = gil.python();
let list = vec![3, 6, 5, 4, 7].to_object(py);
let dict = vec![("reverse", true)].into_py_dict(py);
list.call_method(py, "sort", (), Some(dict)).unwrap();
assert_eq!(list.extract::<Vec<i32>>(py).unwrap(), vec![7, 6, 5, 4, 3]);

let new_element = 1.to_object(py);
list.call_method(py, "append", (new_element,), None).unwrap();
assert_eq!(list.extract::<Vec<i32>>(py).unwrap(), vec![7, 6, 5, 4, 3, 1]);

pub fn call_method0(&self, name: &str) -> PyResult<&PyAny>

Calls a method on the object without arguments.

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

pub fn call_method1(
    &self,
    name: &str,
    args: impl IntoPy<Py<PyTuple>>
) -> PyResult<&PyAny>

Calls a method on the object with only positional arguments.

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

pub fn is_true(&self) -> PyResult<bool>

Returns whether the object is considered to be true.

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

pub fn is_none(&self) -> bool

Returns whether the object is considered to be None.

This is equivalent to the Python expression self is None.

pub fn is_empty(&self) -> PyResult<bool>

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

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

pub fn get_item<K>(&self, key: K) -> PyResult<&PyAny> where
    K: ToBorrowedObject, 

Gets an item from the collection.

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

pub fn set_item<K, V>(&self, key: K, value: V) -> PyResult<()> where
    K: ToBorrowedObject,
    V: ToBorrowedObject, 

Sets a collection item value.

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

pub fn del_item<K>(&self, key: K) -> PyResult<()> where
    K: ToBorrowedObject, 

Deletes an item from the collection.

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

pub fn iter(&self) -> PyResult<&PyIterator>

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.

pub fn get_type(&self) -> &PyType

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

pub fn get_type_ptr(&self) -> *mut PyTypeObject

Returns the Python type pointer for this object.

pub fn cast_as<'a, D>(&'a self) -> Result<&'a D, PyDowncastError<'_>> where
    D: PyTryFrom<'a>, 

Casts the PyObject to a concrete Python object type.

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

pub fn extract<'a, D>(&'a self) -> PyResult<D> where
    D: FromPyObject<'a>, 

Extracts some type from the Python object.

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

pub fn get_refcnt(&self) -> isize

Returns the reference count for the Python object.

pub fn repr(&self) -> PyResult<&PyString>

Computes the “repr” representation of self.

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

pub fn str(&self) -> PyResult<&PyString>

Computes the “str” representation of self.

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

pub fn hash(&self) -> PyResult<isize>

Retrieves the hash code of self.

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

pub fn len(&self) -> PyResult<usize>

Returns the length of the sequence or mapping.

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

pub fn dir(&self) -> &PyList

Returns the list of attributes of this object.

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

pub fn is_instance<T: PyTypeObject>(&self) -> PyResult<bool>

Checks whether this object is an instance of type T.

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

Trait Implementations

impl AsPyPointer for PyModule

fn as_ptr(&self) -> *mut PyObject

Gets the underlying FFI pointer, returns a borrowed pointer.

impl AsRef<PyAny> for PyModule

fn as_ref(&self) -> &PyAny

Performs the conversion.

impl Debug for PyModule

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Deref for PyModule

type Target = PyAny

The resulting type after dereferencing.

fn deref(&self) -> &PyAny

Dereferences the value.

impl Display for PyModule

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<&'_ PyModule> for Py<PyModule>

fn from(other: &PyModule) -> Self

Performs the conversion.

impl<'a> From<&'a PyModule> for &'a PyAny

fn from(ob: &'a PyModule) -> Self

Performs the conversion.

impl<'py> FromPyObject<'py> for &'py PyModule

fn extract(obj: &'py PyAny) -> PyResult<Self>

Extracts Self from the source PyObject.

impl IntoPy<Py<PyModule>> for &PyModule

fn into_py(self, py: Python<'_>) -> Py<PyModule>

Performs the conversion.

impl PartialEq<PyModule> for PyModule

fn eq(&self, o: &PyModule) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl PyLayout<PyModule> for PyObject

const IS_NATIVE_TYPE: bool

fn get_super(&mut self) -> Option<&mut T::BaseLayout>

fn py_init(&mut self, _value: T)

unsafe fn py_drop(&mut self, _py: Python<'_>)

impl PyNativeType for PyModule

fn py(&self) -> Python<'_>

unsafe fn unchecked_downcast(obj: &PyAny) -> &Self

Cast &PyAny to &Self without no type checking.

impl PyTypeInfo for PyModule

type Type = ()

Type of objects to store in PyObject struct

type BaseType = PyAny

Base class

type Layout = PyObject

Layout

type BaseLayout = PyObject

Layout of Basetype.

type Initializer = PyNativeTypeInitializer<Self>

Initializer for layout

type AsRefTarget = Self

Utility type to make Py::as_ref work

const NAME: &'static str

Class name

const MODULE: Option<&'static str>

Module name, if any

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

PyTypeObject instance for this type.

fn is_type_of(ptr: &PyAny) -> bool

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

const DESCRIPTION: &'static str

Class doc string

const FLAGS: usize

Type flags (ie PY_TYPE_FLAG_GC, PY_TYPE_FLAG_WEAKREF)

fn is_exact_type_of(object: &PyAny) -> bool

Checks if object is an instance of this type.

impl ToPyObject for PyModule

fn to_object(&self, py: Python<'_>) -> PyObject

Converts self into a Python object.