The CPython port

The CPython port packages LVGL for CPython as the native lvgl extension, distributed under the omnipython-lvgl project name. It exposes the same Python-shaped API as the MicroPython and CircuitPython targets, and it does not embed or run a MicroPython interpreter.

Most people install a prebuilt wheel and import lvgl as lv: they never clone the repository or compile LVGL. Install shows how.

What is generated and what is written by hand

The port’s own code is the CPython runtime layer in ports/cpython/src/, and its tests. The binding itself is generated, from the same API model as the MicroPython and CircuitPython builds, and is not edited by hand.

binding/ (generator and API policy)
        |
        | ./regenerate_all.sh --target cpython
        v
omnipython-lvgl
  |-- generated/lvgl_python.c and lvgl.pyi   generated binding surface
  |-- ports/cpython/src/lvpy_runtime.c       CPython ownership, callbacks, locking
  |-- lvgl/                                  pinned upstream C submodule
  `-- setup.py                               compiles one CPython extension
        |
        v
import lvgl as lv
  |-- generated wrappers convert Python arguments and results
  |-- runtime wrappers manage objects, structs, the GIL and callback lifetime
  `-- the LVGL C core owns widgets, displays, rendering and event dispatch

The public API is generated. The lifecycle, ownership and concurrency behavior behind it is CPython runtime work, in ports/cpython/src/lvpy_runtime.*.

A call from Python into LVGL

  1. The wheel provides the binary module lvgl. Importing it exposes the generated module surface: LVGL-style enum namespaces, functions, object constructors and struct methods, rather than a separate Python UI model.

  2. Widget constructors and methods enter the generated wrappers. They validate and convert Python values, take the runtime’s LVGL lock where needed, and call the matching LVGL C function.

  3. The extension does not choose a display, an event loop or a board. With omnipython installed, its display_driver wires one up; without it you give LVGL a buffer and a flush callback.

Rules the runtime keeps

  • Pair lv.init() and lv.deinit() in standalone programs. Callback cleanup during interpreter shutdown is covered by the tests.

  • A callback belongs to its registration, not to the widget’s Python wrapper. mp_lv_callback stores it in a dict that LVGL’s event descriptor points at, and the runtime drops that dict’s one reference when the event is removed or the object deleted. The drop waits until no LVGL call or Python callback is in flight, because LVGL sends LV_EVENT_DELETE to the runtime’s hook before the user’s. Dropping the wrapper neither stops nor leaks the callback.

  • A struct’s callbacks share one dict reference, owned by the struct. lv_anim_t and lv_timer_t callbacks work this way: the generated setters pass the struct as containing_struct. A Python-owned struct releases the reference in its dealloc; a timer and each running copy of an animation release theirs through LVGL’s ext_data free callback (lvpy_timer_bind, lvpy_anim_bind), which needs LV_USE_EXT_DATA, set for the CPython build only.

  • Unsafe C signatures stay out. Unbounded pointer-to-pointer and variadic APIs are omitted unless a conversion has been reviewed, even if that leaves the C surface looking incomplete.

  • Availability can differ by target. The project shares naming and API policy with the other runtimes, but it is a CPython extension, and a feature may be explicitly different on another target.

Threads

LVGL is not thread-safe and the binding keeps shared state of its own, so one thread drives it. Use LVGL from threads explains the rule and what it means on a free-threaded build.