rapydscript-ns 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+version 0.8.0 - 0.8.3
+=======================
+
+  * Add language service with tab-completion, return type inference, hover tips, and typing exports
+  * Add source maps support for the transpiled js
+  * Add `itertools` standard library module
+  * Add `collections` standard library module
+  * Add `functools` standard library module
+  * Add `numpy` standard library module
+  * Add `async`/`await` support
+  * Add lambda expression support
+  * Add structural pattern matching (`match`/`case`) support
+  * Add starred assignment support (e.g. `a, *b = [1, 2, 3]`)
+  * Add ellipsis operator and subscript tuple support
+  * Add walrus operator (`:=`) support
+  * Add dict merge literal support (`{**a, **b}`)
+  * Add positional-only (`/`) and keyword-only (`*`) parameter separators
+  * Add `@classmethod` decorator support with improved class property access
+  * Add nested comprehension support
+  * Add overloaded operator support
+  * Add Python-style truthiness for empty lists and dicts
+  * Add `super()` support
+  * Add compiler flags to enable optional pythonic behaviors
+  * Add `any()` and `all()` builtins
+  * Add tree shaking support for reduced output size
+  * Add module mode for exporting root-level functions
+  * Add support for virtual imports
+  * Add support for bundling pythonized strings into compiled output
+  * `print` now maps to `console.log`; `window.print` maps to the JS printer dialog
+  * Add custom class mapping support in `dict()`
+
 version 0.7.22
 =======================
 

package/CONTRIBUTORS

@@ -1,11 +1,12 @@
-This project is officially supported by Kovid Goyal.
+This project is officially supported by Michael Ficocelli.
 
 Main Developers
 ---------------
-Kovid Goyal
+Michael Ficocelli
 
 Other Contributors
 ------------------
+Kovid Goyal (Previous main developer, developer of rapydscript-ng)
 Alexander Tsepkov (main developer of the original RapydScript)
 Charles Law
 Tobias Weber

package/PYTHON_DIFFERENCES_REPORT.md

@@ -0,0 +1,291 @@
+# RapydScript vs Python: Differences Report
+
+This report catalogs every place in the README where RapydScript behavior
+differs from standard Python, assesses whether each claim is still accurate,
+and notes which items are covered by tests.
+
+---
+
+## Summary Table
+
+| # | Topic | README Claim | Accurate? | Tested? |
+|---|-------|-------------|-----------|---------|
+| 1 | Function argument leniency | Too few args → `undefined` instead of `TypeError` | ✓ Yes | Added (python_compat.pyj) |
+| 2 | `*args` + optional arg duplication | Duplicate kwarg silently ignored | ✓ Yes | Added (python_compat.pyj) |
+| 3 | Positional-only parameter enforcement | Passing by keyword silently ignored | ✓ Yes | Added (python_compat.pyj) |
+| 4 | Keyword-only parameter enforcement | Passing positionally raises no error | ✓ Yes | Added (python_compat.pyj) |
+| 5 | `is` operator | Maps to `===` (strict equality, not Python identity) | ✓ Yes | generic.pyj |
+| 6 | Arithmetic: `1 + '1'` | Results in `'11'` (JS string coercion) | ✓ Yes | Added (python_compat.pyj) |
+| 7 | List concatenation without `overload_operators` | `[1] + [1]` results in a string, not a list | ✓ Yes | Added (python_compat.pyj) |
+| 8 | Ordering operators on containers | `<`, `>`, `<=`, `>=` use JS coercion (not element-wise) | ✓ Yes | Added (python_compat.pyj) |
+| 9 | List `sort()` | `sort()` = Python numeric sort; JS sort available as `jssort()` | ✓ Fixed | baselib.pyj, collections.pyj, python_compat.pyj |
+| 10 | List `pop()` | `pop()` = Python bounds-checked pop; JS pop available as `jspop()` | ✓ Fixed | baselib.pyj, collections.pyj, python_compat.pyj |
+| 11 | Sets: no `__hash__` for custom objects | Object equality via `is` (identity); `__hash__` not dispatched for set membership | ✓ Yes | Noted in python_features.pyj #47 (skipped) |
+| 12 | Dicts: JS object by default | Non-existent key returns `undefined` (not `KeyError`) | ✓ Yes | Added (python_compat.pyj) |
+| 13 | Dicts: numeric keys auto-converted | Number keys become strings in JS object dicts | ✓ Yes | Added (python_compat.pyj) |
+| 14 | Dicts: keys as attributes | Dict keys accessible as object properties | ✓ Yes | Added (python_compat.pyj) |
+| 15 | Dicts: no `.keys()/.values()/.items()` etc. by default | JS objects lack Python dict methods without `dict_literals` flag | ✓ Yes | scoped_flags.pyj |
+| 16 | Strings: not Python strings by default | Python string methods on `str` object, not on string instances | ✓ Yes | str.pyj |
+| 17 | `strings()` leaves `split()`/`replace()` as JS versions | After `strings()`, `split()` and `replace()` remain JS implementations | ✓ Yes | Added (python_compat.pyj) |
+| 18 | Strings: UTF-16 semantics | Non-BMP characters are surrogate pairs | ✓ Yes | Documented; `str.uchrs/uslice/ulen` helpers exist |
+| 19 | Truthiness: JS semantics by default | Empty `[]` and `{}` are truthy without `truthiness` flag | ✓ Yes | python_features.pyj #40 |
+| 20 | Method binding: not automatic | `f = obj.method; f()` loses `self` | ✓ Yes | scoped_flags.pyj |
+| 21 | Nested classes | Fully supported — full tests in `test/classes.pyj` | ✓ Yes | classes.pyj |
+| 22 | Multiple inheritance MRO | May differ from Python's C3 MRO in complex hierarchies | ✓ Yes | Documented |
+| 23 | `global` keyword | Prefers outer-scope variable over module-global when both exist | ✓ Yes | Added (python_compat.pyj) |
+| 24 | `__slots__` | Accepted syntactically but does not restrict attribute creation | ✓ Yes | Noted in python_features.pyj #23 (skipped) |
+| 25 | Star imports | Not supported (by design) | ✓ Yes | Documented |
+| 26 | Regex: no lookbehind | JavaScript regex engine has no lookbehind support | ✓ Yes (ES5); ES2018+ does have lookbehind, so ES6 mode may vary | regexp.pyj |
+| 27 | Regex: MatchObject `start()`/`end()` | May return incorrect values for nested capture groups | ✓ Yes | regexp.pyj |
+| 28 | Generators: ES5 default | Down-compiled to ES5 switch statements by default | ✓ Yes | generators.pyj |
+| 29 | Extra keywords | All JavaScript keywords are also reserved | ✓ Yes | generic.pyj (throws tests) |
+| 30 | `slice()` builtin | Fully supported — `slice(start, stop, step)`, `.indices()`, equality, `isinstance` all work | ✓ Yes | python_features.pyj #63, slice.pyj |
+| 31 | `int.bit_length()` | Not supported | ✓ Yes | Noted in python_features.pyj #17 (skipped) |
+| 32 | `float.is_integer()` | Not supported | ✓ Yes | Noted in python_features.pyj #18 (skipped) |
+| 33 | `zip(strict=True)` | Not supported | ✓ Yes | Noted in python_features.pyj #27 (skipped) |
+| 34 | `vars()`/`locals()`/`globals()` | Not implemented | ✓ Yes | Noted in python_features.pyj #60 (skipped) |
+| 35 | `complex()` / `j` suffix | No complex number type | ✓ Yes | Noted in python_features.pyj #42, #59 (skipped) |
+| 36 | `b'...'` bytes literals | No bytes type; use `encodings` module | ✓ Yes | Noted in python_features.pyj #43 (skipped) |
+| 37 | `except*` (exception groups) | Not supported (Python 3.11+) | ✓ Yes | Noted in python_features.pyj #44 (skipped) |
+| 38 | `__new__` constructor hook | Not supported | ✓ Yes | Noted in python_features.pyj #45 (skipped) |
+| 39 | `__del__` destructor | Not supported | ✓ Yes | Noted in python_features.pyj #46 (skipped) |
+| 40 | `__hash__` for set/dict membership | Not dispatched; uses JS identity (`===`) | ✓ Yes | Noted in python_features.pyj #47 (skipped) |
+| 41 | `__getattr__`/`__setattr__`/`__delattr__` | Not supported | ✓ Yes | Noted in python_features.pyj #48 (skipped) |
+| 42 | `__getattribute__` | Not supported | ✓ Yes | Noted in python_features.pyj #49 |
+| 43 | `__class_getitem__` | Not supported | ✓ Yes | Noted in python_features.pyj #51 (skipped) |
+| 44 | `__init_subclass__` | Not supported | ✓ Yes | Noted in python_features.pyj #52 (skipped) |
+
+---
+
+## Detailed Notes on Key Differences
+
+### Function Argument Validation
+
+RapydScript intentionally does **not** raise `TypeError` for:
+- Calling a function with too few arguments (extra params are `undefined`)
+- Calling a function with too many arguments (extras silently discarded)
+- Passing a positional-only parameter by keyword (named kwarg silently ignored)
+- Passing a keyword-only parameter positionally (no error raised)
+- Specifying an optional argument twice when `*args` is present
+
+**Rationale:** Performance and interoperability with JavaScript libraries that
+frequently call functions with varying argument patterns.
+
+### Dict Defaults (JavaScript Object Semantics)
+
+Without `from __python__ import dict_literals, overload_getitem`:
+- `{...}` creates a plain JS object, not a Python dict
+- Missing keys return `undefined`, not `KeyError`
+- Numeric keys are silently coerced to strings: `d[1]` and `d['1']` are the same key
+- Dict keys are also accessible as properties: `d.foo == d['foo']`
+- No `.keys()`, `.values()`, `.items()`, `.get()`, `.pop()` methods
+
+Use `from __python__ import dict_literals, overload_getitem` for full Python dict semantics.
+
+### List Method Name Conflicts (Resolved)
+
+RapydScript lists are native JavaScript arrays. The method naming has been
+restored to match Python conventions:
+- `list.sort()` — Python numeric sort (in-place, supports `key` and `reverse`)
+- `list.pop()` — Python bounds-checked pop (raises `IndexError` for out-of-bounds)
+- `list.jssort()` — native JS lexicographic sort (for JS interop)
+- `list.jspop()` — native JS pop (no bounds check, ignores arguments)
+- `list.pysort()` / `list.pypop()` — backward-compat aliases for `sort()`/`pop()`
+
+### Truthiness
+
+Default truthiness follows JavaScript rules:
+- `[]`, `{}`, any non-null object → **truthy** (unlike Python)
+- `0`, `''`, `null`, `undefined`, `NaN` → falsy
+
+Enable Python truthiness with `from __python__ import truthiness`:
+- Empty containers (`[]`, `{}`, `set()`, `''`) → falsy
+- `__bool__` and `__len__` dunders are dispatched
+
+### String Method Availability
+
+Python string methods are available via the `str` object:
+```python
+str.strip('  hello  ')   # 'hello'
+str.split('a b')         # ['a', 'b']
+```
+
+To make them available on string instances, call `from pythonize import strings; strings()`.
+However, `split()` and `replace()` are **always** the JS versions — Python semantics
+for these two methods must be accessed via `str.split(s)` / `str.replace(s, ...)`.
+
+Notable JS-vs-Python difference for `split()`:
+- Python `'a  b'.split()` → `['a', 'b']` (splits on any whitespace, strips leading/trailing)
+- JS `'a  b'.split()` → `['a  b']` (no-arg form returns single-element array)
+
+### Method Binding
+
+RapydScript **does not** auto-bind methods to instances. This matches
+JavaScript semantics but differs from Python:
+```python
+obj = MyClass()
+obj.method()          # ✓ works — 'self' is correctly set
+f = obj.method
+f()                   # ✗ 'self' is undefined/window (unbound)
+```
+
+Use `from __python__ import bound_methods` inside a class to enable auto-binding.
+
+### `global` Keyword Scope
+
+RapydScript's `global` keyword slightly differs from Python's: if a variable
+exists in an intermediate outer function scope **and** in the module-level
+(global) scope, the outer function scope variable takes precedence.
+In Python, `global` always refers to the module-level scope.
+
+### `is` Operator
+
+`is` compiles to `===` (strict equality), not Python's object identity check.
+This means:
+- `1 is 1` is `True` (same as Python)
+- `'a' is 'a'` is `True` (same as Python for interned strings)
+- `[1] is [1]` is `False` (same as Python — different objects)
+- But `NaN is NaN` is `False` in JS (`NaN !== NaN`), which differs from Python
+
+### Ordering Operators on Containers
+
+RapydScript does **not** overload `<`, `>`, `<=`, `>=` for lists or other
+containers. These fall through to JS comparison which coerces to strings:
+```python
+[10] < [9]    # True in RapydScript (JS: '10' < '9' string compare)
+              # False in Python (numeric element comparison)
+```
+Use explicit element comparisons or define `__lt__` etc. and call them directly.
+
+### Regular Expressions
+
+The `re` module wraps JavaScript's regex engine. Key limitations:
+1. **Lookbehind** — not supported in ES5; may work in ES6+ environments
+2. **Unicode** — non-BMP characters may require ES6 `u` flag
+3. **`MatchObject.start()`/`.end()`** for sub-groups — incorrect for some
+   nested-capture patterns (JS doesn't expose sub-group positions directly)
+
+### Generators
+
+By default, generators compile to ES5 state-machine switch statements (larger
+but widely compatible). Pass `--js-version 6` to emit native ES6 generators.
+
+---
+
+## Features Completely Absent (not in Python either, but noteworthy)
+
+| Feature | Notes |
+|---------|-------|
+| `v'...'` verbatim JS | RapydScript-only; embeds raw JS |
+| Existential operator `x?.y` | Borrowed from CoffeeScript |
+| `?` null-coalescing shorthand `a = b ? c` | RapydScript-specific |
+| `def` as expression | Assign anonymous multi-line functions |
+| `.call(this)` chaining syntax | Invoke anonymous functions immediately |
+
+---
+
+*Report generated 2026-03-21. Test coverage additions in `test/python_compat.pyj`.*
+
+---
+
+## Recommendations for Improving Python Compatibility
+
+The following improvements are prioritized by how frequently they surprise Python users and how disruptive the gap is in practice. Items marked 🔥 are silent footguns — they produce wrong behavior with no error, making them especially harmful.
+
+---
+
+### 1. 🔥 Fix List Concatenation (`+`) Without `overload_operators`
+
+**Current:** `[1, 2] + [3, 4]` silently produces the string `'[1, 2][3, 4]'` — a completely wrong result with no warning.
+
+**Recommendation:** Make basic list `+` concatenation work correctly by default, without requiring `overload_operators`. This could be done at the compiler level by emitting a `.concat()` call whenever the `+` operator is applied between two list literals or list-typed variables. Alternatively, emit a runtime check: if both operands are arrays, use `.concat()`.
+
+**Why:** This is one of the worst silent footguns in the language. Any Python programmer who writes `result = list_a + list_b` will get corrupted output that looks like a string. The fact that `overload_operators` fixes it is obscure and adds overhead for an operation Python users expect to always work.
+
+---
+
+### 2. ✅ Rename `pysort()` / `pypop()` Back to `sort()` / `pop()` — **IMPLEMENTED**
+
+**Implemented:** `list.sort()` now performs Python-style numeric sort (in-place, supports `key` and `reverse`). `list.pop()` now performs Python-style bounds-checked pop (raises `IndexError` for out-of-bounds). The native JS versions are available as `list.jssort()` and `list.jspop()`. The old `pysort()` / `pypop()` names are retained as backward-compat aliases.
+
+---
+
+### 3. 🔥 Enable Python Truthiness by Default (or Warn on Empty Container Tests)
+
+**Current:** `if []:` evaluates to `True` (JS semantics). Python semantics require `from __python__ import truthiness`.
+
+**Recommendation:** Either (a) make `truthiness` the default behavior and provide a `from __js__ import truthiness` escape hatch for legacy code, or (b) emit a compiler warning when a list/dict/set literal is used directly as an `if` condition without the `truthiness` flag.
+
+**Why:** The truthiness of empty containers is one of the most fundamental Python idioms. `if items:`, `while queue:`, and `if not result:` are idiomatic Python in virtually every codebase. Getting them silently wrong without the `truthiness` flag is a trap that is very hard to debug.
+
+---
+
+### 4. Make Python Dict the Default (or Promote `dict_literals` to a Global Default)
+
+**Current:** `{}` creates a plain JS object. Missing keys return `undefined`, numeric keys are coerced to strings, and `.keys()` / `.values()` / `.items()` don't exist. Full Python dict semantics require `from __python__ import dict_literals, overload_getitem`.
+
+**Recommendation:** Promote `dict_literals` to an opt-out default via a compiler flag (`--python-dicts` or similar). Alternatively, provide a project-level config option to enable it globally so users don't have to add the import to every file.
+
+**Why:** Python dicts are used everywhere. The behavior gap (missing key → `undefined` instead of `KeyError`, numeric keys aliasing to string keys, no `.items()`) causes subtle bugs that are extremely hard to trace. The current model forces users to remember a file-level import for behavior they'd expect to be the baseline.
+
+---
+
+### 5. Auto-Apply `strings()` or Make Python String Methods Available on Instances
+
+**Current:** Python string methods like `.strip()`, `.split()`, `.upper()` live on the `str` module object (`str.strip(s)`) rather than on string instances. To use instance-style calls, users must call `from pythonize import strings; strings()`. Even then, `.split()` and `.replace()` remain JS versions.
+
+**Recommendation:** Two improvements:
+1. Make `strings()` apply automatically in Python-compatibility mode, or provide a cleaner `from __python__ import strings` import.
+2. Overwrite the JS `.split()` and `.replace()` with Python-correct implementations inside `strings()`. The current doc explicitly says these two are **intentionally** left as JS versions — this should be reconsidered, as it makes `strings()` provide incomplete Python compatibility.
+
+**Why:** Method calls on string instances (`s.split()`, `s.strip()`, `s.startswith('x')`) are the default mental model for every Python user. Having to write `str.split(s)` instead of `s.split()` is jarring and prevents Python code from running without modification.
+
+---
+
+### 6. Add `__getattr__` / `__setattr__` Support via ES6 Proxy
+
+**Current:** `__getattr__` and `__setattr__` are not supported. Attribute access interception is impossible.
+
+**Recommendation:** In ES6 mode (`--js-version 6`), implement `__getattr__` and `__setattr__` by wrapping class instances in a `Proxy` when those dunders are defined. The `get` and `set` traps can delegate to the user's `__getattr__` / `__setattr__` methods with a fallback to the underlying object.
+
+**Why:** `__getattr__` is used extensively for lazy loading, dynamic APIs, mock objects, ORMs, and proxy patterns. It's the basis for many Python libraries (e.g. `dataclasses`-style field access, `unittest.mock`, `attrs`). Without it, an entire class of Python patterns is unavailable. ES6 Proxy support is well-established in all modern JS environments.
+
+---
+
+### 7. Add Stub Modules for `typing`, `dataclasses`, and `enum`
+
+**Current:** `typing`, `dataclasses`, and `enum` are completely absent.
+
+**Recommendation:**
+- **`typing`**: Add a stub `src/lib/typing.pyj` that exports `List`, `Dict`, `Optional`, `Union`, `Tuple`, `Any`, `TypeVar`, `Generic`, `Callable` — all as no-ops or identity functions. This lets users write `from typing import Optional, List` without import errors, and allows type-annotated Python code to run unchanged.
+- **`enum`**: Add a basic `Enum` base class where `class Color(Enum): RED = 1` creates an object with `.name` and `.value` attributes, iteration over members, and `Color.RED` access. This is well-defined behavior with no JS-fundamental blockers.
+- **`dataclasses`**: Add a `@dataclass` decorator that introspects class-level annotations and generates `__init__`, `__repr__`, and `__eq__`. This is a high-value feature — dataclasses are ubiquitous in modern Python and could be implemented in ~100 lines of RapydScript using the existing annotation support.
+
+**Why:** These three modules are among the most-imported in modern Python codebases. Their absence means entire categories of modern Python patterns — type hints, structured data classes, enumerated constants — fail at import time with no workaround other than rewriting the code.
+
+---
+
+### 8. Add a `copy` Module (`copy.copy` / `copy.deepcopy`)
+
+**Current:** No `copy` module. Shallow and deep copy must be done via JS idioms (`Object.assign`, `JSON.parse(JSON.stringify(...))`) or verbatim JS.
+
+**Recommendation:** Add `src/lib/copy.pyj` with:
+- `copy(obj)` — shallow clone: spread for plain objects, `.slice()` for arrays, class instance duplication via `Object.assign(Object.create(proto), obj)`.
+- `deepcopy(obj)` — deep clone: recursive traversal for plain objects/arrays; use `structuredClone()` (ES2022) when available with a recursive fallback.
+
+**Why:** `copy.deepcopy` is one of the most commonly needed utilities when porting Python code. Many algorithms depend on working with independent copies of mutable data structures. Without it, users either introduce subtle aliasing bugs or write verbose verbatim-JS workarounds.
+
+---
+
+### Summary: Priority Order
+
+| Priority | Item | Effort | Impact |
+|---|---|---|---|
+| 1 | Fix list `+` concatenation (silent footgun) | Low — compiler emit change | 🔥 High |
+| 2 | ~~Rename `pysort`/`pypop` back to `sort`/`pop`~~ | ✅ Done | 🔥 High |
+| 3 | Default Python truthiness | Medium — flag change + regression test | 🔥 High |
+| 4 | Default Python dicts | Medium — compiler flag or config | High |
+| 5 | Python string methods on instances | Low — fix `strings()` split/replace | High |
+| 6 | `typing`, `dataclasses`, `enum` stubs | Medium — ~200 lines per module | High |
+| 7 | `copy` module | Low — ~80 lines | Medium |
+| 8 | `__getattr__`/`__setattr__` via Proxy | High — ES6 only, code-gen complexity | Medium |

package/PYTHON_FEATURE_COVERAGE.md

@@ -0,0 +1,200 @@
+# Python Feature Coverage Report — RapydScript-NS
+
+## ✅ Fully Supported
+
+| Feature | Notes |
+|---|---|
+| `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 |
+| `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 |
+| `while / else` | `else` block runs when loop condition becomes `False` without a `break`; nested `break` isolation correct |
+| `with A() as a, B() as b:` | Multiple context managers in one statement; exits in LIFO order (Python-correct) |
+| `callable(fn)` | Works for plain functions and objects with `__call__` |
+| `round(x, ndigits=0)` | Full Python semantics including negative `ndigits` |
+| `enumerate(iterable, start=0)` | `start` parameter supported |
+| `str.isspace()`, `str.islower()`, `str.isupper()` | Working string predicates |
+| `str.isalpha()` | Regex-based; empty string returns `False` |
+| `str.isdigit()` | Regex-based (`\d+`) |
+| `str.isalnum()` | Regex-based |
+| `str.isidentifier()` | Checks `^[a-zA-Z_][a-zA-Z0-9_]*$` |
+| `str.casefold()` | Maps to `.toLowerCase()` |
+| `str.removeprefix(prefix)` | Returns unchanged string if prefix not found |
+| `str.removesuffix(suffix)` | Returns unchanged string if suffix not found |
+| `str * n` string repetition | Works when `from __python__ import overload_operators` is active |
+| `list * n` / `n * list` | Works with `overload_operators`; returns a proper RapydScript list |
+| `list + list` concatenation | `[1,2] + [3,4]` returns `[1, 2, 3, 4]`; `+=` extends in-place. No flag required. |
+| `match / case` | Structural pattern matching (Python 3.10) fully supported |
+| Variable type annotations `x: int = 1` | Parsed and ignored (no runtime enforcement); annotated assignments work normally |
+| Ellipsis literal `...` as expression | Parsed as a valid expression; evaluates to JS `undefined` at runtime |
+| Generator `.throw()` | Works via JS generator protocol |
+| Generator `.send()` | Works via `g.next(value)` |
+| `yield from` | Works; return value of sub-generator is not accessible |
+| `+=`, `-=`, `*=`, `/=`, `//=`, `**=`, `%=`, `&=`, `\|=`, `^=`, `<<=`, `>>=` | All augmented assignments work |
+| `raise X from Y` exception chaining | Sets `__cause__` on the thrown exception; `from None` also supported |
+| Starred assignment `a, *b, c = ...` | Works |
+| `@classmethod`, `@staticmethod`, `@property` / `@prop.setter` | All work |
+| `{**dict1, **dict2}` dict spread | Works as merge replacement for the missing `\|` operator |
+| `dict.fromkeys()` | Works with `dict_literals` flag |
+| Chained comparisons `a < b < c` and `a < b > c` | Same-direction and mixed-direction chains both work; middle operand evaluated once |
+| `for`, `while`, `try/except/finally`, `with`, `match/case` | All control-flow constructs work |
+| Classes, inheritance, decorators, `__dunder__` methods | Fully supported |
+| Nested class definitions | Accessible as `Outer.Inner` and via instance (`self.Inner`); arbitrary nesting depth; nested class may inherit from outer-scope classes |
+| List / dict / set comprehensions, generator expressions | Fully supported |
+| f-strings, `str.format()`, `format()` builtin, all common `str.*` methods | Fully supported |
+| `abs()`, `divmod()`, `any()`, `all()`, `sum()`, `min()`, `max()` | All work |
+| `sorted()`, `reversed()`, `zip()`, `map()`, `filter()` | All work |
+| `set` with full union/intersection/difference API | Fully supported |
+| `isinstance()`, `hasattr()`, `getattr()`, `setattr()`, `dir()` | All work |
+| `bin()`, `hex()`, `oct()`, `chr()`, `ord()` | All work |
+| `int(x, base)`, `float(x)` with ValueError on bad input | Works |
+| `lambda` keyword | Full support: args, defaults, `*args`, ternary body, closures, nesting |
+| Arithmetic operator overloading — `__add__`, `__sub__`, `__mul__`, `__truediv__`, `__floordiv__`, `__mod__`, `__pow__`, `__neg__`, `__pos__`, `__abs__`, `__invert__`, `__lshift__`, `__rshift__`, `__and__`, `__or__`, `__xor__`, `__radd__`, `__iadd__` etc. | Dispatched when `from __python__ import overload_operators` is active; comparison operators (`<`, `>`, `<=`, `>=`) are **not** re-dispatched — call `obj.__lt__(other)` directly |
+| Nested comprehensions (multi-`for` clause) | `[x for row in matrix for x in row if cond]`; works for list, set, and dict comprehensions |
+| Positional-only parameters `def f(a, b, /):` | Full support — parser enforces placement; runtime passes positional args correctly |
+| Keyword-only parameters `def f(a, *, b):` | Full support — bare `*` separator enforced; `b` must be passed as keyword |
+| Walrus operator `:=` | Fully supported: hoisted in `if`/`while` conditions at any scope; comprehension filter assigns to enclosing scope (Python-correct). |
+| `__call__` dunder dispatch | `obj()` dispatches to `obj.__call__(args)` for callable objects; `callable(obj)` also returns `True`; both forms work. Requires `from __python__ import truthiness`. |
+| **Truthiness / `__bool__`** | Full Python truthiness via `from __python__ import truthiness`: empty `[]`, `{}`, `set()`, `''` are falsy; `__bool__` is dispatched; `and`/`or` return operand values; `not`, `if`, `while`, `assert`, ternary all use `ρσ_bool()`. |
+| `frozenset(iterable)` | Immutable set: construction from list/set/iterable; `in`, `len()`, iteration, `copy()`, `union()`, `intersection()`, `difference()`, `symmetric_difference()`, `issubset()`, `issuperset()`, `isdisjoint()` — all return `frozenset`. `isinstance(x, frozenset)` works. Compares equal to a `set` with the same elements via `__eq__`. No mutation methods (`add`, `remove`, etc.). |
+| `issubclass(cls, classinfo)` | Checks prototype chain; `classinfo` may be a class or tuple of classes; every class is a subclass of itself; raises `TypeError` for non-class arguments. |
+| `hash(obj)` | Numbers hash by value (int identity, float → int form if whole); strings use djb2; `None` → 0; booleans → 0/1; objects with `__hash__` dispatch to it; class instances get a stable identity hash; `list`, `set`, `dict` raise `TypeError`. |
+| `next(iterator[, default])` | Advances a JS-protocol iterator (`{done, value}`); returns `default` when exhausted if provided, otherwise raises `StopIteration`. Works with `iter()`, `range()`, `enumerate()`, generators, and any object with a `.next()` or `__next__()` method. |
+| `StopIteration` exception | Defined as a builtin exception class; raised by `next()` when an iterator is exhausted and no default is given. |
+| `iter(callable, sentinel)` | Two-argument form calls `callable` (no args) repeatedly until the return value equals `sentinel` (strict `===`). Returns a lazy iterator compatible with `for` loops, `next()`, `list()`, and all iterator consumers. Works with plain functions and callable objects (`__call__`). |
+| `dict \| dict` and `dict \|= dict` (Python 3.9+) | Dict merge via `\|` creates a new merged dict (right-side values win); `\|=` updates in-place. Requires `from __python__ import overload_operators, dict_literals`. |
+| `slice(start, stop[, step])` | Full Python `slice` class: 1-, 2-, and 3-argument forms; `.start`, `.stop`, `.step` attributes; `.indices(length)` → `(start, stop, step)`; `str()` / `repr()`; `isinstance(s, slice)`; equality `==`; use as subscript `lst[s]` (read, write, `del`) all work. |
+
+---
+
+## ❌ Not Supported — Missing from Baselib (runtime)
+
+| Feature                             | Priority                                                               |
+|-------------------------------------|------------------------------------------------------------------------|
+| `complex(real, imag)`               | 🟢 Low — no complex number type                                        |
+| `vars()` / `locals()` / `globals()` | 🟢 Low — not defined; use direct attribute access                      |
+| `str.expandtabs(tabsize)`           | 🟢 Low                                                                 |
+| `int.bit_length()`                  | 🟢 Low — useful for bit manipulation                                   |
+| `float.is_integer()`                | 🟢 Low                                                                 |
+| `exec(code)`                        | 🟢 Low — use `v'eval(...)'` for inline JS evaluation                  |
+| `eval(expr)`                        | 🟢 Low — use `v'eval(...)'` for inline JS evaluation                  |
+| `__import__(name)`                  | 🟢 Low — not supported; use `import` statement                        |
+| `input(prompt)`                     | 🟢 Low — not built in; use `prompt()` via `v'prompt(...)'`            |
+| `bytes(x)` / `bytearray(x)`        | 🟢 Low — no built-in bytes type; use `Uint8Array` via verbatim JS     |
+| `object()`                          | 🟢 Low — base `object` type not exposed; use plain `{}` or a class    |
+| `abc` module — `ABC`, `@abstractmethod`, `Protocol` | 🟢 Low — no abc module; no enforcement of abstract methods |
+| `compile()`                         | 🔴 N/A — Python compile/code objects have no JS equivalent            |
+| `memoryview(obj)`                   | 🔴 N/A — no buffer protocol in browser context                        |
+| `open(path)`                        | 🔴 N/A — no filesystem access in browser context                      |
+
+---
+
+## ❌ Not Supported — Parser / Syntax Level
+
+| Feature                                       | Priority                                                             |
+|-----------------------------------------------|----------------------------------------------------------------------|
+| `from module import *` (star imports)         | 🟢 Low — intentionally unsupported (by design, to prevent namespace pollution) |
+| `zip(strict=True)`                            | 🟢 Low                                                               |
+| `__slots__` enforcement                       | 🟢 Low — accepted but does not restrict attribute assignment         |
+| Complex number literals `3+4j`                | 🟢 Low — no `j` suffix; no complex type                              |
+| `b'...'` bytes literals                       | 🟢 Low — no `b` prefix; use the `encodings` module for encoding work |
+| `except*` (exception groups, Python 3.11+)    | 🟢 Low — no parser support                                           |
+| `__new__` constructor hook                    | 🟢 Low — no alternative constructor support                          |
+| `__del__` destructor / finalizer              | 🟢 Low — JS has no guaranteed finalizer                              |
+| `__hash__` dunder                             | 🟢 Low — not dispatched; set/dict use `===` object identity          |
+| `__getattr__` / `__setattr__` / `__delattr__` | 🟢 Low — no attribute-access interception                            |
+| `__getattribute__`                            | 🟢 Low — no attribute-lookup override                                |
+| `__format__` dunder                           | 🟢 Low — `format()` builtin not defined; `__format__` not dispatched |
+| `__class_getitem__`                           | 🟢 Low — no `MyClass[T]` generic subscript syntax                    |
+| `__init_subclass__` hook                      | 🟢 Low                                                               |
+
+---
+
+## Standard Library Modules
+
+Modules with a `src/lib/` implementation available are marked ✅. All others are absent.
+
+| Module        | Status      | Notes                                                                                         |
+|---------------|-------------|-----------------------------------------------------------------------------------------------|
+| `math`        | ✅           | Full implementation in `src/lib/math.pyj`                                                     |
+| `random`      | ✅           | RC4-seeded PRNG in `src/lib/random.pyj`                                                       |
+| `re`          | ✅           | Regex wrapper in `src/lib/re.pyj`;  limited vs full PCRE (no lookbehind, limited unicode, no conditional groups); `MatchObject.start()`/`.end()` may return incorrect values for sub-groups in nested-capture patterns (JS regex API does not expose sub-group positions) |
+| `encodings`   | ✅           | Base64 and encoding helpers; partial `base64` coverage                                        |
+| `collections` | ✅           | `defaultdict`, `Counter`, `OrderedDict`, `deque`                                              |
+| `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 |
+| `typing`      | ❌           | `List`, `Dict`, `Optional`, `Union`, `Tuple`, `Generic`, `TypeVar` — none available           |
+| `dataclasses` | ❌           | `@dataclass`, `field()`, `asdict()`, `astuple()` not available                                |
+| `contextlib`  | ❌           | `contextmanager`, `suppress`, `ExitStack`, `asynccontextmanager` not available                |
+| `copy`        | ❌           | `copy()` / `deepcopy()` not available                                                         |
+| `string`      | ❌           | Character constants, `Template`, `Formatter` not available                                    |
+| `json`        | ❌           | No Python wrapper; JS `JSON.parse` / `JSON.stringify` work directly via verbatim JS           |
+| `datetime`    | ❌           | `date`, `time`, `datetime`, `timedelta` not available                                         |
+| `inspect`     | ❌           | `signature`, `getmembers`, `isfunction` etc. not available                                    |
+| `asyncio`     | ❌           | Event loop, `gather`, `sleep`, `Queue`, `Task` wrappers not available; use `async`/`await`    |
+| `enum`        | ❌           | `Enum`, `IntEnum`, `Flag` not available                                                       |
+| `abc`         | ❌           | `ABC`, `abstractmethod` not available                                                         |
+| `io`          | ❌           | `StringIO`, `BytesIO` 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                                                                   |
+| `base64`      | ❌ (partial) | Partial coverage via `encodings` module; no full `base64` module                              |
+| `urllib`      | ❌           | URL parsing/encoding (`urllib.parse`) not available; use JS `URL` API                         |
+| `html`        | ❌           | `escape`, `unescape` not available; use JS DOM APIs                                           |
+| `csv`         | ❌           | CSV parsing not available                                                                     |
+| `textwrap`    | ❌           | `wrap`, `fill`, `dedent`, `indent` not available                                              |
+| `pprint`      | ❌           | Pretty-printing not available                                                                 |
+| `logging`     | ❌           | Logging framework not available; use `console.*` directly                                     |
+| `unittest`    | ❌           | Not available; RapydScript uses a custom test runner (`node bin/rapydscript test`)            |
+
+---
+
+## Semantic Differences
+
+Features that exist in RapydScript but behave differently from standard Python:
+
+| Feature | Python Behavior | RapydScript Behavior |
+|---|---|---|
+| Truthiness of `[]` / `{}` | `False` | `True` (JS semantics) unless `from __python__ import truthiness` is active |
+| `is` / `is not` | Object identity | Strict equality `===` / `!==` |
+| `//` floor division on floats | `math.floor(a/b)` always | Correct for integers; uses `Math.floor` (same result for well-behaved floats) |
+| `%` on negative numbers | Python modulo (always non-negative) | JS remainder (can be negative) |
+| `int` / `float` distinction | Separate types | Both are JS `number`; `isinstance(x, int)` and `isinstance(x, float)` use heuristics |
+| `str * n` repetition | Always works | Requires `from __python__ import overload_operators` |
+| Unbound method references | Methods are unbound by default | Same — but storing a method in a variable without the `bound_methods` compiler flag loses `self` binding |
+| `dict` key ordering | Insertion order guaranteed (3.7+) | Depends on JS engine (V8 preserves insertion order in practice) |
+| `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) |
+| `re` module | Full PCRE (lookbehind, full unicode, conditional groups) | No lookbehind; limited unicode property escapes; no `(?(1)...)` conditional groups |
+| `parenthesized with (A() as a, B() as b):` | Multiple context managers in parenthesized form (3.10+) | Not meaningful in a browser/event-driven context; multi-context `with` without parens works |
+| 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 |
+| `is` / `is not` with `NaN` | `math.nan is math.nan` → `True` (same object) | `x is NaN` compiles to `isNaN(x)` (not `x === NaN`), making NaN checks work correctly |
+| Arithmetic type coercion | `1 + '1'` raises `TypeError` | `1 + '1'` → `'11'`; JS coerces the number to a string |
+| `list + list` | Concatenation returns a new list | Now matches Python: `[1,2] + [3,4]` returns `[1, 2, 3, 4]`; `+=` extends the list in-place. No `overload_operators` flag required. (Pre-existing JS `+` coercion is replaced by a lightweight `ρσ_list_add` helper.) |
+| `<`, `>`, `<=`, `>=` on lists / containers | Element-wise lexicographic comparison | Falls through to JS coercion — operands are stringified first (e.g. `[10] < [9]` is `True` because `'[10]' < '[9]'`). Comparison dunders (`__lt__` etc.) can be defined and called directly but are not auto-dispatched by these operators. |
+| Default `{}` dict — missing key | `KeyError` raised | Returns `undefined`; use `from __python__ import dict_literals, overload_getitem` to get `KeyError` |
+| Default `{}` dict — numeric keys | Integer keys are stored as integers | Numeric keys are auto-coerced to strings by the JS engine: `d[1]` and `d['1']` refer to the same slot |
+| Default `{}` dict — attribute access | `d.foo` raises `AttributeError` | `d.foo` and `d['foo']` access the same slot; keys are also properties |
+| Default `{}` dict — Python dict methods | `.keys()`, `.values()`, `.items()`, `.get()`, `.pop()`, `.update()` all available | None of these methods exist on a plain JS object dict; use `from __python__ import dict_literals` for full Python dict semantics |
+| String methods on instances | `'hello'.strip()` works directly | Python string methods live on the `str` module object (`str.strip(s)`), not on string instances. JS native methods (`.toUpperCase()`, `.trim()`, etc.) work on instances. Call `from pythonize import strings; strings()` to copy Python methods onto string instances. |
+| `strings()` — `split()` / `replace()` | `'a b'.split()` splits on whitespace; `'aaa'.replace('a','b')` replaces all | After `strings()`, `split()` and `replace()` are **intentionally left** as JS versions: no-arg `.split()` returns a one-element array; `.replace(str, str)` replaces only the first occurrence. Use `str.split(s)` / `str.replace(s, old, new)` for Python semantics. |
+| String encoding | Unicode strings (full code-point aware) | UTF-16 — non-BMP characters (e.g. emoji) are stored as surrogate pairs. Use `str.uchrs()`, `str.uslice()`, `str.ulen()` for code-point-aware operations. |
+| Multiple inheritance MRO | C3 linearization (MRO) always deterministic | Built on JS prototype chain; may differ from Python's C3 MRO in complex or diamond-inheritance hierarchies |
+| Generators — output format | Native Python generator objects | Down-compiled to ES5 state-machine switch statements by default; pass `--js-version 6` for native ES6 generators (smaller and faster) |
+| Reserved keywords | Python keywords only | All JavaScript reserved words (`default`, `switch`, `delete`, `void`, `typeof`, etc.) are also reserved in RapydScript, since it compiles to JS |
+
+---
+
+## Test File
+
+`test/python_features.pyj` contains runnable assertions for all features surveyed.
+Features that are not supported have their test code commented out with a `# SKIP:` label
+and an explanation. Run with:
+
+```sh
+node bin/rapydscript test python_features
+```