cpython-extensions

Production-oriented CPython 3.13 extensions for switch dispatch, guarded specialization/partial evaluation, bytecode-level function inlining, and validated local goto.

The distribution is cpython-extensions and the primary import package is python_extensions. The project deliberately targets CPython internals and currently supports CPython 3.13.x (>=3.13,<3.14).

python -m pip install cpython-extensions

from python_extensions import (
    case,
    enable_goto,
    enable_switch,
    hotpath,
    inline_calls,
    inline_function,
    optimize_extensions,
    partial,
    runtime_diagnostics,
    specialize,
    switch,
)

goto .name and label .name are compile-time pseudo-statements recognized inside @enable_goto functions; they are not runtime objects that need to be imported.

At a glance

The package favors general Python semantics, explicit opt-ins, bounded adaptive state, and fail-closed transformation over benchmark-specific shortcuts.

Why cpython-extensions?

Python intentionally keeps its language and execution model structured. Some hot interpreters, parsers, generated state machines, numeric kernels, and stable internal helpers nevertheless benefit from lower-level control. cpython-extensions provides a set of CPython-specific transformations while keeping the selected plan inspectable and independently verifiable.

• Switch — efficient multi-route dispatch without a manually maintained handler dictionary or long if/elif ladder.
• Partial / specialize / hotpath — expose constants and exact runtime types to the bytecode optimizer while retaining explicit guards or generic fallback where required.
• Inline — clone eligible helper bodies into callers, with profitability analysis and guarded binding for replaceable targets.
• Goto — local control-flow jumps for generated state machines and carefully audited low-level code.

This is not a replacement Python implementation and does not claim portability to PyPy or other interpreters.

Quick start

Switch dispatch

from python_extensions import case, enable_switch, switch

@enable_switch
def classify(command: str) -> int:
    with switch(command):
        if case("read", "peek"):
            return 1
        if case("write"):
            return 2
        if case():
            return 0

Use exact runtime type as part of case identity when Python's ordinary equality aliases are undesirable:

@enable_switch(case_key_mode="typed")
def exact(value):
    with switch(value):
        if case(1):
            return "int"
        if case(1.0):
            return "float"
        if case(True):
            return "bool"
        if case():
            return "other"

The default mode="auto" is deliberately portable and never mutates executable bytecode unless you explicitly supply live_threshold. In 1.3.0 that threshold opt-in is plan-aware: direct-value, expression-template, and statement-template portable plans veto live mutation even above the threshold because their compact lowering is already the preferred architecture. Live dispatch remains a CPython-3.13-only optimization for hot, repeated in-frame routing:

@enable_switch(mode="fast", live_engine="auto")
def run_vm(opcodes):
    acc = 0
    for opcode in opcodes:
        with switch(opcode):
            if case(0):
                acc += 1
            if case(1):
                acc ^= 7
            # ... many heterogeneous opcode bodies ...
    return acc

live_engine="auto" uses the optional fused C dispatcher when its runtime self-test succeeds and otherwise falls back to the historical ctypes gate. live_engine="native" requires the C accelerator; live_engine="ctypes" is mainly useful for diagnostics and reproducible comparisons.

Do not assume live is universally faster. The extensive 1.2.0 qualification shows strong gains for large dense integer VM/parser loops, while portable statement-template/direct-value lowering remains preferable for ordinary HTTP/RPC routing and trivial cases. See Live switch architecture and performance.

Partial evaluation

from python_extensions import partial

def parse(data, mode="safe"):
    if mode == "fast":
        return fast_parse(data)
    return checked_parse(data)

fast_parse_only = partial(parse, mode="fast")

partial() produces a transformed Python function whose frozen parameters are removed from the effective call signature. Safe constant propagation and dead-branch elimination are applied without changing observable local-variable behavior.

Guarded specialization

from python_extensions import specialize

@specialize(constants={"mode": "fast"}, types={"value": int})
def convert(value, mode="safe"):
    if type(value) is int and mode == "fast":
        return value + 1
    return slow_convert(value, mode)

The specialized variant is guarded. A guard miss executes the original generic function. Exact-type and constant guards are used only where their matching semantics are safe.

Adaptive hot paths

from python_extensions import hotpath

@hotpath(threshold=64, max_variants=1, policy="speed")
def decode(value, mode):
    if mode == "binary":
        return decode_binary(value)
    return decode_text(value)

hotpath() observes only a bounded number of shapes for a bounded profiling budget. On eligible ordinary functions, backend="auto" prefers CPython 3.13 sys.monitoring during warm-up and can install a verified in-frame dispatcher after promotion. It falls back to a wrapper where that contract is not suitable. See Specialization and partial evaluation.

Function inlining

from python_extensions import inline_calls, inline_function

@inline_function(register_only=True)
def affine(x: int, scale: int = 4) -> int:
    return x * scale + 3

@inline_calls(policy="speed")
def hot_path(x: int) -> int:
    return affine(x)

The default binding="frozen" is the highest-optimization mode and assumes the target intentionally remains stable after transformation. Use guarded binding when a callee may be rebound or mutated:

@inline_calls(policy="always", binding="guarded")
def plugin_sensitive(x):
    return affine(x)

Validated goto

from python_extensions import enable_goto

@enable_goto
def countdown(n: int) -> int:
    total = 0
    label .loop
    if n <= 0:
        goto .done
    total += n
    n -= 1
    goto .loop
    label .done
    return total

Strict mode is the production default and rejects jumps that cross unsafe control-flow or exception-region boundaries.

The source-level notation is inspired in part by Entrian's “goto for Python”. cpython-extensions uses an independent CPython 3.13 lowering pipeline with strict CFG/exception-region validation and post-transform verification.

Compose extensions

Composition uses one fixed order:

switch -> partial -> inline -> goto -> specialize/hotpath

from python_extensions import optimize_extensions

@optimize_extensions(
    switch=True,
    partial={"mode": "fast"},
    inline={"policy": "speed"},
    goto=True,
    specialize={"types": {"value": int}},
)
def execute(value, mode="safe"):
    ...

specialize and hotpath are alternative final layers and cannot both be enabled in the same pipeline.

Inspect transformed functions rather than blindly trusting them:

from python_extensions import explain_extensions, verify_code

print(explain_extensions(execute))
verify_code(execute.__code__)

Choosing the right mode

Installation and native accelerator

PyPI

python -m pip install cpython-extensions

When the build environment can compile the optional extension, the installed wheel contains python_extensions._livegate, the native live-switch accelerator. Source installations retain portable/ctypes functionality if that optional extension build is unavailable. Tagged Linux releases are built on GitHub Actions as PyPI-compatible manylinux wheels via cibuildwheel; raw linux_x86_64 setuptools wheels are never staged for publication.

Check availability:

import importlib.util
print(importlib.util.find_spec("python_extensions._livegate") is not None)

The native accelerator is not imported automatically on free-threaded CPython 3.13 builds because this release does not certify live self-modifying dispatch for no-GIL execution. Portable switch mode remains the supported path there.

Development checkout

git clone https://github.com/Karvp/cpython-extensions.git
cd cpython-extensions
python -m venv .venv

Windows PowerShell:

.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev]"
python -m pytest

POSIX shells:

source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
python -m pytest

Runtime qualification and diagnostics

Version 1.3.0 performs bounded package-owned runtime qualification automatically during import python_extensions. The import-time probe verifies the CPython 3.13 wordcode/alignment contract, required opcodes, CodeType.replace, exception-table decoding, the shared CFG/stack verifier, portable switch execution, and goto runtime prerequisites. It never calls application functions.

Historically lazy or mutation-sensitive checks remain deferred so ordinary import stays bounded. Request the complete snapshot when diagnosing a deployment:

from python_extensions import runtime_diagnostics

print(runtime_diagnostics())
print(runtime_diagnostics(full=True))

full=True additionally qualifies live-switch memory layout/native _livegate when supported and the bytecode-dependent inline/specialization subsystems. Results and failures are cached per process; returned dictionaries are detached copies. Free-threaded CPython reports live mode as unsupported rather than importing the native live accelerator. See Runtime qualification.

Verification and development gates

python -m compileall -q src tests tools benchmarks/scripts
python -m pytest
python -m coverage run --branch -m pytest
python -m coverage report
python tools/check_repo.py

Long-running stress tests are intentionally separated from ordinary pull-request feedback. See .github/workflows/stress.yml and the harnesses under tests/.

Release quality

Version 1.3.0 is the current documented release line. It keeps the 1.2.0 generated hot paths intact while reducing transformation/profiling overhead, adds bounded automatic runtime qualification, makes switch(mode="auto", live_threshold=...) plan-aware, and migrates the current source/release license to GPL-3.0-only. Historical 1.0.x–1.2.0 artifacts retain the licenses under which they were distributed.

The final 1.3.0 qualification on CPython 3.13.5 records 458/458 native-enabled tests, the same 458/458 under CPython -X dev, debug allocation, and warnings-as-errors, plus the inherited 8,316,000-call specialization adversarial and 1,239,100-call live-switch compatibility harnesses. Optimization evidence records faster construction for goto/switch/inline/partial/specialize and approximately 1.94× faster monomorphic hotpath profiling before promotion; representative steady-state transformed co_code fingerprints remain identical to 1.2.0.

Release evidence:

• PYTHON_EXTENSIONS_1.3.0_CERTIFICATION.txt
• RELEASE_AUDIT_1.3.0.txt
• docs/RELEASE_NOTES.md
• benchmarks/results/BENCHMARK_OPTIMIZATION_V130.md
• benchmarks/results/BENCHMARK_OPTIMIZATION_V130.json
• benchmarks/results/BENCHMARK_LIVE_EXTENSIVE_V122.md for retained 1.2 live-workload qualification.

The v121/v122/v130 suffixes in benchmark and regression filenames are engineering evidence identifiers, not package versions.

1.3.0 optimization evidence

The V130 benchmark separates transformation/profiling cost from steady-state execution. On the certified CPython 3.13.5 host, median construction improved by about 1.15× goto, 1.13× switch-auto, 1.24× inline, 1.07× partial, and 1.18× explicit specialize. Monomorphic hotpath warm-up profiling improved from about 1216.7 ns/call to 628.3 ns/call (1.94×).

Automatic import qualification adds a measured import cost (11.73 ms → 13.14 ms in the recorded fresh-process sample). That overhead is intentional and bounded; expensive lazy/mutation-sensitive probes are deferred. Representative steady-state code fingerprints are byte-identical to 1.2.0, so short-run timing movement there is not advertised as a generated-code speedup.

Performance: use workload shape, not slogans

The portable compiler and live backend solve different problems. Portable mode is still the default because it can often collapse direct values and shared statement/expression shapes into extremely compact dispatch. Live mode keeps heterogeneous bodies inline and changes a bytecode jump gate at runtime; it is strongest when one outer call performs many dispatches among many distinct code regions.

Selected real-backend CPython 3.13.5 results from the extensive qualification:

A separate 10,000,384-dispatch 1,024-route VM sample recorded about 329.4 ns portable vs 169.0 ns native, or 1.95×. A 10-million-dispatch HTTP loop remained essentially tied (228.9 ns portable vs 231.2 ns native).

For a classic server that performs one router call per request, the 64-route control measured approximately 135.9 ns portable, 141.0 ns shared native, and 246.2 ns thread-local native. This is why ordinary web routing should remain portable even though live dispatch is excellent for interpreter loops embedded inside a request or worker.

These are measured results from one certified host, not universal guarantees. CPU, OS, CPython patch/build, adaptive state, key type, route-body shape, traffic distribution, and surrounding work matter. Read the live-switch guide and benchmark methodology before making a backend decision.

The earlier 1.1.0 direct-value scaling evidence remains valid and is retained unchanged under benchmarks/results/: it answers a different question—how a portable table-backed switch scales against linear if/elif and match chains.

Documentation

• Comprehensive guide — complete API, composition, deployment, and troubleshooting guidance.
• Runtime qualification — automatic import-time checks, exhaustive diagnostics, caching, failure behavior, and deployment interpretation.
• Live switch architecture and performance — native/ctypes engines, concurrency contracts, benchmark interpretation, and workload selection.
• Specialization and partial evaluation — partial, specialize, hotpath, guards, profiling bounds, and composition.
• Architecture — transformation pipeline, invariants, and subsystem responsibilities.
• Compatibility — interpreter/runtime/build support boundary.
• Release process — reproducible build, artifact verification, and tag/release workflow.
• Release notes — release summaries.
• Benchmarks — benchmark reproduction and evidence-retention rules.
• Changelog — public release changes.
• Contributing — development expectations and test requirements.
• Security policy — reporting verifier, crash, unsafe-boundary, and native live-gate issues.

Repository metadata

Canonical repository: Karvp/cpython-extensions. Recommended repository settings and topics are tracked in .github/REPOSITORY_METADATA.md.

Recommended GitHub description:

CPython 3.13 extensions for fast switch/live dispatch, specialization, function inlining, and verified local goto.

Contributing

Contributions are welcome when they preserve general Python semantics and avoid benchmark- or fixture-specific shortcuts. Performance changes must include correctness coverage and a workload-appropriate benchmark; a microbenchmark win is not sufficient if a broader certified workload regresses.

See CONTRIBUTING.md.

Security

Low-level bytecode transformation and explicit live self-modification amplify interpreter/runtime assumptions. Crashes, verifier bypasses, incorrect exception-region handling, unsafe gate writes, or unexpected no-GIL behavior should be treated as security-relevant until triaged.

See SECURITY.md.

License

The current source and the 1.3.0 release are licensed under the GNU General Public License v3.0 only (GPL-3.0-only). See LICENSE.

This is a strong-copyleft license. Distribution of covered or derivative works must comply with GPLv3's source and licensing obligations. Releases that were already distributed under MPL-2.0 retain those historical license grants; the 1.3.0 relicensing does not revoke them.