Every module displayif registers uses MP_REGISTER_MODULE, which makes it a
non-extensible builtin. MicroPython resolves those before the filesystem is
consulted at all (py/builtinimport.c):
// An import of a non-extensible built-in will always bypass the
// filesystem. e.g. `import micropython` or `import pyb`. So try and
// match a non-extensible built-ins first.
module_obj = mp_module_get_builtin(level_mod_name, false);
if (module_obj != MP_OBJ_NULL) {
return module_obj;
}
// Next try the filesystem. Search for a directory or file relative to
// all the locations in sys.path.
So import spibus cannot reach a spibus.py on the device, no matter where it
sits on sys.path — the filesystem root included. MP_REGISTER_EXTENSIBLE_MODULE
reverses that: the filesystem is searched first and the builtin is the fallback.
Affects spibus, i2cbus, qspibus, rgbmatrix, and the notimpl stubs
(picodvi, dotclockframebuffer, mipidsi, i80bus).
Why it might be worth changing
- A user could override a C driver with a Python one to debug it, or ship a
fixed version, without rebuilding firmware.
pydevices ships a pure-Python spibus; today it is dead code on any
firmware carrying displayif, because the builtin always wins.
- The
notimpl stubs are the strongest case: their whole job is to raise on
unsupported ports. A Python implementation on the filesystem cannot currently
replace one.
Why it might not
- Extensible lookup stats the filesystem on every import of these names, so
every board pays a small startup cost so that overriding is possible.
- A stray
spibus.py in someone's project directory would silently shadow the C
driver, and the failure would look like a driver bug. Today that cannot
happen.
- It changes import semantics for every displayif module at once.
No recommendation. Raised while looking for a way to A/B the C spibus against
the Python one; that comparison does not need this — a renamed copy works — so
this is a question about what displayif wants its modules to be, not a
blocker. Brad, 2026-09-10.
Every module displayif registers uses
MP_REGISTER_MODULE, which makes it anon-extensible builtin. MicroPython resolves those before the filesystem is
consulted at all (
py/builtinimport.c):So
import spibuscannot reach aspibus.pyon the device, no matter where itsits on
sys.path— the filesystem root included.MP_REGISTER_EXTENSIBLE_MODULEreverses that: the filesystem is searched first and the builtin is the fallback.
Affects
spibus,i2cbus,qspibus,rgbmatrix, and thenotimplstubs(
picodvi,dotclockframebuffer,mipidsi,i80bus).Why it might be worth changing
fixed version, without rebuilding firmware.
pydevicesships a pure-Pythonspibus; today it is dead code on anyfirmware carrying displayif, because the builtin always wins.
notimplstubs are the strongest case: their whole job is to raise onunsupported ports. A Python implementation on the filesystem cannot currently
replace one.
Why it might not
every board pays a small startup cost so that overriding is possible.
spibus.pyin someone's project directory would silently shadow the Cdriver, and the failure would look like a driver bug. Today that cannot
happen.
No recommendation. Raised while looking for a way to A/B the C
spibusagainstthe Python one; that comparison does not need this — a renamed copy works — so
this is a question about what displayif wants its modules to be, not a
blocker. Brad, 2026-09-10.