Module pycompat 

CPython 3.11 string / float / round semantics (PORT-CONTRACT.md §“Python- compatibility primitives”, PORT-CONTRACT.d/07 §1.4–1.5).

Unicode behavior is table-driven from the packaged assets/spec/pycompat-tables.json (generated by rust/spec/extract_pycompat_tables.py against the oracle interpreter), embedded at build time and parsed once into a static.

Float formatting (py_float_repr) reproduces CPython repr(float): shortest round-trip digits reshaped Python-style (.0 for integral, 1e-05/1e+20 exponent shaping). py_round and the .1f/.0% format helpers do correct decimal rounding (half-to-even) of the exact binary value via an arbitrary-precision decimal expansion of the mantissa — never multiply-by-10^n tricks.

Constants

SURROGATE_SENTINEL_BASE

First sentinel code point; add the raw byte value (0x80..=0xFF).

Functions

decode_stdin_surrogateescape

Decode stdin bytes the way the oracle’s sys.stdin.read() does under the parity environment: UTF-8 with surrogateescape — every undecodable byte becomes one sentinel char (CPython maps each bad byte individually, which matches walking Rust’s Utf8Error with per-byte emission).

encode_stdout_surrogateescape

Encode a rendered stdout payload, re-materializing sentinel chars as their raw original bytes (the oracle’s stdout uses surrogateescape, so a lone surrogate prints as the byte that produced it). Borrow when no translation is needed.

first_nonempty_line

The first non-empty py_strip’d line of s (str.splitlines() boundaries), or "" when every line is blank.

is_re_digit

Python re \d class membership (Unicode default).

is_re_word

Python re \w class membership (Unicode default).

py_abspath

Python posixpath.abspath(path) — normpath(join(cwd, path)), lexical (never touches the filesystem beyond reading the cwd).

py_casefold

Python str.casefold() — full Unicode case folding (ß → ss).

py_float_repr

CPython repr(float): shortest round-trip decimal digits (David Gay dtoa mode-0 semantics: among round-tripping candidates prefer the one nearest the exact binary value, ties to even), fixed notation when the decimal point position is in (-4, 16], otherwise exponent form with lowercase e, mandatory sign, and a minimum two-digit exponent. Integral in-range floats keep a .0 suffix. inf / -inf / nan.

py_format_1f

Python f"{x:.1f}" — one fixed decimal, round-half-to-even on the exact binary value.

py_format_fixed

Python f"{x:.<nd>f}" for an arbitrary decimal count (eval’s .3f, .6f, and .0f report/gate formats).

py_format_percent0

Python f"{x:.0%}" — multiplies by 100 in binary (a rounding f64 multiply, exactly as CPython does), formats with zero decimals half-to-even, appends %.

py_is_printable

Python str.isprintable() for a single character.

py_is_space

Python str.isspace() for a single character (includes \x1c–\x1f and NBSP; excludes U+FEFF and U+200B).

py_lstrip

Python str.lstrip() with no argument.

py_normpath

Python posixpath.normpath(path): collapse duplicate slashes and . components, resolve .. lexically (kept when it would climb past a relative start; dropped at an absolute root), preserve an exactly-double leading slash. Empty input yields ..

py_relpath

Python os.path.relpath(path, start) on POSIX: both sides are abspath’d lexically, then the relative walk is derived from the component lists. Returns . when they coincide.

py_repr_str

Python repr() for strings: single quotes unless the string contains a single quote and no double quote; escapes for backslash/quote/\t\n\r; \xXX/\uXXXX/\UXXXXXXXX (lowercase hex) for non-printable characters; printable non-ASCII stays literal.

py_round

CPython round(x, ndigits): correct decimal rounding, half-to-even, of the exact binary value (David Gay dtoa semantics). Non-finite and zero inputs return unchanged; a magnitude overflow (CPython raises OverflowError) saturates to infinity here.

py_rstrip

Python str.rstrip() with no argument.

py_splitlines

Python str.splitlines() (keepends=False): splits on the exact Python boundary set (\n \r \v \f \x1c \x1d \x1e \x85 U+2028 U+2029), with a \r\n pair consumed as a single boundary; no trailing empty element.

py_strip

Python str.strip() with no argument (strips the Python whitespace set).

quote_plus

urllib.parse.quote_plus(s, safe='') over the string’s UTF-8 bytes: the ALWAYS-SAFE set (ASCII alphanumerics plus _.-~) stays literal, a space becomes +, and every other byte becomes uppercase %XX.

quote_plus_urlencode

urllib.parse.urlencode(mapping) over string pairs — quote_plus on each key and value, pairs joined with & in the given order.

read_text_universal

Path(path).read_text(encoding="utf-8") — strict UTF-8 with universal newlines (\r\n/\r → \n); None on OSError/UnicodeDecodeError (callers substitute “” or a structured unreadable error).

sentinel_surrogate

If c is an active sentinel, the surrogate code point (0xDC80..=0xDCFF) the oracle would hold instead.

set_surrogate_sentinels_active

Test hook: reset/force the sentinel flag.

surrogate_sentinels_active

True once decode_stdin_surrogateescape has produced a sentinel.