Reference
Divergences from CPython

Divergences from CPython

pyscriptc targets CPython 3.14.x. Parsing, probes and the compatibility oracle follow 3.14.
Compiled programs match CPython 3.14 on stdout for everything that compiles, except the numbered divergences below.
The list is load-bearing: anything not listed here is claimed identical, so a difference you find that is not listed is a bug.

Constructs pyscriptc cannot compile are not divergences.
They stop the compile with a PSxxxx code, and every code is in Diagnostics.

Parity contract

stdout: byte-exact for every compiled call. The corpus scorer compares whitespace-stripped stdout; the nightly strict corpus A/B lane (scripts/strict_corpus_ab.py) compares untrimmed bytes over the visible corpus and reports every difference it finds.
stderr: for a raises probe, only the exception name must appear. Full traceback text is not matched.
exit code: an uncaught exception prints its name to stderr and exits 1, as CPython does. An uncaught SystemExit follows CPython’s own rule instead: an int value is the exit status, a str value is written to stderr and the process exits 1, and no value exits 0, with no class name or traceback text printed. raise SystemExit(<int>) from <cause> does not compile (PS2003).

The tool host and the target

The compiler runs on CPython 3.11 through 3.15 (requires-python = ">=3.11"); the program it emits claims CPython 3.14 (src/pyscriptc/target.json). The two are separate, and the split is the contract:

The source grammar is the host’s. The compiler parses user source with the host interpreter’s ast, so a source the host cannot parse is a SyntaxError before pyscriptc sees it. Syntax newer than the host (PEP 646 def f[*Ts], for example) needs a host that knows it; a 3.11 host refuses such a source where a 3.14 host lowers it.
The emitted semantics are the target’s. The error wording (division by zero), the baked sys.version constant, the sys.version_info branch folds, the typeshed version gate, the dependency resolution’s Python minor and the runtime pack’s stdlib tree all read target.json, not the host. A 3.11 host and a 3.14 host emit the same program for the same source; the canonical IR of the whole probe corpus is byte-identical across 3.11, 3.13, 3.14 and 3.15 hosts once the cpython stamp line is stripped (the stamp names the lowering interpreter by design, and the typed hash serializer (pyscriptc/tirhash.py) never emits it, so the IR hash gate is unaffected).
The island mirrors the host it links. A program that embeds CPython runs the interpreter the binary carries, and sys.executable is the binary’s own path (divergence 41 and 42 describe the embedded interpreter’s version).
The verify oracle still needs a 3.14 interpreter. The PS3001 refusal names uv python install 3.14.

Two constants are deliberately not target-pinned, because they describe the machine rather than the program: sys.executable (an environment path, which the IR hash serializer classifies as incidental) and the host’s own sys.platform.

Numbered divergences

Every entry has a row and a probe in divergence-ledger.json, regenerated by scripts/gen_divergence_ledger.py; a test replays each row’s recorded bytes, so a divergence that is fixed or that moves is a reviewed change.

int is i64. Overflow aborts the process instead of growing a big int.
// and % by zero raise ZeroDivisionError matching CPython 3.14’s division by zero (or 3.13’s variant on a 3.13 host), rather than aborting the process.
The str model is mid-migration to the CPython code-point model (epic #472; this item is rewritten again when it lands). A str is a UTF-8 byte buffer with a code-point count and an ASCII flag, so len, indexing, slicing and the find/count/justify family count code points, the case family applies the full Unicode 16.0.0 mappings, and text output (stdout, text-mode files, stdin reads) is UTF-8 bytes as CPython writes it. A literal may hold any scalar code point; a lone surrogate stops the compile with PS2005 (no UTF-8 bytes to store). chr() with a literal surrogate stops with PS2005; at run time, chr() with a variable surrogate code point raises ValueError: chr() arg not in range(0x110000) where CPython returns the surrogate character. format widths and precisions count code points, repr follows CPython’s escape rules (repr("café") is 'caf\xe9'), %c and the c spec take a code point, and the six is* predicates plus isascii decide on code points. The is* predicates that need Unicode category tables beyond the case data (isalpha/isalnum on a non-cased code point, isspace beyond ASCII) raise NotImplementedError naming the predicate and the code point. translate, maketrans, istitle, isdecimal, isnumeric, isprintable, iscapitalize do not compile (PS2001). Still Latin-1-bound: unicodedata covers only Latin-1 code points and a normalization that would leave Latin-1 raises ValueError; re and json are separate items (4 and 5).
re is the runtime’s byte-oriented backtracking subset, not CPython’s re. L, T, DEBUG and unknown flag bits raise ValueError, A and U are no-ops, and a pattern that can loop without consuming stops with RuntimeError once its fuel is spent. Five or more groups are refused.
json has no non-ASCII text.
Set and frozenset iteration is insertion order, not CPython’s hash order. Length and membership match.
After for i in range(0), a new loop target reads as 0 instead of raising UnboundLocalError.
A subclass __init__ that never assigns an inherited field leaves it at the zero value of its type instead of raising AttributeError.
raise AppError("no") for a user exception class stores a code and an optional str and does not call __init__.
@classmethod and @staticmethod of the form Class.method(...) do not pass the class object.
Some library failures surface as a different exception type: importlib.resources.files on a zip or missing package raises ValueError rather than ModuleNotFoundError, shutil.copyfile of the same path raises RuntimeError rather than SameFileError, other shutil and os failures (except os.mkdir, os.makedirs and Path.mkdir which raise FileExistsError) are RuntimeError, and type errors on unicodedata calls surface as ValueError.
assert is always evaluated; a compiled binary has no -O.
x is None compiles as == against None. Identical for None because it is a singleton; every other is on a scalar is refused.
ABC, ABCMeta, Protocol, @abstractmethod and @overload compile as plain classes and methods with no CPython runtime semantics.
Calls that run through embedded CPython (subprocess.check_output, socket.gethostname, threading, logging) follow the interpreter the binary links, not the pin.
dotenv compiles a closed subset of python-dotenv’s parsing rules, and it differs from the library in three places. The subset: a UTF-8 BOM is stripped, blank lines and whole-line comments are skipped, an export prefix is allowed, keys are bare (KEY alone binds None), an unquoted value runs to the end of the line with the # comment cut and the rest right-stripped, a double-quoted value decodes \" \\' \\ \a \b \f \n \r \t \v and a single-quoted one only \\ and \', and a later binding overwrites an earlier one. No interpolation ($NAME stays literal), no multi-line values, no quoted keys, and the stream, verbose, interpolate, override and encoding arguments are refused. The three differences: a malformed line raises ValueError where python-dotenv skips it with a warning, a missing file parses as the empty document where python-dotenv searches with find_dotenv(), and load_dotenv does not overwrite a variable that is already in the environment (its override=False default) while still returning True for a document with bindings.
yaml.safe_load covers a closed YAML subset, not all of PyYAML: timestamps and sexagesimal numbers (1:30) raise ValueError where PyYAML resolves them to date and int objects, and errors surface as ValueError rather than yaml.YAMLError.
Plaintext http:// is native: the compiled program makes the request itself, with no subprocess and no host curl. https:// rides the system libcurl, linked at build time as a shared library (issue #235): a program whose emitted IR reaches an https:// URL gains libcurl’s flags (resolved through curl-config --libs or pkg-config libcurl) on its link line, so the libcurl development package is a build dependency of such a program and the compile fails with a diagnostic naming the package to install when neither tool finds it (apt install libcurl-dev on Debian/Ubuntu, brew install curl on macOS, dnf install libcurl-devel on Fedora). PSC_CURL_DYNAMIC=1 opts out of the build-time link; the https:// request then raises OSError at run time where CPython makes the request. Peer and hostname verification stay on in every shape; there is no insecure fallback. An http://-only program carries no libcurl dependency. See HTTP.
generator.send(v) on a generator that has not started ignores v and runs the body from the top, where CPython raises TypeError: can't send non-None value to a just-started generator. None (the priming send) behaves identically in both.
generator.throw(E) marks the frame done and raises E out of the call site. CPython’s “the generator catches it, execution continues” outcome is not reachable through this surface: throw is a separate entry point that never runs the generator’s own except handlers. GeneratorExit semantics do not apply either: close() marks the frame done without running a pending finally, where CPython raises GeneratorExit inside the generator so its finally runs.
yield from <subgenerator> drains the subgenerator and discards its return value (StopIteration.value), where CPython’s yield from expression evaluates to it. Statement-form yield from (the only form that compiles) never reads the value, so no observable program differs. A return <value> in a generator compiles (the value rides in the frame) but no surface reads it back.
The curated pyscriptc-jwt distribution package compiles the HMAC family only: HS256, HS384 and HS512 through jwt.encode and jwt.decode over a dict[str, str] payload. RS/ES algorithms and a non-literal algorithm argument stop the compile where PyJWT signs with a private key, claims beyond str values (exp, aud) are refused, errors surface as ValueError rather than PyJWT’s InvalidTokenError hierarchy, and a multi-claim payload is emitted with the claims sorted by key where PyJWT emits insertion order (decode does not depend on the order; single-claim tokens are byte-identical to PyJWT’s).
The curated pyscriptc-orjson distribution package compiles orjson.dumps and orjson.loads over the same C JSON writer and reader as json: compact bytes output, OPT_SORT_KEYS and OPT_INDENT_2, with the json subset’s value shapes. The default= callable, every other OPT_* flag, orjson.Fragment and orjson’s extended types (dataclass, UUID, datetime, numpy) are refused, and errors surface as ValueError rather than orjson.JSONDecodeError.
@contextmanager runs the body’s code after the yield when the with exits cleanly, and re-raises the in-flight exception when the body raises, but the CPython gen.throw path that lets the generator catch the exception is unreachable: the manager’s __exit__ marks the frame done instead of throwing into it, so a try/except inside the generator cannot see the in-flight exception.
A finally that is pending when the generator is abandoned does not run: close() marks the frame done and drops the pending finally, where CPython raises GeneratorExit inside the generator so its finally runs and its cleanup happens. A finally that is reached because the generator runs to completion or raises through the try behaves exactly like CPython’s.
The threading surface that needs a second thread (threading.Thread, threading.Condition, threading.Semaphore, threading.Event, queue.Queue) is native-only: on a wasm32 target the link is refused with a diagnostic naming the target and the runtime symbols it cannot use, because wasi-libc stubs pthread_create to return EAGAIN and its pthread_cond_wait traps. The threading.Lock primitives that need no second thread are unaffected.
The HTTP client is a closed subset of urllib.request: only urlopen and Request compile. urlopen accepts url, data and timeout; headers ride the Request as a dict display with constant str keys and values, so runtime-built header dicts are refused. urlretrieve, openers and proxy handling are refused. The error types are synthetic HTTPError and URLError records that match through the OSError chain, not the full urllib.error class surface. See HTTP.
https:// raises OSError in the compiled program: the native client speaks plaintext HTTP/1.1 only, because TLS (mbedTLS through the FFI manifest) has not landed. CPython raises nothing and makes the request. Issue #235.
socket, ssl, http.client and http.server do not compile: an import of any of them stops the compile with PS2001 naming the module. CPython provides them. Inbound servers and http.client keep-alive are issues #227-#230 and #237; the event loop underneath (epoll/kqueue) is #177, which is also why asyncio I/O without the compiled run/sleep/gather/create_task/wait_for surface is refused. selectors compiles as a closed subset over that loop (src/pyscriptc/runtime/ps_select.c, the DefaultSelector records over the #177 poller): DefaultSelector, SelectorKey, EVENT_READ/EVENT_WRITE, and register/unregister/modify/select/get_key/close. The subset takes a bare int fd where CPython takes a fileobj - the typed socket handle is #229, and until it lands the fd-carrying object has no type to hand over, so sel.register(sock, events) fences with PS1003 naming #229. Two further shapes differ from CPython: select() returns list[SelectorKey], not CPython’s list[tuple[SelectorKey, int]] pairs, and get_key of an unregistered fd returns None, where CPython raises KeyError. SelectorKey carries fd and events; CPython’s fileobj and data attributes stay outside the subset for the same #229 reason. When #229 lands, register reads the fd off the handle and the runtime records do not change. The scope decision is recorded in issue #485.
urlopen and Request are native-only: on the wasm32 and *-windows-* targets the runtime stub raises URLError (an OSError) at run time with a message naming the target family, because WASI has no sockets and Windows needs winsock. Programs that never call urlopen link unchanged for those targets.
On wasm32-wasi-musl the program is a WASI preview1 command module, and the preview1 surface is smaller than a POSIX host: there is no subprocess (fork/exec has no WASI story, so subprocess calls are refused at link time with a diagnostic naming the target), no dlopen and therefore no native-to-embedded call (zlib.crc32 through that path is refused the same way), no symbolic links (os.symlink and os.readlink are refused at link time with the same target-naming diagnostic), and no fallback mode (already refused for every cross target). The threading primitives that compile everywhere (Lock, RLock, get_ident, active_count, current_thread().name) work on the one thread a WASI program has; wasi-libc’s pthread stubs never block, and threading.Thread is refused on every target. The filesystem is preopen-only, so the wasmtime invocation must pass --dir or -S dir::/path preopens for the program to see any file; os.getcwd and the tempfile helpers write into whatever is preopened. tempfile.NamedTemporaryFile and tempfile.mkstemp use an open(O_CREAT|O_EXCL) port (ps_mkstemp) because wasi-libc declares no mkstemp; the file lands in whatever preopen holds the temp directory. The emitted entry point is @__main_argc_argv on wasm targets, since wasm-ld resolves a C-style main only through that name. Everything else is unchanged: the smoke lane proves stdout byte-identical to the native binary on the same program.
On wasm32-wasi-p2 the program is a WASI 0.2 component: the same preview1 core module wrapped by wasm-tools component new --adapt with the preview1 adapter pinned from the wasmtime v50.0.0 release (URL, version and sha256 recorded in src/pyscriptc/wasm_adapter.py; a fetched adapter whose digest does not match the pin is refused, never used). The component imports wasi:cli/run@0.2.x instead of the raw preview1 functions, and every constraint of divergence 31 applies unchanged. There is no thread world to spawn into on 0.2; threading arrives with the WASI 0.3 coop-threads lane, which is a separate deliverable. Generators compile through the wrap unchanged.
On a *-windows-* target the program is a Win32 PE binary built by cross-compilation, and the Win32 surface is smaller than a POSIX host in ways the runtime cannot paper over: os.path.islink is always false and os.lstat follows the link instead of reporting it, because Windows has no lstat; path handling is Win32-flavoured, so \ and / are both separators, drive letters (C:\) are absolute, and os.path.join still emits /; os.symlink makes file links only and os.readlink raises RuntimeError at run time, because Windows has no CRT readlink; urlopen and Request raise URLError at run time because the HTTP client needs BSD sockets and Windows needs winsock. The remaining Windows semantics (CRLF stdout, input(), signals, threading) are unverified rather than claimed: the emitted binaries are never executed anywhere, in CI or otherwise. Windows is experimental cross-compilation only; native Windows compiles are not supported yet.
Only refusals in modules the compiled tree’s import graph reaches stop a compile with dependency source roots (PyPI pure wheels, issue #424). In a program the graph starts at the entry module; in a library package it starts at every module, because any of them can be the consumer’s import target. The rule rests on CPython’s import-time side effect rule: a module body runs once, at the import that reaches it, and never otherwise, so a dependency module the tree never imports never runs and a refusal inside it cannot change what the compiled program does. Such a module is pruned (named on stderr as a note, not compiled) or kept in the export table without compiling when an unreached program module imports it. A reached dependency refusal stops the compile with its code and the distribution that ships it. The reach walk is static and name-based, so a dynamic import (importlib.import_module, __import__, both refused) never extends it. The program’s own modules keep the whole-tree rule: a refusal in one of them always stops the compile. CPython runs every module whose import appears anywhere in the executed call graph, so a program whose entry reaches that module through a dynamic import behaves differently: CPython refuses at run time or succeeds through the import, where the compile succeeded without the module’s code.
The __getattr__ hook compiles for unknown-name reads only, and only for one shape: a plain instance method def __getattr__(self, name: str) -> T. The read compiles as a direct call of the first MRO definer with the attribute name as a compile-time constant, and the hook’s declared return type must cover the read site exactly (PS4204 otherwise). Everything else in the dynamic attribute protocol stays refused at the definition site: __setattr__, __getattribute__, __get__, __set__ (PS4201), __delattr__ (PS4202), __del__ (PS4203), and a __getattr__ in any other shape (a decorator, a different parameter list). Where CPython dispatches a missing attribute through __getattr__ on any shape, or an attribute write or deletion through the protocol, the compile stops instead. An unguarded read of a name the hook itself reads recurses to no limit in the binary where CPython raises RecursionError. Writes (__setattr__) are still refused. Issue #434.
The shortest float spelling sometimes carries an exponent form CPython does not use at that magnitude: 10.0 prints 1e+01 where CPython prints 10.0 (100.0 prints 1e+02). The shortest round-trip search accepts %g’s exponent spelling before CPython’s fixed-notation preference kicks in, so the value is exact and the bytes differ for whole floats whose shortest spelling picks an exponent. Values whose shortest spelling is fixed-notation (0.5, 16.1, 0.1) are byte-identical.
A round(x, n) call whose constant ndigits is outside 0 to 8 stops the compile (PS2003) where CPython rounds for -8 <= n <= 20. A variable ndigits outside the range raises ValueError: round ndigits is out of the supported range at run time. In range, round(x, n) rounds the exact binary value of x the way CPython’s dtoa path does (round(2.675, 2) is 2.67).
newline= is refused on open, so text-mode reads always apply the default universal-newline translation (\r\n and \r read as \n); a program that needs CPython’s newline="" (no translation) or a specific newline spelling cannot compile the call. encoding= compiles only as a str constant from {utf-8, ascii, latin-1} and their firm/short spellings, and it rides the same read path as the no-encoding call, so a file whose content is not representable under the subset’s byte read differs from CPython’s decode there. CPython accepts any encoding object and honors it. A third positional (buffering) and the other open keyword arguments are refused.
int(text, base) compiles for bases 2 to 36 and matches CPython’s read and messages (the leading prefix sits behind the sign, base names check like CPython’s, the surrounding-whitespace strip takes the Unicode space set, and the underscore digit separator follows CPython’s rule: one _ between two digits, never at an end, never doubled), with the i64 ceiling of divergence 1. Base 0 and out-of-range base constants stop the compile (PS2003), where CPython accepts both (base 0 prefixes off the text). One message detail stays open: an invalid literal in the bytes form is reported with the str repr (invalid literal for int() with base 10: '1x') where CPython writes the bytes repr (b'1x'), because the runtime reads both forms through one buffer ABI that does not carry the str/bytes distinction.
subprocess.run takes capture_output=, text= and check= as bool literals: check=True raises the check_call stand-in RuntimeError on a non-zero exit where CPython raises CalledProcessError carrying the cmd and returncode. text=True (or an encoding= name) decodes the captured streams through the runtime’s CPython-exact decoder (utf-8/ascii/latin-1 with strict/replace/ignore/backslashreplace), so the record’s stdout/stderr are str like CPython’s text-mode record; the default bytes path is unchanged. cwd= compiles as a str, Path or None; input=, shell= and the remaining popen keyword arguments are refused.
Fallback mode (compile --fallback=cpython, alias --island) routes a function pyscriptc cannot compile to embedded CPython: that function’s source segment plus the module’s top-level imports and module-global initializers are exec’d once inside the binary (so a global initializer runs again in the embedded interpreter; for a deterministic initializer like Path.home() / x the value matches, and a change to a global made there is never visible to native code), and every call to it crosses into the embedded interpreter. Under fallback mode an annotated function that accumulates an unbounded int also runs there (issue #677): a conservative static check finds the growth shape (a *=, <<=, **= in-place update, or the loop-carry assign name = name <op> anything with a multiplying operator) and plans that function for the embedded interpreter instead of letting the native i64 overflow of divergence 1 abort it, so an annotated program keeps CPython’s arbitrary-precision result where the same function compiled natively would not. A single name = name ** k assign with a literal exponent of at most 62 and no loop in the body stays native. Values cross one way per call: scalars, str, bytes and lists of scalars by value (a list is copied, so a change made there is not visible to native code), dict and everything else as an opaque handle usable through attribute reads, item reads, further calls and str()/f-string formatting, never by native operators. No object identity survives a crossing. A function running in the embedded interpreter that calls a compiled sibling stops the compile with a diagnostic naming both functions, where CPython would run the call. A class definition that pyscriptc cannot compile (@attrs.define, @dataclasses.dataclass(frozen=True), any decorator the native dataclass form does not take, class keywords, a class-body statement) or whose method bodies cannot compile is routed the same way (issue #628): the class leaves the native class table, the embedded interpreter defines it, and every compiled function that names it is routed there too. A native class method that still uses that class reaches it through the handle path: an instance is a call on the class name, a class-level attribute read goes through the handle path, and an attribute write from compiled code stops the compile because values cross one way. Functions and classes routed there run under the host CPython (3.14.x), not the compiled runtime.
With fallback mode on, the module top level is all-or-nothing: the synthesized entry body is probed like a function, and a refused probe (a module-level statement the subset does not take, an unannotated yaml.safe_load result, a Path global) plans the whole top level for the embedded interpreter instead of stopping the compile. The binary’s main seeds the embedded interpreter with the module’s own source text, exec’d once with __name__ = "__main__" (the script’s main guard fires there exactly once) and __file__ set to the compiled source path; sys.argv mirrors the process argv, so sys.argv[0] is the binary path where CPython shows the script path. raise SystemExit(status) out of the body delivers the process status (an int becomes the exit code, a str prints to stderr and exits 1), and any other uncaught exception surfaces as its own type and message with exit 1, matching CPython’s shape but not its traceback bytes. Annotated scalar globals the top level binds (LABEL: str = os.environ.get(...)) unbox once at init into native shadow slots, so typed native functions read the embedded interpreter’s initial value; a later rewrite of the global there is never visible to native code, and a native write to a global owned there stops the compile naming the global. Unannotated top-level globals stay in the embedded interpreter only. The native entry never runs when the top level is routed there: every function rides the seed, and it runs under the host CPython (3.14.x).
argparse type=Path options compile to a native Path in the namespace, but the namespace has no None slot, so an absent option cannot be None. A type=Path option without required=True or a str default stops the compile (PS2003), and a default is converted to a Path at parse time. parse_args takes None, a list of str, or an Optional list; the list form skips sys.argv.
A local that is first bound to a value and later assigned None (or an Optional call result) in a branch is not widened to Optional. The first binding fixes the type, so lp = Path(x) followed by lp = find_latest() stops the compile with PS1003, and lp is None on a plain Path stops with PS2004. The typed form lp: Optional[Path] = None compiles. Narrowing through is None and is not None guards combined with and, or, conditional expressions, early exits and loop bodies does compile.
These shapes are refused after the mechanical-delta pass, each as its own PS code: set(d) and list(d) over a dict (PS2002, the set kind takes a list of int or str), sorted(paths) over Path elements (PS2003), incremental hashlib update calls and a hashlib constructor with data (PS2003), Path.open("rb") (PS2001), collections.abc.Sequence annotations (PS1104), class-body values the compiler cannot compute (PS1204; a name = <constant> or name: T = <constant> class attribute compiles and reads through the class and its instances, and so does a value the compiler computes — a call to a lowered function, a container literal, a comprehension, a name bound at module scope — stored in a runtime slot keyed C.<name> and initialized at module init, where CPython computes it in the class body; a value with no slot form, a tuple or a float or a multi-target assign, still fences), module-level list-of-dict tables (PS1106, dict values are not heterogeneous), and a module-level Path(__file__).resolve().parents[n] constant (PS1001).
Under fallback mode for a whole program, the compile stages the program directory’s non-Python files beside the binary (<binary dir>/pyscriptc-data/<program name>/, the exact compile-time bytes) and rebases the module origins and __file__ of the embedded interpreter’s finder onto that tree, so Path(__file__).parent / "data.json" reads the staged copy after the output is relocated and the source tree is gone. Lookups that leave the program directory (Path(__file__).parent.parent / "x", absolute paths) are not staged and still resolve against the compile-time path: with the source tree absent they raise FileNotFoundError where CPython reads the real file. A single-file fallback compile stages nothing and keeps the compile-time __file__ (the same restriction divergence 42 documents). Issue #665.
os.walk(top) is a materialized list of the (dirpath, dirnames, filenames) triples in CPython’s topdown pre-order, so the visit order and the rows match a CPython walk over the same tree read in the same readdir order. The walk is computed before the loop body runs, so a body that edits dirnames does not prune the walk where CPython honours the edit; topdown=, onerror= and followlinks= are refused (os.scandir and the other os names outside the fixed rows keep their PS2001). json.load(fp) reads the whole handle and reuses the json.loads annotation path: a missing result annotation stops the compile (PS1001) where CPython returns an untyped value, and a decode failure stays the runtime ValueError. json.dump(obj, fp) serializes through the same json.dumps subset and writes the handle with one call, so the bytes are the dumps bytes (no trailing newline); the closed dumps keyword set (indent, sort_keys, ensure_ascii=True) rides along and any other keyword stops the compile (PS2003). time.perf_counter and time.monotonic read the monotonic clock as a float.
A --embed-python=bundle output carries a trimmed runtime: the standard library travels as the safe-trimmed zip (test, idlelib, tkinter, turtledemo, ensurepip, pydoc_data and __phello__ are out), the pack interpreter’s own site-packages tooling (pip) is not bundled, and the unversioned libpython3.X.so name of a bundled Linux runtime is a symlink to the versioned library, not a second copy. A program that imports a trimmed tree stops the compile closed (PS4301) where CPython imports it; a bundled program that calls pip at runtime gets the same ModuleNotFoundError a CPython interpreter without pip would. Issues #709 and #885.
The program island carries a precompiled code cache next to the embedded sources (issue #782): the compiler marshals every program unit’s code object at compile time, zlib-compresses the entries into one blob, and the seed’s loader unmarshals a module on its first import instead of compiling it (a 523 ms to 333 ms --version on yt-dlp). The cache is guarded, not trusted: each entry names the compiling interpreter’s .pyc magic number and the source’s sha256, the loader re-checks both at run time against the interpreter that runs the binary and the embedded text, and any mismatch (a binary moved to a different CPython build, a corrupted blob) falls back to compiling the source, so behavior never differs - only start time. A cached program answers CPython byte for byte; traceback frames name the same co_filename either way. Source: program_island_source and _module_code_entry in src/pyscriptc/boxed.py, ps_island_codecache in src/pyscriptc/runtime/ps_island.c, and tests/test_island_code_cache.py.
A module-scope container bound without an annotation (xs = [...], d = {...}, s = {...}) in a script is a compile-time constant: every read re-builds the literal, so the name has no object identity. Mutating it through a method call (xs.sort(), d.update(), s.add()), an item or slice store (xs[i] = v), or a copy-on-alias bind (ys = xs, x = y = xs) stops the compile with PS2002 naming the annotation fix: annotating the name (xs: list[int] = ...) gives it a global slot and CPython identity. Two paths still read copies where CPython aliases: passing the name to a function hands the callee a fresh container, so a callee that mutates its parameter leaves the module value unchanged, and ys = xs[i] binds a copy of the element, so a mutation through ys is not shared.
x += ys and x *= n on a list desugar to a fresh-concat rebind, not CPython’s in-place __iadd__/__imul__. The rebound name’s own value is right, but a second name bound to the same list keeps the old object where CPython mutates the shared one.
itertools.tee(xs) and tee(xs, 2) return a pair of eager list copies of the materialized source (restlower/_itertools.py), so later mutation of one copy does not affect the other and next is not defined on them; CPython returns two lazy iterators that share an underlying buffer. itertools.batched(xs, n) yields lists of elements (a short last list when the length is not a multiple of n) rather than tuples, because a leftover of one element cannot be a one-field tuple in the IR. Issue #490.
A class decorator other than @dataclass is erased: the class lowers undecorated (fields, methods, constructor and every read of it unchanged) and the decorator call never runs. CPython applies the decorator to the class object after the body executes, so side effects the decorator has (a registry write, a flag, a returned replacement class) are missing in the binary. Every decorator spelling other than the single @dataclass form takes the erase; the compile prints a note: PS3099 ... line on stderr and still succeeds, and the binary runs with the class’s own value semantics. Under --fallback=cpython the class keeps the decorator: it runs through embedded CPython with the wrap applied. Issue #732.
A method decorator or module-function decorator outside the closed set that does not synthesize behavior is erased: the function lowers undecorated and the decorator call never runs. CPython replaces the attribute (or the module name) with whatever the decorator returns, so side effects the decorator has (a registry write, a flag, a wrapper with different call semantics) are missing in the binary. A decorator stack that carries a behavior-synthesizing member (functools.lru_cache, functools.cache, functools.wraps, functools.singledispatchmethod) never takes the erase: the stack would lower undecorated and the synthesis would be lost with it, so it keeps its fence (PS1201 for a method, PS2006 for a module function). The closed set (property, staticmethod, classmethod, contextmanager, the erased typing names) keeps its existing lowering. The compile prints a note: PS3099 ... line per erased decorator and still succeeds. Under --fallback=cpython the decorated definition keeps the decorator: it runs through embedded CPython with the wrap applied. Issue #732.
The uuid subset covers uuid4(), uuid1(), uuid5(namespace, name) and UUID(text). uuid4 and uuid1 draw their random bytes from the host entropy source and set the version and variant bits the way CPython does, so the shape, the version nibble and the variant bits match but the values differ from CPython’s by construction. uuid5 hashes the namespace bytes and the name bytes with SHA-1 exactly as CPython does, so uuid5 and UUID are byte-identical to CPython’s. UUID is not lowered as a class: the call returns the canonical text, so str(UUID(text)) reads the way CPython’s does, and the .hex attribute of a lowered uuid call is the canonical text without the dashes (what CPython’s UUID.hex holds). The .int, .urn and .bytes forms are refused (PS2001), and uuid.UUID as a parameter or return annotation is refused (PS1106) because the lowered value is text, not a class instance.
The binascii subset covers unhexlify(text) and hexlify(data). Both are byte-identical to CPython’s for ASCII hex, including the error cases: an odd-length hex string and a non-hex character raise ValueError, which is what CPython’s binascii.Error reads as at an except (ValueError, ...) handler (binascii.Error itself is a ValueError subclass). hexlify takes bytes and returns bytes, as CPython’s does; a str argument is refused at compile time (PS1003) where CPython raises TypeError. Every other binascii name is refused (PS2001).
The shlex subset covers split(text), quote(word) and join(words). split runs CPython’s POSIX-mode lexer, so the words match CPython’s byte for byte for the quoting, escaping and comment rules; the comments flag must be a constant bool (a variable is refused with PS1003), where CPython reads it at run time. An unterminated quote and a trailing backslash raise ValueError, as CPython’s do. quote leaves a word alone when it holds only the characters CPython’s safe set holds and wraps it in single quotes otherwise, spelling an embedded single quote '"'"'; join spaces the quoted words. The shlex class itself, the posix flag and the punctuation_chars mode are refused (PS2001).
The secrets subset covers token_hex(n), token_bytes(n) and randbelow(n). The bytes come from the host entropy source (/dev/urandom), the source CPython’s SystemRandom reads through os.urandom, so the shapes match CPython’s but the values differ by construction. token_hex returns the lowercase hexadecimal text of n random bytes (two digits per byte), token_bytes returns the bytes, and randbelow returns an int in [0, n) drawn the way CPython’s SystemRandom._randbelow draws it: n.bit_length() bits at a time, redrawn while the draw is out of range. n is a constant int (a variable is refused with PS1003) and defaults to CPython’s 32 bytes when omitted; randbelow(0) raises ValueError, as CPython’s does. Every other secrets name (choice, randbits, token_urlsafe, compare_digest, SystemRandom) is refused (PS2001).
The island plan is conservative past the module that forced it: once any import in a module is routed to embedded CPython, the module’s whole top level plans there (divergence 42) and every function whose body names an island-planned import or an unannotated value reaching one is planned there too, transitively through calls. On a real Flask-plus-LLM backend this compounds: 41% of its definitions pass the per-definition check in isolation, but the plane map routes 100% of them to the island because untyped imports at the module top level demote everything below them (the assess --json planeMap.demotedBy names the function that pulled each demotion). No compiled code runs unless the forced imports are moved behind a typed boundary or routed out of the compiled tree. The program still builds and runs there: the island is the route for code the subset cannot lower, not a failure, and it costs interpreter speed on the island plane plus a marshalling cost on every native-island crossing (Libraries and fallback mode).
math.factorial(n) follows divergence 1: int is i64, so the factorial past 20! raises OverflowError where CPython grows a big int. Every other integer helper (gcd, lcm) stays in range the way CPython’s does for the same inputs; the domain errors (factorial(-1) is ValueError) match CPython exactly.
Float text output is shortest-round-trip without CPython’s fixed-exponent rule: a value CPython prints as 180.0 prints as 1.8e+02 here. Values CPython also spells in exponent form byte-match, and every %.17g-style numeric comparison is unaffected; only exact print text near CPython’s exponent crossover can differ.
struct.calcsize and struct.unpack_from lower only with a string-literal format that opens with an explicit byte-order prefix (<, >, ! or =); calcsize folds to an int constant at compile time and unpack_from(fmt, buffer, offset=0) takes a bytes buffer and an int offset (negative offsets count from the end, as in CPython). A computed format (PS2001), the native @ default and an unprefixed format (PS2001, native alignment is not lowered), pack_into, iter_unpack, Struct and error stay refused. Like struct.unpack, unpack_from returns a list, not a tuple, and a buffer too short for the format raises ValueError (struct.unpack_from buffer is too small) where CPython raises struct.error. Issue #489.
The random subset runs one module-level CPython-compatible Mersenne Twister: random.seed(int) seeds it with init_by_array over the int’s little-endian 32-bit limbs, and every draw consumes the stream the way CPython 3.14’s random.py does, so a seeded program prints the same numbers as CPython (the differential probe probes/differential/random_surface.py byte-compares them). seed() with no argument is nondeterministic, as in CPython, and seed takes an int only (no version=, no str, bytes or float seeds). The subset covers random, randint, randrange, uniform, getrandbits, choice, shuffle, randbytes(n), sample(population, k), choices(population, k=n) and choices(population, weights=w, k=n), and the draws gauss, normalvariate, lognormvariate, expovariate, triangular, gammavariate and betavariate. population is a list (a str, tuple or range is refused with PS1003), weights is a list[int] or list[float], and choices takes weights and k as keywords. Integer weights are accumulated in 64 bits and compared as floats, where CPython compares exact ints, so cumulative weights beyond 2**53 can pick a different index. lognormvariate returns inf on overflow where CPython raises OverflowError. sample has no counts=, choices has no cum_weights=, and the Random and SystemRandom classes plus vonmisesvariate, paretovariate, weibullvariate, binomialvariate, getstate and setstate are refused (PS2001).
The pyscriptc_arrow FFI adapter (--ffi packaging/adapters/pyscriptc-arrow/ffi.toml, issue #1209) carries the primitive fixed-width Arrow dtypes only: int32, int64, float32, float64, bool and utf8. array_get and array_sum widen every numeric element to double, so an int64 value above 2**53 loses integer precision where CPython-level int arithmetic stays exact, and an int32 value above the f64 mantissa reads rounded. The Arrow IPC wire form is a one-column record batch named v whose top level is a struct (the wire format requires it), so a stream PyArrow produced with a multi-column or differently named schema refuses with ValueError instead of projecting a silent subset; stream_read returns list[dict[str, str]] whose values are the element’s own text (ints decimal, floats %g, bools True/False), not typed values. Every other Arrow type (nested types, dictionaries, unions, timestamps, extension metadata, decimal) is the honest fence: the thunk refuses the dtype word with ValueError naming the six supported constants, never a silent cast. The adapter has no __arrow_c_array__/__arrow_c_stream__ capsule protocol in-process: the exchange with a live Arrow implementation goes over the wire bytes (export_array/import_stream), and a consumer under CPython opens them with pyarrow.ipc.open_stream.
The statistics subset (mean, fmean, median, median_low, median_high, mode, variance, pvariance, stdev, pstdev, quantiles with the default exclusive method and n in {2, 4, 8}) takes a list[int] or list[float]; every other statistics name is refused (PS2001) and other container shapes are refused (PS1003). The functions never mutate the caller’s list. Two seams come from CPython’s exact-rational implementation (statistics converts every number to a Fraction and converts the result to float at the end) against the i64/double runtime: stdev and pstdev differ from CPython by one ulp on a minority of datasets (CPython’s correctly-rounded square root needs math.isqrt of a big integer), and the mean/median/variance family over list[int] returns float where CPython returns int (the mean of an exactly divisible int dataset, the median of an odd-length one, a variance whose exact fraction is integral): the value is equal, the repr is not, so print(statistics.mean([1, 2, 3])) prints 2.0 where CPython prints 2. Over list[float] the mean/median/variance family folds in double arithmetic, so a minority of datasets round differently from the exact-rational path. mode takes list[int] only (a dict[int, int] count; float keys are outside the subset, PS1003), breaks ties the way CPython does (the first key to reach the top count), and quantiles takes n as a constant int. See divergence 61 for the float spelling rule that can also move a print of a whole float.
csv.DictReader returns a materialized list[dict[str, str | None]] where CPython returns a lazy iterator: the rows are all parsed before the loop body runs, so a loop body that mutates the source lines does not see the edit, and the reader cannot be resumed after list() or a second for (CPython’s iterator is spent the same way, so a fresh DictReader call is the fix either way). Two row-shape differences ride along: a record longer than the header raises ValueError: dict reader has more fields than fieldnames at run time where CPython stores the extra fields under the None restkey (a None key and a list[str] value are outside the row dict’s type), and restkey=/restval= are refused (PS2003) where CPython re-keys or refills the row. Blank records are skipped like CPython skips them. The writer matches CPython’s excel dialect byte for byte, including the \r\n terminator, the minimal quoting and the empty-text restval for a missing field. Issue #488.

Where each entry comes from

Every entry names the runtime file or compiler module that produces the difference, so a report can point at the code.
The live support state across modules and language features is on the compat site, and the code that stops a compile is in Diagnostics.

Last updated:

Divergences from CPython

Parity contract

The tool host and the target

Numbered divergences

Where each entry comes from

On This Page