Homemade-CPython

The goal of this repository is not to fully rewrite CPython from day one. Instead, it first establishes a stable, regression-friendly, and extensible sample suite, then gradually implements the system with a TDD / SDD workflow:

1. Python source input
2. Compile Python source into .pyc
3. Inspect compiled .pyc artifacts
4. Execute them with a simplified virtual machine
5. Verify behavior through regression checks

Implementation Principles

The entire project is implemented in Python, without using C.

This choice has several direct advantages:

• the code is simpler and the overall structure is clearer
• it is better suited for teaching, reading, and step-by-step experimentation
• iteration is cheaper and changes are faster to make
• it is also more AI-agent-friendly and costs fewer tokens during collaboration

The focus of this project is to understand .pyc, bytecode, parsers, and virtual machines themselves, rather than spending large amounts of effort on C engineering details.

Why Start with Many Samples

When building a CPython-style interpreter yourself, the easiest way to fail is not "not knowing how to code," but rather:

• not having enough behavioral samples
• not knowing what regressed after a change
• only being able to run extremely simple demos
• being unable to systematically observe the transition from .py to .pyc

So in the first phase, this repository prioritizes two things:

• collecting a large number of Python samples that can be compiled, executed, and asserted
• generating .pyc files for each sample as input for later parsing and execution work

Current Directory Plan

• tests/ Stores a collection of small and clear Python samples
• py2pyc-parser/ Responsible for py -> pyc
• pyc-vm/ Responsible for pyc -> run
• dis-study/ Used to inspect dis output, generate .pyc, and save disassembly text

Current Module Responsibilities

The responsibilities of these three directories are intentionally kept very clear:

• dis-study/ Uses the standard library to get the .py -> .pyc -> .txt observation pipeline working first, while preserving the generated artifacts
• py2pyc-parser/ Studies and implements how Python source code is compiled into .pyc
• pyc-vm/ Reads .pyc and executes it on a handwritten VM

In other words, the current mainline of the project is not "parsing .pyc back into source code," but:

1. tests/*.py
2. py2pyc-parser handles py -> pyc
3. dis-study is used to inspect .pyc and dis text
4. pyc-vm handles pyc -> run

Current Progress

Already completed:

• tests/ A large set of regression-friendly Python samples is already in place
• dis-study/ Can already generate and preserve .pyc files and matching dis text reliably
• pyc-vm/ Already has phase1 and phase2 designs, and phase2 runs successfully across the current batch of .pyc files

Still to be advanced:

• py2pyc-parser/ Continue making the "Python source to .pyc" layer more handwritten, clearer, and more suitable for teaching

Sample Design Principles

Files under tests/ follow these rules as much as possible:

• each file should express one clear topic
• use normal Python syntax without third-party dependencies
• use assert directly to express expected results
• include both basic exercises and more LeetCode-style problems
• prioritize semantic points that interpreters commonly get wrong

Examples include:

• function calls
• recursion
• loops
• conditional branches
• lists, dictionaries, and sets
• string processing
• slicing
• sorting
• binary search
• stacks and queues
• dynamic programming

Recommended Development Flow

You can move forward in the following order:

1. Write or add one Python sample first
2. Compile the corresponding .pyc using the existing toolchain
3. Inspect the dis output
4. Gradually study and implement the py -> pyc compilation path inside py2pyc-parser/
5. Gradually support more opcodes inside pyc-vm/
6. Re-run the sample and confirm the behavior stays consistent

Phase 1 Goals

The first phase does not aim for a complete interpreter. It aims for:

• many stable samples
• many .pyc files
• a clear separation between the compilation layer and the execution layer
• incremental support for basic control flow and data structures
• immediate regression cases whenever a new capability is added

Future Suggestions

After this batch of foundational samples runs successfully, the next things to add can include:

• closures
• generators
• classes and objects
• exception handling
• the import system
• context managers

Build the "sample library + .pyc sample library" first, and the later interpreter implementation will become much more stable.