GoPy

Specification series for gopy — a port of CPython's Python/ runtime to Go with 100% behavioural compatibility.

63 items

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

Spec › GoPy ›

gopy overview

Top-level overview of the gopy project. Ports CPython's Python/ runtime to Go with 100% behavioural compatibility.

Spec › GoPy ›

gopy naming conventions

Mechanical translation rules for converting CPython C identifiers to Go-idiomatic names while preserving 1:1 semantics.

Spec › GoPy ›

gopy file map

One-line per CPython source file, with the target Go package path and a short purpose note. Canonical lookup table for porters.

Spec › GoPy ›

gopy roadmap

Phased 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.

Spec › GoPy ›

gopy arena spec

Faithful 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.

Spec › GoPy ›

gopy pythread spec

Port 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.

Spec › GoPy ›

gopy pysync spec

Port 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.

Spec › GoPy ›

gopy hash secret spec

Port 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.

Spec › GoPy ›

gopy errors

Port of cpython/Python/errors.c and the gating subset of cpython/Objects/exceptions.c. Exception types, set/get/clear, raise/chain, normalize.

Spec › GoPy ›

gopy gc, weakrefs, finalizers

v0.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).

Spec › GoPy ›

gopy compile pipeline

AST, 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.

Spec › GoPy ›

gopy bytecodes DSL

Port 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.

Spec › GoPy ›

gopy lifecycle

Port of cpython/Python/pylifecycle.c, preconfig.c, initconfig.c, interpconfig.c, pathconfig.c. Py_Initialize / Py_Finalize and the config plumbing they consume.

Spec › GoPy ›

gopy pythonrun

Port of cpython/Python/pythonrun.c. PyRun_SimpleString, PyRun_File, the REPL loop, and the .pyc read/write helpers that the lifecycle calls.

Spec › GoPy ›

gopy v0.5 testing strategy

Per-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.

Spec › GoPy ›

gopy codegen

Detailed 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.

Spec › GoPy ›

gopy flowgraph

Detailed 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.

Spec › GoPy ›

gopy assemble

Detailed 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.

Spec › GoPy ›

gopy compile golden tests

Disassembly-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`.

Spec › GoPy ›

gopy vm overview

Top-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.

Spec › GoPy ›

gopy intrinsics

Port 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).

Spec › GoPy ›

gopy eval loop

Port 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.

Spec › GoPy ›

gopy frame

Port of cpython/Python/frame.c. Frame layout, locals-plus storage, frame chain push/pop, generator frame suspension.

Spec › GoPy ›

gopy stackref

Port of cpython/Python/stackrefs.c. Tagged stack reference values, borrow tracking, and the conversion shims between PyObject* and stackref.

Spec › GoPy ›

gopy eval gil

Port 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.

Spec › GoPy ›

gopy parser overview

Top-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.

Spec › GoPy ›

gopy lexer and tokenizer

Port of cpython/Parser/lexer/ and cpython/Parser/tokenizer/. Lexer state machine, buffer, token emission, and the four tokenizer drivers (file, string, utf8, readline).

Spec › GoPy ›

gopy pegen

Port 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.

Spec › GoPy ›

gopy parser errors and helpers

Port 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.

Spec › GoPy ›

gopy string parser

Port 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.

Spec › GoPy ›

gopy myreadline

Port 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.

Spec › GoPy ›

gopy modules

Port 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.

Spec › GoPy ›

gopy strings and numbers

Locale-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.

Spec › GoPy ›

gopy hash

Port of cpython/Python/pyhash.c. SipHash-1-3 plus FNV-1a, secret seed bootstrap from 1607.

Spec › GoPy ›

gopy hamt

Hash Array Mapped Trie immutable mapping. Backs contextvars (1663). Ports cpython/Python/hamt.c byte-for-byte preserving the 5-bit-per-level tree shape.

Spec › GoPy ›

gopy contextvars

PEP 567 contextvars. Ports cpython/Python/context.c plus _contextvars.c. Uses the HAMT (1662) as backing store.

Spec › GoPy ›

gopy pytime

Internal time utilities. Ports cpython/Python/pytime.c. Provides PyTime_t (int64 nanoseconds), monotonic / perf / wall clocks, double / timespec / timeval conversions, deadline math.

Spec › GoPy ›

gopy tokenize

Public TokenizerIter wrapper. Ports Python-tokenize.c. The actual lexer lives in cpython/Parser/tokenizer/ and is covered by the parser spec series.

Spec › GoPy ›

gopy runtime helpers

Two 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.

Spec › GoPy ›

gopy objects overview

Top-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.

Spec › GoPy ›

gopy object protocol

Object interface, Header, VarHeader, refcount, and identity. Mirrors PyObject and PyVarObject in cpython/Include/object.h.

Spec › GoPy ›

gopy type

Type, slots, MRO, lookup. Mirrors PyTypeObject from cpython/Include/cpython/typeobject.h.

Spec › GoPy ›

gopy long

Port 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.

Spec › GoPy ›

gopy float and complex

Port of cpython/Objects/floatobject.c and complexobject.c. IEEE-754 binary64 float with shortest-roundtrip repr, plus the complex builtin used by cmath.

Spec › GoPy ›

gopy bool and singletons

Port of cpython/Objects/boolobject.c plus the None and NotImplemented singletons. bool is a subtype of int.

Spec › GoPy ›

gopy bytes

Port of cpython/Objects/bytesobject.c, bytearrayobject.c, and bytes_methods.c. Immutable bytes plus mutable bytearray with the full string-like method panel.

Spec › GoPy ›

gopy unicode

Port of cpython/Objects/unicodeobject.c and unicodectype.c. PEP 393 kind-tagged str with the full method surface and Unicode classification tables.

Spec › GoPy ›

gopy tuple

Port of cpython/Objects/tupleobject.c. Immutable sequence with the empty-tuple singleton and the CPython tuple hash.

Spec › GoPy ›

gopy list

Port of cpython/Objects/listobject.c. Mutable variable-length sequence with the CPython list_resize growth curve and Timsort.

Spec › GoPy ›

gopy dict

Port of cpython/Objects/dictobject.c and odictobject.c. Insertion-ordered open-addressing hash table with the CPython probing sequence.

Spec › GoPy ›

gopy set

Port of cpython/Objects/setobject.c. set and frozenset on the same open-addressing layout as dict, sharing the probing sequence.

Spec › GoPy ›

gopy slice and range

Port of cpython/Objects/sliceobject.c and rangeobject.c. The slice and range builtins, plus the Ellipsis singleton.

Spec › GoPy ›

gopy abstract

Port of cpython/Objects/abstract.c. Cross-type protocol dispatch (PyObject_*, PyNumber_*, PySequence_*, PyMapping_*, PyIter_*) that the bytecode interpreter calls into.

Spec › GoPy ›

gopy call

Port of cpython/Objects/call.c. Vectorcall fast path, generic call dispatch, argument tuple construction, and the kwargs handling rules.

Spec › GoPy ›

gopy descriptor and method

Port 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.

Spec › GoPy ›

gopy exceptions

Port of cpython/Objects/exceptions.c. The full BaseException hierarchy with the args slot byte-equal to CPython for every constructor.

Spec › GoPy ›

gopy code, frame, generator

Port 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.

Spec › GoPy ›

gopy module and misc

Port 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.

Spec › GoPy ›

gopy objects misc

Port of the remaining cpython/Objects/ files. weakref, memoryview, file, picklebuffer, typevar / TypeAliasType, union, GenericAlias, Interpolation / Template, plus the obmalloc stub.

Spec › GoPy ›

gopy marshal

Port 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.

Spec › GoPy ›

gopy import

Port 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.

Spec › GoPy ›

gopy codecs

Port 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.

Spec › GoPy ›

gopy vm remaining bytecodes

Bytecodes ported in v0.9 that finish the Tier-1 panel: import, generator, pattern-match, with/finally, set builders, and the async-protocol stubs.