Specs

This is the canonical specification set for gopy. Each spec is a long-form plan for one part of the CPython port. We write the spec before the code, keep it in sync as the port lands, and use it as the source of truth when something behaves surprisingly.

Specs are split into two series:

• The 1600 series covers the runtime port itself, organized by CPython subsystem. Each number maps to a slice of CPython's source tree: parser, compiler, VM, object protocol, GC, imports, codecs, and so on. If you want to know how a CPython function gets to Go, start here.
• The 1700 series covers the test gate and porting workflow. It catalogs the end-to-end test corpus, tracks which subsystems have been audited for full ports, and records the lessons learned while vendoring CPython sources.

1600 series: runtime port

Foundations

• 1600. Overview. Top-level goals, scoping, and what 100% behavioural compatibility means in practice.
• 1601. Naming conventions. The translation table from CPython C names to Go-idiomatic identifiers.
• 1602. File map. How CPython source files map to gopy packages.
• 1603. Roadmap. Release-by-release porting plan.

Runtime infrastructure

• 1604. Arena allocator
• 1605. PyThread
• 1606. PySync primitives
• 1607. Hash secret
• 1611. Errors and exceptions infrastructure
• 1613. Garbage collector
• 1668. Runtime helpers

Compile pipeline

• 1620. Compile pipeline overview
• 1621. Bytecodes DSL
• 1622. Lifecycle
• 1624. PythonRun
• 1625. Compile testing
• 1626. Codegen
• 1627. Flowgraph
• 1628. Assembler
• 1629. Compile goldens

Virtual machine

• 1630. VM overview
• 1635. Intrinsics
• 1636. Eval loop
• 1637. Frame
• 1638. Stackref
• 1639. Eval / GIL
• 1693. VM remaining bytecodes

Parser

• 1640. Parser overview
• 1641. Lexer and tokenizer
• 1642. PEG generator
• 1643. Parser errors
• 1644. String parser
• 1645. MyReadline
• 1665. Tokenize module

Strings, numbers, hashing

• 1660. Strings and numbers
• 1661. Hash
• 1662. HAMT
• 1663. Context
• 1664. Time

Objects

• 1670. Objects overview
• 1671. Object protocol
• 1672. Type object
• 1673. Long
• 1674. Float and complex
• 1675. Bool and None
• 1676. Bytes
• 1677. Unicode
• 1678. Tuple
• 1679. List
• 1680. Dict
• 1681. Set
• 1682. Slice and range
• 1683. Abstract object protocol
• 1684. Call protocol
• 1685. Descriptors and methods
• 1686. Exceptions hierarchy
• 1687. Code, frame, generator
• 1688. Module and misc
• 1689. Object misc

Imports, marshalling, codecs

• 1651. Modules
• 1690. Marshal
• 1691. Import
• 1692. Codecs

Optimizer and instrumentation

• 1694. Specialize
• 1695. Instrumentation
• 1696. Legacy tracing
• 1697. Optimizer overview
• 1698. Optimizer uops
• 1699. Optimizer analysis

1700 series: test gate and porting workflow

• 1700. End-to-end test suite. Master plan for porting CPython's Lib/test/ corpus.
• 1701. Unittest enablement. Bring up the unittest package end-to-end so test files can run.
• 1702. Subsystem port log. Per-module ledger of "ported in full" vs "still a shim".
• 1703. re and _sre full port. Replace the RE2 fallback with a CPython-faithful interpreter.
• 1704. Object protocol full port. Eight-phase plan to bring Objects/object.c to parity.

How to read a spec

Every spec follows the same shape:

1. Goal. What problem the spec is solving and the constraint (usually "match CPython 1:1").
2. Sources. The CPython files and line ranges the spec covers.
3. Mapping. The Go names, packages, and field layouts the port uses, with the CPython equivalents alongside.
4. Checklist (1700 series). The shipped vs. pending steps. We keep this current as work lands.
5. Notes. Edge cases, surprises from the CPython source, and anything that diverged and why.

When a spec disagrees with the code, the code is right and the spec is the bug. We update the spec, not the runtime, unless the runtime itself is wrong.