Skip to content

Latest commit

 

History

History
134 lines (102 loc) · 60.2 KB

divergences.md

File metadata and controls

134 lines (102 loc) · 60.2 KB
title Divergences from CPython
description The parity contract and every numbered difference from CPython 3.14.

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.

  1. int is i64. Overflow aborts the process instead of growing a big int.

  2. // 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.

  3. 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).

  4. 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.

  5. json has no non-ASCII text.

  6. Set and frozenset iteration is insertion order, not CPython's hash order. Length and membership match.

  7. After for i in range(0), a new loop target reads as 0 instead of raising UnboundLocalError.

  8. A subclass __init__ that never assigns an inherited field leaves it at the zero value of its type instead of raising AttributeError.

  9. raise AppError("no") for a user exception class stores a code and an optional str and does not call __init__.

  10. @classmethod and @staticmethod of the form Class.method(...) do not pass the class object.

  11. 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.

  12. assert is always evaluated; a compiled binary has no -O.

  13. x is None compiles as == against None. Identical for None because it is a singleton; every other is on a scalar is refused.

  14. ABC, ABCMeta, Protocol, @abstractmethod and @overload compile as plain classes and methods with no CPython runtime semantics.

  15. Calls that run through embedded CPython (subprocess.check_output, socket.gethostname, threading, logging) follow the interpreter the binary links, not the pin.

  16. 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.

  17. 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.

  18. 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.

  19. 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.

  20. 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.

  21. 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.

  22. 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).

  23. 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.

  24. @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.

  25. 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.

  26. 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.

  27. 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.

  28. 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.

  29. 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.

  30. 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.

  31. 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 pipe or descriptor copy (os.pipe, os.dup and os.dup2 are refused at link time with the same target-naming diagnostic; wasi-libc keeps pipe and dup out of the preview1 surface), 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.

  32. 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/[email protected] 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.

  33. 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.

  34. 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.

  35. 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.

  36. 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.

  37. 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).

  38. 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.

  39. 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.

  40. 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 (timeout= is its own entry, divergence 71).

  41. 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.

  42. 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).

  43. 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.

  44. 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.

  45. 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), 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).

  46. 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.

  47. 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 raises the runtime JSONDecodeError (a ValueError subclass, so except ValueError catches it too) with the runtime's own message, not CPython's Expecting value: line 1 column 1 (char 0) wording. 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.

  48. 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.

  49. 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.

  50. 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.

  51. 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.

  52. 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.

  53. 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.

  54. 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.

  55. 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.

  56. 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).

  57. 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).

  58. 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).

  59. 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).

  60. 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.

  61. 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.

  62. 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.

  63. 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).

  64. 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.

  65. 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.

  66. 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.

  67. An island binary that links the build host's libpython is refused at the end of the compile (PS4304): the audit reads the linked artifact's dynamic dependencies (otool -L on Mach-O, readelf -d on ELF) and a reference to the host interpreter's library, reached by absolute path or through an absolute runpath, fails the build with that path in the message. The binary would run on the build machine and break on a target without that Python, so the build output says so before the artifact is shipped. --embed-python=bundle produces a relocatable binary instead, and --allow-host-libpython (or [tool.pyscriptc.island] allow_host_libpython = true) accepts the host link on purpose and warns instead. A native binary links no libpython and is unaffected.

  68. The process-control surface (os.kill, os.killpg over the ps_os_kill runtime helpers, plus the signal module's POSIX constants SIGKILL, SIGTERM, SIGINT, SIGCONT, SIGUSR1, SIGUSR2) is POSIX-only. The error translation follows CPython's errno mapping exactly (ESRCH raises ProcessLookupError, EPERM raises PermissionError, everything else the plain RuntimeError stand-in), so a kill probe is byte-identical to CPython 3.14 on the host (the differential probe probes/differential/os_kill_signal.py byte-compares stdout, stderr and the exit code). On wasm32-* the call is refused at link time with the target-naming diagnostic (WASI has no process identifiers, and its signal.h errors out without the emulation macro), and on *-windows-* targets the runtime helpers do not compile (Windows has no POSIX kill; the process handle spelling is TerminateProcess), so a kill call stops the cross compile where CPython would run it. The signal module carries the constants only: every handler-registration form (signal.signal, signal.getsignal, signal.alarm, signal.raise_signal, signal.SIG_DFL, signal.SIG_IGN, the Signals enum) stops the compile with PS2001, because a native binary has no Python handler table; CPython registers the handler and delivers asynchronously. Issue #1244.

  69. The archive read surface (tarfile.open, zipfile.ZipFile) reads a tar as raw 512-byte ustar blocks and a zip by walking its central directory, so r:gz tars and ZIP_DEFLATED members read through zlib and raise RuntimeError on a build without it; the r:bz2 and r:xz tar modes compile and then raise RuntimeError at run time, where CPython reads bzip2 and lzma through its own modules (BZ2File, LZMAFile). The runtime raises KeyError where CPython's tarfile does for a missing extractfile name, but the message wording is the runtime's (filename not found in the archive against CPython's quoted spelling). extractall writes every file with the process umask and does not preserve the archive's file modes, mtime or ownership, where CPython's extractall keeps them by default (CPython's own data filter already refuses the dangerous ones). Only pax headers of the mtime/name/path shape are honored; exotic extended-header records a hand-built archive might carry are ignored.

  70. Class dispatch is static, so a slot annotated with a class only accepts a value of that exact class. The one carve-out is a nominal subclass that adds no instance field: a slot annotated with a base class accepts a value of a subclass declared in the same compile, and the slot keeps the concrete class, so the overridden method answers the subclass's body (the differential probe probes/differential/covariant_return.py byte-compares it). The carve-out is narrow on purpose: a subclass that adds a field keeps the PS1003 fence (the fence names the field, because the base's slot cannot hold the wider layout), a def whose returns split over two subclasses proves no concrete class and keeps the fence at its return sites, and a subclass value passed to a base-annotated parameter keeps the PS1003 fence (the callee's body dispatches on the annotation's class, so the call would answer the base's body where CPython answers the subclass's). CPython dispatches on the value's real class everywhere, so a base-annotated parameter that receives a subclass answers the subclass's method there and the base's method here. Issue #1243.

  71. The subprocess.run(timeout=) path raises subprocess.TimeoutExpired with CPython's exact message (Command '['sleep', '5']' timed out after 1 seconds) and the class matches through CPython's parent chain, so except subprocess.TimeoutExpired catches it and except TimeoutError does not (CPython's TimeoutExpired derives from SubprocessError, not from the builtin TimeoutError). The exception record carries the code and the message only, so the attributes CPython's TimeoutExpired holds (cmd, timeout, output, stdout, stderr) are not readable and e.args holds the message list instead of CPython's (cmd, timeout) pair. The timeout itself is a compile-time number literal: a computed timeout fences with PS2003 where CPython reads it at run time, and a timeout at or below zero fences too (CPython raises before the child starts there). Issue #1223.

  72. The asyncio.create_subprocess_exec subset is closed over the spawn, the wait and the exit code: await asyncio.create_subprocess_exec(program, *args) starts the child, await proc.wait() parks the task until the child exits and reads its exit code, and proc.returncode reads the same code afterwards. The subset has no stdin= pipe and no proc.stdin, proc.stdout or proc.stderr handles, so the streams stay invisible to the program; the stdout=/stderr= capture and communicate() are their own entry (divergence 75). A keyword the subset does not read fences with PS2003 where CPython accepts it. proc.returncode reads -1 while the child still runs, where CPython reads None (the closed subset has no optional int). The child is spawned by the await itself, where CPython's loop spawns it through a child watcher and hands the handle back before the child runs. Issue #1224.

  73. A union annotation erases to its first arm (A | B and Union[A, B] compile; the PS1101 code is retired), so the slot carries the first arm's layout and a value of a later arm stops the compile at the use site with PS1003, where CPython runs the program. The annotation is annotation-only: the union is never a runtime value, values crossing the slot still carry the first arm's type, and no narrowing or isinstance over the other arms exists. An optional of a multi-arm union (A | B | None) keeps the PS1102 fence: the tagged optional holds one arm and None, so a two-arm optional has no representation. A quoted forward reference ("Node") resolves when the module defines the name by module end and keeps the PS1105 fence naming the text when it never resolves; a TypeAlias annotation (Ids: TypeAlias = list[int]) binds the alias name as an erased annotation, so an annotation naming Ids lowers as list[int]. The differential probe probes/differential/erased_annotations.py byte-compares the surface with CPython. Issue #413.

  74. The email read subset is closed over the MIME reader: email.message_from_string, email.message_from_bytes and email.message_from_file parse a message, and the message answers get, get_all, keys, items, walk, get_payload, get_content_type, get_filename, is_multipart and as_string. Two seams ride along. get_payload() on a multipart part raises ValueError (the list of the child parts CPython answers there is outside the closed surface), and an RFC 2047 encoded word in a charset the subset does not decode keeps the raw word in the header value, where CPython decodes the word and records the defect. Everything else in the email package (the mime builders, the policy API, EmailMessage construction, the header setters, sendmail) is refused with PS2001: the subset reads a message, it does not build one. Issue #1228.

  75. os.system(command) runs the command through the host shell and waits for it, and the value is CPython's: on POSIX the raw wait status (the exit code in the high byte, the signal number in the low one), not the decoded exit code, so os.system("exit 3") answers 768 on both sides. The shell owns the interpretation of the command, so the redirection, the pipe and the 127 a missing command reports all match CPython byte for byte (the differential probe probes/differential/os_system.py compares stdout, stderr and the exit code). The command is a str argument: the bytes form and the PathLike form are refused (PS1003) where CPython accepts them. The call is native-only: on wasm32-* it is refused at link time with the target-naming diagnostic (WASI has no subprocess story, the same refusal subprocess gets), on the mobile targets it fences at compile time with PS2001 (an app sandbox has no fork/exec, the same fence subprocess gets), and the *-windows-* cross target runs the command through the CRT shell, whose status is the child's exit code, where CPython's Windows build reports the same way. Issue #503.

  76. The JSON codec over the tagged dynamic value (issue #1226's sum, issue #1267's codec slice) has one number seam: a JSON integer literal too large for i64 parses as the float arm, where CPython's json grows an arbitrary-precision int, so json.loads("12345678901234567890123") prints 1.2345678901234568e+22 where CPython prints the exact digits. Every other arm is CPython's: null is None, true/false the bool, an integral literal the int, a literal with a fraction or exponent the float (CPython's own parse rule), and the writer spells each arm the way the typed writer does. The string arm rides divergence 5's no-non-ASCII contract: the \uXXXX escapes decode to their code points and a decoded code point above Latin-1 keeps the typed path's JSONDecodeError fence, and a malformed document raises the JSONDecodeError/ValueError the typed loads path raises, and the round trip json.loads(text) then json.dumps(value) gives back the text for every document whose numbers fit (the differential probe probes/differential/json_dynval_roundtrip.py compares stdout, stderr and the exit code). print of a dynamic value (or of a dict[str, object] / list[object]) is CPython's str(): the str arm's text, every container its repr with quoted nested strings.

  77. The asyncio.create_subprocess_exec pipe form (issue #1266) takes stdout=/stderr= only, and the value must be the constant asyncio.subprocess.PIPE (-1, CPython's number): any other value (None to say "inherit", an int fd, a file object) fences with PS2003 where CPython accepts it. communicate() answers the (stdout, stderr) pair of bytes with an inherited stream reading as the empty bytes (b''), where CPython's pair carries None for a stream it did not pipe, so a program that reads proc.stdout (not in the subset) or distinguishes b'' from None in the pair behaves differently. The lower-level shapes stay where divergence 72 left them: no stdin=, no proc.stdin/proc.stdout/proc.stderr handles (PS2001), communicate() takes no input= and answers bytes only (CPython's text=True through the loop's stream layer is outside the subset), and the read is a blocking drain of the child's pipes to EOF. The piped paths are byte-identical to CPython on the host (the differential probe probes/differential/asyncio_subprocess_pipes.py compares stdout, stderr and the exit code). Issue #1266.

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.