Skip to content

v0.3.0.md

Latest commit

 

History

History
97 lines (71 loc) · 2.91 KB

v0.3.0.md

File metadata and controls

97 lines (71 loc) · 2.91 KB
Raw

v0.3.0 - 2026-05-04

Errors, traceback, and the refcount path of the GC. After v0.3 a Go caller can raise a Python exception, catch it, walk the chain, and format a traceback. The interpreter still does not run Python code.

Shipped

errors/

Port of cpython/Python/errors.c and cpython/Objects/exceptions.c gating subset:

  • Set, SetString, Format, Occurred, Clear, Fetch, Restore, Raise, RaiseFrom, NormalizeException, AttachTraceback, Print, FormatException, Match, IsSubtype.
  • Exception class hierarchy (matches CPython MRO): BaseException, Exception, LookupError, KeyError, IndexError, ArithmeticError, OverflowError, ZeroDivisionError, RuntimeError, NotImplementedError, AttributeError, NameError, TypeError, ValueError, StopIteration. OSError, ImportError, and the Warning subtree land in later phases as callers need them.
  • KeyError.__str__ override that wraps a single arg via repr.
  • __cause__ / __context__ chaining via Raise/RaiseFrom plus __suppress_context__.

traceback/

Port of cpython/Python/traceback.c:

  • TracebackEntry (file, line, name).
  • Format, FormatException, Print.
  • Hook points for the VM to push frames; in v0.3 the VM is absent so entries are pushed by errors.Set* directly from the Go call site.

errors/suggest.go

Port of cpython/Python/suggestions.c:

  • SuggestAttr(obj, name) string for AttributeError.
  • SuggestKey(mapping, key) string for KeyError.
  • Levenshtein distance with the small-distance fast path.

gc/ (refcount path only)

Port of the rc-only path in cpython/Python/gc.c:

  • RegisterFinalizer, Finalize, Track, Untrack.
  • Cycle collection is a no-op in v0.3; the cycle collector lands in v0.10.

brc/ (partial)

Port of cpython/Python/brc.c field layout only:

  • BiasedRefcount struct with the per-thread queue header.
  • All ops are no-ops in the GIL build.

state/ (skeleton)

Port of the structs from cpython/Python/pystate.c:

  • Runtime, Interpreter, Thread structs. No init flow yet (that arrives in v0.7 with pylifecycle).
  • Thread.exc carries the current exception so errors.Occurred(ts) has somewhere to read.

Gate

ts := state.NewThread()
errors.SetString(ts, errors.PyExc_ValueError, "boom")
exc := errors.Occurred(ts)
if exc == nil {
    t.Fatal("expected exception")
}
errors.AttachTraceback(ts, traceback.Entry{File: "a.py", Line: 1, Name: "f"})
out := errors.FormatException(errors.Occurred(ts))
if len(out) == 0 {
    t.Fatal("empty traceback")
}

Compatibility

  • Go: 1.26 or newer.
  • CPython behavioural target: 3.14.0+.
  • Exception messages must match CPython byte for byte for the leaves v0.3 ships.

Out of scope

  • Cycle collector. v0.10.
  • Free-threading exception slot. v0.14.
  • qsbr and finalize-on-resurrect. v0.10 / v0.14.
  • Real frames in tracebacks. The VM lands in v0.6.