rapydscript-ns 0.9.3 → 0.9.5

package/PYTHON_GAPS.md

@@ -5,6 +5,9 @@ or behave differently in RapydScript-NS, with a focus on what is relevant and us
 browser context. Server-side features (file I/O, subprocesses, sockets, threading, etc.)
 are excluded as they do not apply.
 
+Items that are fully supported — even if only behind a flag — are not listed here. See the
+README for the full feature and module support tables.
+
 ---
 
 ## 1. Silent Behavioral Differences (Gotchas)
@@ -12,23 +15,7 @@ are excluded as they do not apply.
 These features exist but behave differently from Python in ways that will silently produce
 wrong results — no error is raised.
 
-### 1.1 `%` Modulo on Negative Numbers *(partially resolved)*
-
-**Python:** `%` always returns a non-negative result (true modulo).
-```python
--7 % 3   # → 2  (Python)
--7 % 3   # → -1 (RapydScript default — JS remainder semantics)
-```
-**Status:** Fixed when using `from __python__ import overload_operators` or
-`from __python__ import python_modulo`. In bare mode (no flags) the JS remainder semantics
-still apply.
-
-**Impact:** Any algorithm relying on modular arithmetic (wrapping, circular indexing) may
-produce wrong results in code that does not use the Python operator flags.
-
----
-
-### 1.2 `is` / `is not` — Identity vs. Equality
+### 1.1 `is` / `is not` — Identity vs. Equality
 
 **Python:** `is` tests object identity (pointer comparison).
 **RapydScript:** `is` compiles to `===` (strict equality), so `x is y` is true whenever
@@ -48,43 +35,7 @@ The recommended pattern — using a unique sentinel object — works correctly.
 
 ---
 
-### 1.3 Function Arguments: `TypeError` on Wrong Count *(opt-in, not default)*
-
-**Python:** Too few or too many positional arguments raises `TypeError` at call time.
-**RapydScript default:** Extra args are silently discarded; missing args become `undefined`.
-
-```python
-def f(a, b):
-    return a + b
-
-f(1, 2, 3)   # Python: TypeError. RapydScript default: silently returns 3
-f(1)         # Python: TypeError. RapydScript default: returns NaN (1 + undefined)
-```
-**Status:** Argument count and type-annotation enforcement is now available via the
-`type_enforce` flag on function definitions (emits runtime checks). Not enabled by default
-because it adds overhead to every call. Developers writing library code with strict APIs
-should opt in.
-
----
-
-### 1.4 Positional-Only and Keyword-Only Parameters Not Enforced
-
-**Python:** Positional-only params (`/`) cannot be passed by keyword; keyword-only params
-(`*`) cannot be passed positionally. Both raise `TypeError` on violations.
-**RapydScript:** Violations are silently discarded — the param gets `undefined` with no error.
-
-```python
-def f(a, b, /, *, c):
-    return a + b + c
-
-f(1, b=2, c=3)   # Python: TypeError (b is positional-only)
-                  # RapydScript: b silently becomes undefined, a=1, c=3
-```
-**Impact:** API design contracts expressed via param ordering are not enforced.
-
----
-
-### 1.5 String Encoding — UTF-16 Surrogate Pairs
+### 1.2 String Encoding — UTF-16 Surrogate Pairs
 
 **Python:** Strings are sequences of Unicode code points (full 21-bit range).
 **RapydScript:** Strings are JS strings — UTF-16. Emoji and other non-BMP characters
@@ -103,7 +54,7 @@ produce wrong lengths or corrupt characters when sliced.
 
 ---
 
-### 1.6 `global` Scoping in Nested Functions
+### 1.3 `global` Scoping in Nested Functions
 
 **Python:** `global x` inside a nested function forces `x` to refer to the module-level
 variable, bypassing any intermediate closure scopes.
@@ -115,7 +66,7 @@ scope silently.
 
 ---
 
-### 1.7 Numeric Dict Keys Are Coerced to Strings
+### 1.4 Numeric Dict Keys Are Coerced to Strings
 
 **Python:** `d = {}; d[1] = 'a'; d['1'] = 'b'; len(d) == 2` (integer and string keys distinct).
 **RapydScript:** The Python `dict` type (backed by ES6 `Map`) stores them distinctly, but
@@ -126,17 +77,7 @@ when interoperating with JS APIs that return plain objects.
 
 ---
 
-### 1.8 `Exception.args` vs `.message`
-
-**Python:** `Exception('msg').args == ('msg',)` and `.message` is not a standard attribute.
-**RapydScript:** `.message` is the primary attribute (JS `Error` convention). `.args` is
-not populated as a tuple with the message.
-
-**Impact:** Code accessing `.args[0]` to get the error message will get `undefined`.
-
----
-
-### 1.9 Multiple Inheritance MRO
+### 1.5 Multiple Inheritance MRO
 
 **Python:** C3 linearization guarantees a deterministic and consistent method resolution order.
 **RapydScript:** Built on the JS prototype chain. In diamond inheritance or complex hierarchies
@@ -149,18 +90,7 @@ name. Hard to debug because no error is raised.
 
 ## 2. Missing Language Features
 
-### 2.1 `__slots__` Not Enforced
-
-`__slots__ = ['x', 'y']` is parsed and accepted but has no runtime effect — arbitrary
-attributes can still be set on instances. No `AttributeError` is raised for assignments to
-undeclared attributes.
-
-**Browser relevance:** Used frequently for memory efficiency and API documentation. Enforcement
-via `Object.seal()` or a `Proxy`-based guard would be possible in modern browsers.
-
----
-
-### 2.2 `__del__` Destructor — No Guaranteed Finalizer
+### 2.1 `__del__` Destructor — No Guaranteed Finalizer
 
 `__del__` methods are not called reliably. JavaScript's GC is non-deterministic and provides
 no equivalent to CPython's reference-counting finalizer.
@@ -173,15 +103,17 @@ that timing is not guaranteed.
 
 ---
 
-### 2.3 `locals()` Always Returns Empty Dict
+### 2.2 `locals()` Always Returns Empty Dict
 
-JavaScript provides no mechanism to introspect local variables at runtime. `locals()` always
-returns an empty dict. Python code that uses `locals()` for string template substitution
+`vars()`, `locals()`, and `globals()` all exist as builtins. JavaScript provides no mechanism
+to introspect local variables at runtime, so `locals()` always returns an empty dict.
+`globals()` works on module-level/global state, and `vars(obj)` introspects the passed object.
+Python code that uses `locals()` for string template substitution
 (e.g., `'{x}'.format(**locals())`) will break silently.
 
 ---
 
-### 2.4 `from module import *` Not Allowed
+### 2.3 `from module import *` Not Allowed
 
 Star imports are intentionally unsupported to prevent namespace pollution. Python developers
 who rely on them (e.g., `from math import *`) must enumerate imports explicitly.
@@ -190,13 +122,15 @@ who rely on them (e.g., `from math import *`) must enumerate imports explicitly.
 
 ---
 
-### 2.5 `asynccontextmanager` Not Available
+### 2.4 `asynccontextmanager` Not Available
 
 `contextlib.asynccontextmanager` is absent. Only synchronous `@contextmanager` is implemented.
+`async with` itself is also not supported — async context managers need `.acquire()`/`.release()`
+calls instead.
 
 ---
 
-### 2.6 f-string Debugging Format `f'{x=}'` Not Supported
+### 2.5 f-string Debugging Format `f'{x=}'` Not Supported
 
 Python 3.8+ supports `f'{x=}'` which expands to `f'x={repr(x)}'`. This is not implemented.
 
@@ -207,7 +141,7 @@ print(f'{x=}')   # Python: "x=42". RapydScript: syntax error or wrong output
 
 ---
 
-### 2.7 Ellipsis Evaluates to `undefined`
+### 2.6 Ellipsis Evaluates to `undefined`
 
 `...` (Ellipsis) parses as a valid expression but evaluates to JS `undefined` rather than
 Python's `Ellipsis` singleton object. Code that stores `...` in containers or checks
@@ -219,26 +153,35 @@ Python's `Ellipsis` singleton object. Code that stores `...` in containers or ch
 
 These are absent from `src/lib/` and have no substitute.
 
-### 3.1 `decimal` — Decimal Arithmetic
+### 3.1 `enum.IntEnum`, `IntFlag`, and `Flag`
 
-`Decimal` arithmetic avoids floating-point rounding errors. Essential for financial
-calculations in browser apps (e-commerce, budgeting tools). JS does not have a built-in
-equivalent; a pure-JS implementation would need to be compiled in.
+The `enum` module provides `Enum` but not `IntEnum` (auto-comparable with integers),
+`StrEnum` (Python 3.11+), `IntFlag`, or `Flag` (bitfield enums). These are common in protocol
+implementations, permission systems, and state machines.
+
+```python
+from enum import IntEnum
+class Color(IntEnum):
+    RED = 1
+    GREEN = 2
+Color.RED < Color.GREEN   # True — comparison with int semantics
+```
 
 ---
 
-### 3.2 `fractions` — Rational Arithmetic
+### 3.2 `hashlib` — Cryptographic Hashing
 
-`Fraction(numerator, denominator)` with full arithmetic. Useful for music theory apps,
-math tutoring tools, and any domain requiring exact rational computation.
+`hashlib.sha256`, `hashlib.md5`, etc. The Web Crypto API provides `crypto.subtle.digest`
+but its async/buffer-based interface is awkward. A thin `hashlib`-compatible wrapper over
+`crypto.subtle` with a synchronous-friendly API (using the sync `crypto.getRandomValues`)
+for non-cryptographic hashes would be valuable.
 
 ---
 
-### 3.3 `statistics` — Statistical Functions
+### 3.3 `fractions` — Rational Arithmetic
 
-`mean`, `median`, `mode`, `stdev`, `variance`, `quantiles`. Very commonly needed in
-data-visualization browser apps. Currently `numpy` covers much of this but `statistics`
-is lighter-weight and doesn't require the full numpy import.
+`Fraction(numerator, denominator)` with full arithmetic. Useful for music theory apps,
+math tutoring tools, and any domain requiring exact rational computation.
 
 ---
 
@@ -249,42 +192,11 @@ for browser-based code editors, version comparison tools, and fuzzy matching UIs
 
 ---
 
-### 3.5 `pprint` — Pretty Printing
-
-`pprint.pformat` / `pprint.pprint`. Primarily a debugging/REPL aid. Given the in-browser
-REPL in this project, implementing `pprint` would make output more readable.
-
----
+### 3.5 `decimal` — Decimal Arithmetic
 
-### 3.6 `hashlib` — Cryptographic Hashing
-
-`hashlib.sha256`, `hashlib.md5`, etc. The Web Crypto API provides `crypto.subtle.digest`
-but its async/buffer-based interface is awkward. A thin `hashlib`-compatible wrapper over
-`crypto.subtle` with a synchronous-friendly API (using the sync `crypto.getRandomValues`)
-for non-cryptographic hashes would be valuable.
-
----
-
-### 3.7 `enum.IntEnum` and `enum.Flag`
-
-The `enum` module provides `Enum` but not `IntEnum` (auto-comparable with integers),
-`StrEnum` (Python 3.11+), or `Flag` (bitfield enums). These are common in protocol
-implementations, permission systems, and state machines.
-
-```python
-from enum import IntEnum
-class Color(IntEnum):
-    RED = 1
-    GREEN = 2
-Color.RED < Color.GREEN   # True — comparison with int semantics
-```
-
----
-
-### 3.8 `collections.ChainMap`
-
-`ChainMap` provides a multi-level dict lookup (like layered config or scope chains) without
-copying. Not currently in `collections.pyj`.
+`Decimal` arithmetic avoids floating-point rounding errors. Essential for financial
+calculations in browser apps (e-commerce, budgeting tools). JS does not have a built-in
+equivalent; a pure-JS implementation would need to be compiled in.
 
 ---
 
@@ -404,17 +316,15 @@ The `jstype()` builtin is the RS equivalent of JS's `typeof`.
 
 ## 5. Summary Priority Table
 
+Priority weighs frequency-of-need, effort-to-implement, and whether a workaround exists.
+
 | Priority | Feature | Effort | Impact |
 |---|---|---|---|
-| High | `enum.IntEnum`, `Flag` | Medium | Protocol and permission modeling |
-| High | `statistics` module | Low | Data analysis without full numpy import |
-| Medium | `pprint` module | Low | REPL output quality |
-| Medium | `collections.ChainMap` | Low | Multi-level scope/config dicts |
-| Medium | f-string `f'{x=}'` debugging format | Low | Developer experience |
-| Medium | `__slots__` enforcement via `Proxy` | Medium | Memory + API documentation |
+| High | `enum.IntEnum`, `IntFlag`, `Flag` | Medium | Protocol and permission modeling; bitfield enums |
+| Medium | `hashlib` shim over Web Crypto | Medium | Avoids verbatim Web Crypto calls in user code |
 | Medium | `fractions` module | Medium | Exact rational arithmetic |
-| Medium | `hashlib` shim over Web Crypto | Medium | Hashing without verbatim JS |
-| Low | `decimal` module | High | Financial calculations |
-| Low | `difflib` module | High | Text diff, fuzzy matching |
-| Low | `asynccontextmanager` | Medium | Async resource management |
+| Medium | f-string `f'{x=}'` debugging format | Low | Developer experience |
+| Low | `asynccontextmanager` + `async with` | Medium | Async resource management |
 | Low | `__del__` via `FinalizationRegistry` | Medium | Resource cleanup (best-effort) |
+| Low | `difflib` module | High | Text diff, fuzzy matching |
+| Low | `decimal` module | High | Financial calculations |

package/README.md

@@ -1381,19 +1381,28 @@ ba += bytearray([7, 8])       # in-place concatenation
 
 RapydScript provides a `long` builtin backed by JavaScript's native `BigInt`,
 giving you arbitrary-precision integers beyond the safe range of JS `Number`.
+You can use the `long()` function or Python-style `n` suffix literals:
 
 ```python
+# Literal syntax (preferred)
+a = 10n
+b = 3n
+c = 0xFFn        # hex
+d = 0b1010n      # binary
+e = 0o77n        # octal
+
+# Function syntax
 a = long(10)
 b = long(3)
 
-a + b           # long(13)
-a - b           # long(7)
-a * b           # long(30)
-a // b          # long(3)   — floor division (Python semantics, not JS truncation)
-a % b           # long(1)   — Python-style modulo (result has same sign as divisor)
-a ** b          # long(1000)
-long(-7) // long(2)   # long(-4)  — floors toward −∞ (JS BigInt would give −3)
-long(-7) % long(3)    # long(2)   — result matches sign of divisor
+a + b           # 13n
+a - b           # 7n
+a * b           # 30n
+a // b          # 3n    — floor division (Python semantics, not JS truncation)
+a % b           # 1n    — Python-style modulo (result has same sign as divisor)
+a ** b          # 1000n
+long(-7) // long(2)   # -4n  — floors toward −∞ (JS BigInt would give −3)
+long(-7) % long(3)    # 2n   — result matches sign of divisor
 ```
 
 #### Precision beyond JS Number
@@ -1402,9 +1411,13 @@ The main motivation for `long` is numbers outside the safe integer range of
 JavaScript `Number` (`2^53 − 1 = 9007199254740991`):
 
 ```python
-n = long('9007199254740993')  # 2^53 + 1 — cannot be represented as a JS Number
-str(n)                        # '9007199254740993'  (exact)
-str(n + long(1))              # '9007199254740994'  (still exact)
+n = 9007199254740993n   # 2^53 + 1 — cannot be represented as a JS Number
+str(n)                  # '9007199254740993'  (exact)
+str(n + 1n)             # '9007199254740994'  (still exact)
+
+# equivalent using long():
+n = long('9007199254740993')
+str(n + long(1))
 ```
 
 #### Operator overloading
@@ -3299,16 +3312,26 @@ finally:
     cleanup()
 ```
 
+Like Python, exceptions accept variadic arguments stored in `.args`:
+
+```py
+e = ValueError('bad input', 42)
+print(e.args)       # ['bad input', 42]
+print(e.args[0])    # 'bad input'
+print(e.message)    # 'bad input' (first arg, for JS Error compatibility)
+```
+
 You can create your own Exception classes by inheriting from `Exception`, which
 is the JavaScript Error class, for more details on this, see the [MDN documentation](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error).
 
 ```py
 class MyError(Exception):
-	def __init__(self, message):
-		self.name = 'MyError'
-		self.message = message
+	def __init__(self, code, detail):
+		Exception.__init__(self, code, detail)
+		self.code = code
+		self.detail = detail
 
-raise MyError('This is a custom error!')
+raise MyError(404, 'not found')
 ```
 
 You can catch multiple exception types in one `except` clause. Both the comma form and the tuple form are supported:
@@ -3455,7 +3478,7 @@ One of Python's main strengths is the number of libraries available to the devel
 	                    # fields(), asdict(), astuple(), replace(), is_dataclass(), frozen=True, order=True
 	abc                 # ABC base class, @abstractmethod, Protocol, @runtime_checkable;
 	                    # abstract enforcement at instantiation; ABC.register() virtual subclasses
-	collections         # namedtuple, deque, Counter, OrderedDict, defaultdict
+	collections         # namedtuple, deque, Counter, OrderedDict, defaultdict, ChainMap
 	copy                # copy (shallow), deepcopy; honours __copy__ / __deepcopy__ hooks
 	typing              # TYPE_CHECKING, Any, Union, Optional, List, Dict, Set, Tuple, TypeVar,
 	                    # Generic, Protocol, Callable, Literal, Final, TypedDict, NamedTuple,
@@ -3465,6 +3488,8 @@ One of Python's main strengths is the number of libraries available to the devel
 	                    # product, permutations, combinations, combinations_with_replacement
 	io                  # StringIO (in-memory text stream), BytesIO (in-memory binary stream)
 	base64              # b64encode/decode, urlsafe_b64encode/decode, b32encode/decode, b16encode/decode, encodebytes/decodebytes
+	statistics          # mean, median, mode, variance, stdev, quantiles, correlation,
+	                    # linear_regression, NormalDist
 
 For the most part, the logic implemented in these libraries functions identically to the Python versions. I'd be happy to include more libraries, if other members of the community want them. However, unlike most other Python-to-JavaScript compilers, RapydScript doesn't need them to be complete since there are already tons of available JavaScript libraries that it can use natively.
 
@@ -3998,6 +4023,7 @@ Python Feature Coverage
 | `super()` — 0-arg and 2-arg forms                                                                                                                                                                                                                             | `super().method()` and `super(Cls, self).method()` both work |
 | `except TypeA, TypeB as e:`                                                                                                                                                                                                                                   | RapydScript comma-separated form; catches multiple exception types |
 | `except (TypeA, TypeError) as e:`                                                                                                                                                                                                                             | Tuple form also supported |
+| `Exception.args` variadic constructor                                                                                                                                                                                                                          | `Exception('a', 'b').args == ['a', 'b']`; `.message` set to first arg for JS compatibility; works on all builtin and custom exception subclasses |
 | `except*` / `ExceptionGroup` (Python 3.11+)                                                                                                                                                                                                                   | Full support: `ExceptionGroup` class with `subgroup()`/`split()`; `except*` dispatches to typed handlers, re-raises unmatched; bare `except*:` catches all remaining |
 | `try / else`                                                                                                                                                                                                                                                  | `else` block runs only when no exception was raised |
 | `for / else`                                                                                                                                                                                                                                                  | `else` block runs when loop completes without `break`; nested break isolation works |
@@ -4044,6 +4070,7 @@ Python Feature Coverage
 | f-strings, `str.format()`, `format()` builtin, all common `str.*` methods                                                                                                                                                                                     | Fully supported; includes `f'{x=}'` debug format (prints `x=<value>`), format-spec (`f'{x=:.2f}'`), and conversion (`f'{x=!r}'`) |
 | `abs()`, `divmod()`, `any()`, `all()`, `sum()`, `min()`, `max()`                                                                                                                                                                                              | All work |
 | `sorted()`, `reversed()`, `zip()`, `map()`, `filter()`                                                                                                                                                                                                        | All work |
+| `list.sort()` / `sorted()` — `key`, `reverse`, comparators, `__lt__`                                                                                                                                                                                          | `key` and `reverse` keyword arguments both work; a positional **two-argument** function is auto-detected as a comparator (JS-style `.sort((a, b) => …)` / `functools.cmp_to_key` semantics) while a one-argument function is treated as a `key`; custom objects are ordered through their `__lt__` method (with a reflected `__gt__` fallback); the sort is stable, so equal elements keep their original order even under `reverse=True` |
 | `zip(strict=True)`                                                                                                                                                                                                                                            | Raises `ValueError` when iterables have different lengths; equal-length iterables work normally |
 | `set` with full union/intersection/difference API                                                                                                                                                                                                             | Fully supported |
 | `isinstance()`, `hasattr()`, `getattr()`, `setattr()`, `dir()`                                                                                                                                                                                                | All work |
@@ -4078,7 +4105,7 @@ Python Feature Coverage
 | `float.is_integer()`                                                                                                                                                                                                                                          | Returns `True` if the float has no fractional part (i.e. is a whole number), `False` otherwise. `float('inf').is_integer()` and `float('nan').is_integer()` both return `False`, matching Python semantics. Added to `Number.prototype` in the baselib so it works on any numeric literal or variable. |
 | `int.bit_length()`                                                                                                                                                                                                                                            | Returns the number of bits needed to represent the integer in binary, excluding the sign and leading zeros. `(0).bit_length()` → `0`; `(255).bit_length()` → `8`; `(256).bit_length()` → `9`; sign is ignored (`(-5).bit_length()` → `3`). Added to `Number.prototype` in the baselib. |
 | Arithmetic type coercion — `TypeError` on incompatible operands                                                                                                                                                                                               | `1 + '1'` raises `TypeError: unsupported operand type(s) for +: 'int' and 'str'`; all arithmetic operators (`+`, `-`, `*`, `/`, `//`, `%`, `**`) enforce compatible types in their `ρσ_op_*` helpers. `bool` is treated as numeric (like Python's `int` subclass). Activated by `overload_operators` (on by default). String `+` string and numeric `+` numeric are allowed; mixed types raise `TypeError` with a Python-style message. |
-| `long(val[, base])` — arbitrary-precision integers                                                                                                                                                                                                            | Backed by JS `BigInt`. `long(42)`, `long('ff', 16)`, `long('1010', 2)`, `long(True)`. Arithmetic: `+`, `-`, `*`, `//`, `%`, `**` — `//` and `%` follow Python floor-division semantics (floor toward −∞), not JS BigInt truncation. `/` raises `TypeError` (use `//`). Bitwise: `&`, `\|`, `^`, `<<`, `>>`. Comparisons: `<`, `<=`, `>`, `>=`, `==`, `!=`. `isinstance(x, long)` works. Mixing `long` with `int` or `float` raises `TypeError`. Requires `BigInt` (Chrome 67+, Firefox 68+, Safari 14+, Node 10.3+). |
+| `long(val[, base])` and `42n` literal — arbitrary-precision integers                                                                                                                                                                                          | Backed by JS `BigInt`. Literal syntax: `42n`, `0xFFn`, `0b1010n`, `0o77n`. Function syntax: `long(42)`, `long('ff', 16)`, `long('1010', 2)`, `long(True)`. Arithmetic: `+`, `-`, `*`, `//`, `%`, `**` — `//` and `%` follow Python floor-division semantics (floor toward −∞), not JS BigInt truncation. `/` raises `TypeError` (use `//`). Bitwise: `&`, `\|`, `^`, `<<`, `>>`. Comparisons: `<`, `<=`, `>`, `>=`, `==`, `!=`. `isinstance(x, long)` works. Mixing `long` with `int` or `float` raises `TypeError`. Requires `BigInt` (Chrome 67+, Firefox 68+, Safari 14+, Node 10.3+). |
 | `complex(real=0, imag=0)` and complex literals `3+4j`                                                                                                                                                                                                         | Full complex number type via `ρσ_complex` class. `complex(real, imag)`, `complex(string)` (parses `'3+4j'`), and `j`/`J` imaginary literal suffix (e.g. `4j`, `3.5J`). Attributes: `.real`, `.imag`. Methods: `conjugate()`, `__abs__()`, `__bool__()`, `__repr__()`, `__str__()`. Arithmetic: `+`, `-`, `*`, `/`, `**` via dunder methods (or operator overloading with `overload_operators`). `abs(z)` dispatches `__abs__`. `isinstance(z, complex)` works. String representation matches Python: `(3+4j)`, `4j`, `(3-0j)`. |
 | `eval(expr[, globals[, locals]])`                                                                                                                                                                                                                             | String literals are compiled as **RapydScript source** at compile time (the compiler parses and transpiles the string, just like Python's `eval` takes Python source). `eval(expr)` maps to native JS direct `eval` for scope access. `eval(expr, globals)` / `eval(expr, globals, locals)` use `Function` constructor with explicit bindings; `locals` override `globals`. Runtime `ρσ_` helpers referenced in the compiled string are automatically injected into the Function scope. Only string *literals* are transformed at compile time; dynamic strings are passed through unchanged. |
 | `exec(code[, globals[, locals]])`                                                                                                                                                                                                                             | String literals are compiled as **RapydScript source** at compile time. Executes the compiled code string; always returns `None`. Without `globals`/`locals` uses native `eval` (scope access). With `globals`/`locals` uses `Function` constructor — mutable objects (lists, dicts) passed in `globals` are accessible by reference, so side-effects are visible after the call. `ρσ_dict` instances (created when `dict_literals` flag is active) are correctly unwrapped via their `jsmap` backing store. |
@@ -4142,7 +4169,6 @@ This restores the original RapydScript behavior: plain JS objects for `{}`, no o
 
 | Feature                               | Notes                                                                                   |
 |---------------------------------------|-----------------------------------------------------------------------------------------|
-| `__slots__` enforcement               | Accepted, but does not restrict attribute assignment                                    |
 | `locals()`                            | Returns an empty `dict`. JS has no runtime mechanism for introspecting local variables. |
 | `input(prompt)`                       | There is no simple cli input in browser; use `prompt()`                                 |
 | `compile()`                           | Python compile/code objects have no JS equivalent                                       |
@@ -4163,7 +4189,7 @@ Modules with a `src/lib/` implementation available are marked ✅. All others ar
 | `random`      | ✅           | RC4-seeded PRNG in `src/lib/random.pyj`                                                       |
 | `re`          | ✅           | Regex wrapper in `src/lib/re.pyj`; uses the JS engine — full PCRE-level support on modern runtimes: positive/negative lookbehind (ES2018+, including variable-width), unicode via automatic `u` flag (ES2015+), `re.fullmatch()`, `re.S`/`re.NOFLAG` aliases. `MatchObject.start()`/`.end()` return exact positions on runtimes with the ES2022 `d` flag (Node 18+); heuristic fallback on older runtimes. Conditional groups `(?(id)yes\|no)` are not supported (JS limitation) and raise `re.error`. |
 | `encodings`   | ✅           | UTF-8 encode/decode helpers and low-level base64 utilities; for the standard Python API use the `base64` module instead |
-| `collections` | ✅           | `defaultdict`, `Counter`, `OrderedDict`, `deque`                                              |
+| `collections` | ✅           | `defaultdict`, `Counter`, `OrderedDict`, `deque`, `namedtuple`, `ChainMap`                     |
 | `functools`   | ✅           | `reduce`, `partial`, `wraps`, `lru_cache`                                                     |
 | `itertools`   | ✅           | Common iteration tools                                                                        |
 | `numpy`       | ✅           | Full numpy-like library in `src/lib/numpy.pyj`; `numpy.random` and `numpy.linalg` sub-modules |
@@ -4187,11 +4213,15 @@ Modules with a `src/lib/` implementation available are marked ✅. All others ar
 | `textwrap`    | ✅           | `wrap(text[, width=70[, ...]])`, `fill(text[, width=70[, ...]])`, `shorten(text, width[, ...])`, `dedent(text)`, `indent(text, prefix[, predicate])`, `TextWrapper` class in `src/lib/textwrap.pyj`; `TextWrapper` supports all standard options: `width`, `initial_indent`, `subsequent_indent`, `expand_tabs`, `tabsize`, `replace_whitespace`, `fix_sentence_endings`, `break_long_words`, `break_on_hyphens`, `drop_whitespace`, `max_lines`, `placeholder`; module-level `wrap`/`fill`/`shorten` accept the same options as explicit keyword parameters; `shorten()` normalises internal whitespace before truncating; `break_on_hyphens=True` (default) splits on em-dashes (2+ hyphens) between word characters, matching Python 3 behaviour |
 | `logging`     | ✅           | `getLogger(name)`, `basicConfig(**kwargs)`, `debug/info/warning/error/critical/exception/log()` module-level shortcuts, `disable(level)`, `addLevelName(level, name)`, `getLevelName(level)`, `captureWarnings(capture)`, `makeLogRecord(dict)`, `setLogRecordFactory(factory)`, `getLogRecordFactory()` in `src/lib/logging.pyj`; `Logger` class with `setLevel`, `isEnabledFor`, `getEffectiveLevel`, `addHandler`, `removeHandler`, `hasHandlers`, `addFilter`, `removeFilter`, `debug/info/warning/error/critical/exception/log` methods; `Handler` base class; `StreamHandler(stream=None)` (writes to `console.debug/info/warn/error` when no stream given, or to any object with `.write(s)`); `NullHandler`; `Formatter(fmt, datefmt, style)` with full `%(attr)s/d/f` record formatting and `formatTime(record, datefmt)` (supports `%Y %m %d %H %M %S %f` strftime codes); `Filter(name)` and `Filterer` mixin; `LogRecord` with `getMessage()` supporting `%s/%d/%f/%e/%g/%x/%o/%%` %-formatting; level constants `NOTSET=0`, `DEBUG=10`, `INFO=20`, `WARNING=30`, `ERROR=40`, `CRITICAL=50`; full logger hierarchy (dotted names, `propagate`, `parent`); `lastResort` handler; note: `FileHandler` raises `NotImplementedError` (no file I/O in JS); `exception()` logs at ERROR without automatic exc_info capture |
 | `heapq`       | ✅           | `heappush(heap, item)`, `heappop(heap)`, `heapify(x)`, `heapreplace(heap, item)`, `heappushpop(heap, item)`, `nsmallest(n, iterable[, key])`, `nlargest(n, iterable[, key])` in `src/lib/heapq.pyj`; min-heap operations on plain lists; heap invariant maintained by sift-up/sift-down (ported from CPython); `nsmallest`/`nlargest` support an optional `key` function; `heappop` and `heapreplace` raise `IndexError` on an empty heap; original iterable is not mutated by `nsmallest`/`nlargest` |
+| `pprint`      | ✅           | `pformat(object, ...)` → str, `pprint(object[, stream], ...)`, `pp(object, ...)` (same as `pprint` but `sort_dicts=False` by default), `saferepr(object)`, `isreadable(object)`, `isrecursive(object)`, `PrettyPrinter` class in `src/lib/pprint.pyj`; keyword options `indent` (default 1), `width` (default 80), `depth`, `compact`, `sort_dicts` (default True), `underscore_numbers` (accepted, currently a no-op); a value's `repr()` is used when it fits within `width`, otherwise lists/tuples/dicts/sets/frozensets are broken across multiple lines with Python-style indentation; recursive references are detected and rendered as `<Recursion on … with id=…>`; pretty-prints RapydScript `dict`/`set`/`frozenset`, plain JS objects, and arrays; `pprint`/`pp` write to a `stream` object's `.write()` (defaulting to stdout via `print()`) |
+| `statistics`  | ✅           | `mean`, `fmean`, `geometric_mean`, `harmonic_mean`, `median`, `median_low`, `median_high`, `median_grouped`, `mode`, `multimode`, `variance`, `pvariance`, `stdev`, `pstdev`, `quantiles`, `covariance`, `correlation`, `linear_regression` in `src/lib/statistics.pyj`; `NormalDist` class (`.mean`/`.median`/`.mode`/`.stdev`/`.variance` properties, `pdf()`, `cdf()`, `inv_cdf()`, `quantiles()`, `zscore()`, `overlap()`, `samples(n[, seed])`, `from_samples()`, plus arithmetic with scalars and other `NormalDist` instances); `StatisticsError` (a `ValueError` subclass); every data argument may be a list, a JS array, a string, or any iterable; `correlation()` supports `method='ranked'` (Spearman); `quantiles()` supports `method='inclusive'`/`'exclusive'`; `linear_regression()` returns an object with `.slope`/`.intercept`; all computation is IEEE-754 double precision (no `Fraction`/`Decimal` preservation), and `cdf()`/`overlap()` use a rational error-function approximation accurate to ~1e-7 |
+| `decimal`     | ❌           | Fixed-precision decimal arithmetic not available; JS `Number` is IEEE-754 only                |
+| `fractions`   | ❌           | Rational arithmetic (`Fraction(num, den)`) not available                                      |
+| `difflib`     | ❌           | `unified_diff`, `SequenceMatcher`, `get_close_matches` not available                          |
 | `inspect`     | ❌           | `signature`, `getmembers`, `isfunction` etc. not available                                    |
 | `struct`      | ❌           | Binary packing/unpacking not available                                                        |
 | `hashlib`     | ❌           | MD5, SHA-256 etc. not available; use Web Crypto API via verbatim JS                           |
 | `hmac`        | ❌           | Keyed hashing not available                                                                   |
-| `pprint`      | ❌           | Pretty-printing not available                                                                 |
 | `unittest`    | ❌           | Not available; RapydScript uses a custom test runner (`node bin/rapydscript test`)            |
 
 ---
@@ -4206,7 +4236,7 @@ Features that exist in RapydScript but behave differently from standard Python:
 | `//` floor division on floats | `math.floor(a/b)` always | uses `Math.floor` - same result for well-behaved floats                                                                                                                                                                    |
 | `%` on negative numbers | Result takes the sign of the divisor (`-7 % 3 == 2`) | Same as Python by default (via `python_modulo`, on by default). Disable with `from __python__ import no_python_modulo` to revert to raw JS remainder semantics.                                                              |
 | `global` / `nonlocal` scoping | Full cross-scope declaration | `global` works for module-level; if a variable exists in both an intermediate outer scope **and** the module-level scope, the outer scope takes precedence (differs from Python where `global` always forces module-level) |
-| `Exception.message` | Not standard; use `.args[0]` | `.message` is the standard attribute (JS `Error` style)                                                                                                                                                                    |
+| `Exception.message` | Not standard; use `.args[0]` | `.args` is populated (like Python); `.message` also set to first arg for JS `Error` compatibility                                                                                                                          |
 | Function call argument count | Too few args → `TypeError`; too many → `TypeError` | Too few args → extra params are `undefined`; too many → extras silently discarded. No `TypeError` is raised in either case.                                                                                                |
 | Positional-only param enforcement | Passing by keyword raises `TypeError` | Passing by keyword is silently ignored — the named arg is discarded and the parameter gets `undefined` (no error raised)                                                                                                   |
 | Keyword-only param enforcement | Passing positionally raises `TypeError` | Passing positionally raises no error — the extra positional arg is silently discarded and the default value is used                                                                                                        |

package/TODO.md

@@ -1,34 +1,9 @@
 
-### libraries
-
-- The 7n literal isn't supported by the parser — use BigInt()
-
 - remove repl_mode and make repl make a new context for each "run" press
 
 - vscode plugin based on language service?
 
 
-I would like you to add support for [python async def functions with yield (async generators)] to rapydscript. It should have the same syntax as the Python implementation, and be transpiled into equivalent javascript. Ensure with unit tests that it transpiles and the output JS runs correctly, and that the language service correctly handles it in parsed code. Make sure it works in the web-repl. Update the README if it has any outdated info about this, and the PYTHON_FEATURE_COVERAGE report. Add a simple example to the bottom of the TODO document using this feature (make no other changes to that file). Remove the suggestion from PYTHON_GAPS if it is there.
-
-### Async generator example
-
-```py
-# `async def` + `yield` makes an async generator. The function returns an
-# async iterator immediately; values are pulled with `await it.next()` or
-# consumed with `async for`.
-
-from asyncio import sleep
-
-async def countdown(n):
-    while n > 0:
-        await sleep(0)            # cooperative yield to the event loop
-        yield n
-        n -= 1
-
-async def main():
-    async for x in countdown(3):
-        print(x)                  # prints 3, then 2, then 1
+I would like you to add support for [python style __slots__ enforcement] to rapydscript. It should have the same syntax as the Python implementation, and be transpiled into equivalent javascript. Ensure with unit tests that it transpiles and the output JS runs correctly, and that the language service correctly handles it in parsed code. Make sure it works in the web-repl. Update the README if it has any outdated info about this, and the PYTHON_FEATURE_COVERAGE report. Add a simple example to the bottom of the TODO document using this feature (make no other changes to that file). Remove the suggestion from PYTHON_GAPS if it is there. Run the full unit test suite to check for regressions.
 
-main()
-```
 

package/add-toc-to-readme

@@ -1,2 +1,2 @@
-#!/bin/sh
-exec node_modules/doctoc/doctoc.js --title '**Contents**' README.md
+#!/bin/sh
+exec node_modules/doctoc/doctoc.js --title '**Contents**' README.md