The Python Architecture: Why It Works So Elegantly

Python's data model for MATLAB and DSP engineers: a free guide to dunder methods, protocols, descriptors and CPython internals.

Read it online · Download the PDF

Much of Python's elegance comes from one design decision: the syntax is fixed, but what the syntax does is decided by your objects. This guide starts from that idea and follows it down to the C structs in CPython and up to a working signal-processing block.

Questions it answers

• How does self get filled in, when Python has no special machinery for methods?
• What is a descriptor, and how do property, classmethod and staticmethod use them?
• Why does 3 * Gain(2) work, when int was written decades before your class?
• Why does giving one object its own __len__ do nothing?
• Why can two small methods make for, in, reversed, sorted and max all work on your class?
• Why does x * my_object sometimes return a slow NumPy array of dtype object, and how do you stop it?
• How do you build a MATLAB System object in Python, with nontunable properties and setupImpl/stepImpl?
• Is Python fast enough compared with MATLAB, and when do you need Numba, CuPy, Cython or pybind11?
• What does this design cost you, from the GIL to memory use and late errors?

Who it's for

Engineers who can already write Python, or who are moving to it from MATLAB, C, C++ or Java, and want to understand why it behaves as it does. The examples come from DSP and GNSS work, such as filters, delay lines and streaming large recordings, but the Python applies to any field.

What's inside

1. The Core Philosophy: Fixed Syntax, Pluggable Behavior: dunder methods and protocols
2. Under the Hood: The C-Struct Architecture: PyObject, reference counting and garbage collection
3. The Grand Unification: Two Pillars and a Keystone: descriptors, bound methods and namespaces
4. Deep Dive: First-Class Objects: closures, and Python compared with C, C++ and Java
5. Conceptual Paradigm: Python as a Plugin Architecture: duck typing and abstract base classes
6. The Data Model, Protocols and Dunder Methods: operator dispatch, context managers and __array_ufunc__
7. Python as an ICD: The Client/Supplier Dynamic: the data model as an interface contract
8. The Golden Rule of Dunders: when to call them directly, and when not to
9. Practical Synthesis: The MATLAB System Object in Python: a full worked example with a delay line
10. IDE Integration and Essential Protocols: The Cheat Sheet: type hints, generators and __slots__
11. Performance Reality: Python vs. MATLAB: measured NumPy overhead, Numba, CuPy and GPU code
12. What the Design Costs: the GIL, memory, late errors and the limits of the model
13. Epilogue: Why "Data Model"?

Building it yourself

The guide is one Markdown file, The Python Architecture Why It Works So Elegantly.md. build.py turns it into the website and PDF in _site/, and every push to main deploys them to GitHub Pages.

PDF generation needs WeasyPrint's system dependencies. With those installed, using Python 3.12:

python -m venv .venv
source .venv/bin/activate        # Windows (Git Bash): source .venv/Scripts/activate
pip install -r requirements.txt
python build.py