Expand description
PyO3 bindings for fhy-core’s Rust implementation, as a library that a
Python extension module is composed from.
§Composition
Each PyO3 extension module links its own copy of every Rust crate it
uses, so two extension modules that both link fhy-core in one Python
process hold two identifier id counters, two registries per interned
type and two sets of Python classes. This crate therefore builds no
extension module itself. It is an rlib that adds its classes and
functions to a module it is given, so that one cdylib per product
links fhy-core, this crate, and the binding crates of the packages that
build on fhy_core, and registers all of them into one module:
fhy_core’s own extension,fhy_core._rs, is thefhy-core-extcrate, whose one#[pymodule]callsregister;- an aggregate extension for a downstream product is a
cdylibwhose#[pymodule]callsregisterand then its own crates’ registration functions, and takes and returnsfhy-corevalues throughconvert. Its classes are written over the building blocks ofutil, asfhy_core’s are.
The split into a library and a thin cdylib is deliberate. A #[pymodule]
exports a PyInit_<name> symbol, which an rlib that is linked into an
aggregate would export from it too, so a crate that is both the module and
the library cannot be linked into an aggregate whose module has the same
name, and every aggregate would export a second module’s initializer.
§Class identity
Every #[pyclass] here names its module explicitly, module = "fhy_core._rs", and so keeps the qualified name users see, such as
fhy_core._rs.Param, whichever native module holds it: __module__,
repr, and pickle, which imports the class by that name, all follow
it. The binding also finds its own module state by that name, through
sys.modules["fhy_core._rs"]. An aggregate module is therefore
installed as fhy_core._rs as well as under its own name, which
fhy_core._extension does when it loads the module: the loader documents
the protocol.
§Module state and version
register creates the verification registry of the Python API and
the kind registry of fhy_core.search_space in the module’s state, and
sets VERSION_ATTRIBUTE, the version of this crate,
which the loader compares with the installed package’s. It refuses a
module it has registered into already.
Modules§
- convert
- The conversions between
fhy_core’s Python objects andfhy-core’s Rust values that a downstream binding crate needs to accept and return them. - util
- The building blocks of a Rust-backed Python class, for the binding crates
of the packages that build on
fhy_core.
Macros§
- cached_
attr - Return the attribute
$nameof the module$module, imported once for this call site:cached_attr!(py, "fhy_core.types", "Type"), or with a type,cached_attr!(py, "fhy_core.types", "Type" => PyType).
Constants§
- VERSION_
ATTRIBUTE - The attribute of a module
registerwas called on that holds this crate’s version, which isfhy_core’s.
Functions§
- register
- Add every class, function and piece of module state of
fhy_core’s binding tomodule.