Skip to main content

Crate fhy_core_py

Crate fhy_core_py 

Source
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 the fhy-core-ext crate, whose one #[pymodule] calls register;
  • an aggregate extension for a downstream product is a cdylib whose #[pymodule] calls register and then its own crates’ registration functions, and takes and returns fhy-core values through convert. Its classes are written over the building blocks of util, as fhy_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 and fhy-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 $name of 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 register was called on that holds this crate’s version, which is fhy_core’s.

Functions§

register
Add every class, function and piece of module state of fhy_core’s binding to module.