Concepts
Design principles
The eight rules that guide the public API.
- No required application base class. Compose objects instead of subclassing the app. Sources, targets and filters need no inherited base or plugin registry. Control maps are plain data, often kept in TOML files. The one exception is
Outlet. Anything you write against a shape is a structuralProtocoland needs no base. This applies toSource,TargetandVectorFilter.Outletis a base class because it contains shared running code. It is not a shape. It provides a paced daemon thread with compensated timing, a latest-wins slot and per-error-kind deduplication. The alternative to inheriting it is copying it once per transport. Subclass it to add_send. Nothing else in the library asks you to subclass anything. - User code is plain functions,
extract(),train(),predict(). - Every public function has typed arguments and a typed return.
- One name, one meaning. No overloaded types.
- Errors tell you what to write. A description of what went wrong is insufficient.
- The entire public API fits on one page.
- Each widget is a plain public class with a
.ui()method, no widget base class. Implementation may be split into a private subpackage of_<aspect>.pyhelpers (state, plot, controls) when a widget grows beyond ~200 LOC. Seewidgets/signals/viewer.pyplus its_state.py/_plot.py/_controls.pyhelpers for the reference pattern. Aim to keep the public entry file under 200 lines and any single helper under ~350. - Immediate-mode rendering. Widget state lives on the instance or in a private helper module keyed by widget identity.
These rules keep application code small. Compose the framework objects, keep domain logic in functions, and draw each widget through .ui() without a required widget base class.