pyo3/guide/pyclass_parameters.md
Georg Brandl a7a53d6c0d Add a nox task to rustfmt code in the guide.
Also apply it. Two caveats:

1) needs nightly rustfmt to be available
2) not all reformat diffs have been applied; using best judgment for readability.
2022-11-22 09:19:40 +01:00

3.2 KiB

#[pyclass] can be used with the following parameters:

Parameter Description
crate = "some::path" Path to import the pyo3 crate, if it's not accessible at ::pyo3.
dict Gives instances of this class an empty __dict__ to store custom attributes.
extends = BaseType Use a custom baseclass. Defaults to PyAny
freelist = N Implements a free list of size N. This can improve performance for types that are often created and deleted in quick succession. Profile your code to see whether freelist is right for you.
frozen Declares that your pyclass is immutable. It removes the borrowchecker overhead when retrieving a shared reference to the Rust struct, but disables the ability to get a mutable reference.
get_all Generates getters for all fields of the pyclass.
mapping Inform PyO3 that this class is a Mapping, and so leave its implementation of sequence C-API slots empty.
module = "module_name" Python code will see the class as being defined in this module. Defaults to builtins.
name = "python_name" Sets the name that Python sees this class as. Defaults to the name of the Rust struct.
sequence Inform PyO3 that this class is a Sequence, and so leave its C-API mapping length slot empty.
set_all Generates setters for all fields of the pyclass.
subclass Allows other Python classes and #[pyclass] to inherit from this class. Enums cannot be subclassed.
text_signature = "(arg1, arg2, ...)" Sets the text signature for the Python class' __new__ method.
unsendable Required if your struct is not Send. Rather than using unsendable, consider implementing your struct in a threadsafe way by e.g. substituting Rc with Arc. By using unsendable, your class will panic when accessed by another thread.
weakref Allows this class to be weakly referenceable.

All of these parameters can either be passed directly on the #[pyclass(...)] annotation, or as one or more accompanying #[pyo3(...)] annotations, e.g.:

// Argument supplied directly to the `#[pyclass]` annotation.
#[pyclass(name = "SomeName", subclass)]
struct MyClass {}

// Argument supplied as a separate annotation.
#[pyclass]
#[pyo3(name = "SomeName", subclass)]
struct MyClass {}