1602. File map: cpython/Python/* to gopy/*

The mapping is one-to-many: a CPython file may split across several Go files (or vice-versa). Where multiple C files collapse into one Go package, the package’s doc.go lists the source files it derives from.

Conventions:

• All Go packages live at the module root (gopy/<pkg>). We do not use Go’s internal/ directory convention. See 1601 for rationale.
• Files named like dynload_*.c and emscripten_*.c are platform glue we do not port. Go’s runtime handles the equivalents. They are listed here for completeness with a -- Go target.
• Generated headers (generated_cases.c.h, executor_cases.c.h, optimizer_cases.c.h, opcode_targets.h) are regenerated from the CPython DSL via our own Go-emitting code generator. See 1621.

Compiler pipeline

Bytecode interpreter & frame

Specializer / optimizer / JIT / instrumentation

State, lifecycle, init, run

Errors, modules, codecs

Memory, GC, concurrency

Note on pysync: we use the package name pysync (not sync) to avoid shadowing Go’s standard library sync package inside the gopy module, since these CPython primitives have semantics distinct from sync.Mutex / sync.Cond.

Strings, numbers, hashing, time, hamt, context

Note on pystrconv: same reasoning as pysync. Avoids colliding with Go’s standard library strconv. pystrconv holds the Python-specific string/number routines (dtoa, locale-independent strcmp, mystrtoul). Go’s strconv is used for plain Go conversions.

Misc / drop list

Go top-level layout

gopy/
├── go.mod                        # module tamnd/gopy
├── cmd/
│   ├── gopy/                     # main interpreter entry (mirror of python.c)
│   └── gopy-frozen/              # embedded-only entry (mirror of frozenmain.c)
├── arena/
├── ast/
├── build/                        # version/platform/compiler/copyright strings
├── builtin/                      # __builtins__ module
├── codecs/
├── compile/                      # codegen, flowgraph, assemble, instrseq
├── contextvar/
├── crossinterp/
├── errors/
├── fileutils/
├── format/
├── future/
├── gc/
├── getargs/
├── getopt/
├── hamt/
├── hash/
├── hashtable/
├── imp/                          # import + frozen + stdlib_names; see 1612
├── initconfig/
├── intrinsics/
├── jit/                          # stub
├── lifecycle/
├── marshal/
├── modsupport/
├── monitor/
├── object/                       # NB: cpython/Objects/* lives in a separate spec series
├── opcode/                       # opcode constants + metadata
├── optimizer/
├── pathconfig/
├── pymath/
├── pystrconv/                    # Python-specific str/number conversion
├── pysync/                       # Python-specific sync primitives
├── pythonrun/
├── pythread/
├── pytime/
├── remotedebug/                  # stub
├── specialize/
├── state/
├── structmember/
├── symtable/
├── sysmod/
├── tokenize/
├── traceback/
├── tracemalloc/
├── vm/
├── warnings/
└── compat/                       # cross-runtime golden tests
    ├── bytecode/
    ├── marshal/
    └── hash/

On flat layout vs internal/

Go’s internal/ directory convention restricts imports to packages within the same module subtree. We deliberately do not use it for gopy, for three reasons:

1. Embedders: third-party Go programs that embed gopy as a Python runtime (think python -c style execution from Go code) need to import vm, state, lifecycle, compile etc. directly. Burying them under internal/ would block that.
2. Stdlib re-implementations: the Go-native ports of CPython’s Modules/* and Lib/* live in companion modules (tamnd/gopy-stdlib, etc.). Those need to import from this module’s runtime packages.
3. Tooling and tests: compat/ and external golden-test harnesses import the same packages the runtime uses. internal/ would force awkward indirections.

Discoverability is preserved by the package name itself. There is no ambiguity that compile, vm, gc, frame etc. belong to the gopy runtime.