An interactive visual guide and laboratory for mastering Python & CPython 3.12 internals.
Explore bytecode execution, memory layout, PyObjects, garbage collection, the GIL, asyncio, and Big-O with real-time animated diagrams and code simulations.
Most developers know how to write Python, but few understand what actually happens inside the CPython runtime when code executes.
Python Internals Visualized bridges that gap. It replaces dry textbook theory with an interactive, animated visual studio that breaks down low-level mechanisms into two distinct perspectives:
- 💡 Simple Analogy: Intuitive, plain-English mental models (sticky notes, boxes, bookmarks).
- ⚙️ Under the Hood: Deep CPython C-structs, opcodes, and memory allocations (
PyObject,ob_refcnt,_PyEval_EvalFrameDefault,PyCellObject).
- Live Animated SVG Architecture: Watch data packets move along quadratic bezier curves in real time using requestAnimationFrame.
- Node Inspector: Click any stage (Lexer, AST, Bytecode, PVM stack) to inspect its exact CPython function and internal role.
- Interactive Controls: Adjust animation speeds (
0.5x,1x,2x), pause at any frame, or replay from the beginning. - Dual Explanations: Seamlessly toggle between "Simple Analogy" and "Under the Hood" for every single step.
- Concept Guide & Examples: Comprehensive definition, detailed breakdown, and 2 practical Python examples with exact outputs and notes for all 28 topics.
An interactive memory visualizer that runs Python statements line-by-line and maps stack names to heap PyObject pointers and reference counters:
- List Aliasing vs
.copy(): Visualize shared references vs shallow clones. - Small Int Interning (-5 to 256): See CPython's pre-allocated singleton cache in action.
- Mutable Default Arguments: Learn why
def fn(bag=[]):shares state across invocations. - Closure Cell Capture: Watch
PyCellObjectkeep variables alive after the enclosing function exits. - Supports Auto-Play and manual single-step execution.
- Test your mental models on real-world tricky Python scenarios:
- Reference aliasing & mutability
- List
insert(0)vsappend()time complexity - GIL release during blocking I/O syscalls
- Generator frame suspension on
yield
- Real-time score tracking with instant feedback and in-depth explanations for every choice.
- Big-O Complexities: Indexing, searching, appending, and slicing across Lists, Dicts, and Sets.
- Core Dunder Protocols:
__repr__,__eq__,__len__,__iter__,__enter__/__exit__. - Concurrency Decision Matrix: When to choose
asyncio,ThreadPoolExecutor,ProcessPoolExecutor, or NumPy. - Standard Collections:
deque,Counter,defaultdict,heapq. - Memory &
__slots__: Eliminating per-instance__dict__overhead.
- Instant fuzzy search across all 28 lessons, concept definitions, and step mechanisms with keyboard arrow navigation.
| Module | Lesson | Level | Key Concepts Covered |
|---|---|---|---|
| 01. Execution & Memory | How Python Runs Code | Beginner | Lexer, Tokens, PEG Parser, AST, Bytecode (.pyc), PVM Eval Loop |
| Everything Is an Object | Beginner | PyObject, ob_refcnt, ob_type, id(), arbitrary-precision PyLongObject |
|
| Variables & References | Beginner | Name binding, sticky-note model, is vs ==, shallow vs deep copy |
|
| Garbage Collection | Intermediate | Reference counting, zero-count reclamation, cyclic GC (Gen 0, 1, 2) | |
| 02. Core Data Structures | Lists & Dynamic Arrays | Beginner | Contiguous pointer arrays, 12.5% over-allocation, amortized O(1) append |
| Dicts & Hash Tables | Intermediate | Compact hash table layout (Python 3.7+), open addressing, probing | |
| Tuples, Sets & Strings | Beginner | Immutability optimizations, hash sets, O(1) membership, string interning | |
| Comprehensions & Generators | Beginner | Eager list allocation vs lazy generator O(1) memory evaluation | |
| 03. Functions & Scope | Call Stack & Frames | Beginner | PyFrameObject, LOAD_FAST locals array, recursion depth limit |
| LEGB Scope & Closures | Intermediate | Local, Enclosing, Global, Built-in resolution, PyCellObject closure cells |
|
| Decorators Under the Hood | Intermediate | Higher-order wrappers, definition-time binding, @functools.wraps |
|
| *args, **kwargs & Unpacking | Beginner | Positional tuple packing, keyword dictionary packing, sequence unpacking | |
| 04. Object-Oriented Python | Classes, Instances & __dict__ |
Beginner | Instance namespace vs class namespace, bound method descriptors |
MRO & super() |
Intermediate | C3 Linearization algorithm, diamond inheritance resolution | |
| Dunder Methods & Protocols | Intermediate | Python data model hooks: __len__, __getitem__, __repr__ |
|
Descriptors & @property |
Advanced | __get__, __set__, __delete__ protocol powering properties and ORMs |
|
| 05. Iteration & Laziness | Iterators & iter()/next() |
Beginner | Iterable vs Iterator protocol, StopIteration sentinel |
yield & Generator State |
Intermediate | Suspended stack frames on the heap, memory-efficient data streaming | |
Context Managers (with) |
Beginner | __enter__ and __exit__ lifecycle, exception handling, @contextmanager |
|
| 06. Concurrency & Async | The GIL Explained | Intermediate | Global Interpreter Lock, thread safety for ob_refcnt, I/O GIL release |
| Threading vs Multiprocessing | Intermediate | Shared memory threads vs separate CPU processes, pickle IPC overhead | |
asyncio Event Loop |
Advanced | Cooperative multitasking, single-threaded event loop, await yield points |
|
| 07. Typing & Packaging | Type Hints & Protocols | Beginner | Static analysis (mypy/pyright), structural typing (typing.Protocol) |
Modules & sys.path |
Beginner | sys.modules cache, module search paths, __name__ == "__main__" |
|
Virtual Envs & pyproject.toml |
Beginner | Site-packages isolation (venv, uv), modern PEP 621 packaging |
|
| 08. Performance & Internals | __slots__ & Memory Layout |
Advanced | Eliminating per-instance __dict__ hash tables to cut 40–60% RAM |
Caching & lru_cache |
Intermediate | Memoization hash tables, doubly-linked list eviction, cache_info() |
|
| Profiling & Big-O in Python | Intermediate | cProfile function hotspot analysis, timeit microbenchmarking |
The codebase is structured according to clean architecture and SOLID principles:
src/
├── main.jsx # React 18 root mounting
├── App.jsx # Clean 20-line orchestrator
│
├── context/
│ └── AppContext.jsx # Global application state provider & custom hook
│
├── constants/
│ └── theme.js # Theme tokens & styling constants
│
├── data/ # Pure data layer (zero UI coupling)
│ ├── index.js # Barrel export
│ ├── curriculum.js # 8 Modules & 28 Lesson structures
│ ├── topicGuides.js # 28 Definitions, breakdowns, and practical examples
│ ├── quiz.js # Quiz questions & explanations
│ ├── labScenarios.js # Interactive Heap simulator scenarios
│ └── cheatsheets.js # Quick reference data cards
│
├── hooks/ # Reusable hooks & browser listeners
│ ├── useTheme.js # Dark/Light theme with localStorage persistence
│ ├── useProgress.js # Visited steps & lesson completion tracker
│ ├── useAnimationLoop.js # SVG packet animation loop (requestAnimationFrame)
│ └── useKeyboardShortcuts.js # Keyboard navigation (Ctrl+K, arrows, R, Space)
│
├── styles/
│ └── global.css # CSS custom properties & neo-brutalist styling
│
└── components/
├── common/ # Shared UI widgets (CopyButton, SearchModal)
├── layout/ # Structural shell (Header, Sidebar, ViewRouter, MobileDrawer)
└── views/ # Isolated feature views
├── learn/ # DiagramCanvas, CodeStrip, StepTimeline, ConceptGuide...
├── practice/ # PracticeView quiz bench
├── lab/ # LabView heap simulator
└── cheatsheets/ # CheatsheetsView reference grid
| Shortcut | Action |
|---|---|
| Ctrl + K / ⌘ + K | Open Command Palette / Search concepts |
| → | Next Step / Next Lesson |
| ← | Previous Step |
| Space | Pause / Resume Diagram Animation |
| R | Replay Active Diagram Animation |
| Esc | Close Search Modal / Mobile Drawer |
-
Clone the repository:
git clone https://github.com/gajanan0707/python-internals-visualized.git cd python-internals-visualized -
Install dependencies:
npm install
-
Start the development server:
npm run dev
Open your browser at
http://localhost:5173to explore the interactive studio! -
Build for production:
npm run build
-
Preview production build:
npm run preview
- Framework: React 18
- Build Tool: Vite 6
- Styling: Tailwind CSS 3.4
- Icons: Lucide React
- Analytics & Telemetry: @vercel/speed-insights
- Deployment: Vercel
Contributions, issues, and feature requests are welcome!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/NewConcept) - Commit your Changes (
git commit -m 'Add new visualization for Generator delegation') - Push to the Branch (
git push origin feature/NewConcept) - Open a Pull Request
Want to add a new lesson? Simply add your lesson definition in src/data/curriculum.js and its explanation in src/data/topicGuides.js. The sidebar, search index, metrics, and diagrams will update automatically!
Created with ❤️ by Gajanan Patil
- X (Twitter): @Gajanan48373486
- GitHub: @gajanan0707
This project is licensed under the MIT License - see the LICENSE file for details.