#spec

gopy strings and numbers

1660. Strings and numbers What we are porting Eight files from cpython/Python/ : C source Lines Go target pyctype.c 215 pystrconv/ctype.go pystrcmp.c 31 pystrconv/cmp.go mystrtoul.c 297 pystrconv/strtoul.go pystrtod.c 1286 pystrconv/strtod.go dtoa.c 2843 pystrconv/dtoa.go (see below) pystrhex.c 171 pystrconv/hex.go pymath.c 19 pymath/pymath.go pyfpe.c ~5 pymath/fpe.go formatter_unicode.c 1726 format/format.go Together they form the bedrock that int.__repr__ , float.__repr__ , int.__str__ , float.__str__ , format() , f"{x:.2f}" , int(s, base) , float(s) ,...

gopy compile pipeline

1620. Compile pipeline What we are porting Twelve files from cpython/Python/ (~39k lines) form the compiler that turns an AST into a code object: C source Lines Go target asdl.c 6 ast/asdl.go Python-ast.c (generated) 18485 ast/nodes_gen.go ast.c 1091 ast/validate.go ast_preprocess.c 990 ast/preprocess.go ast_unparse.c 1029 ast/unparse.go future.c 119 future/future.go symtable.c 3266 symtable/symtable.go instruction_sequence.c 483 compile/instrseq.go codegen.c 6483 compile/codegen.go flowgraph.c 4165 compile/flowgraph.go assemble.c 802 compile/assemble.go compile.c 1753 compile/compiler.go The 1620 series runs...

gopy hash secret spec

1607. Hash secret bootstrap ( hash/secret.go ) bootstrap_hash.c does two things: Provides the _PyOS_URandom* family that fills a buffer with OS entropy (Windows BCryptGenRandom, Linux getrandom, /dev/urandom, etc.). Initializes _Py_HashSecret , the per-process secret used by SipHash to randomize hash output. The initialization respects the PYTHONHASHSEED environment variable: a positive integer gives a deterministic LCG-derived secret; 0 zeroes the secret (so hashes are not randomized, useful for debugging); the literal...

gopy hamt

1662. HAMT immutable mapping What we are porting cpython/Python/hamt.c (~2885 lines) plus the public API in cpython/Include/internal/pycore_hamt.h . Output: C source Lines Go target Python/hamt.c 2885 hamt/hamt.go Include/internal/pycore_hamt.h (public API) ~120 hamt/api.go The HAMT (Hash Array Mapped Trie) is an immutable persistent mapping used as the backing store for Context in PEP 567. Its API is private to the runtime: stdlib code reaches it only through contextvars. gopy ships it...

gopy tuple

1678. Tuple What we are porting Objects/tupleobject.c (~1300 lines). Immutable, fixed-size heterogeneous sequence. Used everywhere: argument tuples, multiple return values, dict keys, namedtuple base, exception args. Go shape // Tuple mirrors PyTupleObject. Immutable after construction. type Tuple struct { VarHeader items []Object } Empty-tuple singleton: () returns the same *Tuple every call. CPython's _Py_SINGLETON(tuple_empty) . Small-tuple freelist: CPython caches tuples of size 1..20 in a type-specific freelist. Go GC does...

gopy lexer and tokenizer

1641. Lexer and tokenizer drivers What we are porting CPython's lexer is split into two layers: Parser/lexer/ : the state machine that consumes bytes and emits tokens. lexer.c is the FSM, state.c owns the per-tokenizer state struct, buffer.c owns the slidable input buffer. Parser/tokenizer/ : four drivers that feed the lexer from different sources. utf8_tokenizer.c (in-memory UTF-8 string), string_tokenizer.c (legacy string with encoding detection), file_tokenizer.c (FILE*), readline_tokenizer.c (REPL callback). helpers.c...

gopy modules

1651. Modules: builtins, sys, _warnings What we are porting Three companion modules that the runtime hands to user code as soon as Py_Initialize returns: Python/bltinmodule.c (the v0.7 subset listed below). The builtins module: print , len , range , iter , abs , type , isinstance , repr , str , int , float , list , tuple , dict , set , getattr , setattr , hasattr , callable...

gopy exceptions

1686. Exceptions What we are porting Objects/exceptions.c (~3000 lines). The full exception class hierarchy plus the special slots ( __traceback__ , __cause__ , __context__ , __suppress_context__ , __notes__ ) and the constructor-specific args-slot handling. The hierarchy is wide: BaseException -> Exception -> ArithmeticError -> {OverflowError, FloatingPointError, ZeroDivisionError}, LookupError -> {IndexError, KeyError}, OSError with the platform errno subclasses (FileNotFoundError, PermissionError, etc.), SyntaxError with the position fields, ImportError with name/path, StopIteration with...

gopy unicode

1677. Unicode (str) What we are porting Two files, ~17000 lines total. The single largest object port: Objects/unicodeobject.c : PEP 393 kind-tagged string. Three storage kinds (1-byte, 2-byte, 4-byte) chosen at construction to fit the largest code point. Method surface ( split , join , find , replace , format , encode , decode , casefold , etc.). String interning. Codecs registry hooks. Objects/unicodectype.c : Unicode 16.0 classification tables. is_alnum...

gopy objects overview

1670. gopy: Porting CPython's Objects/ to Go Goal The 1670-1689 block covers the port of cpython/Objects/ (about 112k lines of C across 47 .c files). It runs alongside the rest of the 1600 series and together they form the gopy interpreter core. This block was previously the 1700 series; the renumber keeps the whole port under one spec folder. Old references to "1700" point here. Same rule as 1600: 100%...

gopy list

1679. List What we are porting Objects/listobject.c (~3500 lines). The most-used mutable container. Append-amortised, sort via Timsort, slice assignment, in-place reverse, the full mutable sequence protocol. Go shape // List mirrors PyListObject. type List struct { VarHeader items []Object // len = size, cap >= len } We back the list with a Go slice. append already amortises, but CPython's list_resize curve is observable (it determines how often __sizeof__ changes),...

gopy vm overview

1630. gopy: Porting CPython's Tier-1 interpreter to Go Goal The 1630-1639 block covers the port of CPython's Tier-1 bytecode interpreter: ceval.c , ceval_macros.h , ceval_gil.c , frame.c , stackrefs.c , plus the bytecode generator output that lives at Python/generated_cases.c.h (regenerated from Python/bytecodes.c ). About 35k lines of C across the runtime files plus another ~30k in the generated dispatch table. The output of this block is a Go function vm.Eval(state.Thread,...

gopy pytime

1664. PyTime utilities What we are porting C source Lines Go target Python/pytime.c 1356 pytime/pytime.go Include/cpython/pytime.h (public types) ~80 pytime/types.go pytime is the runtime's clock layer. Every part of CPython that deals with time (lock timeouts, signal alarms, time.monotonic , asyncio deadlines, selectors , the GIL release interval) goes through it. The header exposes one type, PyTime_t = int64_t nanoseconds, plus a small constellation of conversion and clock helpers. The...

gopy codecs

1692. codecs (Python/codecs.c) What we are porting Python/codecs.c (1708 lines): the codec registry and the encode/decode dispatch layer that str.encode() , bytes.decode() , and the import system's source-file reader all call into. CPython's codec system is lookup-driven. Encodings are registered as search functions via codecs.register(search_fn) . Each search function is called with a normalised encoding name and returns either None (not handled) or a CodecInfo four-tuple (encode, decode, incrementalencoder, incrementaldecoder)...

gopy flowgraph

1627. Flowgraph Port of cpython/Python/flowgraph.c (4165 lines) to gopy/compile/flowgraph.go . This spec is the detailed source-of-truth for section 7 of 1620. What flowgraph does Flowgraph takes a flat instrseq.Sequence from codegen (1626), converts it to a control-flow graph of basic blocks, runs ~25 optimisation and bookkeeping passes over the graph, and converts the graph back to a Sequence ready for assembly (1628). The optimisations are not peephole only. Jump threading,...

gopy assemble

1628. Assemble Port of cpython/Python/assemble.c (802 lines) to gopy/compile/assemble.go . This spec is the detailed source-of-truth for section 8 of 1620. What assemble does Assemble takes the optimised instrseq.Sequence from flowgraph (1627) plus the per-unit metadata from codegen (1626) and produces a final *objects.Code ready to hand to the VM (1630) or to marshal to a .pyc file (1623). The work is mostly serialisation. There are no further optimisations. Three...

gopy set

1681. Set and frozenset What we are porting Objects/setobject.c (~2500 lines). set (mutable) and frozenset (immutable, hashable) share one struct. Layout is the same open-addressing hash table as dict minus the values column. Go shape // Set mirrors PySetObject. Used for both set and frozenset; the // type is decided by the type pointer in the Header. type Set struct { Header table []setEntry used int fill int mask int...

GoPy

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 frame

1637. Frame layout and lifecycle What we are porting Python/frame.c (~700 lines) plus the _PyInterpreterFrame declarations in Include/internal/pycore_frame.h . The frame is the runtime activation record the eval loop reads and writes on every instruction: it owns the value stack, the fast locals array, the current instruction pointer, the previous frame, and a back-pointer to the code object. The Python-visible frame object (the one sys._getframe() returns) is a thin wrapper...

gopy dict

1680. Dict and OrderedDict What we are porting Objects/dictobject.c (~5500 lines). Insertion-ordered open-addressing hash table. The dual-table layout (compact index array + dense entry array) introduced in 3.6 and kept through 3.14. Combined / split storage for instance dicts. Objects/odictobject.c (~1500 lines). collections.OrderedDict C accelerator. Distinct from dict despite both preserving order: OrderedDict has move_to_end and equality compares order. Go shape // Dict mirrors PyDictObject. Compact-and-ordered. type Dict struct {...

gopy call

1684. Call protocol What we are porting Objects/call.c (~1500 lines). Every Python call goes through here. Three layers: Generic PyObject_Call(callable, args, kwargs) . The vectorcall fast path: PyObject_Vectorcall(callable, args, nargsf, kwnames) . Avoids constructing a tuple/dict for typical calls. The bound-method / classmethod / staticmethod call routing. Vectorcall is what the v0.6 VM hot path uses (CALL opcode). This spec gates v0.6 because the bytecode interpreter cannot be fast without...

gopy pegen

1642. PEG runtime and generated parser What we are porting The PEG parser is two files at runtime: Parser/pegen.c : the runtime. ~3500 lines. Memo cache, token buffer, error pinning, _PyPegen_* helpers used by the generated rules. Parser/parser.c : the generated parser. ~40k lines, regenerated from Grammar/python.gram by Tools/peg_generator/ . Each rule is one C function returning an AST node or NULL . Parser/peg_api.c is a thin public wrapper (...

gopy float and complex

1674. Float and complex What we are porting Objects/floatobject.c (~2400 lines): boxed IEEE-754 binary64. Numeric protocol, repr (shortest-roundtrip via dtoa), hash, __format__ , parsing. Objects/complexobject.c (~1400 lines): complex built on two float64 fields. Same numeric protocol shape with explicit real/imag. floatobject.c lands in v0.2 (it gates the v0.2 repr corpus). complexobject.c lands in v0.6 (no upstream user before then). Go shape // Float mirrors PyFloatObject. type Float struct { Header...

gopy lifecycle

1622. Lifecycle: initialize, finalize, configuration What we are porting Five C files, ~11k lines total, that together drive the runtime from cold start to Py_Initialize() returning, and back down through Py_Finalize() : Python/pylifecycle.c (~3.6k lines). The Py_Initialize and Py_Finalize entry points plus the staged init phases: preinit, core, main. Sets up the runtime, builtins, sys, the initial thread state, and the import system. Python/preconfig.c (~1k lines). Pre-init: locale, encoding detection,...

gopy descriptor and method

1685. Descriptor and method What we are porting Four files, ~5000 lines: Objects/descrobject.c : descriptor objects ( property , member_descriptor , getset_descriptor , method_descriptor , wrapper_descriptor , slot_wrapper ). The descriptor protocol ( __get__ , __set__ , __delete__ ). Objects/methodobject.c : PyCFunction (built-in functions and bound methods of C-implemented methods). v0.4 lands the surface; v0.6 wires it into the VM call path. Objects/classobject.c : bound-method ( method ) for Python...

gopy myreadline

1645. myreadline What we are porting Parser/myreadline.c (~700 lines) is CPython's host-readline shim. It owns: The signal-safe PyOS_Readline entry point that the REPL calls one line at a time. Integration with GNU readline / libedit when present. The fallback for when no readline library is linked (raw stdin with Ctrl-C handling). Atomicity around PyOS_FinalizeReadline . This file is the smallest of the parser block and the most divergent from CPython,...

gopy pysync spec

1606. Synchronization primitives ( pysync/ ) CPython's runtime uses a small set of custom synchronization primitives that have semantics distinct from sync.Mutex / sync.Cond : PyMutex is a 1-byte field with a parked-waiter flag. It does not use a heavy OS mutex per instance. _PyRawMutex is the same idea but reuses the mutex word itself as the head of a linked list of waiters, so it can be used inside...

gopy overview

1600. gopy: Porting CPython's Python/ to Go Goal gopy is a fresh re-implementation of CPython's interpreter core in Go. The target is 100% behavioural compatibility with the upstream CPython 3.14-era sources at $HOME/github/python/cpython . That means same data structures, same models, same code logic, same wire formats, same error messages. The only change is naming and surface API style , which adopts Go-idiomatic conventions modelled on the Go standard library....

gopy intrinsics

1635. Intrinsic dispatch What we are porting Python/intrinsics.c (~400 lines). Two opcodes, CALL_INTRINSIC_1 and CALL_INTRINSIC_2 , are emitted by the compiler in places where a runtime helper is cleaner than a dedicated opcode. The oparg selects which helper to call. This is a small, well-bounded surface. The helper set is closed: about 10 unary intrinsics and 4 binary intrinsics. CPython adds to it sparingly (one or two per release), so...

gopy tokenize

1665. Tokenize What we are porting One file from cpython/Python/ : C source Lines Go target Python-tokenize.c 445 tokenize/tokenize.go Python-tokenize.c is the Python-visible wrapper around the lexer. It exposes the _tokenize.TokenizerIter class that tokenize.tokenize() in the stdlib delegates to. The actual lexer (state machine, indent tracking, f-string handling, encoding detection) lives in cpython/Parser/tokenizer/ and is in the parser spec series. This spec is small on purpose. It covers only the...

gopy long

1673. Long (int) What we are porting Objects/longobject.c (~6500 lines). The most-used numeric type in CPython. Arbitrary precision via 30-bit digit arrays (15-bit on 32-bit builds, but gopy is 64-bit-only). Per-process cache of the small-int range ( -5..256 ). Numeric-protocol slot table covering add, subtract, multiply, true/floor div, mod, pow, bitwise ops, shifts, negation, abs, conversion to/from float, hashing, repr, parsing from string with arbitrary base. CPython 3.12+ stores small...

gopy stackref

1638. Stack reference values What we are porting Python/stackrefs.c (~250 lines) plus the inline declarations in Include/internal/pycore_stackref.h . The stackref system is CPython's compact representation for stack values that distinguishes "strong reference" from "borrowed reference" without spending a refcount op per push. It is the foundation the eval loop's stack operations are written against. A stackref is a tagged pointer: the low bit (or a deferred-refcount bit on free-threading) marks...

gopy gc, weakrefs, finalizers

1613. gopy gc, weakrefs, finalizers Goal Port CPython's cycle collector and weakref machinery to Go so that the user-visible behaviour of the gc and weakref modules matches upstream byte-for-byte. v0.3 shipped a refcount/finalizer skeleton at gc/gc.go ; gc.Collect() is currently a no-op ( gc/gc.go:113 ). v0.10 makes it real. Why a Python collector on top of Go's GC Go's runtime already reclaims unreachable cycles. We do not need a second...

gopy object protocol

1671. Object protocol What we are porting cpython/Include/object.h and cpython/Include/cpython/object.h define PyObject and PyVarObject . Every Python value carries a header with a refcount and a type pointer; variable-size types (tuple, str, bytes, int) add an ob_size field. In CPython: struct _object { Py_ssize_t ob_refcnt; PyTypeObject *ob_type; }; typedef struct { PyObject ob_base; Py_ssize_t ob_size; } PyVarObject; The free-threaded build adds ob_tid , ob_mutex , ob_gc_bits , ob_ref_local , ob_ref_shared...

gopy type

1672. Type and slots What we are porting PyTypeObject is the meta-class. Every Python value has an ob_type pointing to its PyTypeObject . The type carries slots: function pointers for arithmetic, comparison, hashing, calling, attribute access, and so on. Slots are the dispatch table that drives the entire object protocol. CPython has roughly 80 slots split across tp_* (type-level), nb_* (numeric protocol, PyNumberMethods ), sq_* (sequence, PySequenceMethods ), mp_* (mapping,...

gopy roadmap

1603. Phased roadmap The port advances along a critical path: runtime state, then object model, then compiler, then VM, then import, then runtime polish . Each phase has a boot test and a release tag. Anything past v0.5 can interleave; the order before v0.5 is load-bearing. Each phase lists: In scope : which cpython/Python/* files are ported in this phase. Out of scope : explicitly deferred to a later phase....

gopy bytes

1676. Bytes and bytearray What we are porting Three files, ~6000 lines total: Objects/bytesobject.c : immutable bytes . Hash, repr, the string-like method surface ( split , join , find , replace , translate , decode , etc.), parsing, % -formatting, buffer protocol exposure. Objects/bytearrayobject.c : mutable bytearray . Same method surface plus mutation ( append , extend , pop , __setitem__ , slice assignment). Objects/bytes_methods.c : shared method bodies...

gopy codegen

1626. Codegen Port of cpython/Python/codegen.c (6483 lines) to gopy/compile/codegen.go . This spec is the detailed source-of-truth for section 6 of 1620. The 1620 file keeps the cross-cutting view; the per-visitor and per-opcode detail lives here. What codegen does Codegen takes a fully-resolved scope (a symtable.Entry ) plus the AST nodes that belong to that scope, and produces an instrseq.Sequence of labelled instructions. It does not produce a finished code object;...

gopy module and misc

1688. Module, namespace, structseq, capsule, iter, enum What we are porting Six small files, ~3500 lines combined: Objects/moduleobject.c : module type. Holds __dict__ , __name__ , __doc__ , __loader__ , __spec__ , __file__ , __path__ . The dual-storage pattern: most attributes live in __dict__ , but the type also tracks md_dict , md_def , md_state for C-defined modules. Objects/namespaceobject.c : types.SimpleNamespace . Tiny: attribute access through __dict__ , repr lists...

gopy file map

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

gopy marshal

1690. marshal (Python/marshal.c) What we are porting Python/marshal.c (2163 lines): the binary serialisation format that Python uses for .pyc bytecode files, marshal.dumps / marshal.loads , and the compile-time constant pool. Every .pyc file is a 16-byte header followed by a marshalled code object. The existing marshal/marshal.go skeleton (v0.5) handles None, bool, int (TYPE_INT), float (binary), str, bytes, tuple, and list. The following are missing and must land in v0.8: TYPE_LONG:...

gopy import

1691. Import system (Python/import.c, Python/frozen.c) What we are porting Python/import.c (4956 lines) and Python/frozen.c (132 lines): the full module import machinery. The import system is the gating deliverable for v0.8. import json; json.dumps({"a": 1}) requires all of the following to work: sys.modules dict lookup (fast path). Frozen importlib._bootstrap bootstrap sequence. A source-file loader ( .py source to parse + compile + exec). A .pyc bytecode-cache loader (read, validate via source...

gopy eval loop

1636. Eval loop and dispatch macros What we are porting Two files, ~10k lines total: Python/ceval.c (~9000 lines): the Tier-1 eval loop. Entry, dispatch, exception unwind, frame push/pop on call and return, generator resume, eval breaker poll points, and the small set of hand-written opcodes that do not live in bytecodes.c (RESUME, ENTER_EXECUTOR, INSTRUMENTED_*). Python/ceval_macros.h (~700 lines): macros the generated dispatch arms expand against. STACK_GROW, GETLOCAL, SETLOCAL, TARGET, DISPATCH, JUMPBY,...

gopy runtime helpers

1668. getopt and hashtable What we are porting Two unrelated but small files bundled into one spec: C source Lines Go target Python/getopt.c 163 getopt/getopt.go Python/hashtable.c 424 hashtable/hashtable.go Both are pre-existing infrastructure that other v0.9 callers depend on but neither warranted their own multi-page spec. They share this file because the alternative is two near-empty specs. getopt Python/getopt.c is not GNU getopt; CPython ships its own to avoid locale and...

gopy contextvars

1663. Context, ContextVar, Token What we are porting C source Lines Go target Python/context.c 1359 contextvar/context.go Python/_contextvars.c 68 contextvar/module.go _contextvars.c is the thin module-init wrapper that exposes the three classes ( Context , ContextVar , Token ) under the _contextvars import name. context.c is the full implementation, including the HAMT-backed mapping, the per-thread context stack, and Context.run() semantics. What contextvars is PEP 567 gives you per-task implicit state with snapshot-and-restore...

gopy eval gil

1639. GIL and eval breaker What we are porting Python/ceval_gil.c (~1500 lines) plus the eval-breaker bit declarations in Include/internal/pycore_ceval.h . Two intertwined concerns: GIL : the global interpreter lock. CPython serializes Python bytecode execution behind one mutex per interpreter. The eval loop drops it on long-running C calls and re-acquires it before returning to Python. Eval breaker : a bitfield the eval loop polls each RESUME and each backward jump....

gopy abstract

1683. Abstract protocol What we are porting Objects/abstract.c (~3000 lines). The dispatcher layer between the VM and the type slots. Every BINARY_OP, COMPARE_OP, GET_ITER, FOR_ITER opcode (and their kin) routes through here. Five families: PyObject_* : Length, GetItem, SetItem, DelItem, GetAttr, SetAttr, RichCompare, Hash, Type, IsInstance, IsSubclass, Repr, Str, Bytes, Format, Call, Iter. PyNumber_* : Add, Subtract, Multiply, MatMul, TrueDivide, FloorDivide, Remainder, Divmod, Power, Negative, Positive, Absolute, Invert, Lshift, Rshift,...

gopy hash

1661. Hash What we are porting cpython/Python/pyhash.c (498 lines). Plus the public API in cpython/Include/pyhash.h . The companion seed-init file cpython/Python/bootstrap_hash.c was already ported to hash/secret.go in v0.1 (spec 1607). pyhash.c carries: SipHash-1-3 the default hash for str, bytes, memoryview, and any object whose hash falls back to a buffer hash. Two 64-bit rounds in compress, three in finalize. FNV-1a the fallback path used when CPython is built with Py_HASH_ALGORITHM...

gopy parser errors and helpers

1643. Parser errors, action helpers, token table What we are porting Three small-to-medium files plus the token table: Parser/pegen_errors.c (~1500 lines): every SyntaxError text the parser emits. Most of CPython's user-visible parser quality lives here: "expected ':'", "cannot assign to ...", "did you mean :=?". Parser/action_helpers.c (~1500 lines): the helpers the generated parser calls in rule actions to build AST nodes. _PyPegen_singleton_seq , _PyPegen_seq_insert_in_front , _PyPegen_join_names_with_dot , etc. Parser/peg_api.c (~200...

gopy slice and range

1682. Slice and range What we are porting Objects/sliceobject.c (~700 lines). The slice type plus the Ellipsis singleton (cross-listed in 1675). Slice indices are arbitrary objects until normalization. Objects/rangeobject.c (~1100 lines). The range type and its iterator. Lazy: stores (start, stop, step) , never materialises the sequence. Go shape // Slice mirrors PySliceObject. type Slice struct { Header Start Object // may be None Stop Object Step Object // may...

gopy parser overview

1640. gopy: Porting CPython's Parser/ to Go Goal The 1640-1645 block covers the port of cpython/Parser/ : the PEG-driven Python parser, the lexer state machine, the tokenizer drivers, the string literal parser, the error helpers, and interactive readline. About 30k lines of C across roughly 18 files. The output of this block is a Go function that takes source text (or a readline callback) and returns an *ast.Module ready for...

gopy bool and singletons

1675. Bool, None, NotImplemented What we are porting Objects/boolobject.c (~250 lines). bool is a subtype of int with exactly two singleton instances ( True , False ). Most slots inherit from int ; only repr , str , __and__ , __or__ , __xor__ override. The None singleton from Objects/object.c . Type NoneType , one instance, repr 'None' , hash 0 . The NotImplemented singleton. Type NotImplementedType , one instance, repr...

gopy pythread spec

1605. Threads ( pythread/ ) What we port and what we drop cpython/Python/thread.c is the cross-platform shim. It includes one of thread_pthread.h , thread_pthread_stubs.h , thread_nt.h to get the platform primitives. Go's runtime already provides goroutines, preemption, and a scheduler, so the platform .h files are dropped outright (they are listed as -- in 1602). We port only the cross-platform layer. In v0.1 the surface is intentionally narrow: C entry...

gopy code, frame, generator

1687. Code, frame, generator, cell What we are porting Four files, ~6000 lines. The objects that exist because there is a bytecode interpreter: Objects/codeobject.c : code object. Bytecode, consts, names, varnames, freevars, cellvars, line/exception tables, co_flags, co_qualname, co_name, co_filename, co_firstlineno. PEP 626 / 657 tables. Objects/frameobject.c : frame object. The runtime activation record. f_back, f_code, f_locals, f_globals, f_builtins, f_lasti, f_lineno, f_trace, f_trace_lines, f_trace_opcodes. The PEP 558 fast-locals proxy. Objects/genobject.c :...

gopy arena spec

1604. Arena allocator ( arena/ ) The arena is a bump allocator with a linked list of fixed-size blocks. The compiler pipeline (parser, AST, symbol table, codegen) allocates many small short-lived nodes that share a lifetime: they are all freed together when compilation of a module finishes. CPython implements this with pyarena.c . gopy ports the same shape into pure Go. C reference Source: cpython/Python/pyarena.c (207 lines). Key constants: DEFAULT_BLOCK_SIZE...

gopy bytecodes DSL

1621. Bytecodes DSL and Go-emitting generator What we are porting CPython's bytecode interpreter is generated. The source of truth is Python/bytecodes.c , a C file written in a small DSL. The upstream generator lives in Tools/cases_generator/ (Python), walks the DSL, and emits five C headers: Generated file Consumer Python/generated_cases.c.h Python/ceval.c Python/executor_cases.c.h Python/optimizer.c (Tier-2) Python/optimizer_cases.c.h Python/optimizer.c (analysis) Include/internal/pycore_opcode_metadata.h shared metadata Include/internal/pycore_uop_metadata.h Tier-2 micro-op metadata For v0.6 we need just two: the...

gopy errors

1611. errors: exception protocol What we are porting Two files from CPython: cpython/Python/errors.c (about 2200 lines). Holds the C-API for setting, fetching, clearing, formatting, normalizing, and printing exceptions, plus the chaining ( __cause__ / __context__ ) machinery. Reads and writes through the current thread state. cpython/Objects/exceptions.c (about 4500 lines). Defines every built-in exception class, the BaseException slots ( args , traceback , __cause__ , __context__ , __suppress_context__ , __notes__ ),...

gopy v0.5 testing strategy

1625. v0.5 testing strategy This spec is the test-side companion to 1620 and 1665. The checklist in 1620 names every Go file that must land for v0.5; this spec names the test that proves each file matches CPython 3.14. The rule is one-to-one: every implementation checkbox in 1620 has a test checkbox here. A v0.5 release ships only when every box on both specs is ticked. Layered gates The v0.5...

gopy vm remaining bytecodes

1693. Remaining Tier-1 bytecodes What we are porting Five panels of opcodes from cpython/Python/bytecodes.c that the v0.6 VM left as ErrNotImplemented placeholders. With v0.8 the import machinery (1691) became real, which unblocked IMPORT_* . The rest land here. Panel Opcodes CPython lines Import IMPORT_NAME, IMPORT_FROM, IMPORT_STAR (intrinsic) 2863, 2873 Generator RETURN_GENERATOR, YIELD_VALUE, SEND, GET_YIELD_FROM_ITER, CLEANUP_THROW 4982, 1370, 1297, 3091, 1471 Pattern MATCH_MAPPING, MATCH_SEQUENCE, MATCH_KEYS, MATCH_CLASS 3062, 3067, 3072, 3043 With/finally...

gopy naming conventions

1601. Naming conventions: CPython C to gopy Go The port keeps structure , logic , and field-by-field state identical to CPython. Only identifier surface changes. This file is the canonical translation table. When in doubt, follow these rules. Guiding principles Preserve fidelity. A Go reader should be able to grep CPython for the original symbol and find the Go counterpart in seconds. Look like Go stdlib. Match conventions of go/ast...

Spec

gopy string parser

1644. String literal parser What we are porting Parser/string_parser.c (~2000 lines) is the post-tokenizer that turns a STRING / FSTRING_* token sequence into one of: ast.Constant{Value: str|bytes} for plain string and bytes literals. ast.JoinedStr{Values: [Constant | FormattedValue]} for f-strings ( f"..." ). ast.TemplateStr{Values: [Constant | Interpolation]} for t-strings ( t"..." , PEP 750, 3.14). It owns escape sequence decoding ( \n , \xHH , \uHHHH , \UHHHHHHHH , \N{NAME} ,...

gopy compile golden tests

1629. Compile golden tests This spec lives next to 1625 (the broad v0.5 testing strategy) but narrows to one thing: the disassembly-golden corpus that pins the output of the full compile pipeline ( symtable -> codegen -> flowgraph -> assemble ) for a curated panel of programs. The marshal-byte parity gate against host CPython lands in v0.8 with the import system. Until then the disassembly text is the gate: it...

gopy pythonrun

1624. Pythonrun: source-to-result entry points What we are porting Python/pythonrun.c (~1.7k lines). Three concerns: String / file evaluation . PyRun_SimpleString , PyRun_AnyFile , PyRun_FileEx , PyRun_String . The plumbing that takes a chunk of source, calls the parser, compiles, and runs through the VM. Interactive REPL . PyRun_InteractiveLoop and friends. Reads a line, parses, compiles, runs, prints. Until EOF. .pyc read/write helpers . _PyRun_PycFile and the marshal-magic check. (The marshal...

gopy objects misc

1689. Object misc (weakref, memoryview, file, typing, templates, obmalloc) What we are porting Ten files, ~7500 lines combined. The "everything else" of Objects/ : Objects/weakrefobject.c : weak references, weakref proxies, callback chains. v0.10 along with cycle GC. Objects/memoryobject.c : memoryview . The buffer-protocol consumer. v0.10. Objects/fileobject.c : small set of file-object helpers ( PyFile_WriteObject , PyFile_GetLine ). The actual file types come from io/ stdlib; this file is just glue....