How the Python binding is created

Simplified overview

graph libnopegl_install(libnopegl install) pynopegl_setup(pynopegl cython(Cython) cc(C compiler) specs(nodes.specs) c(_pynopegl.c) pyx(nodes_def.pyx) mod( pymod(pynopegl) libnopegl_install -- write --> specs pynopegl_setup -- read --> specs pynopegl_setup -- write --> pyx cython -- read --> pyx cython -- write --> c cc -- read --> c cc -- write --> mod pymod -- import --> mod classDef installers fill:#8ee5ee,color:#222 classDef ctools fill:#ee6aa7,color:#222 classDef files fill:#7cfc00,color:#222 class libnopegl_install,pynopegl_setup installers class cython,cc ctools class specs,c,pyx files style mod fill:#ffd700,color:#222 style pymod fill:#ff7f50,color:#222

Detailed steps

libnopegl → nodes.specs

libnopegl writes the nodes.specs specifications in JSON using a dedicated tool (gen_specs.c) crawling the internal node C definitions.

This generated nodes.specs file (see updatespecs build rule in libnopegl’s generated Makefile) is installed on the system or targeted environment by the install rule.

nodes.specs ← pynopegl

In its, pynopegl uses pkg-config to query the libnopegl installation data directory, in order to obtain the path to the installed nodes.specs file. The file is then loaded as JSON file.

pynopegl → nodes_def.pyx

Using the loaded nodes.specs as JSON, writes the Cython code definitions into a nodes_def.pyx file.

nodes_def.pyx ← Cython

The setuptools module used to package pynopegl calls Cython to read the generated .pyx file (along with _pynopegl.pyx).

Cython → _pynopegl.c

From the .pyx files, Cython will generate a C source code using the C Python API. This source file declares the Python classes calling the libnopegl C functions, based on the rules contained in the .pyx files.

_pynopegl.c ← C compiler

In the Cython toolchain triggered by the setuptools, a C compiler will compile the generated C source.

C compiler →

Compiled source ends up being linked against Python library to create a loadable Python module.

pynopegl ←

The final binding exposed to the user is a traditional pure Python module, which imports the native _pynopegl module. All the nodes and their methods are dynamically generated into that module at runtime.