Contributing: Architecture
Edit this pageHigh-level architecture map for contributors working on parser, compiler, VM, and extension runtime.
This page summarizes where major interpreter responsibilities live so contributors can place changes in the right subsystem.
Top-Level Flow
| Stage | Primary modules |
|---|---|
| Parsing | src/parser/* (packrat parser entry points and lexer/token handling) |
| Compilation | src/compiler/* (AST-to-bytecode lowering and scope analysis) |
| Runtime/VM | src/vm/* (execution loop, builtins, import substrate, object-model behavior) |
| CLI and REPL | src/cli/mod.rs, src/cli/repl.rs |
| Native extensions | src/vm/vm_extensions/* and include/pyrs_capi.h |
VM Ownership Rules (Contributor View)
| Area | Where to change behavior |
|---|---|
| Bytecode execution flow | src/vm/vm_execution.rs |
| Builtin dispatch mapping | src/vm/vm_native_dispatch.rs |
| Import/bootstrap wiring | src/vm/vm_bootstrap_import.rs, src/vm/builtins_import.rs |
| Core runtime helpers | src/vm/vm_runtime_methods.rs |
| Native stdlib substrates | src/vm/stdlib/* |
| C-API/extension runtime | src/vm/vm_extensions/* (split by API surface family) |
Placement Discipline
- Do not put new domain logic into monolithic orchestrator files when a focused module exists.
- Keep behavior in the owning subsystem (parser/compiler/vm/extensions) with minimal cross-leakage.
- Ship behavior changes with tests in the same commit.
- For CPython-visible behavior, treat CPython semantics as the sole target.