errors

Documentation

Overview

Package errors ports cpython/Python/errors.c and the gating subset of cpython/Objects/exceptions.c. v0.3 ships the BaseException class hierarchy needed by v0.1 and v0.2, plus the Set/SetString/Format/ Occurred/Clear/Fetch/Restore/Raise/RaiseFrom/Print API.

Index

• Variables
• func AttachTraceback(ts *state.Thread, entry traceback.Entry)
• func Clear(ts *state.Thread)
• func FormatException(exc *Exception) string
• func IsSubtype(sub, super *objects.Type) bool
• func Match(exc *Exception, t *objects.Type) bool
• func NormalizeException(ts *state.Thread)
• func Print(ts *state.Thread, w io.Writer)
• func Raise(ts *state.Thread, exc *Exception)
• func RaiseFrom(ts *state.Thread, exc, cause *Exception)
• func Restore(ts *state.Thread, typ *objects.Type, value *Exception, tb *traceback.Traceback)
• func Set(ts *state.Thread, t *objects.Type, args *objects.Tuple)
• func SetString(ts *state.Thread, t *objects.Type, msg string)
• func SuggestAttr(name string, candidates []string) string
• func SuggestKey(key string, candidates []string) string
• type Exception
  • func Fetch(ts *state.Thread) (typ *objects.Type, value *Exception, tb *traceback.Traceback)
  • func Format(ts *state.Thread, t *objects.Type, format string, args ...any) *Exception
  • func New(t *objects.Type, args *objects.Tuple) *Exception
  • func Occurred(ts *state.Thread) *Exception
  • func (e *Exception) IsException()
  • func (e *Exception) Message() string
  • func (e *Exception) TypeName() string

Variables

var (
	PyExc_BaseException       = newExcType("BaseException", []*objects.Type{objects.ObjectType()})
	PyExc_Exception           = newExcType("Exception", []*objects.Type{PyExc_BaseException})
	PyExc_LookupError         = newExcType("LookupError", []*objects.Type{PyExc_Exception})
	PyExc_ArithmeticError     = newExcType("ArithmeticError", []*objects.Type{PyExc_Exception})
	PyExc_RuntimeError        = newExcType("RuntimeError", []*objects.Type{PyExc_Exception})
	PyExc_KeyError            = newExcType("KeyError", []*objects.Type{PyExc_LookupError})
	PyExc_IndexError          = newExcType("IndexError", []*objects.Type{PyExc_LookupError})
	PyExc_OverflowError       = newExcType("OverflowError", []*objects.Type{PyExc_ArithmeticError})
	PyExc_ZeroDivisionError   = newExcType("ZeroDivisionError", []*objects.Type{PyExc_ArithmeticError})
	PyExc_NotImplementedError = newExcType("NotImplementedError", []*objects.Type{PyExc_RuntimeError})
	PyExc_AttributeError      = newExcType("AttributeError", []*objects.Type{PyExc_Exception})
	PyExc_NameError           = newExcType("NameError", []*objects.Type{PyExc_Exception})
	PyExc_TypeError           = newExcType("TypeError", []*objects.Type{PyExc_Exception})
	PyExc_ValueError          = newExcType("ValueError", []*objects.Type{PyExc_Exception})
	PyExc_StopIteration       = newExcType("StopIteration", []*objects.Type{PyExc_Exception})
)

Built-in exception type singletons. Names match CPython.

CPython: Objects/exceptions.c:L1937 PyExc_BaseException and friends

Functions

func AttachTraceback

func AttachTraceback(ts *state.Thread, entry traceback.Entry)

AttachTraceback prepends entry to the current exception's traceback. The VM (v0.6+) calls this on every frame unwind; v0.3 callers (Go-side) use it to record their own positions.

CPython: Python/traceback.c:L154 PyTraceBack_Here

func Clear

func Clear(ts *state.Thread)

Clear drops the current exception. Mirrors PyErr_Clear.

CPython: Python/errors.c:L488 _PyErr_Clear

func FormatException

func FormatException(exc *Exception) string

FormatException returns the multi-line rendering of exc, including any chained __cause__ / __context__ exceptions. Mirrors `traceback.format_exception`.

CPython: Python/traceback.c:L1129 _PyErr_Display

func IsSubtype

func IsSubtype(sub, super *objects.Type) bool

IsSubtype reports whether sub inherits from super, walking the MRO.

CPython: Objects/typeobject.c:L2556 PyType_IsSubtype

func Match

func Match(exc *Exception, t *objects.Type) bool

Match reports whether exc's type inherits from t. Mirrors PyErr_GivenExceptionMatches.

CPython: Python/errors.c:L327 PyErr_GivenExceptionMatches

func NormalizeException

func NormalizeException(ts *state.Thread)

NormalizeException is a no-op in the modern API path; Set / Raise already produce a normalized Exception. Preserved for source-shape parity with CPython's legacy three-argument form.

CPython: Python/errors.c:L501 _PyErr_NormalizeException

func Print

func Print(ts *state.Thread, w io.Writer)

Print writes FormatException of the current exception to w and clears the slot. Mirrors PyErr_Print.

CPython: Python/pythonrun.c:L656 PyErr_Print

func Raise

func Raise(ts *state.Thread, exc *Exception)

Raise installs exc as the current exception. If a previous exception was current, it becomes exc.Context.

CPython: Python/errors.c:L83 _PyErr_SetObject (chaining branch)

func RaiseFrom

func RaiseFrom(ts *state.Thread, exc, cause *Exception)

RaiseFrom is `raise exc from cause`. It sets exc.Cause and suppresses context display.

CPython: Python/errors.c:L1438 _PyErr_SetFromCause

func Restore

func Restore(ts *state.Thread, typ *objects.Type, value *Exception, tb *traceback.Traceback)

Restore atomically installs an exception triple. Mirrors PyErr_Restore.

CPython: Python/errors.c:L37 _PyErr_Restore

func Set

func Set(ts *state.Thread, t *objects.Type, args *objects.Tuple)

Set raises an exception of type t with the given args.

CPython: Python/errors.c:L83 _PyErr_SetObject

func SetString

func SetString(ts *state.Thread, t *objects.Type, msg string)

SetString raises an exception of type t with a single-string args.

CPython: Python/errors.c:L283 _PyErr_SetString

func SuggestAttr

func SuggestAttr(name string, candidates []string) string

SuggestAttr returns a "Did you mean: 'name'?" candidate for an AttributeError, picking the closest match from candidates by Levenshtein distance. Returns "" when nothing is close enough.

CPython: Python/suggestions.c:L335 _Py_Offer_Suggestions for getattr

func SuggestKey

func SuggestKey(key string, candidates []string) string

SuggestKey returns a "Did you mean: 'key'?" candidate for a KeyError. CPython only suggests for string keys against string keys in a dict; gopy applies the same rule at the call site.

CPython: Python/suggestions.c:L398 _Py_Offer_Suggestions for KeyError

Types

type Exception

type Exception struct {
	objects.Header
	ExcType  *objects.Type
	Args     *objects.Tuple
	Cause    *Exception
	Context  *Exception
	Suppress bool
	Notes    *objects.List
	TB       *traceback.Traceback
}

Exception is the runtime representation of a raised Python exception. Mirrors PyBaseExceptionObject.

CPython: Objects/exceptions.c:L34 BaseExceptionObject

func Fetch

func Fetch(ts *state.Thread) (typ *objects.Type, value *Exception, tb *traceback.Traceback)

Fetch atomically removes and returns the current exception triple (type, value, traceback). Mirrors PyErr_Fetch.

CPython: Python/errors.c:L460 _PyErr_Fetch

func Format

func Format(ts *state.Thread, t *objects.Type, format string, args ...any) *Exception

Format raises an exception built from a printf-style template. Returns nil so callers can `return errors.Format(ts, ...)`.

CPython: Python/errors.c:L1138 _PyErr_FormatV

func New

func New(t *objects.Type, args *objects.Tuple) *Exception

New constructs an exception with the given type and args. Mirrors BaseException_new + BaseException_init.

CPython: Objects/exceptions.c:L42 BaseException_new

func Occurred

func Occurred(ts *state.Thread) *Exception

Occurred returns the current exception or nil. Mirrors PyErr_Occurred.

CPython: Python/errors.c:L138 _PyErr_Occurred

func (*Exception) IsException

func (e *Exception) IsException()

IsException implements the state.Exception marker.

func (*Exception) Message

func (e *Exception) Message() string

Message returns the exception's args[0] as a string when args has one item, matching CPython's BaseException.__str__ for single-arg exceptions.

CPython: Objects/exceptions.c:L226 BaseException_str

func (*Exception) TypeName

func (e *Exception) TypeName() string

TypeName returns the class name. Mirrors `type(exc).__name__`.

CPython: Objects/exceptions.c:L226 BaseException_str