1622. gopy lifecycle

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, -X flags read before site.py runs.
• Python/initconfig.c (~4.7k lines). The full PyConfig schema, env-var and CLI parsing, defaults, validation.
• Python/pathconfig.c (~600 lines). sys.path defaults, prefix/exec_prefix discovery, PYTHONHOME handling.
• Python/interpconfig.c (~300 lines). Per-sub-interpreter config knobs (mostly relevant in v0.13).

The companion Python/pythonrun.c lives in spec 1624 because its surface (REPL, PyRun_*) is consumer-facing rather than init-time.

Why this lands in v0.7

In v0.6 the cmd/gopy entry point hand-rolled a tiny boot sequence: state.NewThread, builtins.Init, then vm.EvalCode. v0.7 replaces that with the real CPython lifecycle so gopy -c and gopy script.py both flow through Py_Initialize / pythonrun / Py_Finalize. Once 1622 is in place, every later subsystem (import in v0.8, contextvars in v0.9, monitor in v0.11) can attach via the standard init hooks instead of bespoke wiring.

Package layout

gopy/
  initconfig/             # 1622: preconfig + initconfig
    preconfig.go
    config.go
    config_env.go         # PYTHON* env-var parsing
    config_cli.go         # CLI -X / -c / -m parsing
    config_validate.go
  pathconfig/             # 1622: path discovery
    pathconfig.go
    pathconfig_unix.go
    pathconfig_win.go
  lifecycle/              # 1622: Py_Initialize / Py_Finalize
    init.go
    init_phases.go
    finalize.go
    interp.go
    main.go               # the Py_Main equivalent that cmd/gopy calls
  pythonrun/              # 1624: separate spec, listed for context
    runstring.go
    runfile.go
    repl.go
    pyc.go

Existing v0.6 packages it touches:

• gopy/state: Runtime / Interpreter / Thread already exist but were minimal. Lifecycle wires them through the real init.
• gopy/builtins: builtins.Init keeps its signature but becomes one of the init phases instead of the entry point.
• gopy/cmd/gopy: main.go shrinks to a thin lifecycle.Main(os.Args) call.

Init staging (the porting unit)

CPython splits init into ordered phases. We mirror them one-for-one because import, signals, codecs, and warnings each attach at a specific phase and changing the order would change when their callbacks fire.

Phase	CPython call	gopy entry
pre-init: locale + UTF-8	_PyPreConfig_Read	initconfig.PreConfig.Read
pre-init: allocators	_PyPreConfig_InitFromPreConfig	initconfig.PreConfig.Apply
core init: runtime alloc	pyinit_core step 1	lifecycle.initRuntime
core init: types	_PyTypes_InitTypes	(handled in objects, called here)
core init: builtins	_PyBuiltin_Init	builtins.Init (already exists)
core init: sys	_PySys_Create	sysmod.Init (1651)
core init: import system	init_importlib_external	(deferred to v0.8 spec 1623)
main init: site/userpath	init_set_builtins_open, pymain_run_*	pythonrun.* (1624)
finalize: shutdown phases	Py_FinalizeEx	lifecycle.Finalize

Each row maps to one Go function with a CPython citation. The spec 1622 work order is top-to-bottom: a phase only lands when the phase above it lands.

v0.7 release blockers

Tracked as individual tasks; each one must close before tagging v0.7.0.

• 1622-A Port PyPreConfig struct + defaults + PyPreConfig_InitPythonConfig. CPython: Python/preconfig.c:33 PyPreConfig_InitPythonConfig.
• 1622-B Port the PYTHON* env-var reader subset gopy honours (PYTHONHOME, PYTHONPATH, PYTHONHASHSEED, PYTHONDONTWRITEBYTECODE, PYTHONUNBUFFERED, PYTHONUTF8, PYTHONDEBUG, PYTHONVERBOSE, PYTHONOPTIMIZE, PYTHONNOUSERSITE). CPython: Python/initconfig.c:_Py_str_to_int panel.
• 1622-C Port the PyConfig struct (the v0.7 subset; full schema lands incrementally with later phases).
• 1622-D Port PyConfig_Read (env then CLI then defaults). CPython: Python/initconfig.c:_PyConfig_Read.
• 1622-E Port pyinit_core and pyinit_main skeletons. CPython: Python/pylifecycle.c:pyinit_core, Python/pylifecycle.c:pyinit_main.
• 1622-F Port the path-config defaults for darwin and linux (Windows arrives later). CPython: Modules/getpath.py is the modern source: gopy reimplements the resolved logic in Go.
• 1622-G Port Py_Finalize shutdown order (modules, sys, threads, types, runtime). CPython: Python/pylifecycle.c:Py_FinalizeEx.
• 1622-H lifecycle.Main entry: parses args, runs init, hands off to pythonrun, runs finalize. CPython: Modules/main.c:Py_Main.

Test gates

• lifecycle/init_test.go: Initialize, ask for state.GetThreadState(), Finalize, Initialize again. Must not panic and must not leak goroutines (counted via runtime.NumGoroutine).
• lifecycle/main_test.go: feed []string{"-c", "print(1+2)"} through lifecycle.Main with a captured stdout. Output is "3\n" and exit code 0.
• initconfig/config_test.go: env-var precedence: a flag set in env is overridden by a CLI value; CLI is overridden by an explicit PyConfig field set after Read.
• pathconfig/pathconfig_unix_test.go: given a synthetic prefix layout (a temp dir with lib/python3.14/), the resolved sys.path matches the documented order from Doc/using/cmdline.rst.

Out of scope for v0.7

• Py_NewInterpreter and the sub-interpreter init flow stays stubbed; spec 1622 lands a single-interpreter shape.
• The pymain_run_module import-driven case (gopy -m foo) is gated on import (v0.8); v0.7 returns ErrNotImplemented.
• Py_BytesMain (the wide-char Windows entry) is deferred.

CPython divergences worth pinning here

• gopy never reads C-level allocator hooks (PyMemAllocatorEx) because Go owns allocation. The fields exist on PyPreConfig for shape parity but have no effect.
• sys.implementation.cache_tag is "gopy-3140" (see 1690_quirks). The init code that builds sys.implementation must hard-code this string and pin it in tests.