Specification series for gopy — a port of CPython's Python/ runtime to Go with 100% behavioural compatibility.
Port of CPython’s Python/ (and related Objects/, Parser/) runtime to Go. Each spec file maps directly to one or more CPython C source files and defines the Go package, types, and functions that replace them.
| # | Spec | Topic |
|---|---|---|
| 1600 | 1600_gopy_overview | gopy overview |
| 1601 | 1601_gopy_naming | gopy naming conventions |
| 1602 | 1602_gopy_filemap | gopy file map |
| 1603 | 1603_gopy_roadmap | gopy roadmap |
| 1604 | 1604_gopy_arena | gopy arena spec |
| 1605 | 1605_gopy_pythread | gopy pythread spec |
| 1606 | 1606_gopy_pysync | gopy pysync spec |
| 1607 | 1607_gopy_hashsecret | gopy hash secret spec |
| 1611 | 1611_gopy_errors | gopy errors |
| 1613 | 1613_gopy_gc | gopy gc, weakrefs, finalizers |
| 1620 | 1620_gopy_compile_pipeline | gopy compile pipeline |
| 1621 | 1621_gopy_bytecodes_dsl | gopy bytecodes DSL |
| 1622 | 1622_gopy_lifecycle | gopy lifecycle |
| 1624 | 1624_gopy_pythonrun | gopy pythonrun |
| 1625 | 1625_gopy_compile_testing | gopy v0.5 testing strategy |
| 1626 | 1626_gopy_codegen | gopy codegen |
| 1627 | 1627_gopy_flowgraph | gopy flowgraph |
| 1628 | 1628_gopy_assemble | gopy assemble |
| 1629 | 1629_gopy_compile_goldens | gopy compile golden tests |
| 1630 | 1630_gopy_vm_overview | gopy vm overview |
| 1635 | 1635_gopy_intrinsics | gopy intrinsics |
| 1636 | 1636_gopy_eval_loop | gopy eval loop |
| 1637 | 1637_gopy_frame | gopy frame |
| 1638 | 1638_gopy_stackref | gopy stackref |
| 1639 | 1639_gopy_eval_gil | gopy eval GIL |
| 1640 | 1640_gopy_parser_overview | gopy parser overview |
| 1641 | 1641_gopy_lexer_tokenizer | gopy lexer tokenizer |
| 1642 | 1642_gopy_pegen | gopy pegen |
| 1643 | 1643_gopy_parser_errors | gopy parser errors |
| 1644 | 1644_gopy_string_parser | gopy string parser |
| 1645 | 1645_gopy_myreadline | gopy myreadline |
| 1651 | 1651_gopy_modules | gopy modules |
| 1660 | 1660_gopy_strings_numbers | gopy strings and numbers |
| 1661 | 1661_gopy_hash | gopy hash |
| 1662 | 1662_gopy_hamt | gopy HAMT |
| 1663 | 1663_gopy_context | gopy context |
| 1664 | 1664_gopy_time | gopy time |
| 1665 | 1665_gopy_tokenize | gopy tokenize |
| 1668 | 1668_gopy_runtime_helpers | gopy runtime helpers |
| 1670 | 1670_gopy_objects_overview | gopy objects overview |
| 1671 | 1671_gopy_object_protocol | gopy object protocol |
| 1672 | 1672_gopy_type | gopy type |
| 1673 | 1673_gopy_long | gopy long |
| 1674 | 1674_gopy_float_complex | gopy float complex |
| 1675 | 1675_gopy_bool_none | gopy bool none |
| 1676 | 1676_gopy_bytes | gopy bytes |
| 1677 | 1677_gopy_unicode | gopy unicode |
| 1678 | 1678_gopy_tuple | gopy tuple |
| 1679 | 1679_gopy_list | gopy list |
| 1680 | 1680_gopy_dict | gopy dict |
| 1681 | 1681_gopy_set | gopy set |
| 1682 | 1682_gopy_slice_range | gopy slice range |
| 1683 | 1683_gopy_abstract | gopy abstract |
| 1684 | 1684_gopy_call | gopy call |
| 1685 | 1685_gopy_descr_method | gopy descr method |
| 1686 | 1686_gopy_exceptions | gopy exceptions |
| 1687 | 1687_gopy_code_frame_gen | gopy code frame gen |
| 1688 | 1688_gopy_module_misc | gopy module misc |
| 1689 | 1689_gopy_obj_misc | gopy obj misc |
| 1690 | 1690_gopy_marshal | gopy marshal |
| 1691 | 1691_gopy_import | gopy import |
| 1692 | 1692_gopy_codecs | gopy codecs |
| 1693 | 1693_gopy_vm_remaining | gopy vm remaining |
gopy overviewTop-level overview of the gopy project. Ports CPython's Python/ runtime to Go with 100% behavioural compatibility.
gopy naming conventionsMechanical translation rules for converting CPython C identifiers to Go-idiomatic names while preserving 1:1 semantics.
gopy file mapOne-line per CPython source file, with the target Go package path and a short purpose note. Canonical lookup table for porters.
gopy roadmapPhased milestone plan from v0.0.1 (parser smoke) to v1.0 (full CPython parity). Defines the ordering of subsystem ports and the gating criteria for each release.
gopy arena specFaithful port of cpython/Python/pyarena.c to gopy/arena. Bump-allocator with linked-block layout used by the compiler pipeline for AST and scratch buffers.
gopy pythread specPort of cpython/Python/thread.c to gopy/pythread. Thread create, join, ident, and stack-size hooks layered over Go's goroutine scheduler. The OS-specific thread_pthread.h / thread_nt.h files are dropped.
gopy pysync specPort of cpython/Python/lock.c, parking_lot.c, and critical_section.c into the gopy/pysync package. Address-keyed parking, byte-flag PyMutex, PyEvent, PyOnceFlag, RecursiveMutex, RWMutex, SeqLock, and the PEP 703 critical-section stack.
gopy hash secret specPort of the seed-init half of cpython/Python/bootstrap_hash.c to gopy/hash. PYTHONHASHSEED parsing, the LCG used when a seed is given, and an OS-entropy fallback. The full SipHash-1-3 / FNV / x86_aes hashing land in v0.4.
gopy errorsPort of cpython/Python/errors.c and the gating subset of cpython/Objects/exceptions.c. Exception types, set/get/clear, raise/chain, normalize.
gopy gc, weakrefs, finalizersv0.10 cycle GC port. Maps Python/gc.c, Python/gc_gil.c, Python/object_stack.c, Objects/weakrefobject.c onto gopy/gc and objects/weakref. Defines what '100% behavioural compatibility' means when the host runtime is Go (which already collects cycles).
gopy compile pipelineAST, future flags, symbol table, codegen, flowgraph, assemble. Ports asdl.c, Python-ast.c, ast.c, ast_preprocess.c, ast_unparse.c, future.c, symtable.c, instruction_sequence.c, codegen.c, flowgraph.c, assemble.c, compile.c.
gopy bytecodes DSLPort of cpython/Tools/cases_generator. Reads Python/bytecodes.c, emits the Go dispatch table at vm/opcodes_gen.go and metadata at compile/opcodes_gen.go.
gopy lifecyclePort of cpython/Python/pylifecycle.c, preconfig.c, initconfig.c, interpconfig.c, pathconfig.c. Py_Initialize / Py_Finalize and the config plumbing they consume.
gopy pythonrunPort of cpython/Python/pythonrun.c. PyRun_SimpleString, PyRun_File, the REPL loop, and the .pyc read/write helpers that the lifecycle calls.
gopy v0.5 testing strategyPer-package test plan covering every checklist item in 1620 (compile pipeline) and 1665 (tokenize). Each entry maps a CPython source range to the Go test that locks parity.
gopy codegenDetailed port plan for cpython/Python/codegen.c (~6500 lines) to compile/codegen.go. Statement and expression visitors, frame block stack, pattern matching panel, with-statement state machine, deferred annotations, PEP 695 type-parameter codegen, comprehensive test plan.
gopy flowgraphDetailed port plan for cpython/Python/flowgraph.c (~4200 lines) to compile/flowgraph.go. CFG construction, optimization passes (jump threading, dead-code, const fold, swaptimize, super-instructions), stackdepth, exception handler labelling, comprehensive test plan.
gopy assembleDetailed port plan for cpython/Python/assemble.c (~800 lines) to compile/assemble.go. Sequence-to-Code conversion, line table varint format, exception table varint format, co_consts/names/varnames/freevars/cellvars layout, fastlocalskinds, comprehensive test plan.
gopy compile golden testsDisassembly-golden corpus for the v05test gate. Each fixture is a Go-built AST plus a checked-in .golden file with the expected dis.dis output. Refresh via `go test -update`.
gopy vm overviewTop-level overview of the gopy VM (Tier-1 bytecode interpreter) port. Covers ceval, ceval_macros, ceval_gil, frame, stackrefs, and the bytecodes DSL output. Lives in the 1630-1639 block.
gopy intrinsicsPort of cpython/Python/intrinsics.c. The CALL_INTRINSIC_1 / CALL_INTRINSIC_2 dispatch tables that back compile-time-emitted runtime helpers (print expr, list-to-tuple, import-star, type-alias).
gopy eval loopPort of cpython/Python/ceval.c and cpython/Python/ceval_macros.h. The Tier-1 bytecode dispatch loop, exception unwind, generator resume, and call/return trampolines.
gopy framePort of cpython/Python/frame.c. Frame layout, locals-plus storage, frame chain push/pop, generator frame suspension.
gopy stackrefPort of cpython/Python/stackrefs.c. Tagged stack reference values, borrow tracking, and the conversion shims between PyObject* and stackref.
gopy eval gilPort of cpython/Python/ceval_gil.c. The GIL acquire/release protocol, the eval breaker bitfield, signal pending flags, and the gopy-vs-Go-runtime threading mapping.
gopy parser overviewTop-level overview of the gopy Parser port. Covers the PEG parser, lexer, tokenizer drivers, string literal parser, error helpers, and readline. Lives in the 1640-1645 block of the 1600 spec series.
gopy lexer and tokenizerPort of cpython/Parser/lexer/ and cpython/Parser/tokenizer/. Lexer state machine, buffer, token emission, and the four tokenizer drivers (file, string, utf8, readline).
gopy pegenPort of cpython/Parser/pegen.c and the generated cpython/Parser/parser.c. PEG runtime plus the parser table that turns a token stream into an AST.
gopy parser errors and helpersPort of cpython/Parser/pegen_errors.c, action_helpers.c, peg_api.c, and token.c. SyntaxError text panel, AST construction helpers, and the token table.
gopy string parserPort of cpython/Parser/string_parser.c. Decodes Python string, bytes, f-string, and t-string literals into AST nodes. Handles escape sequences, prefixes, and f-string interpolation re-entry.
gopy myreadlinePort of cpython/Parser/myreadline.c. Cross-platform readline shim used by the interactive REPL. Mostly a thin wrapper over the host readline library; gopy substitutes Go-native line editing.
gopy modulesPort of cpython/Python/bltinmodule.c (subset), sysmodule.c (subset), _warnings.c, and the _contextvars hook. The minimum builtins/sys surface v0.7 needs to ship.
gopy strings and numbersLocale-independent string and number conversion. Ports pyctype.c, pystrcmp.c, mystrtoul.c, pystrtod.c, dtoa.c, pystrhex.c, pymath.c, pyfpe.c, formatter_unicode.c.
gopy hashPort of cpython/Python/pyhash.c. SipHash-1-3 plus FNV-1a, secret seed bootstrap from 1607.
gopy hamtHash Array Mapped Trie immutable mapping. Backs contextvars (1663). Ports cpython/Python/hamt.c byte-for-byte preserving the 5-bit-per-level tree shape.
gopy contextvarsPEP 567 contextvars. Ports cpython/Python/context.c plus _contextvars.c. Uses the HAMT (1662) as backing store.
gopy pytimeInternal time utilities. Ports cpython/Python/pytime.c. Provides PyTime_t (int64 nanoseconds), monotonic / perf / wall clocks, double / timespec / timeval conversions, deadline math.
gopy tokenizePublic TokenizerIter wrapper. Ports Python-tokenize.c. The actual lexer lives in cpython/Parser/tokenizer/ and is covered by the parser spec series.
gopy runtime helpersTwo small infra ports - getopt.c (CLI option parser used during interpreter init) and hashtable.c (generic _Py_hashtable_t internal hash table). Bundled because each is tiny and self-contained.
gopy objects overviewTop-level overview of the gopy Objects port. Ports cpython/Objects/ to Go with 100% behavioural compatibility. Lives in the 1670-1689 block of the 1600 spec series.
gopy object protocolObject interface, Header, VarHeader, refcount, and identity. Mirrors PyObject and PyVarObject in cpython/Include/object.h.
gopy typeType, slots, MRO, lookup. Mirrors PyTypeObject from cpython/Include/cpython/typeobject.h.
gopy longPort of cpython/Objects/longobject.c. Arbitrary-precision int with the small-int cache, base-2/8/10/16 parsing, hash, and the full numeric protocol.
gopy float and complexPort of cpython/Objects/floatobject.c and complexobject.c. IEEE-754 binary64 float with shortest-roundtrip repr, plus the complex builtin used by cmath.
gopy bool and singletonsPort of cpython/Objects/boolobject.c plus the None and NotImplemented singletons. bool is a subtype of int.
gopy bytesPort of cpython/Objects/bytesobject.c, bytearrayobject.c, and bytes_methods.c. Immutable bytes plus mutable bytearray with the full string-like method panel.
gopy unicodePort of cpython/Objects/unicodeobject.c and unicodectype.c. PEP 393 kind-tagged str with the full method surface and Unicode classification tables.
gopy tuplePort of cpython/Objects/tupleobject.c. Immutable sequence with the empty-tuple singleton and the CPython tuple hash.
gopy listPort of cpython/Objects/listobject.c. Mutable variable-length sequence with the CPython list_resize growth curve and Timsort.
gopy dictPort of cpython/Objects/dictobject.c and odictobject.c. Insertion-ordered open-addressing hash table with the CPython probing sequence.
gopy setPort of cpython/Objects/setobject.c. set and frozenset on the same open-addressing layout as dict, sharing the probing sequence.
gopy slice and rangePort of cpython/Objects/sliceobject.c and rangeobject.c. The slice and range builtins, plus the Ellipsis singleton.
gopy abstractPort of cpython/Objects/abstract.c. Cross-type protocol dispatch (PyObject_*, PyNumber_*, PySequence_*, PyMapping_*, PyIter_*) that the bytecode interpreter calls into.
gopy callPort of cpython/Objects/call.c. Vectorcall fast path, generic call dispatch, argument tuple construction, and the kwargs handling rules.
gopy descriptor and methodPort of cpython/Objects/descrobject.c, methodobject.c, classobject.c, and funcobject.c. The descriptor protocol (data and non-data), bound methods, builtin function objects, and Python function objects.
gopy exceptionsPort of cpython/Objects/exceptions.c. The full BaseException hierarchy with the args slot byte-equal to CPython for every constructor.
gopy code, frame, generatorPort of cpython/Objects/codeobject.c, frameobject.c, genobject.c, and cellobject.c. The four objects the VM thinks in: bytecode, execution frame, generator state machine, and closure cells.
gopy module and miscPort of cpython/Objects/moduleobject.c, namespaceobject.c, structseq.c, capsule.c, iterobject.c, and enumobject.c. Module, SimpleNamespace, structseq, Capsule, the generic iterator wrappers, and enumerate / reversed.
gopy objects miscPort of the remaining cpython/Objects/ files. weakref, memoryview, file, picklebuffer, typevar / TypeAliasType, union, GenericAlias, Interpolation / Template, plus the obmalloc stub.
gopy marshalPort of cpython/Python/marshal.c (2163 lines) to the marshal/ package. Full type-tag dispatch, TYPE_LONG arbitrary-precision encoding, FLAG_REF back-reference dedup, TYPE_CODE read/write, and .pyc file header. Gates the v0.8 milestone.
gopy importPort of cpython/Python/import.c (4956 lines) and Python/frozen.c (132 lines). Frozen module loader, sys.modules lookup, source and bytecode loaders, builtin module table, and the IMPORT_NAME / IMPORT_FROM / IMPORT_STAR bytecodes. Gates v0.8.
gopy codecsPort of cpython/Python/codecs.c (1708 lines) to the codecs/ package. Codec registry, error-handler registry, Encode/Decode entry points, and the three built-in codecs (utf-8, ascii, latin-1) needed by the import source reader.
gopy vm remaining bytecodesBytecodes ported in v0.9 that finish the Tier-1 panel: import, generator, pattern-match, with/finally, set builders, and the async-protocol stubs.