tpy-lang 0.3.0.dev0__py3-none-any.whl

tpyc/_data/docs/STDLIB_ROADMAP.md

@@ -0,0 +1,1258 @@
+# Python Stdlib Coverage
+
+Tracks TPy's coverage of the CPython standard library. This is a living
+document -- update it whenever a stdlib module or item gains/loses support.
+
+**Scope**: modules present in CPython's `stdlib` plus the implicit `builtins`
+module (len, print, list, dict, exceptions, etc.). TPy-native extras
+(`tplib.Box`, `tplib.ArrayList`, `tplib.FixStr`, `tplib.json`) are tracked in
+`LANGUAGE_FEATURES.md` since they don't have CPython equivalents.
+
+Status legend:
+- **Done** -- matches CPython semantics for the items listed below
+- **Partial** -- usable; some items missing or differ from CPython
+- **Stub** -- minimal scaffolding, most items missing
+- **Missing** -- not started
+- **Blocked** -- needs a language/runtime feature before meaningful work
+
+Priority reflects impact for typical Python programs (P0 = essential for
+most real programs; P3 = rarely needed / specialized).
+
+Approach legend: **native** (thin `@native` bindings to libc / OS / existing
+C++ libraries), **pure** (pure TPy), **macro** (compile-time macro module),
+**mixed** (combination).
+
+---
+
+## Implementation Policy
+
+Stdlib modules should be written in **pure TPy (.py)** by default. C++ code
+is introduced only where it genuinely must be:
+
+1. **OS / libc / syscalls** -- wall-clock time, filesystem, sockets, process
+   spawning, memory maps. There is no TPy-level equivalent.
+2. **Existing C++ library bindings** -- regex engines (std::regex, PCRE2),
+   crypto (OpenSSL), compression (zlib), etc. We wrap, we don't rewrite.
+3. **Performance-critical inner loops where TPy generation is demonstrably
+   worse.** Must be justified with a benchmark; not a default assumption.
+
+Everything else is pure TPy. If the language is missing something that blocks
+a clean pure-TPy implementation -- closures, generators, a specific dunder,
+module-level mutable state, `*args`/`**kwargs`, runtime type info -- the
+**right fix is to extend the language**, not to drop into C++. A stdlib that
+hits language gaps is the best possible driver for language work, because
+each gap has a concrete user-visible payoff.
+
+For modules that do need native code, follow the **thin-binding pattern**:
+import raw symbols via `@native` into a minimal module (e.g.
+`tplib.cppstd.re`, `tpy._os.libc`), then build the CPython-compatible surface
+as pure-TPy wrappers on top. The native layer should expose the underlying
+primitive faithfully -- no Python semantics baked in -- and the pure-TPy
+layer translates to Python semantics (error handling, optional args,
+defaults, naming, iteration protocols). Benefits:
+
+- One place to swap backends (e.g. std::regex -> PCRE2) without touching
+  user-visible code.
+- CPython stubs in `lib/cpy/` can mirror the pure-TPy wrappers directly --
+  only the bottom layer differs.
+- Type checker, IDE, and LLMs see real Python code, not opaque C++ symbols.
+- Macro-based modules can inspect the pure-TPy layer.
+
+### C++ helper convention
+
+When a stdlib module genuinely needs a small C++ helper beyond raw libc /
+`std::` calls -- e.g. wrappers that return `std::tuple` to bridge CPython's
+multi-return APIs (`math.modf`, `math.frexp`) or that compose a handful of
+`std::` calls into a Python-semantics primitive (`math.ulp`) -- place it in
+`runtime/cpp/include/tpy/stdlib/<module>.hpp` under namespace
+`tpy::stdlib::<module>`. Example: `tpy/stdlib/math.hpp` defines
+`tpy::stdlib::math::modf(...)`.
+
+This keeps stdlib-backing helpers cleanly separated from TPy's own runtime
+core (`tpy::` at the top level, covering `tpy::BigInt`, `tpy::ordered_map`,
+`tpy::varargs`, etc.). Path mirrors namespace, standard C++ convention, and
+future modules slot in predictably: `tpy/stdlib/random.hpp` ->
+`tpy::stdlib::random`, `tpy/stdlib/time.hpp` -> `tpy::stdlib::time`, and so
+on.
+
+Complementary Python-side convention (already in use): stdlib `.py` modules
+declare `# tpy: cpp_namespace("tpystd::<module>")` so the generated code for
+the pure-TPy wrappers lives under `tpystd::math::`, `tpystd::bisect::`, etc.
+Three layers, three namespaces, all distinct:
+
+| Layer | Namespace | Example |
+|---|---|---|
+| Raw C/C++ primitives | `std::` (or third-party) | `std::log`, `std::modf` |
+| TPy-authored C++ helpers | `tpy::stdlib::<module>::` | `tpy::stdlib::math::modf` |
+| Generated code for pure-TPy wrappers | `tpystd::<module>::` | `tpystd::math::gcd` |
+
+The `approach` column in the overview table below reflects the **public-facing**
+strategy. Internally nearly every module ends up "mixed" if it touches the OS --
+the distinction is whether the Python-visible logic lives in .py or C++.
+
+### Test location convention
+
+Stdlib-module tests live under `tests/cases/stdlib/<module>/` -- one directory
+per CPython module, matching the import name (`stdlib/bisect`, `stdlib/heapq`,
+`stdlib/math/...` for grouped subcases, etc.). This keeps the stdlib surface
+discoverable as a group (`pytest -k stdlib/`) and separates it from feature
+tests under `cases/<feature>/`. Earlier stdlib tests that ended up under
+`cases/imports/` or `cases/builtins/` are being migrated as they're touched.
+
+Examples of the policy in action:
+
+- `bisect` -- fully pure TPy over the `Comparable` protocol. No native code.
+- `math` -- thin `@native` bindings to `std::log`, `std::sqrt`, etc. (libc
+  math is the primitive); no TPy-visible C++ logic beyond the bindings.
+  `log(x, base)`, `radians`, `degrees` are pure-TPy overloads/wrappers.
+- `random` -- currently thin binds to `std::rand`; long-term should be a
+  pure-TPy Mersenne Twister (matches CPython), with only `os.urandom`-style
+  entropy as the native primitive.
+- `re` -- thin `tplib.cppstd.re` / `_bindings.pcre2.re` binding (the regex engine
+  is the primitive), with a pure-TPy facade for the Python surface and a
+  pure-TPy syntax translator.
+- `pathlib` -- pure TPy over thin filesystem-syscall bindings.
+- `json` (stdlib-compat) -- pure TPy on top of `tplib.json`'s parser/writer.
+
+---
+
+## Module Overview
+
+| Module | Priority | Status | % | Approach | Blockers / Notes |
+|---|---|---|---|---|---|
+| [`builtins`](#builtins) | P0 | Partial | ~75% | mixed | Implicit import. Core types + most common functions + most exception types present and catchable (`Index/Key/Value/Type/Attribute/Assertion/OS/FileNotFound/ZeroDivision/Overflow/Arithmetic/Runtime/NotImplemented/Memory/StopIteration`); fixed-int arithmetic overflow stays panic by design (future policy switch). Missing: `frozenset`, `complex`, `memoryview`, `input`, `format`, `ascii`, `callable`, `id`, `type(x)` runtime. D16 dyn-attrs (`getattr`/`setattr`/`delattr`/`hasattr` for both literal and runtime names) fully shipped. See [builtins](#builtins) for per-item status |
+| [`math`](#math) | P0 | Done | ~99% | mixed | Thin libc bindings + pure TPy wrappers. All CPython funcs present with matching signatures (`Iterable[float]` for fsum/sumprod/dist; `prod` has Int32 / int (BigInt) / float overloads). Remaining gap: tuple as iterable (blocked on tuple-iteration bundle) |
+| [`time`](#time) | P0 | Partial | ~50% | mixed | Thin clock/sleep syscalls. `time`, `sleep`, `perf_counter`, `monotonic`, `time_ns`, `perf_counter_ns`, `monotonic_ns`, `process_time` all done. Missing `struct_time`/`strftime`/`gmtime`/`localtime`/timezone constants |
+| [`sys`](#sys) | P0 | Stub | ~15% | mixed | Thin syscall bindings + pure TPy. `argv`, `stdout`, `stderr` done; needs `stdin`/`exit`/`path`/`version_info` |
+| [`os`](#os) | P0 | Missing | 0% | -- | Needs filesystem wrapper + path handling |
+| [`os.path`](#ospath) | P0 | Missing | 0% | -- | Independent of `os`; candidate for pure TPy over C++ `<filesystem>` |
+| [`pathlib`](#pathlib) | P0 | Missing | 0% | -- | Class-heavy; depends on filesystem bindings |
+| [`io`](#io) | P0 | Partial | ~30% | pure | `StringIO` / `BytesIO` (chunked storage, write/read/readline/seek/tell/truncate/iter/context-manager). `Readable` / `Writable` / `BinaryReadable` / `BinaryWritable` protocols on tpy core, re-exported from `io`. Missing: `IOBase` ABC hierarchy (deliberately deferred -- protocols cover the static-dispatch use case), `TextIOWrapper`, `io.SEEK_SET/CUR/END` constants (collide with `<cstdio>` macros), encoding/newline/errors kwargs, `read(size=-1)` arg |
+| [`json`](#json) | P0 | Partial | ~70% | pure | `loads` / `dumps` + `JSONDecodeError` done over a recursive union `JsonValue`. CPython byte-compatible across cpy phase. Missing: `load(fp)` / `dump(obj, fp)` (needs `io`), `JSONEncoder` / `JSONDecoder`, most `dumps`/`loads` kwargs |
+| [`re`](#re) | P0 | Partial | ~50% | pure | Pure-TPy facade over `_bindings.pcre2` raw bindings. PCRE2 vendored under `runtime/cpp/third_party/pcre2/` (5MB) and built bundled by default; `--pcre2={bundled,system,auto}` selects backend. compile/search/match/fullmatch/findall/sub/split + Pattern/Match classes + IGNORECASE/MULTILINE/DOTALL/VERBOSE/ASCII flags + `re.error`. Missing: named-group accessors, `count` arg on sub, true generator finditer, bytes input, compile cache |
+| [`collections`](#collections) | P0 | Missing | 0% | -- | OrderedDict trivial (have ordered_map); deque needs C++ struct; Counter/defaultdict/namedtuple need macros |
+| [`itertools`](#itertools) | P0 | Missing | 0% | -- | C++ primitives exist in `runtime/itertools.hpp`; needs Python-surface module |
+| [`functools`](#functools) | P0 | Partial | ~25% | pure | `reduce(func, a, initial)`, `reduce(func, a)`, `total_ordering` done. `cmp_to_key`, `wraps` blocked on specific compiler / macro-infrastructure gaps (see section). partial/lru_cache/singledispatch/cached_property/partialmethod need closures + macros |
+| [`random`](#random) | P1 | Partial | ~90% | pure | Pure-TPy MT19937 + CPython's distribution suite, byte-identical to CPython on the same seed. Done: `Random` class, `random`, `seed(Int32)` (negatives mapped to abs), `seed()` no-arg auto-seed via OS entropy, `getrandbits(k)` for arbitrary k, `randint`, `randrange`, `randbytes`, `choice`, `shuffle`, `uniform`, `triangular`, `gauss`, `normalvariate`, `lognormvariate`, `expovariate`, `paretovariate`, `weibullvariate`, `gammavariate`, `betavariate`, `vonmisesvariate`. Missing: `choices`/`sample`/`SystemRandom`/`binomialvariate`/`getstate` (Tier 3). See module docstring TODOs |
+| [`struct`](#struct) | P1 | Partial | ~60% | macro | unpack/calcsize only; `pack` needs statement-expr or buffer builder |
+| [`bisect`](#bisect) | P1 | Done | 100% | pure | All four functions implemented generically over `Comparable` |
+| [`enum`](#enum) | P1 | Partial | ~50% | macro | Enum/IntEnum/auto; missing functional API, lookup by name/value, iteration |
+| [`dataclasses`](#dataclasses) | P1 | Partial | ~75% | macro | frozen/order/inheritance/asdict/astuple; missing InitVar, __post_init__, replace(), metadata |
+| [`typing`](#typing) | P1 | Partial | ~60% | native | Protocols/Sized/Iterator/TypedDict/Unpack; missing Generic, TypeVar, ParamSpec, ClassVar |
+| [`datetime`](#datetime) | P1 | Missing | 0% | -- | Class-heavy; needs timedelta arithmetic and timezone handling |
+| [`csv`](#csv) | P1 | Missing | 0% | -- | Depends on `io` |
+| [`base64`](#base64) | P1 | Partial | ~95% | pure | Pure-TPy b64/b32/b16 encode+decode + urlsafe/standard variants + altchars=/validate=/casefold=/map01= kwargs + encodebytes/decodebytes. bytes/bytearray/str accepted on decoders (matches CPython). Missing: b85/a85 (rare, separate algorithms); `memoryview` depends on builtin gap |
+| [`hashlib`](#hashlib) | P1 | Partial | ~20% | pure | SHA-256 pure-TPy. MD5/SHA-1/SHA-512 are straight follow-ups (same class pattern, different round functions / endian). BLAKE2/SHA-3 later. Optional OpenSSL backend also later |
+| [`argparse`](#argparse) | P1 | Partial | ~88% | macro | Builder-trace macro (Phase 7); positionals/optional flags, all 7 actions, all 4 nargs, type=int\|float\|str + fixed-width ints + Float32 + custom records via `from_arg` (all 4 nargs + append/extend), choices/required/dest/help/metavar, Optional[T]/Optional[list[T]] for absent flags, list-literal defaults, bare parse_args() reads sys.argv[1:], --help/-h auto-generation, add_help=False opt-out, prog=/usage=/epilog= help customization, subparsers (flat-namespace; per-sub fields land as Optional[T] on the top namespace). Missing: mutually-exclusive groups, argument groups, runtime-derived `prog`, terminal-width help wrap, per-sub `--help` auto-emit, BooleanOptionalAction, parents=, allow_abbrev, fromfile_prefix_chars, custom formatter classes, action=<callable> |
+| [`logging`](#logging) | P2 | Missing | 0% | -- | Module-level state + handler architecture |
+| [`configparser`](#configparser) | P2 | Missing | 0% | -- | Depends on `io` |
+| [`urllib.parse`](#urllibparse) | P2 | Missing | 0% | -- | Pure-TPy candidate; no network dependency |
+| [`heapq`](#heapq) | P2 | Partial | ~90% | pure | Pure TPy over `list[T: Comparable]`. All non-variadic ops done; `merge(*iterables)` unblocked by variadic-in-method-call fix, still needs a generator-based iterator-heads heap |
+| [`copy`](#copy) | P2 | Missing | 0% | -- | `copy()` deep semantics need intrinsic support |
+| [`textwrap`](#textwrap) | P2 | Missing | 0% | -- | Pure TPy candidate |
+| [`decimal`](#decimal) | P2 | Missing | 0% | -- | Large surface; candidate for BigInt-based pure impl or native lib |
+| [`fractions`](#fractions) | P3 | Missing | 0% | -- | Pure TPy over BigInt |
+| [`statistics`](#statistics) | P2 | Missing | 0% | -- | Pure TPy candidate |
+| [`pickle`](#pickle) | P2 | Blocked | 0% | -- | Needs dynamic type info + `io` |
+| [`shelve`](#shelve) | P3 | Blocked | 0% | -- | Needs pickle |
+| [`inspect`](#inspect) | P2 | Blocked | 0% | -- | Needs runtime type/func introspection |
+| [`asyncio`](#asyncio) | P1 | Partial | ~35% | pure | v1: `run`/`sleep`/`create_task`/`Task[T]`/`Future[T]`/`Event`/`CancelledError` + thread-local executor with slot table, runnable deque, timer min-heap, cancel-drain at run-end. v1.5 M5+M6: `async with` (cleanup-only), `async for` + `StopAsyncIteration`. v1.5 M8: `wait_for`/`TimeoutError`. v1.5 M9: `gather(*tasks)` (homogeneous variadic-positional) + `gather_list(tasks)` (homogeneous list shape). Missing: CPython-shape *heterogeneous* variadic `gather[*Ts](*coros) -> tuple[*Ts]` (needs variadic generics + async-def `*args` codegen); I/O reactor (v2); multi-thread (v3+) |
+| [`threading`](#threading) | P1 | Blocked | 0% | -- | Needs threading primitives |
+| [`multiprocessing`](#multiprocessing) | P2 | Blocked | 0% | -- | Needs process spawning + IPC |
+| [`subprocess`](#subprocess) | P1 | Blocked | 0% | -- | Needs process spawning |
+| [`socket`](#socket) | P1 | Blocked | 0% | -- | Needs network primitives |
+| [`http.client`](#httpclient) | P2 | Blocked | 0% | -- | Needs socket + regex |
+| [`urllib.request`](#urllibrequest) | P2 | Blocked | 0% | -- | Needs http |
+
+---
+
+## Cross-cutting Language / Runtime Gaps
+
+These unlock multiple stdlib modules. Listed with the modules each would
+unblock.
+
+| Gap | Unblocks | Rough effort |
+|---|---|---|
+| `io.IOBase` protocol + text/binary wrappers (StringIO, BytesIO, TextIOWrapper) | io, json (stdlib), csv, configparser, pickle, shelve | M |
+| Regex engine (std::regex phase 1, PCRE2 phase 2, SRE if needed) | re, argparse quality, urllib | M phase 1, L phase 2 |
+| Compile-time conditional compilation / build profiles (F8) | re backend selection, allocator choice, embedded variants, debug/release | M |
+| Filesystem bindings (wrap C++ `<filesystem>`) | os.path, pathlib, os, shutil | M |
+| async/await + event loop | asyncio (v1 shipped), aiohttp, async generators | XL (v1 done) |
+| Threading primitives (Thread, Lock, Event, Queue) | threading, multiprocessing.dummy, concurrent.futures | XL |
+| Process spawning (fork/exec or std::process) | subprocess, multiprocessing | M-L |
+| Socket primitives | socket, http.client, smtplib, ftplib, urllib.request | L |
+| Runtime type info / reflection for `get_type_hints`, `type(x)`, `isinstance` on concrete | typing runtime, inspect, pickle | L |
+| Closure capture for `partial`/`lru_cache` | functools | S-M (may already work via Callable) |
+
+### Existing BUGS.md entries that gate pure-TPy stdlib work
+
+Under the implementation policy (pure TPy over thin native bindings), several
+known compiler bugs block clean stdlib modules. These were lower-priority as
+isolated issues but become **stdlib prerequisites** when stdlib development
+ramps up.
+
+| Tracker entry | Effect on stdlib | Blocks |
+|---|---|---|
+| _open verification, no entry yet_: Module-level mutable state across compilation units. Verified working for regular stdlib modules with a reference-type module-level singleton (e.g. `random`'s shared RNG instance); still needs checking for facade-routed or reassignment-based patterns -- file as a bug if a real failure is reproduced. | Single source of truth for per-process state | `logging` (handlers registry), `sys.path`, `warnings` |
+
+The original "stdlib enablement" workstream (variable re-exports through
+native_module facades, init chain propagation, `import pkg.sub` + attribute
+access for variables, `from pkg import submod` namespace binding, qualified
+type names in annotations, always-qualify `@native` refs) shipped on branch
+`stdlib-enablement-imports` plus the earlier `D24 Phase 10` commit -- now
+behaviour-tested under `tests/cases/imports/native_facade_*`,
+`from_pkg_import_submod`, and `import_pkg_sub_attr_var`.
+
+---
+
+## Module Detail
+
+Item status legend (per-row): **Done** / **Partial** / **Missing** / **Blocked**.
+
+### builtins
+
+Implicitly imported. Surface lives in `lib/tpy/tpy/_builtins/` (types,
+functions, exceptions, I/O) and is re-exported by `lib/tpy/builtins.py`.
+
+**Types**
+
+| Item | Status | Notes |
+|---|---|---|
+| `int` | Done | Arbitrary-precision `BigInt` |
+| `float` | Done | IEEE 754 double |
+| `bool` | Done | |
+| `str` | Done | Context-dependent `std::string` / `std::string_view` |
+| `bytes`, `bytearray` | Done | |
+| `list` | Done | `std::vector<T>` |
+| `dict` | Done | Insertion-ordered `tpy::ordered_map<K, V>` |
+| `set` | Done | Insertion-ordered `tpy::ordered_set<T>` |
+| `tuple` | Done | `std::tuple<...>` |
+| `range` | Done | `Range[T]` |
+| `slice`, `basic_slice` | Done | Three-arg and two-arg slices |
+| `frozenset` | Missing | Immutable set; would be `tpy::ordered_set<T>` with mutation-free surface |
+| `complex` | Missing | Not yet planned; niche |
+| `memoryview` | Missing | `BytesView` exists for bytes-like; general memoryview over any buffer is bigger scope |
+| `type` | Partial | `isinstance(x, T)` works; `type(x)` as a runtime value is not yet supported |
+| `object` | Done | Implicit root |
+| `None` | Done | |
+
+**Functions -- numeric and conversion**
+
+| Item | Status | Notes |
+|---|---|---|
+| `abs`, `min`, `max`, `sum` | Done | |
+| `pow`, `divmod`, `round` | Done | |
+| `bin`, `hex`, `oct` | Done | |
+| `chr`, `ord` | Done | |
+| `len`, `hash` | Done | |
+
+**Functions -- iteration**
+
+| Item | Status | Notes |
+|---|---|---|
+| `iter`, `next` | Done | |
+| `all`, `any`, `sorted` | Done | |
+| `enumerate`, `filter`, `map`, `reversed`, `zip` | Done | |
+
+**Functions -- introspection / attribute access**
+
+| Item | Status | Notes |
+|---|---|---|
+| `isinstance` | Done | Some CPython cases missing -- see TODO.md entries on protocol/union isinstance in ternary expressions and `@runtime_checkable` |
+| `repr` | Done | User-type fallback partial; see BUGS.md "repr() and f-string {} don't work on union types" |
+| `issubclass` | Missing | |
+| `callable` | Missing | Compile-time evaluable under static dispatch |
+| `getattr`, `setattr`, `delattr` (literal-name dynamic-fallback) | Done (D16 v1) | 2-arg literal-name form routes to `__getattr__` / `__setattr__` / `__delattr__`. Declared-member names rejected (use direct attribute access). See `docs/DYNAMIC_ATTRS_DESIGN.md` |
+| `hasattr`, 3-arg `getattr` | Done (D16 v1.5) | Phases 7+8 of D16; lambda IIFE wraps the dunder call in try/catch on `AttributeError`. Zero-cost on the happy path under modern table-based EH |
+| Dynamic-name 2-arg builtins | Done (D16 v1.5 phase 9) | Option A: routes unconditionally to the dunder when the name is a runtime expression. CPython divergence documented in `docs/DYNAMIC_ATTRS_DESIGN.md` divergence #8 |
+| `id` | Missing | `tpy.unsafe.unsafe_address_of` exists as an approximation; `id` semantics differ under static compilation |
+| `type(x)` (runtime value) | Missing | See TODO.md "type(); T = type(x); z = T()" |
+| `vars`, `dir` | Missing | Not meaningful without runtime object introspection |
+| `ascii`, `format` | Missing | f-strings cover most `format` uses |
+
+**Functions -- I/O**
+
+| Item | Status | Notes |
+|---|---|---|
+| `print` | Done | |
+| `open`, `open_text`, `open_binary` | Done | `TextIO` / `BinaryIO` context managers |
+| `input` | Missing | Needs stdin reader |
+
+**Descriptors / class utilities**
+
+| Item | Status | Notes |
+|---|---|---|
+| `@property` | Done | See LANGUAGE_FEATURES Properties |
+| `@staticmethod` | Done | |
+| `@classmethod` | Open | Tracked in FEATURE_ROADMAP Future Extensions (sugar over `type[T]`) |
+| `super()` | Done | See LANGUAGE_FEATURES |
+
+**Dynamic / not-meaningful under AOT**
+
+| Item | Status | Notes |
+|---|---|---|
+| `eval`, `exec`, `compile` | Missing | Not meaningful without a runtime interpreter |
+| `globals`, `locals` | Missing | Static compilation; no dict-shaped scope |
+| `__import__` | Missing | Imports resolve at compile time |
+| `breakpoint`, `help` | Missing | N/A |
+
+**Exceptions**
+
+Exception hierarchy support. Most built-in exception types raised by
+runtime checks are now user-catchable TPy types. Sites that remain panics
+are deliberate (internal invariants, OOM, fixed-int arithmetic overflow);
+see `docs/EXCEPTION_DESIGN.md` for the per-type migration table and the
+helper-API surface.
+
+| Item | Status | Notes |
+|---|---|---|
+| `BaseException`, `Exception` | Done | Two-tier exception model |
+| `ValueError` | Done | Catchable. Migrated runtime sites: `list.remove`/`list.index`, `bytearray.remove`, `bytes` value/`negative count`, `str.split`/`bytes.split` empty separator, `str.index`/`str.rindex` substring not found, `float()`/`int()`/`Int*()` parse errors, `slice` step==0, extended-slice assignment size mismatch, `range()` arg-3 zero, `time.sleep` negative, fixed-int + BigInt negative shift, `int(float('nan'))`, `open()` invalid mode, `from_range` size mismatch, codegen-side `__len__()` negative + enum `from_value` invalid value |
+| `OSError`, `FileNotFoundError` | Done | `OSError` also raised by `read()`/`write()`/`flush()`/`readline()`/`readlines()` when the file is opened in the wrong mode. CPython's `io.UnsupportedOperation` (diamond OSError+ValueError) is not reproducible since TPy MI doesn't support diamonds; one-sided divergence (`except OSError` works, `except ValueError` doesn't) |
+| `StopIteration` | Done | |
+| `IndexError` | Done | Catchable. List/array/span/string/bytes/bytearray out-of-range indexing, list/bytearray `pop` empty all throw `IndexError`. Messages match CPython ("list index out of range" etc.) |
+| `KeyError` | Partial | Catchable. Dict `__getitem__` / `__delitem__` / `pop`-no-default missing key, set `remove`-missing / `pop`-empty, TypedDict `total=False` field access on absent value, enum `from_name` (`Color["unknown"]`) all throw `KeyError`. CPython's `str(KeyError(k))` reprs the key (`'missing'`); TPy currently returns the catchall message verbatim -- alignment is a v2 follow-up |
+| `TypeError` | Done | Catchable. `ord(s)`/`Char(s)` length-1 violation, `cast(T, any_val)` typeid mismatch (with demangled type names), `hash(any_val)` on an unhashable contained type. User code can `raise TypeError(...)` anywhere |
+| `AttributeError` | Done | Catchable throw-tier type; raised by user `__getattr__` / `__setattr__` / `__delattr__` bodies. `hasattr` and 3-arg `getattr` wrap the dunder call in try/catch |
+| `ArithmeticError` | Done | Base class of `ZeroDivisionError` and `OverflowError`, matching CPython's hierarchy. `except ArithmeticError` catches either subtype |
+| `ZeroDivisionError` | Done | Catchable. Float `/`/`//`/`%`, fixed-int `//`/`%`, BigInt `//`/`%`, `divmod`. Messages match CPython per operation (`float division by zero`, `integer modulo by zero`, etc.) |
+| `OverflowError` | Done (catchable) + fixed-int overflow stays panic | Catchable: `int(float('inf'))`, BigInt `2 ** huge_value`, user `raise OverflowError`. Fixed-int arithmetic overflow (Int8..Int64, UInt8..UInt64 add/sub/mul/neg/shift/pow/cast/divmod/round) routes through `raise_fixedint_overflow` -- currently panics, future build/module/function-scope policy switch (`action=none/panic/throw`) plugs in without rewriting call sites |
+| `AssertionError` | Done | `assert` failure throws `AssertionError(msg)`; catchable via `try/except` |
+| `RuntimeError` | Done (class-only) | Class exposed for `raise RuntimeError(...)` in user code; no runtime panic sites migrated |
+| `NotImplementedError` | Done (class-only) | Class exposed for `raise NotImplementedError(...)` |
+| `MemoryError` | Done (class-only) | Class exposed; the BigInt OOM panic deliberately stays panic (catching MemoryError is fragile) |
+| `FloatingPointError`, `RecursionError` | Missing | Niche; not currently raised by TPy runtime |
+| `LookupError` | Missing | Base of IndexError/KeyError; not yet exposed |
+| `NameError`, `UnboundLocalError` | Not applicable | Compile-time concerns |
+| `ImportError`, `ModuleNotFoundError` | Not applicable | Import failures are compile-time today |
+| `UnicodeError` and subtypes | Missing | TPy has few encoding-panic sites today |
+| `SystemExit`, `KeyboardInterrupt`, `GeneratorExit` | Missing | Control-flow exceptions; need signal/runtime support |
+| `SystemError` | Missing | Internal-interpreter notion not directly applicable |
+| `EOFError`, `PermissionError` | Missing | I/O error hierarchy follow-ups |
+| `TimeoutError` | Done | Built-in re-export of `tpy::TimeoutError` (inherits `Exception`); raised by `asyncio.wait_for` |
+
+**Sentinels**
+
+| Item | Status | Notes |
+|---|---|---|
+| `True`, `False` | Done | |
+| `None` | Done | |
+| `NotImplemented` | Missing | Used by `__eq__` etc. to signal "try the reflected op"; TPy's overload dispatch handles this differently |
+| `Ellipsis` (`...`) | Partial | Usable in stub bodies (`def f(): ...`); not a first-class runtime value |
+
+Tests: `tests/cases/builtins/` has a broad suite covering the working
+surface (enumerate, filter, map, zip, sorted, hash, abs, bin, hex, oct,
+all, any, sum, divmod, range, and many more).
+
+### math
+
+Current: `lib/tpy/math.py` -- native C++ wrappers. Sufficient for numerics-heavy code.
+
+| Item | Status | Notes |
+|---|---|---|
+| `pi`, `tau`, `e`, `inf`, `nan` | Done | Constants as `Final[float]`. `nan` is `Final[float] = float("nan")` -- the `float(str)` literal forms (`"nan"`, `"inf"`, `"-inf"`, plus case/whitespace variants) fold at codegen to constexpr `std::numeric_limits<double>::quiet_NaN()` / `::infinity()`, bypassing the non-constexpr `tpy::float_from_str` runtime |
+| `log`, `log10`, `log2` | Done | `log(x, base)` is pure-TPy overload |
+| `log1p`, `expm1` | Done | Thin `std::log1p` / `std::expm1` |
+| `sqrt`, `cbrt`, `pow`, `exp`, `exp2` | Done | `cbrt` / `exp2` are Python 3.11+ |
+| `floor`, `ceil`, `trunc` | Done | Return `int` (BigInt) / generic `T` |
+| `sin`, `cos`, `tan` | Done | |
+| `asin`, `acos`, `atan`, `atan2` | Done | |
+| `sinh`, `cosh`, `tanh` | Done | |
+| `asinh`, `acosh`, `atanh` | Done | |
+| `fabs` | Done | |
+| `hypot` | Done | Variadic `hypot(*coords)`; internal `_hypot2` native binding to `std::hypot` + overflow-safe hypot-fold |
+| `radians`, `degrees` | Done | Pure-TPy |
+| `isnan`, `isinf`, `isfinite` | Done | Thin `std::isnan` / `std::isinf` / `std::isfinite` |
+| `copysign` | Done | |
+| `fmod`, `remainder` | Done | C fmod semantics (truncation); IEEE remainder (nearest-even) |
+| `nextafter`, `ldexp`, `fma` | Done | Thin natives; `fma` is CPython 3.13+ (cpy test is no_cpython) |
+| `ulp` | Done | `tpy::stdlib::math::ulp` helper matching CPython edge cases for nan/inf/0 |
+| `modf` | Done | `tpy::stdlib::math::modf` wrapper returning `std::tuple<double, double>` |
+| `frexp` | Done | Generic over the exponent type: `frexp[T](x) -> tuple[float, T]`. Default T is `DefaultInt` (Int32 under default config); users can pick `Int64` or `int` (BigInt) for wider ranges |
+| `gcd`, `lcm` | Done | Variadic `gcd(*ints)` / `lcm(*ints)` over BigInt. Internal `_gcd2` binary helper; `lcm` uses `(a // gcd(a,b)) * b` to keep the intermediate bounded by `max(|a|, |b|)`. Generic-over-int-type is a follow-up (see math.py header) |
+| `factorial` | Done | Pure-TPy over BigInt; raises `ValueError` on negative |
+| `isqrt` | Done | Pure-TPy Newton's method over BigInt; initial guess from `bit_length()` for O(log log n) iteration count |
+| `perm`, `comb` | Done | Pure-TPy over BigInt. `perm` has both one-arg (`perm(n) == factorial(n)`) and two-arg overloads via `@overload`. `comb` is binary only |
+| `isclose` | Done | Pure-TPy; `rel_tol` / `abs_tol` are kw-only to match CPython |
+| `prod` | Done | Pure-TPy; `start` is kw-only to match CPython. Three overloads: `Iterable[Int32]` -> Int32 (fast path), `Iterable[int]` -> int (exact BigInt for arbitrary-precision products), `Iterable[float]` -> float. Kwarg disambiguation lets `prod(empty, start=1.0)` / `start=int(1)` / `start=Int32(1)` pick the right family |
+| `fsum` | Done | Pure-TPy Neumaier compensated summation. Takes `Iterable[float]` |
+| `sumprod` | Done | Pure-TPy; raises `ValueError` on length mismatch via iterator lockstep drive (mirrors CPython's `zip(..., strict=True)`). Takes `Iterable[float]` |
+| `dist` | Done | Pure-TPy Euclidean distance via hypot-fold (overflow-safe for coordinates up to `DBL_MAX`). Takes `Iterable[float]` |
+| `gamma`, `lgamma`, `erf`, `erfc` | Done | Thin natives (`std::tgamma` etc.) |
+
+Tests: `math_module`, `math_extended`, `math_log_base`, `math_hyperbolic`,
+`math_numeric`, `math_special`, `math_fma`, `math_frexp_generic`,
+`math_variadic`, `math_iterable`, `panic_sumprod_mismatch` in
+`tests/cases/builtins/`; `float_special_values` in `tests/cases/float/`
+(covers `float("nan"/"inf"/"-inf")` fold).
+
+**Remaining gaps to reach 100%:**
+- Tuples as `Iterable[T]`. Tuples don't iterate today in TPy regardless of protocol context -- real CPython compat gap but bundled scope (needs coordinated sema + codegen + runtime story, not just a conformance flag flip). See TODO.md.
+
+### time
+
+Current: `lib/tpy/time.py` -- native_module. Wall-clock + monotonic +
+process-CPU clocks shipped; calendar / formatting surface deferred.
+
+| Item | Status | Notes |
+|---|---|---|
+| `time()` | Done | Seconds since epoch as float |
+| `sleep(s)` | Done | |
+| `perf_counter()` / `monotonic()` | Done | `std::chrono::steady_clock`. CPython's `perf_counter` and `monotonic` share the same underlying clock on POSIX; we mirror that |
+| `perf_counter_ns()` / `monotonic_ns()` / `time_ns()` | Done | Return `Int64`; epoch reasonable through year 2262 (INT64_MAX ns) |
+| `process_time()` | Done | `std::clock() / CLOCKS_PER_SEC`. CPU time, ~1us resolution on Linux glibc (CPython uses `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)` for ns precision -- a future tightening) |
+| `sleep_until_steady(deadline)` | Done | TPy extension (no CPython equivalent). Sleeps until the given `monotonic()`-domain deadline; used by `asyncio`'s timer-heap drain |
+| `struct_time` | Missing | Needs named-tuple-like or @dataclass |
+| `gmtime`, `localtime` | Missing | Depends on struct_time |
+| `strftime`, `strptime` | Missing | Formatting strings; depends on struct_time |
+| `mktime` | Missing | Depends on struct_time |
+| `asctime`, `ctime` | Missing | Depends on struct_time |
+| `timezone`, `altzone`, `tzname` | Missing | Module-level constants |
+
+Tests: `time_module`, `time_sleep`, `time_import`, `stdlib/time_clocks`
+(invariants on perf_counter / monotonic / process_time / time_ns since
+absolute timing values are non-deterministic).
+
+### sys
+
+Current: `lib/tpy/sys.py` -- native; `argv`, `stdout`, `stderr`, `exit`.
+
+| Item | Status | Notes |
+|---|---|---|
+| `argv` | Done | List populated at runtime init |
+| `stdout`, `stderr` | Done | Backed by `tpy::StdStream` (wraps `std::cout` / `std::cerr`); satisfy the `Writable` protocol so they work as `print(file=...)` targets and expose `write(str) -> Int32` / `flush()` |
+| `stdin` | Missing | Needs read-side protocol; lower priority than write |
+| `exit(code)` | Done | `Int32` arg lowered to `std::exit(int)` via `tpy::sys_exit`; `[[noreturn]]` |
+| `platform` | Missing | Compile-time constant |
+| `version`, `version_info` | Missing | Already in `tpy.version`; could re-export |
+| `path` | Missing | List; relates to import machinery (TPy resolves at compile time, so semantics differ) |
+| `modules` | Missing | Not meaningful under static compilation |
+| `maxsize` | Missing | `PTRDIFF_MAX` constant |
+| `byteorder` | Missing | Compile-time constant |
+| `getsizeof` | Missing | Hard: sizes differ from CPython (inline fields vs boxed) |
+| `executable` | Missing | `argv[0]` / `/proc/self/exe` |
+
+Tests: `sys_argv`, `kwargs_print_file_std`.
+
+### os
+
+**Missing.** Depends on filesystem + process bindings. When attacking, likely in order:
+
+| Item | Status | Notes |
+|---|---|---|
+| `getcwd`, `chdir` | Missing | `std::filesystem::current_path` |
+| `listdir`, `scandir` | Missing | `std::filesystem::directory_iterator` |
+| `mkdir`, `makedirs`, `rmdir`, `removedirs` | Missing | `std::filesystem::create_directory` etc. |
+| `remove`, `rename`, `replace` | Missing | `std::filesystem::remove` / `rename` |
+| `stat`, `lstat` | Missing | Needs `stat_result` struct |
+| `environ`, `getenv`, `putenv` | Missing | `std::getenv` |
+| `path` | Missing | See [os.path](#ospath) |
+| `walk` | Missing | Pure TPy over `scandir` |
+| `fork`, `exec*`, `spawnv*`, `system` | Blocked | Process spawning |
+
+### os.path
+
+**Missing.** Independent of `os` -- pure TPy over `std::filesystem::path`
+would cover most of it.
+
+| Item | Status |
+|---|---|
+| `join`, `split`, `splitext`, `basename`, `dirname` | Missing |
+| `exists`, `isfile`, `isdir`, `islink` | Missing |
+| `abspath`, `realpath`, `normpath`, `relpath` | Missing |
+| `expanduser`, `expandvars` | Missing |
+| `getsize`, `getmtime`, `getatime`, `getctime` | Missing |
+
+### pathlib
+
+**Missing.** Class-based wrapper around `os.path`; depends on filesystem bindings.
+
+| Item | Status |
+|---|---|
+| `Path`, `PurePath` | Missing |
+| Path operators (`/`), `.parent`, `.name`, `.suffix`, `.stem` | Missing |
+| `.read_text`, `.write_text`, `.read_bytes`, `.write_bytes` | Missing |
+| `.glob`, `.rglob`, `.iterdir` | Missing |
+| `.exists`, `.is_file`, `.is_dir`, `.stat`, `.unlink`, `.mkdir` | Missing |
+
+### io
+
+**Partial.** v1 ships `io.StringIO` + `io.BytesIO` plus six IO protocols
+(`Readable`/`Writable`/`BinaryReadable`/`BinaryWritable`/`Seekable`/`Closable`)
+that consumer code parameterizes over (`def f(fp: Writable)`). Both buffer
+types explicitly inherit the relevant protocols (`StringIO(Writable, Readable,
+Seekable, Closable)`), so conformance is documented at the class header.
+
+Storage strategy: `list[str]`/`list[bytes]` chunks. The fast path
+(append-at-end, dominant for the "build payload then `getvalue()`" pattern) is
+O(1) per write and never joins; mid-buffer overwrites collapse the chunks to
+a single contiguous buffer first. `getvalue()` joins lazily and does not
+materialize state.
+
+Design choice: no `IOBase` ABC hierarchy. TPy's static dispatch makes the
+runtime introspection that `IOBase` exists for in CPython (e.g. `isinstance(fp,
+IOBase)`) unnecessary; the protocols give zero-overhead dispatch and cleanly
+split text/binary + seek/close concerns. Adding the `IOBase` family later as a
+combined protocol layer (`class IOBase(Closable, Seekable, Protocol): ...`)
+remains an option without breaking the existing granular surface.
+
+| Item | Status | Notes |
+|---|---|---|
+| `StringIO(initial="")` | Done | Chunked write/read; `read`/`readline`/`readlines`/`seek`/`tell`/`truncate`/`getvalue`/`flush`/`close`/`__iter__`/`__enter__`/`__exit__` |
+| `BytesIO(initial=None)` | Done | Same surface as `StringIO`, returning `bytes` |
+| `Writable` / `Readable` / `BinaryWritable` / `BinaryReadable` | Done | Protocols on `tpy._core._types`, re-exported from `tpy/__init__.py` and from `io` |
+| `Seekable` / `Closable` | Done | Same; `Seekable` is `seek(pos, whence=0)` + `tell()`; `Closable` is `close()` only (the `closed` property is left out of the protocol but available on the concrete classes) |
+| `seek(pos, whence=0)` | Partial | `whence=0/1/2` accepted as integer literals. `io.SEEK_SET/CUR/END` constants not yet exposed -- the names collide with `<cstdio>` macros; needs `#undef` shim from codegen or namespacing |
+| `seek` past end | Diverges | v1 clamps to `_total`; CPython back-fills with NUL/0. Revisit with a real consumer |
+| `__iter__` (line-by-line) | Done | Generator method yielding `readline()` results until empty |
+| `read(size=-1)` | Missing | v1 reads all remaining; CPython supports `size` arg |
+| `IOBase` / `RawIOBase` / `BufferedIOBase` / `TextIOBase` | Missing (deferred) | Not planned -- protocols cover the static-dispatch use case |
+| `TextIOWrapper` | Missing | Encoding + newline translation; defer until a consumer demands it |
+| `encoding=` / `newline=` / `errors=` kwargs | Missing | v1 doesn't translate text |
+| `UnsupportedOperation` | Missing | Defer until a method needs to raise it (e.g. seek on a non-seekable wrapper) |
+| `open()` | Done | In `builtins` (not in `io`); exposes `TextIO`/`BinaryIO` |
+
+Tests: `cases/stdlib/io_stringio_basic`, `cases/stdlib/io_bytesio_basic`,
+`cases/stdlib/io_protocols` (consumer functions parameterized over the four
+protocols, both `StringIO`/`BytesIO` and pass-through wiring).
+
+### json
+
+**Partial.** `lib/tpy/json.py` is a pure-TPy wrapper over `tplib.json`'s
+`JsonReader` / `JsonWriter`. Untyped values are represented by a recursive
+union alias `JsonValue = None | bool | int | float | str | list[JsonValue] |
+dict[str, JsonValue]` -- ints stay BigInt, floats stay double, no precision
+loss. CPython byte-compatible output for the `loads` / `dumps` surface across
+all primitive types and nested containers (verified via the cpy phase in
+`tests/cases/stdlib/json_*`). For typed deserialization into user records,
+`tplib.json` with the `@model` decorator remains faster.
+
+| Item | Status | Notes |
+|---|---|---|
+| `loads(s)` | Done | Returns `Own[JsonValue]`. Raises `JSONDecodeError` on malformed input or trailing data. |
+| `dumps(obj, *, indent, sort_keys)` | Done | `indent` and `sort_keys` kwargs supported. CPython byte-compatible for ASCII. |
+| `JSONDecodeError` | Done | Subclasses `ValueError` (matches CPython). Thrown via normal `try`/`except`. Carries `msg`, `doc`, `pos`, `lineno`, `colno`. |
+| `load(fp)`, `dump(obj, fp)` | Missing | Needs `io` |
+| `JSONEncoder`, `JSONDecoder` | Missing | Extension hooks; not yet implemented |
+| `dumps` kwargs `ensure_ascii`, `separators`, `allow_nan`, `default`, `cls`, `skipkeys` | Missing | Current behavior is `ensure_ascii=False` (raw UTF-8) with CPython default separators |
+| `loads` kwargs `object_hook`, `object_pairs_hook`, `parse_float`, `parse_int`, `parse_constant` | Missing | -- |
+
+### re
+
+**Partial.** Pure-TPy facade in `lib/tpy/re.py` over raw PCRE2 bindings in
+`lib/tpy/_bindings/pcre2.py`. PCRE2 is vendored at
+`runtime/cpp/third_party/pcre2/` (10.44, ~5MB after stripping `doc/`,
+`testdata/`, and autotools build files; reproducible via
+`scripts/vendor_pcre2.py`) and built into the user binary via the existing
+`BuildLayout.build_cpp_commands` infrastructure -- no separate CMake
+required for `tpyc -x` / `-b`. Backend selection: `tpyc --pcre2=bundled`
+(default), `--pcre2=system` (`-lpcre2-8`), or `--pcre2=auto`. The CMake-
+emit path emits a 3-mode selector into `sources.cmake` so users
+integrating into a larger CMake project can flip via `-DTPY_PCRE2=system`.
+
+History: F8 was originally listed as a prerequisite to choose between
+`std::regex` and PCRE2 backends. Reframed as a future enhancement -- v1
+ships PCRE2 only (CPython-quality semantics, mature JIT). cppstd backend
+deferred until embedded targets actually need it.
+
+Architecture (no C++ wrapper layer, no pcre2.h in TPy-generated TUs):
+
+  * `runtime/cpp/include/tpy/stdlib/pcre2_h.hpp` -- hand-written facade
+    that mirrors the PCRE2 symbols and types we use (opaque struct
+    forward-decls, `extern "C"` function declarations, `PCRE2_SPTR8` /
+    `PCRE2_UCHAR8` / `PCRE2_SIZE` typedefs). Deliberately does NOT
+    `#include <pcre2.h>` -- pcre2.h's `PCRE2_*` macros would otherwise
+    collide with TPy module-level constants of the same name. The vendored
+    PCRE2 .c files include the real pcre2.h during their separate
+    compilation; the linker resolves our extern "C" declarations to those
+    symbols.
+  * `lib/tpy/_bindings/pcre2.py` -- pure `@native` 1:1 bindings to `pcre2_*_8`
+    C primitives. Mirrors upstream constant names exactly
+    (`PCRE2_CASELESS`, `PCRE2_SUBSTITUTE_GLOBAL`, etc.). No Python semantics.
+  * `lib/tpy/re.py` -- facade. Pattern + Match classes manage
+    `pcre2_code*` / `pcre2_match_data*` lifetimes via `__del__`. All flag
+    mapping, group accessors, sub/split/findall logic live here in TPy.
+
+| Item | Status | Notes |
+|---|---|---|
+| `compile`, `Pattern` | Done | Pure-TPy class wrapping `Ptr[pcre2.Code]`; JIT-compiled on construct |
+| `search`, `match`, `fullmatch` | Done | Return `Optional[Own[Match]]` |
+| `findall` | Done | List of group-0 strings. Doesn't yet return captures-tuples for grouped patterns (CPython divergence) |
+| `finditer` | Partial | Returns `list[Match]` instead of a generator (deferred to v2) |
+| `sub` | Partial | Global replacement only; CPython's `count` arg deferred. Backref syntax is PCRE2-native (`$1`, `${name}`), not CPython's `\1` -- syntax translator deferred |
+| `split`, `split(maxsplit=)` | Done | |
+| `Match.group(int)`, `start`, `end`, `span` | Done | All returning `Int32` offsets and TPy `str` slices |
+| `Match.groups()` | Partial | Returns `list[str]` instead of tuple (varadic-tuple support pending) |
+| `Match.group("name")`, `groupdict` | Missing | Needs PCRE2 nametable walk |
+| Flags (`IGNORECASE`, `MULTILINE`, `DOTALL`, `VERBOSE`, `ASCII`) | Done | CPython bit values; mapped to upstream `PCRE2_*` flags. `re.A` / `re.I` / `re.M` / `re.S` / `re.X` aliases too |
+| `re.error` | Done | Catchable exception subtype |
+| Named groups `(?P<name>...)` | Done (syntax) | PCRE2 accepts Python's `(?P<name>...)` form natively for back-compat |
+| Backreferences `(?P=name)` in pattern | Done | PCRE2-native |
+| Backreferences in `sub` replacement | Partial | PCRE2 `$1` syntax only; CPython's `\1` needs a translator (deferred) |
+| Lookahead, lookbehind, `\p{...}`, etc. | Done | All PCRE2 features available -- patterns just work |
+| `re.compile` cache | Missing | Needs module-level mutable state (see "stdlib enablement workstream" above) |
+| bytes input | Missing | str only for now |
+
+Tests:
+  * `cases/stdlib/re_basic/` -- CPython-compatible surface. TPy and
+    CPython produce byte-identical output for compile/search/match/
+    fullmatch/findall/split/sub-without-backref + all 5 flags + pattern
+    features (quantifiers, classes, anchors, backrefs in pattern,
+    non-capturing groups) + error class catching. cpy phase enabled.
+  * `cases/stdlib/re_pcre2_specific/` -- divergent behaviors isolated:
+    sub with PCRE2 `$1`/`$2` backref syntax, `Match.groups()` returning
+    `list[str]` vs CPython's `tuple[str, ...]`. Marked `no_cpython`.
+    Each divergence is tracked as a `TODO(v2)` in `lib/tpy/re.py`; when
+    the syntax translator + varadic-tuple support land, this test folds
+    into `re_basic/`.
+
+### collections
+
+**Missing** as a module. Some building blocks already exist.
+
+| Item | Status | Notes |
+|---|---|---|
+| `OrderedDict` | Missing | TPy already uses `tpy::ordered_map` for `dict[K,V]`; this would be a thin alias or subclass |
+| `defaultdict` | Missing | Macro-friendly: store factory, synthesize `__getitem__` |
+| `Counter` | Missing | Pure TPy over `dict[T, int]` |
+| `deque` | Missing | Needs C++ backing (std::deque) with Python-like API |
+| `namedtuple` | Missing | Would be a class macro; could desugar to @dataclass(frozen=True) |
+| `ChainMap` | Missing | Pure TPy over list of dicts |
+| `abc.*` (Sequence, Mapping, ...) | Partial | Some in `typing`; deeper introspection absent |
+
+### itertools
+
+**Missing** as a Python-surface module, but most primitives exist in
+`runtime/cpp/include/tpy/itertools.hpp`: `chain`, `zip_longest`, `islice`,
+`repeat`, `cycle`, `product`, `combinations`, `permutations`, `groupby`.
+
+Existing builtins `enumerate`, `zip`, `reversed`, `map`, `filter` live in
+`itertools.hpp` too (as builtins, not `itertools.*`).
+
+| Item | Status | Notes |
+|---|---|---|
+| `count`, `cycle`, `repeat` | Missing | Need Python-visible wrappers |
+| `chain`, `chain.from_iterable` | Missing | Wrapper |
+| `compress`, `dropwhile`, `takewhile`, `filterfalse` | Missing | Pure TPy or wrapper |
+| `islice` | Missing | Wrapper |
+| `starmap`, `tee` | Missing | `tee` tricky (needs buffering) |
+| `zip_longest` | Missing | Wrapper |
+| `product`, `permutations`, `combinations`, `combinations_with_replacement` | Missing | Wrapper |
+| `groupby`, `accumulate`, `pairwise`, `batched` | Missing | Wrapper / pure |
+
+Key question: whether the module is pure TPy re-exporting C++ generators
+or `@native` thin shims. The @native qualification gap that previously
+blocked the pure-TPy approach has been resolved (codegen always emits
+`::`-qualified names for `@native` refs).
+
+### functools
+
+Current: `lib/tpy/functools.py` -- pure-TPy `reduce` (both 2-arg and 3-arg
+forms). Landing the rest is gated on specific compiler fixes tracked in
+BUGS.md / TODO.md, not on macro or closure infrastructure:
+
+- **`cmp_to_key`** requires either `copy()` to strip readonly through
+  generic `T`, arithmetic on `readonly[FixedInt]`, or an opt-out from the
+  unconditional readonly deduction on comparison dunders. See BUGS.md
+  "Readonly propagation through generic T blocks storing callable cmp/key".
+
+| Item | Status | Notes |
+|---|---|---|
+| `reduce(func, a, initial)` | Done | Pure TPy. Takes `Iterable[T]` -- accepts list literals, `range()`, bound list/iter vars |
+| `reduce(func, a)` | Done | Pure TPy. Takes `list[T]` (random-access; raises on empty). Restricted to list rather than `Iterable[T]` because TPy doesn't have CPython's iter/next + StopIteration pattern |
+| `cmp_to_key` | Blocked | Pure TPy; blocked on readonly-through-generics. See BUGS.md |
+| `total_ordering` | Done | Class macro in `lib/tpy/_functools_macros.py`, re-exported via `lib/tpy/functools.py`. Synthesizes the missing comparison ops from any one of `__lt__` / `__le__` / `__gt__` / `__ge__` plus `__eq__`. Defers synthesis via `ClassInfo.defer_until_macros_complete` so it composes with `@dataclass` regardless of decorator order -- dataclass adds `__eq__` (and optionally `__lt__`/`__le__`/`__gt__`/`__ge__`), total_ordering then picks an anchor and fills in the rest |
+| `wraps`, `update_wrapper` | Blocked | CPython's `@wraps(f)` is a decorator factory (`wraps(f)` returns a decorator that takes the wrapper). TPy macro_api has no "decorator factory that's identity" form; would need new infrastructure separate from class/call/builder macros |
+| `partial` | Missing | Full variadic form needs function-macro or `*args` forwarding on user classes |
+| `partialmethod` | Missing | Descriptor-protocol heavy |
+| `lru_cache`, `cache` | Missing | Decorator must wrap + return a new callable with mutable cache dict; needs function-macro (not supported today) |
+| `singledispatch` | Missing | Runtime dispatch; use `@overload` instead |
+| `cached_property` | Missing | Needs descriptor support |
+
+### random
+
+Current: `lib/tpy/random.py` -- pure-TPy MT19937 engine. `Random` class
+holds the 624-word state; module-level `random()` / `seed()` /
+`getrandbits()` delegate to a module-level `_inst: Random` singleton
+(auto-seeded from OS entropy at module init, like CPython). Byte-
+identical to CPython's `random._inst.getrandbits(32)` for any Int32
+seed (negatives are mapped to `abs()` to match CPython); verified
+against seeds 42, 1, 7, 99, 12345, -42, INT32_MIN; `cases/stdlib/random`
+and `cases/stdlib/random_seq` exercise both TPy and CPython phases.
+
+Target under the policy: the Mersenne Twister state machine itself is **pure
+TPy** (same as CPython's `_randommodule.c` logic, but in .py). The only native
+primitive is an OS entropy source for seeding when no explicit seed is given
+(e.g. `os.urandom` via thin syscall binding). Everything else -- `randint`,
+`choice`, `shuffle`, `sample`, `gauss`, etc. -- is pure TPy over the MT core.
+
+**Unblocked (engine landed).** Earlier drafts flagged the MT port as gated
+on the `native_module`-facade bugs ("Variable re-exports through native_module
+facades" / "Init chain doesn't propagate transitively through native_module
+facades" in BUGS.md) and "module-level mutable state across compilation
+units." Verified those don't apply here:
+`random.py` is a regular stdlib module, not a facade, so it compiles to one
+TU with a module-level `_inst: Random` whose state is genuinely shared
+across all importers. The one real limitation -- TPy rejects reassigning a
+module-level reference-type variable -- is sidestepped by in-place
+`_inst._seed(s)` mutation, which is how CPython's `random.seed()` works
+anyway.
+
+**Thread safety (deferred).** The module-level `_inst` is shared mutable
+state and NOT thread-safe: concurrent callers can corrupt the 624-word
+vector (double-twist, torn index updates). Currently theoretical -- TPy
+has no threading primitives -- but will need a fix when `threading` lands.
+Three candidate models, each with trade-offs: per-thread `_inst` via
+thread-local storage (muddies `seed()` semantics), lock inside `Random`
+(contention under heavy use), or deprecate module-level helpers in favour
+of explicit `Random()` instances (breaks CPython shorthand). CPython itself
+punts to "use per-thread Random()" in docs and added internal locking in
+free-threaded 3.13+. Decision deferred until the TPy threading model is
+chosen.
+
+Sketch:
+
+    class Random:
+        _state: Array[UInt32, 624]
+        _index: UInt32
+
+        def __init__(self, seed_value: UInt32 | None = None) -> None: ...
+        def _seed(self, s: UInt32) -> None: ...          # init_by_array
+        def _genrand_uint32(self) -> UInt32: ...         # MT step + twist
+        def random(self) -> float: ...                   # genrand_res53
+        def choice[T](self, seq: list[T]) -> T: ...
+        def shuffle[T](self, seq: list[T]) -> None: ...
+        # randint, gauss, ... as methods
+
+    _inst: Random = Random()  # auto-seeds via _os_entropy_uint32()
+
+    @overload
+    def seed() -> None: _inst._seed(_os_entropy_uint32())
+    @overload
+    def seed(n: Int32) -> None: ...                       # negatives -> abs()
+    # ...
+
+OS entropy primitive shipped as `tpy::stdlib::random::os_entropy_uint32`
+in `runtime/cpp/include/tpy/stdlib/random.hpp`, backed by
+`std::random_device`. Used for the no-arg `seed()` and `Random(None)`
+auto-seed paths. `SystemRandom` reuses the same primitive but is
+deferred pending class-hierarchy decisions (subclass `Random` with
+overrides vs standalone class).
+
+Soft gaps for full CPython compat (none gate the core MT port):
+- `choices` / `sample` kwarg iterables (`weights=`, `cum_weights=`, `counts=`)
+  ship as `list[float]`/`list[int]` rather than `Iterable[T]`. The list-
+  literal-vs-protocol conformance gap that blocked this has been closed
+  (see functools/math stdlib updates); remaining work is a mechanical
+  signature swap plus mixed-positional+kwarg argument wiring.
+
+| Item | Status | Notes |
+|---|---|---|
+| `random()` | Done | Uniform [0, 1); MT19937 `genrand_res53`. Byte-identical to CPython |
+| `seed(a)` | Partial | Int32 (negatives mapped to abs()) and `seed()` no-arg auto-seed via OS entropy. CPython also accepts BigInt / `bytes` / `str` (Tier 3 below) |
+| `getrandbits(k)` | Done | Returns `int` (BigInt). k in [1, 32] uses one MT word; k > 32 concatenates ceil(k/32) words little-endian, matching CPython byte-identical |
+| `randint(a, b)` | Done | Inclusive [a, b]; `b - a + 1` must fit Int32 |
+| `randrange(stop)`, `randrange(start, stop)`, `randrange(start, stop, step)` | Done | Three overloads; step can be negative |
+| `randbytes(n)` | Done | Byte-identical to CPython's `getrandbits(n*8).to_bytes(n, 'little')` for any `n` on any host |
+| `choice(seq)` | Done | Pure-TPy generic `choice[T](seq: list[T]) -> T`. Byte-identical to CPython on the same seed |
+| `shuffle(seq)` | Done | Fisher-Yates / Durstenfeld in place; byte-identical to CPython |
+| `uniform(a, b)` | Done | |
+| `triangular(low=0.0, high=1.0, mode=None)` | Done | |
+| `gauss(mu, sigma)` | Done | Box-Muller with cached second value. Reseed clears cache |
+| `normalvariate(mu, sigma)` | Done | Kinderman-Monahan (distinct stream from `gauss`), matches CPython |
+| `lognormvariate(mu, sigma)` | Done | |
+| `expovariate(lambd)` | Done | |
+| `paretovariate(alpha)` | Done | |
+| `weibullvariate(alpha, beta)` | Done | |
+| `gammavariate(alpha, beta)` | Done | Cheng 1977 (alpha>1) + Ahrens-Dieter (0<alpha<1) + exponential (alpha==1) |
+| `betavariate(alpha, beta)` | Done | Composed over `gammavariate` |
+| `vonmisesvariate(mu, kappa)` | Done | Floor-mod workaround for BUGS.md "tpy::fmod uses C semantics" (`%` sign semantics) |
+| `Random` class (per-instance state) | Done | Per-instance 624-word state; `Random(None)` / `Random()` auto-seed from OS entropy |
+| `getstate()`, `setstate(state)` | Missing | Tier 2; CPython tuple shape awkward, `list[UInt32]` variant viable |
+| `choices(pop, weights=, cum_weights=, k=)` | Missing | Tier 3. The `Iterable[T]` conformance gap that previously blocked this is resolved; remaining work is a mechanical signature swap plus weighted-selection wiring |
+| `sample(pop, k, counts=None)` | Missing | Tier 3: same `Iterable[T]` gap + complex algorithm |
+| `binomialvariate(n, p)` | Missing | Tier 3: BTRS state machine; defer until demand |
+| `SystemRandom` class | Missing | Tier 3: OS entropy primitive is wired (`tpy::stdlib::random::os_entropy_uint32`); needs class-hierarchy decisions (subclass `Random` with overrides vs standalone) |
+
+Tests: `cases/builtins/random_basic` (existing API smoke test);
+`cases/stdlib/random` (MT engine byte-identity with CPython + per-instance
+Random + singleton isolation, `cpy` phase enabled);
+`cases/stdlib/random_seq` (choice/shuffle/getrandbits k>32/seed(negative)
+byte-identity); `cases/stdlib/random_autoseed` (entropy-driven `seed()` /
+`Random(None)`, `no_cpython` since entropy is non-deterministic).
+
+### struct
+
+Current: `lib/tpy/struct.py` -- macro module. Format string must be literal.
+
+| Item | Status | Notes |
+|---|---|---|
+| `unpack(fmt, data)`, `unpack_from` | Done | Little-endian only; big-endian emits MacroError |
+| `calcsize(fmt)` | Done | Compile-time constant |
+| `pack(fmt, *values)`, `pack_into` | Missing | Needs statement-expr or buffer-builder pattern (see module docstring) |
+| `iter_unpack` | Missing | |
+| `Struct` class | Missing | Would need per-class macro |
+| Big-endian byte order (`>`, `!`) | Missing | Need `std::byteswap` wrappers in unsafe |
+| Format codes `e` (f16), `P` (ptr), `n`/`N` (ssize_t/size_t) | Missing | |
+
+Tests: `struct_unpack`.
+
+### bisect
+
+**Done.** `lib/tpy/bisect.py` is pure TPy generic over `Comparable`.
+
+| Item | Status | Notes |
+|---|---|---|
+| `bisect_left`, `bisect_right`, `insort_left`, `insort_right` | Done | |
+| `bisect`, `insort` | Done | Aliases to `bisect_right` / `insort_right` |
+
+Tests: `cases/stdlib/bisect`.
+
+### enum
+
+Current: `lib/tpy/enum.py` -- macro module.
+
+| Item | Status | Notes |
+|---|---|---|
+| `Enum` base class | Done | |
+| `IntEnum` | Done | |
+| `auto()` | Done | |
+| `StrEnum` | Missing | Python 3.11+ |
+| `Flag`, `IntFlag` | Missing | Bitwise semantics |
+| Member iteration (`for m in E`) | Partial | Works at runtime; check exhaustiveness |
+| Lookup by value (`E(1)`) | Missing | |
+| Lookup by name (`E["FOO"]`) | Missing | |
+| `.name`, `.value` attributes | Done | |
+| Functional API (`E = Enum("E", "A B C")`) | Missing | Rarely used |
+| `@unique`, `@verify` decorators | Missing | |
+
+Tests: integrated in json_model and enum test group.
+
+### dataclasses
+
+Current: `lib/tpy/dataclasses.py` -- macro module.
+
+| Item | Status | Notes |
+|---|---|---|
+| `@dataclass(frozen, order)` | Done | |
+| `field(default, default_factory)` | Done | |
+| `asdict()`, `astuple()` | Done | Recurse into nested dataclasses, lists, dicts, tuples |
+| `@dataclass(slots)` | N/A | All TPy records use inline storage |
+| `@dataclass(eq=False, repr=False, init=False)` | Missing | Opt-outs |
+| `@dataclass(kw_only)` | Missing | |
+| `__post_init__` | Missing | |
+| `InitVar[T]` | Missing | |
+| `replace(obj, **kw)` | Missing | Would be a call macro |
+| `fields(cls)`, `is_dataclass` | Missing | Needs compile-time or runtime reflection |
+| `field(metadata=...)` | Missing | Currently ignored |
+| `MISSING` sentinel | Missing | |
+
+Tests: multiple `tplib/json_model_*` cases exercise @dataclass.
+
+### typing
+
+Current: `lib/tpy/typing.py` -- re-export from `tpy._typing`.
+
+| Item | Status | Notes |
+|---|---|---|
+| `Protocol`, `runtime_checkable` | Partial | Protocols via `Protocol`; `@runtime_checkable` N/A |
+| `Self` | Done | |
+| `overload`, `override` | Done | |
+| `Sized`, `Iterable`, `Iterator`, `Sequence`, `MutableSequence` | Done | |
+| `Optional`, `Final` | Done | |
+| `Callable` | Done | |
+| `Literal` | Done | |
+| `TypedDict`, `Unpack` | Done | |
+| `Union`, `Annotated` | Missing | TPy uses `A \| B` syntax |
+| `Any` | Missing | Type-system gap; would need dynamic dispatch |
+| `TypeVar`, `Generic`, `ParamSpec`, `TypeVarTuple` | Missing | TPy uses PEP 695 `[T]` syntax |
+| `ClassVar` | Missing | |
+| `NewType` | Missing | Could be macro |
+| `cast` | Missing | Open question: explicit upcast syntax |
+| `get_type_hints`, `get_origin`, `get_args` | Missing | Runtime reflection |
+
+### datetime
+
+**Missing.** Class-heavy; natural fit for @dataclass-style TPy records +
+native conversion helpers. Blocked by nothing architectural; medium effort.
+
+| Item | Status |
+|---|---|
+| `date`, `time`, `datetime`, `timedelta`, `tzinfo`, `timezone` | Missing |
+| `date.today`, `datetime.now`, `datetime.utcnow` | Missing |
+| `strftime`, `strptime`, `isoformat`, `fromisoformat` | Missing |
+| `timedelta` arithmetic | Missing |
+
+### csv
+
+**Missing.** Depends on `io` for `reader`/`writer` accepting file-like objects.
+
+### base64
+
+Current: `lib/tpy/base64.py` -- pure TPy. CPython-compatible defaults:
+`b64decode(validate=False)` silently skips non-alphabet chars (matching
+CPython's lax MIME-mode behavior); `validate=True` makes any non-alphabet
+char raise `ValueError`. Padding errors always raise.
+
+| Item | Status | Notes |
+|---|---|---|
+| `b64encode(data, altchars=None)` | Done | Standard `+/` alphabet; `altchars` builds a custom-alphabet view |
+| `b64decode(data, altchars=None, validate=False)` | Done | `validate=False` default matches CPython |
+| `standard_b64encode`, `standard_b64decode` | Done | Aliases over the standard alphabet |
+| `urlsafe_b64encode`, `urlsafe_b64decode` | Done | `-_` alphabet |
+| `b16encode`, `b16decode(data, casefold=False)` | Done | Hex; uppercase output; `casefold=True` accepts lowercase on decode |
+| `b32encode(data)` | Done | RFC 4648 base32; all five padding remainders covered |
+| `b32decode(data, casefold=False, map01=None)` | Done | Strict by default; `casefold=True` accepts lowercase; `map01` maps `'0'`->`'O'` and `'1'`->`'I'` or `'L'` |
+| `encodebytes(data)` / `decodebytes(data)` | Done | MIME-style 76-char line wrap with trailing `\n`; decode passes through `b64decode` (lax) |
+| `bytes` / `bytearray` inputs | Done | Auto-converted via `__span__` (generated signature is `std::span<const uint8_t>`) |
+| `str` input on decoders (`b64decode`, `standard_b64decode`, `urlsafe_b64decode`, `b32decode`, `b16decode`) | Done | `@overload` delegating through `.encode()`; matches CPython which accepts ASCII str on decoders |
+| `BytesView` input | Partial | Works as C++ span but TPy-level coercion not yet tested |
+| `b85encode`/`b85decode`, `a85encode`/`a85decode` | Missing | Rare; separate ~100-LOC algorithms |
+| `memoryview` input | Blocked | Depends on `memoryview` builtin (see `builtins` section) |
+
+Tests: `cases/stdlib/base64`.
+
+### hashlib
+
+Current: `lib/tpy/hashlib.py` -- pure-TPy FIPS 180-4 port. Only SHA-256
+shipped so far; MD5/SHA-1/SHA-512 are mechanical follow-ups using the
+same class pattern (new H0/K constants, swap the round function,
+little-endian for MD5). Needed new shared primitives to get here:
+
+- `add_wrap`/`sub_wrap`/`mul_wrap` on all eight fixed-width int types
+  (Int8/16/32/64, UInt8/16/32/64) -- wrapping modular arithmetic,
+  analogous to Rust's `wrapping_add`. Signed variants route through the
+  unsigned type (`static_cast<intN_t>(static_cast<uintN_t>(a) OP ...)`)
+  to get defined wrap without signed-overflow UB.
+- `tpy.bits` module (`rotl32`/`rotr32`/`rotl64`/`rotr64`/`byteswap32`/
+  `byteswap64`) wrapping C++20 `std::rotl`/`std::rotr` and C++23
+  `std::byteswap`. Re-usable for ciphers, RNGs, `struct`, and
+  struct-of-ints packing beyond hashlib.
+
+| Item | Status | Notes |
+|---|---|---|
+| `sha256(data=None)` + `SHA256` class | Done | FIPS 180-4 algorithm, verified against NIST vectors + CPython |
+| `.update(data)`, `.digest()`, `.hexdigest()`, `.copy()` | Done | On `SHA256` |
+| `.digest_size`, `.block_size`, `.name` | Done | Instance attrs |
+| `md5`, `MD5` | Missing | Next slice; same pattern with little-endian state |
+| `sha1`, `SHA1` | Missing | Same pattern, 20-byte digest |
+| `sha512`, `SHA512` | Missing | Same pattern, 64-bit words -- needs UInt64 rotate + add_wrap (both already present) |
+| `blake2b`, `blake2s` | Missing | Pure TPy; Python has its own impl too |
+| `sha3_*`, `shake_*` | Missing | Later |
+| `new(name)` dispatcher | Missing | Returns a hash object by name; needs `type(x)`-style dispatch or a dict-of-factories |
+| `algorithms_available` / `algorithms_guaranteed` | Missing | Module-level `set[str]` / `frozenset[str]` |
+| Optional OpenSSL backend | Missing | Future; gated by F8 feature flag. Only justified by a perf-critical use case |
+
+Design note: `hashlib.sha256(data=None)` takes `bytes | None = None`
+instead of CPython's `b""` default because TPy sema rejects non-literal
+constant defaults (see BUGS.md "Default parameter value `b\"\"` rejected").
+Callers pass either nothing or bytes;
+behavior matches CPython.
+
+Tests: `cases/stdlib/hashlib`.
+
+### argparse
+
+Current: `lib/tpy/argparse.py` -- builder-trace macro (Phase 7 of the
+macro system; see `docs/MACRO_DESIGN.md`). The compiler walks the
+``ArgumentParser`` builder calls at compile time and synthesizes a
+per-call-site record + parse function, so ``args`` is statically typed.
+
+| Item | Status | Notes |
+|---|---|---|
+| Positional arguments | Done | Default str type |
+| Optional flags (`-x` / `--foo`) | Done | One or more aliases per add_argument |
+| `type=int\|float\|str` | Done | int maps to BigInt to match CPython |
+| `default=<literal>` | Done | Scalar literals plus list literals for list-typed actions (append/extend or store + nargs=*/+/<int>) |
+| `const=<literal>` | Done | For `store_const` and `store + nargs='?'` |
+| `action=` | Done | `store` / `store_true` / `store_false` / `count` / `append` / `extend` / `store_const` |
+| `nargs=` | Done | `'?'` / `'*'` / `'+'` / positive int. Variable nargs positionals must be last |
+| `choices=(...)` | Done | Macro-time literal sequence |
+| `required=True` | Done | Optional flags only |
+| `dest=` | Done | Override synthesized record field name |
+| `help=` (data) | Done | Stored at macro time |
+| `metavar=` | Done | Per-arg display name override for usage / help |
+| Optional[T] field for absent flag | Done | When no `default=` and not `required=` |
+| ArgumentParser `description=` | Done | |
+| `--help` / `-h` auto-generation | Done | Pre-rendered help printer + argv prelude that exits via `sys.exit(0)` |
+| `add_help=False` opt-out | Done | Suppresses both the auto printer and the `-h` / `--help` reservation, so users can register their own |
+| `prog=` / `usage=` / `epilog=` | Done | Help-text customization. `prog=` substitutes through usage and the `<prog>: error:` parse-error prefix; `usage=` overrides the auto-generated tail; `epilog=` appends after the options block |
+| **TODO**: runtime-derived `prog` default | Missing | CPython uses `os.path.basename(sys.argv[0])` when `prog=` is omitted; we hardcode `"prog"`. Closing this needs a `basename` helper in the TPy stdlib + switching the help printer from a pre-rendered literal to a runtime template. Tracked in MACRO_DESIGN.md's argparse Future Work |
+| **TODO**: terminal-width-aware help wrap | Missing | Help wraps at a hardcoded 80 cols; CPython argparse uses `shutil.get_terminal_size().columns` at runtime. The cpy-phase test pins `COLUMNS=80` so the comparison is deterministic, but a user running our binary in a 200-col terminal still sees help wrapped at 80 while CPython would wrap at 200. Pairs with the runtime-derived `prog` refactor -- both need the help printer to become a runtime template instead of a pre-rendered literal |
+| `type=Int32 / Int64 / UInt8 / ...` | Done | All eight fixed-width ints accepted; field carries the matching primitive |
+| `type=Float32` | Done | Field carries `Float32` (32-bit), parse uses `tpy::float32_from_str` (no Float64 round-trip). Default literals are wrapped in `Float32(...)` so the field type matches |
+| Subparsers | Done | `add_subparsers()` returns a sub-builder via `@builder_returns`; each `add_parser(name)` returns a sub-builder collecting its own arg specs. Top namespace lays per-sub fields out flat (`Optional[T]` per name, mirroring CPython argparse's Namespace shape) so portable test code reads `args.cmd` / `args.<sub-field>` under both backends. Honored kwargs: `dest=` (top field for the chosen subcommand name; default `"cmd"`), `required=`, `help=` (per-sub help text, rendered in --help). Macro-time errors: double `add_subparsers()`, top parser with positional args + subparsers (regex matcher gap), nested `add_subparsers()` in a sub-parser, sub-parser dest collision with a common arg or with `sp.dest`, same per-sub field name with conflicting types across subs. Limitations: typed-union escape hatch (``args._subcommand: A | B`` for `match`/`case`) intentionally not stored -- synth records carry the `__tpy_builder_` private prefix that user code can't reference, so the union would be unreachable for `match`/`case`. The pre-pass-6 builder-trace move (now landed) lifted the sema phasing wall that previously blocked emitting `@property` forwarders over the union; closing the rest needs reachability for the synth records plus per-sub forwarder emission alongside the flat fields. CPython divergence: TPy preemptively populates every per-sub field as `None` on the top namespace; CPython only sets attributes for the chosen sub. Tests using non-active per-sub fields therefore need `getattr(args, ..., None)` (or skip cpy phase) |
+| `add_mutually_exclusive_group()` | Missing | At-most-one constraint across flags |
+| Custom `type=<T>` via `from_arg` | Done | Duck-typed: any record with `@staticmethod from_arg(s: str) -> Self` can be passed as `type=`. Macro emits `T.from_arg(token)`; string defaults route through `from_arg` (mirrors CPython's "string defaults run through type="). All four nargs shapes plus `action=store/append/extend` work; required positional / required-flag fields land as plain `T` (not `Optional[T]`) via an accumulator + post-loop unwrap. Remaining gaps: `choices=` would have to compare unparsed tokens (CPython compares parsed values), and list defaults (`default=["a","b"]`) diverge from CPython too (CPython leaves list-default elements as raw strings) -- both stay rejected |
+| `parents=`, argument groups, `BooleanOptionalAction`, `allow_abbrev`, `fromfile_prefix_chars`, custom formatter classes, `action=<callable>` | Future | Tier-3; full tier table in MACRO_DESIGN.md's argparse Future Work section |
+| Parse-time error wording still differs from CPython | v1 divergence | Stderr+`sys.exit(2)` shape matches; runtime-derived `prog` (`os.path.basename(sys.argv[0])`) and message phrasing parity (e.g. "the following arguments are required") are Tier 2 |
+
+Tests: `cases/argparse/{basic,optional_flags,value_free_actions,list_and_const_actions,choices_required_dest,nargs,empty_parser,positional_nargs_optional,qualified_import,two_parsers_same_module,optional_list_absent,no_argv_uses_sys_argv,fixed_width_types,float32_type,custom_type,custom_type_list,custom_type_positional_nargs,help_basic,help_usage_wrap,explicit_sys_import,prog_epilog,usage_override,metavar,add_help_false,list_default,subparsers_basic,subparsers_common_arg,subparsers_optional,subparsers_help,subparsers_sub_positional,subparsers_sub_required_flag,subparsers_required_unify}` plus `error_argparse_*` cases pinning macro-time validation, `error_subparsers_*` cases (`double_call`, `top_positional`, `nested`, `dest_collide`, `no_subs`, `per_sub_collide_common`, `per_sub_type_conflict`) for subparser-specific validation, and `panic_argparse_*` / `panic_subparsers_*` cases for parse-error stderr+`sys.exit(2)` paths. Help-output cases that pass `prog=` explicitly (`prog_epilog`, `usage_override`, `help_usage_wrap`) run under both backends and assert byte-identical output vs CPython's stdlib argparse; the remaining help cases (`help_basic`, `metavar`) carry `no_cpython.txt` because their hardcoded `"prog"` default differs from CPython's `basename(sys.argv[0])`.
+
+### logging
+
+**Missing.** Needs module-level mutable state + handler/formatter architecture.
+
+### configparser
+
+**Missing.** Depends on `io`.
+
+### urllib.parse
+
+**Missing.** Pure-TPy candidate (no network dependency).
+
+### heapq
+
+Current: `lib/tpy/heapq.py` -- pure TPy over `list[T: Comparable]`. Mirrors
+CPython's algorithm (sift-up/sift-down) line-for-line; heap items ordered by
+`<`.
+
+| Item | Status | Notes |
+|---|---|---|
+| `heappush`, `heappop` | Done | |
+| `heapify` | Done | O(n) bottom-up construction |
+| `heappushpop` | Done | Push then pop in one step |
+| `heapreplace` | Done | Pop then push in one step |
+| `nsmallest(n, a)` | Done | Heap-based O(n + k log n). Takes `list[T]` (CPython accepts `Iterable[T]`). Body uses `a.copy()` which requires list semantics; a switch to `Iterable[T]` would need `list(a)` materialization plus a story for the empty-input generic-T case (CPython returns `[]`; TPy would error on T inference). Deferred to when empty-iterable generic inference is resolved |
+| `nlargest(n, a)` | Done | Sort-based O(n log n). Size-k-heap variant (O(n log k)) is a perf follow-up. Same `list[T]` vs `Iterable[T]` gap as `nsmallest` |
+| `merge(*iterables, key=None, reverse=False)` | Missing | N-way merge; needs a generator-based iterator-heads heap (variadic-in-method-call gap is now fixed) |
+| `key=` arg on `nlargest`/`nsmallest` | Missing | Needs `Callable[[T], K: Comparable]` threading; straightforward add once prioritized |
+
+Design note: CPython's `heapq` operates on any mutable sequence; TPy restricts
+to `list[T]` for now. Ref-type heaps work because (1) `heappush` / `heappushpop`
+/ `heapreplace` take `item: Own[T]` -- caller transfers ownership of the new
+element -- and (2) internal `_siftup` / `_siftdown` reads go through `copy()`
+(mirroring the `bisect.insort_left` pattern); users get explicit ownership
+and copy semantics for reference types. T must be copyable -- `@nocopy`
+element types fail at C++ compile time with a deleted-copy-constructor
+error today (clean sema diagnostic tracked in `BUGS.md`).
+
+Tests: `cases/stdlib/heapq`, `cases/stdlib/heapq_ref_type`.
+
+### copy
+
+**Missing.** `copy`/`deepcopy` need generic copy intrinsic. TPy has `copy()` builtin
+for value types; dataclass deep-copy would need macro-driven recursion similar to asdict.
+
+### textwrap
+
+**Missing.** Pure-TPy candidate.
+
+### decimal
+
+**Missing.** Large surface. Either bind `mpdecimal` or build pure TPy atop BigInt.
+
+### fractions
+
+**Missing.** Pure TPy over BigInt; small surface.
+
+### statistics
+
+**Missing.** Pure TPy (mean/median/mode/stdev/variance).
+
+### pickle
+
+**Blocked.** Needs runtime type info + `io`.
+
+### shelve
+
+**Blocked.** Needs pickle + dbm.
+
+### inspect
+
+**Blocked.** Needs runtime type/function introspection.
+
+### asyncio
+
+**Partial (v1).** Single-threaded executor + minimal viable surface. Design in [`docs/ASYNC_DESIGN.md`](ASYNC_DESIGN.md); status in [`docs/ASYNC_PROGRESS.md`](ASYNC_PROGRESS.md).
+
+Done in v1:
+
+- `asyncio.run(coro)` -- drives a top-level coroutine to completion; sleeps idle on the executor's timer min-heap; cancel-drains remaining spawned tasks at exit so `finally` runs for fire-and-forget tasks.
+- `asyncio.sleep(seconds)` -- registers a steady-clock deadline with the running executor; returns `Own[Task[None]]`.
+- `asyncio.create_task(coro())` -- registers an async-def call with the running executor and returns `Own[Task[T]]` (T inferred from the async def's return type) sharing state with the executor's task slot.
+- `asyncio.Future[T]` -- single-awaiter manual-completion awaitable (`set_result(value)` / `set_exception(exc)` / `done()`); ownership-transfer API on `set_result` so nocopy types flow through. `Future[None]` is currently unusable (void-payload template substitution issue, BUGS.md); use `Event` for no-payload completion signals.
+- `asyncio.Event` -- boolean completion signal (`set` / `clear` / `is_set` / directly awaitable). The no-payload analog of `Future[T]`. CPython parity for the API surface; TPy diverges in that `await event` works directly (CPython requires `await event.wait()`) because TPy can't yet define `async def` methods on classes. Single-awaiter v1.
+- `asyncio.CancelledError` -- raised at the next suspension point of a cancelled task; thread through `try`/`finally`.
+- `Executor` body (slot table for parked tasks with `(slot_id, generation)` wakers, runnable deque, timer min-heap keyed on steady-clock deadlines) lives in TPy at `lib/tpy/asyncio/_executor.py`. `Executor` inherits the `@dynamic Awaker` protocol; `Waker.wake()` dispatches through that vtable. `runtime/cpp/include/tpy/async.hpp` carries two pieces: `CancelledError` and the `poll_with_cancel` resume-case helper template (M8) -- no FFI dispatch shell.
+
+v1.5 M3-M6: SHIPPED. Awaits inside arbitrary control flow (`if`/`while`/`for`/`with` sub-bodies + `try`/`except`/`finally` around awaits) via a localized CFG (`tpyc/codegen_cpp/resumable_cfg.py`). `async with` (cleanup-only) and `async for` (with `StopAsyncIteration`) shipped on top of the same machinery. See `docs/ASYNC_PROGRESS.md` for the milestone-by-milestone summary.
+
+v1.5 M8: SHIPPED. `asyncio.wait_for(coro, timeout) -> T` (`async def` free function) + built-in `TimeoutError`. Pumps inner cleanup through `finally`-with-await on deadline; outer cancellation propagates through to the inner coroutine (the auto-emitted resume-case cancel-check now calls `cancel()` on the in-flight sub-coro before polling, so the inner observes `CancelledError` at its suspension point and can run cleanup before the cancellation surfaces). The async-def codegen path was extended in M8 to handle `Own[Awaitable[T]]`-shaped params via a deduced `T_<pname>` extra template arg with the protocol concept constraint, mirroring the existing non-async pattern. Caller-side sub-coro field declarations use `std::remove_cvref_t<decltype(arg)>` to deduce the concrete coro type without sema knowing it.
+
+v1.5 M9: SHIPPED. Two homogeneous entrypoints sharing one `_GatherFuture[T]` engine: `asyncio.gather(*tasks: Task[T]) -> list[T]` (variadic-positional, a sync factory returning the awaitable directly) and `asyncio.gather_list(tasks: list[Task[T]]) -> list[T]` (the list-shaped form). Both run N already-spawned tasks concurrently and collect their results in input order; on the first sub-task failure (or outer cancel) propagate `cancel()` to siblings, drain to settlement, then re-raise the first exception observed. The CPython-shape *heterogeneous* form `gather[*Ts](*coros) -> tuple[*Ts]` remains deferred (blocked on variadic generics + the async-def `*args` codegen gap; see TODO.md / BUGS.md). Implementation: hand-written `_GatherFuture[T]` Rc-clones each task handle into an owned list via a new `Task[T].clone()` method.
+
+Pending (v1.5): CPython-shape *heterogeneous* variadic `gather`, partial / nested try-around-await (see BUGS.md for the specific CFG-build limits).
+
+v1.5 M1: SHIPPED. Sync `with` upgraded to CPython-shape `__exit__(self, exc_type, exc_val, exc_tb) -> bool | None`; `bool` return suppresses, `None` is cleanup-only. Class-based exception dispatch via `isinstance(exc_val, X)` is deferred to M2 (blocked on `Optional[BaseException]` slicing -- see `BUGS.md`).
+
+Pending (v2+): I/O reactor (epoll on Linux, kqueue on BSD/macOS, IOCP on Windows), `asyncio.Queue`, async generators, `@error_return` async, `__await__` adaptation, multi-thread executor.
+
+v1.1 runtime port: SHIPPED. Executor body + `Task` + `Future` moved from `runtime/cpp/include/tpy/async.hpp` to `lib/tpy/asyncio/_executor.py`, dispatched from C++ via a thread-local `ExecutorOps` function-pointer table.
+
+v1.2: SHIPPED in seven steps. Step 1 added `val_or_ref_t<void>` and ported `asyncio.run` from a C++ template shell to pure TPy. Step 2 added `@cpp_template` auto-move for `Own[T]` args. Step 3 consolidated value-type emission ordering and timer-heap cleanup. Step 4 moved the type-erasure stack (`Task[T]` / `TaskState[T]` / `AnyTask` / `AnyTaskBox`) to TPy via `@dynamic` protocols. Step 5 moved `Poll[T]` itself -- a single `@nocopy class Poll[T]` body covers what the C++ `Poll<T>` + `Poll<void>` + `Poll<T&>` specializations did (storage is `UninitArrayStorage[T, 1] + bool`; void analog rides on `Poll[None]` -> `Poll<std::monostate>`; the reference-T specialization was never instantiated by generated code). Step 6 shrank `async.hpp` by 50 lines (TLS removal + struct/helper moves to TPy) and consolidated `ExecutorHandle` next to `Waker`. Step 7 pivoted dispatch from the C++ `ExecutorOps` function-pointer table to the `@dynamic Awaker` protocol: `Waker` became a pure-TPy `ValueType` holding `Ptr[Awaker]`, `Executor` inherits `Awaker`, and `async.hpp` collapsed to just `CancelledError`. See [`docs/ASYNC_PROGRESS.md`](ASYNC_PROGRESS.md#v1x-milestone-asyncio-runtime-tpy-port-must-precede-v15) for the phase-by-phase history.
+
+### threading
+
+**Blocked** on threading primitives.
+
+### multiprocessing
+
+**Blocked** on process spawning.
+
+### subprocess
+
+**Blocked** on process spawning.
+
+### socket
+
+**Partial.** Pure-TPy facade in `lib/tpy/socket.py` over raw `@native`
+bindings in `lib/tpy/_bindings/posix_socket.py`. One out-of-line C++ helper
+in `runtime/cpp/src/stdlib/socket_impl.cpp` for DNS resolution
+(getaddrinfo walks a `struct addrinfo` whose field order isn't portable
+between Linux and BSD/macOS, so the struct walking lives on the C++ side
+where `<netdb.h>` is available).
+
+Phase 1 ships a working IPv4 TCP client/server shape sufficient for the
+"simple socket client / simple socket server" milestone in the project
+roadmap. Phase 2 is non-blocking I/O + `selectors`. Phase 3 is TLS/ssl.
+Phase 4 is `http.client` (pure TPy). Phase 5 is websocket client.
+
+Architecture (mirrors the re / PCRE2 split):
+
+  * `runtime/cpp/include/tpy/stdlib/socket_h.hpp` -- ABI-glue header.
+    Forward-declares `struct sockaddr_in` (POSIX-stable 16-byte layout)
+    with `static_assert` guards on size + field offsets, plus
+    `extern "C"` decls of libc socket/bind/connect/... and our three
+    runtime helpers. Deliberately does NOT include `<sys/socket.h>` /
+    `<netdb.h>` -- those headers `#define` macros (`AF_INET`, `SOCK_STREAM`,
+    ...) that would collide with TPy module-level constants of the same
+    name.
+  * `runtime/cpp/src/stdlib/socket_impl.cpp` -- implements
+    `tpy_resolve_ipv4(const uint8_t*, uint64_t, uint8_t[4])`,
+    `tpy_errno()`, `tpy_last_resolve_error()`. Includes the system
+    headers freely; isolated to its own TU so macros don't escape.
+    First inhabitant of `runtime/cpp/src/` (new runtime-lib convention
+    -- see "C++ helper convention" above).
+  * `lib/tpy/_bindings/posix_socket.py` -- pure `@native` 1:1 bindings over
+    the libc C ABI + the three runtime helpers. `@native(binding="C")
+    class SockaddrIn` mirrors the struct for typed field access.
+  * `lib/tpy/socket.py` -- facade. `Socket` class (`@nocopy`, RAII via
+    `__del__` closing the fd), SocketError, constants, create_connection
+    / create_server, gethostbyname, with-statement support.
+
+| Item | Status | Notes |
+|---|---|---|
+| `Socket(family, type, proto)` | Done | `@nocopy`, RAII close in `__del__`. Use `Socket(AF_INET, SOCK_STREAM)` or `create_connection` / `create_server`; a CPython-style module-level `socket()` factory is a future addition |
+| `bind`, `connect`, `listen`, `accept` | Done | `accept() -> tuple[Own[Socket], tuple[str, Int32]]` matches CPython's `(conn, (host, port))` shape |
+| `send`, `sendall`, `recv` | Done | `send` returns `Int32` (truncated from `ssize_t`); realistic per-call sends are well under 2 GiB. `recv` returns a fresh `bytes` |
+| `close`, `shutdown`, `fileno` | Done | |
+| `setsockopt_int` | Done | Int-valued options only; struct options (`SO_RCVTIMEO`, `SO_LINGER`) deferred |
+| `getsockname`, `getpeername` | Done | Return `tuple[str, Int32]` |
+| `gethostbyname` | Done | Resolves via `getaddrinfo` behind `tpy_resolve_ipv4`; returns the first A record only |
+| `create_connection`, `create_server` | Done | TCP client/server convenience factories; `create_server` bundles SO_REUSEADDR + bind + listen |
+| `with socket(...) as s:` | Done | `__enter__` returns self, `__exit__` closes |
+| `SocketError` | Done | Wraps errno + strerror. `except socket.SocketError` blocked by qualified-except-clause gap; use `from socket import SocketError` |
+| Constants (`AF_INET`, `SOCK_STREAM`, `SOL_SOCKET`, ...) | Done | Linux glibc values hardcoded. macOS/BSD values differ -- deferred |
+| `socketpair()` | Done | Defaults to `AF_UNIX` + `SOCK_STREAM`; returns `tuple[Own[Socket], Own[Socket]]` |
+| IPv6 / `AF_INET6` | Missing | Needs `SockaddrIn6` binding |
+| `AF_UNIX` | Missing | Needs `SockaddrUn` binding |
+| `sendto`, `recvfrom`, `recv_into` | Missing | UDP out-addr + recv-into-caller-buffer variants |
+| `setblocking`, `settimeout` | Missing | Non-blocking I/O belongs with Phase 2 `selectors` |
+| `getaddrinfo` (full API) | Missing | Flat `tpy_resolve_ipv4` only today; multi-result walk needs typed records |
+| `makefile()` | Missing | Needs io module to grow "adopt this fd" |
+| Windows (Winsock2) | Missing | `SOCKET` unsigned, `WSAStartup`, `closesocket`, `WSAGetLastError` -- all in `#ifdef _WIN32` block inside socket_impl.cpp once we have Windows CI |
+| TLS (`ssl` module) | Missing | Phase 3; needs mbedTLS vendored |
+
+Tests:
+  * No integration test cases under `tests/cases/` -- running real client/
+    server end-to-end needs threading or fork (not in Phase 1), and
+    fingerprint-based skip logic doesn't play well with network ports.
+  * Examples under `examples/net/` (`tcp_client.py` + `tcp_server.py`)
+    serve as manual smoke tests: run the server in one terminal, the
+    client in another, verify the echo round-trip.
+
+### http.client
+
+**Blocked** on TLS (phase 3) for HTTPS; HTTP-over-socket would build on
+Phase 1's `socket` today but makes limited sense without TLS. Slated
+for Phase 4 per the network roadmap discussion.
+
+### urllib.request
+
+**Blocked** on http.
+
+---
+
+## Adjacent: NumPy / Numeric Computing (parked)
+
+Not CPython stdlib, but tracked here to keep it in sight. Not on the near-term
+plan. A separate design doc (`NUMERIC_COMPUTING.md`) will spin off when this
+becomes active.
+
+**Key realization**: numpy itself is not wrappable. The Python object layer
+(`np.array`, `arr.shape`, methods) and the C API (`PyArray_*`) are hard-coupled
+to CPython's refcounting + GIL + PyObject machinery. A natively-compiled TPy
+runtime can't host that.
+
+**However, the low-level pieces people assume are "numpy" mostly aren't**:
+
+| Layer | Wrappable from TPy? | What it actually is |
+|---|---|---|
+| Python object layer | No | Numpy's own, CPython-coupled |
+| C API (`PyArray_*`) | No | Numpy's own, CPython-coupled |
+| Ufunc dispatch / `NpyIter` broadcasting | Theoretically; not packaged as a standalone lib | Numpy's own |
+| Element-wise kernel loops | Theoretically; template-generated, not shipped as reusable | Numpy's own |
+| **BLAS / LAPACK / OpenBLAS / MKL** (linear algebra) | **Yes** | Upstream Fortran/C libs; ABI-stable; numpy just wraps them |
+| **pocketfft** (FFT) | **Yes** | ~2k LOC C++, MIT, header-only, upstream repo exists; numpy vendors it |
+| **sleef** (SIMD transcendentals) | **Yes** | Upstream C lib |
+
+So the "wrap numpy's low-level building blocks" idea collapses into **wrap the
+things numpy itself wraps** -- which are CPython-independent upstream libs we
+can bind directly via the thin-binding pattern. Gets us the raw compute for
+free.
+
+**The container + broadcasting layer is ours to build** regardless. NumPy's
+view/refcount model doesn't fit TPy's ownership/borrow model; a
+reimplementation is mandatory.
+
+### Candidate backends for the ndarray container
+
+| Option | What it is | License | Fit |
+|---|---|---|---|
+| **xtensor** | Header-only C++ "numpy for C++, Python-free". `xt::xarray<T>`, broadcasting, lazy expressions, ufuncs, BLAS/LAPACK bindings | BSD-3 | **Strongest candidate** -- explicitly designed for this use case; matches numpy's API style; years of optimization work already done |
+| **Eigen** | Header-only C++ linear algebra (matrices, decompositions) | MPL2 | Good for linalg specifically; less numpy-shaped than xtensor |
+| **ArrayFire** | GPU-capable numeric library | BSD-3 | Relevant if GPU is ever in scope |
+| **blitz++** | Older C++ numeric library with expression templates | Artistic/LGPL | Historical; less active than xtensor |
+| **Pure TPy + `Span[T]` / `Array[T, N]`** | Build our own | -- | Maximum control; maximum work. Pressure-tests language features (multi-dim arrays, broadcasting via operator overloads, SIMD intrinsics, bounds-check elision) |
+
+Most likely path: prototype **xtensor-backed** and **pure-TPy** options side-
+by-side for the same small API subset (1D/2D dense, element-wise, reductions,
+slicing), benchmark, pick.
+
+### Strategy sketch
+
+- **Phase 0 (now)**: parked. Keep this section up to date as thinking
+  evolves; don't build.
+- **Phase 1**: `tplib.ndarray` -- numpy-*style*, not numpy-compat. 1D/2D
+  dense arrays, element-wise ops, reductions, basic slicing. Backend: TBD
+  (xtensor vs own). Bind BLAS for linalg separately.
+- **Phase 2**: N-D, broadcasting, fancy indexing, dtype system, FFT
+  (pocketfft binding).
+- **Phase 3 (maybe never)**: a `numpy`-named CPython-compat shim over
+  `tplib.ndarray`. Document gaps honestly. Only justified if the shim gets
+  close enough to real numpy that users can flip a switch.
+
+### Other angles worth remembering
+
+- **At compile time, macros run under CPython** -- so a macro like
+  `@np_table` can freely use real numpy to compute lookup tables, validate
+  shapes, or generate specialized kernels that get embedded in the binary.
+  Narrow but real use case, and it's available today without any runtime
+  numpy support.
+- **Nobody has pulled off full numpy compat in a compiled Python.** Codon
+  ships a partial numpy-like lib under its own namespace. PyPy's
+  `micronumpy` is partial and most users fall back to CPython numpy via
+  `cpyext`. Cython/Nuitka/mypyc don't reimplement -- they use real numpy
+  because they run on CPython. The honest precedent is "numpy-style
+  subset", not "numpy-compat".