Unsupported & Fallback

Pyvorin does not compile every Python construct. When compilation is impossible, it falls back to CPython transparently so your program keeps running correctly.

Execution Tiers

Tier	Meaning
COMPILED_FULL	Entire function compiled to native machine code.
COMPILED_PARTIAL	Some regions compiled; others execute in CPython.
COMPATIBILITY_EXECUTED	Entire function ran in CPython (fallback).
DEOPTED	Was native, but deoptimised at runtime due to a guard failure.
UNSUPPORTED	Could not compile; compatibility execution used.
FAILED	Compilation or execution error.

Currently Unsupported Constructs

Construct	Fallback Behaviour
async / await	Compatibility execution (CPython).
eval / exec	Compatibility execution.
yield / generators	Compatibility execution.
global / nonlocal	Compatibility execution.
Arbitrary imports	Compatibility execution.
**kwargs	Compatibility execution.
GPU training / CUDA	Not applicable; use your ML framework directly.
Heavy NumPy / Pandas internals	Compatibility execution or partial compilation.
Network-bound services	Compatibility execution (Python overhead is usually not the bottleneck).

How Fallback Works

Compile-Time Fallback

Before compilation, the AST is scanned for unsupported nodes. If any are found:

• The unsupported features are recorded in CompileResult.unsupported_features.
• If the function can still be partially compiled, it receives COMPILED_PARTIAL.
• If compilation is impossible, the function is marked COMPATIBILITY_EXECUTED and runs in CPython.

Runtime Deoptimisation

Even fully compiled functions may deoptimise at runtime:

• A guard checks a type assumption (e.g., "this variable is always int").
• If the guard fails (e.g., the variable becomes float), execution jumps back to CPython.
• ExecutionStatus.deopt_count is incremented.
• Subsequent calls may recompile with updated type information.

Explicit Fallback

You can force fallback via:

• Environment variable: PYVORIN_FORCE_FALLBACK=1
• CLI flag: pyvorin-thin run --no-fallback (disables it) or rely on default --fallback

Fallback is Never Silent

Pyvorin emits a UserWarning whenever fallback occurs and records the reason in the execution status. You can inspect fallback history with:

pyvorin-thin report

Minimising Fallback

• Use supported types: int, float, list, dict, str, tuple.
• Avoid unsupported constructs in hot paths.
• Keep types stable across loop iterations.
• Run pyvorin-thin scan your_script.py to identify risks before compiling.