rapydscript-ns 0.8.2 → 0.8.4

package/README.md

@@ -41,6 +41,7 @@ backwards compatible) features. For more on the forking, [see the bottom of this
 - [Extended Subscript Syntax](#extended-subscript-syntax)
 - [Variable Type Annotations](#variable-type-annotations)
 - [Regular Expressions](#regular-expressions)
+- [JSX Support](#jsx-support)
 - [Creating DOM trees easily](#creating-dom-trees-easily)
 - [Classes](#classes)
   - [External Classes](#external-classes)
@@ -108,9 +109,6 @@ Here are a few features of RapydScript:
 - similar to above, ability to use both, Python's and JavaScript's tutorials (as well as widgets)
 - it's self-hosting, that means the compiler is itself written in RapydScript and compiles into JavaScript
 
-Let's not waste any more time with the introductions, however. The best way to
-learn a new language/framework is to dive in.
-
 
 Installation
 ------------
@@ -357,17 +355,10 @@ math_ops = {
 }
 ```
 
-I'm sure you will agree that the above code is cleaner than declaring 5
-temporary variables first and assigning them to the object literal keys after.
 Note that the example puts the function header (def()) and content on the same
-line. I'll refer to it as function inlining. This is meant as a feature of
-RapydScript to make the code cleaner in cases like the example above. While you
-can use it in longer functions by chaining statements together using `;`, a
-good rule of thumb (to keep your code clean) is if your function needs
-semi-colons ask yourself whether you should be inlining, and if it needs more
-than 2 semi-colons, the answer is probably no (note that you can also use
-semi-colons as newline separators within functions that aren't inlined, as in
-the example in the previous section).
+line (function inlining). This is a feature of RapydScript that can be used
+to make the code cleaner in cases like the example above. You can also use it 
+in longer functions by chaining statements together using `;`.
 
 
 Lambda Expressions
@@ -543,7 +534,7 @@ $(element)\
 	.show()
 ```
 
-Some of you might welcome this feature, some of you might not. RapydScript always aims to make its unique features unobtrusive to regular Python, which means that you don't have to use them if you disagree with them. Recently, we have enhanced this feature to handle `do/while` loops as well:
+This feature handles `do/while` loops as well:
 
 ```js
 a = 0
@@ -646,7 +637,9 @@ into the names optional parameters you specified in the function definition.
 
 Inferred Tuple Packing/Unpacking
 --------------------------------
-Like Python, RapydScript allows inferred tuple packing/unpacking and assignment. While inferred/implicit logic is usually bad, it can sometimes make the code cleaner, and based on the order of statements in the Zen of Python, 'beautiful' takes priority over 'explicit'. For example, if you wanted to swap two variables, the following looks cleaner than explicitly declaring a temporary variable:
+Like Python, RapydScript allows inferred tuple packing/unpacking and assignment. For 
+example, if you wanted to swap two variables, the following is simpler than explicitly 
+declaring a temporary variable:
 
 ```py
 a, b = b, a
@@ -766,14 +759,19 @@ Containers (lists/sets/dicts)
 ### Lists
 
 Lists in RapydScript are almost identical to lists in Python, but are also
-native JavaScript arrays. The only small caveats are that the ``sort()`` and
-``pop()`` methods are renamed to ``pysort()`` and ``pypop()``. This is so that
-you can pass RapydScript lists to external JavaScript libraries without any
-conflicts. Note that even list literals in RapydScript create python like list
-objects, and you can also use the builtin ``list()`` function to create lists
-from other iterable objects, just as you would in python.  You can create a
-RapydScript list from a plain native JavaScript array by using the ``list_wrap()``
-function, like this:
+native JavaScript arrays. The ``sort()`` and ``pop()`` methods behave exactly
+as in Python: ``sort()`` performs a numeric sort (in-place, with optional ``key``
+and ``reverse`` arguments) and ``pop()`` performs a bounds-checked pop (raises
+``IndexError`` for out-of-bounds indices). If you need the native JavaScript
+behavior for interop with external JS libraries, use ``jssort()`` (lexicographic
+sort) and ``jspop()`` (no bounds check, always pops the last element). The old
+``pysort()`` and ``pypop()`` names are kept as backward-compatible aliases.
+
+Note that even list literals in RapydScript create Python-like list objects,
+and you can also use the builtin ``list()`` function to create lists from other
+iterable objects, just as you would in Python. You can create a RapydScript
+list from a plain native JavaScript array by using the ``list_wrap()`` function,
+like this:
 
 ```py
 a = v'[1, 2]'
@@ -781,13 +779,36 @@ pya = list_wrap(a)
  # Now pya is a python like list object that satisfies pya === a
 ```
 
+### List Concatenation
+
+The `+` operator concatenates two lists and returns a new list, exactly as in Python:
+
+```py
+a = [1, 2]
+b = [3, 4]
+c = a + b   # [1, 2, 3, 4]  — a and b are unchanged
+```
+
+The `+=` operator extends a list in-place (the original list object is mutated):
+
+```py
+a = [1, 2]
+ref = a      # ref and a point to the same list
+a += [3, 4]  # mutates a in-place
+print(ref)   # [1, 2, 3, 4]  — ref sees the update
+```
+
+No special flag is required. The `+` operator compiles to a lightweight helper
+(`ρσ_list_add`) that uses `Array.concat` for lists and falls back to native JS
+`+` for numbers and strings.
+
 ### Sets
 
 Sets in RapydScript are identical to those in python. You can create them using
 set literals or comprehensions and all set operations are supported. You can
-store any object in a set, the only caveat is that RapydScript does not support
-the ``__hash__()`` method, so if you store an arbitrary object as opposed to a
-primitive type, object equality will be via the ``is`` operator.
+store any object in a set. For primitive types (strings, numbers) the value is
+used for equality; for class instances, object identity (``is``) is used by
+default unless the class defines a ``__hash__`` method.
 
 Note that sets are not a subclass of the ES 6 JavaScript Set object, however,
 they do use this object as a backend, when available. You can create a set from
@@ -815,8 +836,8 @@ a in s  # True
 [1, 2] in s # False
 ```
 
-This is because, as noted above, object equality is via the ```is```
-operator, not hashes.
+This is because list identity (not value) determines set membership for mutable
+objects. Define ``__hash__`` on your own classes to control set/dict membership.
 
 ### Dicts
 
@@ -865,6 +886,63 @@ a = {1:1, 2:2}
 isinstance(a, dict) == False # a is a normal JavaScript object
 ```
 
+### List spread literals
+
+RapydScript supports Python's `*expr` spread syntax inside list literals.
+One or more `*expr` items can appear anywhere, interleaved with ordinary
+elements:
+
+```py
+a = [1, 2, 3]
+b = [4, 5]
+
+# Spread at the end
+result = [0, *a]            # [0, 1, 2, 3]
+
+# Spread in the middle
+result = [0, *a, *b, 6]     # [0, 1, 2, 3, 4, 5, 6]
+
+# Copy a list
+copy = [*a]                 # [1, 2, 3]
+
+# Unpack a string
+chars = [*'hello']          # ['h', 'e', 'l', 'l', 'o']
+```
+
+Spread works on any iterable (lists, strings, generators, `range()`).
+The result is always a new Python list.  Translates to JavaScript's
+`[...expr]` spread syntax.
+
+### Set spread literals
+
+The same `*expr` syntax works inside set literals `{...}`:
+
+```py
+a = [1, 2, 3]
+b = [3, 4, 5]
+
+s = {*a, *b}                # set([1, 2, 3, 4, 5]) — duplicates removed
+s2 = {*a, 10}               # set([1, 2, 3, 10])
+```
+
+Translates to `ρσ_set([...a, ...b])`.
+
+### `**expr` in function calls
+
+`**expr` in a function call now accepts any expression, not just a plain
+variable name:
+
+```py
+def f(x=0, y=0):
+    return x + y
+
+opts = {'x': 10, 'y': 20}
+f(**opts)                   # 30  (variable — always worked)
+f(**{'x': 1, 'y': 2})      # 3   (dict literal)
+f(**cfg.defaults)           # uses attribute access result
+f(**get_opts())             # uses function call result
+```
+
 ### Dict merge literals
 
 RapydScript supports Python's `{**d1, **d2}` dict merge (spread) syntax.
@@ -1153,7 +1231,8 @@ semantics:
 | other `float` | derived from the bit pattern |
 | `str` | djb2 algorithm — stable within a process |
 | object with `__hash__` | dispatches to `__hash__()` |
-| class instance | stable identity hash (assigned on first call) |
+| class instance (no `__hash__`) | stable identity hash (assigned on first call) |
+| class with `__eq__` but no `__hash__` | `TypeError` (unhashable — Python semantics) |
 | `list` | `TypeError: unhashable type: 'list'` |
 | `set` | `TypeError: unhashable type: 'set'` |
 | `dict` | `TypeError: unhashable type: 'dict'` |
@@ -1173,8 +1252,67 @@ class Point:
         return self.x * 31 + self.y
 
 hash(Point(1, 2))  # 33
+
+# Python semantics: __eq__ without __hash__ → unhashable
+class Bar:
+    def __eq__(self, other):
+        return True
+hash(Bar())  # TypeError: unhashable type: 'Bar'
 ```
 
+### Attribute-Access Dunders
+
+RapydScript supports the four Python attribute-interception hooks:
+`__getattr__`, `__setattr__`, `__delattr__`, and `__getattribute__`.
+When a class defines any of them, instances are automatically wrapped in a
+JavaScript `Proxy` that routes attribute access through the hooks — including
+accesses that occur inside `__init__`.
+
+| Hook | When called |
+|---|---|
+| `__getattr__(self, name)` | Fallback — only called when normal lookup finds nothing |
+| `__setattr__(self, name, value)` | Every attribute assignment (including `self.x = …` in `__init__`) |
+| `__delattr__(self, name)` | Every `del obj.attr` |
+| `__getattribute__(self, name)` | Every attribute read (overrides normal lookup) |
+
+To bypass the hooks from within the hook itself (avoiding infinite recursion),
+use the `object.*` bypass functions:
+
+| Python idiom | Compiled form | Effect |
+|---|---|---|
+| `object.__setattr__(self, name, val)` | `ρσ_object_setattr(self, name, val)` | Set attribute directly, bypassing `__setattr__` |
+| `object.__getattribute__(self, name)` | `ρσ_object_getattr(self, name)` | Read attribute directly, bypassing `__getattribute__` |
+| `object.__delattr__(self, name)` | `ρσ_object_delattr(self, name)` | Delete attribute directly, bypassing `__delattr__` |
+
+Subclasses automatically inherit proxy wrapping from their parent class — if
+`Base` defines `__getattr__`, all `Child(Base)` instances are also Proxy-wrapped.
+
+```py
+class Validated:
+    """Reject negative values at assignment time."""
+    def __setattr__(self, name, value):
+        if jstype(value) is 'number' and value < 0:
+            raise ValueError(name + ' must be non-negative')
+        object.__setattr__(self, name, value)
+
+v = Validated()
+v.x = 5    # ok
+v.x = -1   # ValueError: x must be non-negative
+
+class AttrProxy:
+    """Log every attribute read."""
+    def __init__(self):
+        object.__setattr__(self, '_log', [])
+
+    def __getattribute__(self, name):
+        self._log.append(name)          # self._log goes through __getattribute__ too!
+        return object.__getattribute__(self, name)
+```
+
+> **Proxy support required** — The hooks rely on `Proxy`, which is available
+> in all modern browsers and Node.js ≥ 6. In environments that lack `Proxy`
+> the class still works, but the hooks are silently bypassed.
+
 Loops
 -----
 RapydScript's loops work like Python, not JavaScript. You can't, for example
@@ -1346,6 +1484,20 @@ str.format('{0:02d} {n}', 1, n=2) == '01 2'
 ...
 ```
 
+The `format(value[, spec])` builtin is also supported. It applies the Python
+format-spec mini-language to a single value — the same mini-language that
+follows `:` in f-strings and `str.format()` fields:
+
+```py
+format(42, '08b')     # '00101010'  — zero-padded binary
+format(3.14159, '.2f') # '3.14'     — fixed-point
+format('hi', '>10')   # '        hi' — right-aligned in 10-char field
+format(42)            # '42'        — no spec: same as str(42)
+```
+
+Objects with a `__format__` method are dispatched to it, matching Python's
+protocol exactly.
+
 String predicate methods are also available:
 
 ```py
@@ -1371,6 +1523,16 @@ Case-folding for locale-insensitive lowercase comparison:
 str.casefold('ÄÖÜ') == str.casefold('äöü')  # True (maps to lowercase)
 ```
 
+Tab expansion:
+
+```py
+str.expandtabs('a\tb', 4)   # 'a   b'  — expand to next 4-space tab stop
+str.expandtabs('\t\t', 8)   # '                '  — two full tab stops
+str.expandtabs('ab\tc', 4)  # 'ab  c'  — only 2 spaces needed to reach next stop
+```
+
+The optional `tabsize` argument defaults to `8`, matching Python's default. A `tabsize` of `0` removes all tab characters. Newline (`\n`) and carriage-return (`\r`) characters reset the column counter, so each line is expanded independently.
+
 However, if you want to make the python string methods available on string
 objects, there is a convenience method in the standard library to do so. Use
 the following code:
@@ -1578,6 +1740,7 @@ can annotate a variable with a type hint, with or without an initial value:
 x: int = 42
 name: str = "Alice"
 items: list = [1, 2, 3]
+coords: tuple = (10, 20)
 
 # Annotation only: declares the type without assigning a value
 count: int
@@ -1650,6 +1813,353 @@ re.match(///
   ///, 'ab')
 ```
 
+JSX Support
+-----------
+
+RapydScript supports JSX syntax for building React UI components. JSX elements compile directly to `React.createElement()` calls, so the output is plain JavaScript — no Babel or JSX transform step is needed.
+
+Enable JSX support with:
+
+```py
+from __python__ import jsx
+```
+
+### Requirements
+
+`React` must be in scope at runtime. How you provide it depends on your environment:
+
+- **Bundler (Vite, webpack, etc.):** `import React from 'react'` at the top of your file (or configure your bundler's global React shim).
+- **CDN / browser script tag:** load React before your compiled script.
+- **Bitburner:** React is already available as a global — no import needed.
+- **RapydScript web REPL:** a minimal React stub is injected automatically so `React.createElement` calls succeed.
+
+### Output format
+
+RapydScript compiles JSX to `React.createElement()` calls. For example:
+
+```py
+from __python__ import jsx
+
+def Greeting(props):
+    return <h1>Hello, {props.name}!</h1>
+```
+
+Compiles to:
+
+```js
+function Greeting(props) {
+    return React.createElement("h1", null, "Hello, ", props.name);
+}
+```
+
+Lowercase tags (`div`, `span`, `h1`, …) become string arguments. Capitalised names and dot-notation (`MyComponent`, `Router.Route`) are passed as references — not strings.
+
+### Attributes
+
+String, expression, boolean, and hyphenated attribute names all work:
+
+```py
+from __python__ import jsx
+
+def Form(props):
+    return (
+        <form>
+            <input
+                type="text"
+                aria-label="Name"
+                disabled={props.readonly}
+                onChange={props.onChange}
+                required
+            />
+        </form>
+    )
+```
+
+Hyphenated names (e.g. `aria-label`, `data-id`) are automatically quoted as object keys: `{"aria-label": "Name"}`. Boolean attributes with no value compile to `true`.
+
+### Nested elements and expressions
+
+```py
+from __python__ import jsx
+
+def UserList(users):
+    return (
+        <ul className="user-list">
+            {[<li key={u.id}>{u.name}</li> for u in users]}
+        </ul>
+    )
+```
+
+### Fragments
+
+Use `<>...</>` to return multiple elements without a wrapper node. Fragments compile to `React.createElement(React.Fragment, null, ...)`:
+
+```py
+from __python__ import jsx
+
+def TwoItems():
+    return (
+        <>
+            <span>First</span>
+            <span>Second</span>
+        </>
+    )
+```
+
+### Self-closing elements
+
+```py
+from __python__ import jsx
+
+def Avatar(props):
+    return <img src={props.url} alt={props.name} />
+```
+
+### Spread attributes
+
+```py
+from __python__ import jsx
+
+def Button(props):
+    return <button {...props}>Click me</button>
+```
+
+Compiles to `React.createElement("button", {...props}, "Click me")`.
+
+### Component tags
+
+Capitalised names and dot-notation are treated as component references (not quoted strings):
+
+```py
+from __python__ import jsx
+
+def App():
+    return (
+        <Router.Provider>
+            <MyComponent name="hello" />
+        </Router.Provider>
+    )
+```
+
+Compiles to:
+
+```js
+React.createElement(Router.Provider, null,
+    React.createElement(MyComponent, {name: "hello"})
+)
+```
+
+### Compiling JSX files
+
+Since the output is plain JavaScript, compile to a `.js` file as normal:
+
+```sh
+rapydscript mycomponent.pyj --output mycomponent.js
+```
+
+React Standard Library
+-----------------------
+
+RapydScript ships a `react` standard library module that re-exports every standard React hook and utility under their familiar Python-friendly names.  Import the pieces you need and the compiler will resolve each name to the corresponding `React.*` property at compile time.
+
+### Importing hooks
+
+```py
+from __python__ import jsx
+from react import useState, useEffect, useCallback, useMemo, useRef
+
+def Counter():
+    count, setCount = useState(0)
+
+    def increment():
+        setCount(count + 1)
+
+    return <button onClick={increment}>{count}</button>
+```
+
+Compiles to:
+
+```js
+var useState = React.useState;
+// ...
+function Counter() {
+    var [count, setCount] = React.useState(0);
+    function increment() {
+        setCount(count + 1);
+    }
+    return React.createElement("button", {onClick: increment}, count);
+}
+```
+
+Tuple unpacking works naturally because `React.useState` returns a two-element array — `count, setCount = useState(0)` compiles to the ES6 destructuring `var [count, setCount] = React.useState(0)`.
+
+### Available exports
+
+**Hooks (React 16.8+)**
+
+| Import name | React API |
+|---|---|
+| `useState` | `React.useState` |
+| `useEffect` | `React.useEffect` |
+| `useContext` | `React.useContext` |
+| `useReducer` | `React.useReducer` |
+| `useCallback` | `React.useCallback` |
+| `useMemo` | `React.useMemo` |
+| `useRef` | `React.useRef` |
+| `useImperativeHandle` | `React.useImperativeHandle` |
+| `useLayoutEffect` | `React.useLayoutEffect` |
+| `useDebugValue` | `React.useDebugValue` |
+
+**Hooks (React 18+)**
+
+| Import name | React API |
+|---|---|
+| `useId` | `React.useId` |
+| `useTransition` | `React.useTransition` |
+| `useDeferredValue` | `React.useDeferredValue` |
+| `useSyncExternalStore` | `React.useSyncExternalStore` |
+| `useInsertionEffect` | `React.useInsertionEffect` |
+
+**Core classes and elements**
+
+| Import name | React API |
+|---|---|
+| `Component` | `React.Component` |
+| `PureComponent` | `React.PureComponent` |
+| `Fragment` | `React.Fragment` |
+| `StrictMode` | `React.StrictMode` |
+| `Suspense` | `React.Suspense` |
+| `Profiler` | `React.Profiler` |
+
+**Utilities**
+
+| Import name | React API |
+|---|---|
+| `createElement` | `React.createElement` |
+| `cloneElement` | `React.cloneElement` |
+| `createContext` | `React.createContext` |
+| `createRef` | `React.createRef` |
+| `forwardRef` | `React.forwardRef` |
+| `isValidElement` | `React.isValidElement` |
+| `memo` | `React.memo` |
+| `lazy` | `React.lazy` |
+
+### Common patterns
+
+**useEffect with cleanup**
+
+```py
+from react import useState, useEffect
+
+def Timer():
+    count, setCount = useState(0)
+    def setup():
+        interval = setInterval(def(): setCount(count + 1);, 1000)
+        def cleanup():
+            clearInterval(interval)
+        return cleanup
+    useEffect(setup, [count])
+    return count
+```
+
+**useReducer**
+
+```py
+from react import useReducer
+
+def reducer(state, action):
+    if action.type == 'increment':
+        return state + 1
+    if action.type == 'decrement':
+        return state - 1
+    return state
+
+def Counter():
+    state, dispatch = useReducer(reducer, 0)
+    def inc():
+        dispatch({'type': 'increment'})
+    return state
+```
+
+**useContext**
+
+```py
+from react import createContext, useContext
+
+ThemeContext = createContext('light')
+
+def ThemedButton():
+    theme = useContext(ThemeContext)
+    return theme
+```
+
+**useRef**
+
+```py
+from __python__ import jsx
+from react import useRef
+
+def FocusInput():
+    inputRef = useRef(None)
+    def handleClick():
+        inputRef.current.focus()
+    return <input ref={inputRef} />
+```
+
+**memo**
+
+```py
+from __python__ import jsx
+from react import memo
+
+def Row(props):
+    return <li>{props.label}</li>
+
+MemoRow = memo(Row)
+```
+
+**forwardRef**
+
+```py
+from __python__ import jsx
+from react import forwardRef
+
+def FancyInput(props, ref):
+    return <input ref={ref} placeholder={props.placeholder} />
+
+FancyInputWithRef = forwardRef(FancyInput)
+```
+
+**Class component**
+
+You can extend `React.Component` directly without importing it, or import `Component` from the `react` module:
+
+```py
+from __python__ import jsx
+from react import Component
+
+class Greeter(Component):
+    def render(self):
+        return <h1>Hello, {self.props.name}!</h1>
+```
+
+**useTransition (React 18)**
+
+```py
+from react import useState, useTransition
+
+def SearchInput():
+    isPending, startTransition = useTransition()
+    query, setQuery = useState('')
+    def handleChange(e):
+        startTransition(def(): setQuery(e.target.value);)
+    return isPending
+```
+
+### Requirements
+
+The `react` module does not bundle React itself — it provides compile-time name bindings only.  `React` must be available as a global variable at runtime, exactly as described in the [JSX Requirements](#requirements) section above.
+
 Creating DOM trees easily
 ---------------------------------
 
@@ -1697,7 +2207,7 @@ E.a(onclick=def():
 
 Classes
 -------
-This is where RapydScript really starts to shine. JavaScript is known for having really crappy class implementation (it's basically a hack on top of a normal function, most experienced users suggest using external libraries for creating those instead of creating them in pure JavaScript). Luckily RapydScript fixes that. Let's imagine we want a special text field that takes in a user color string and changes color based on it. Let's create such field via a class.
+JavaScript is not known for having excellent class implementation - but RapydScript improves on that. Imagine we want a special text field that takes in a user color string and changes color based on it. Let's create such field via a class:
 
 ```js
 class ColorfulTextField:
@@ -1880,6 +2390,176 @@ print(Counter.get_count())  # 2
 
 The `@classmethod` decorator compiles to a method placed directly on the class (not its prototype), with `cls` mapped to `this`. A prototype delegation shim is also generated so instance calls work correctly.
 
+### `__new__` Constructor Hook
+
+RapydScript supports Python's `__new__` method, which runs *before* `__init__` and controls instance creation. Use it to implement patterns like singletons or alternative constructors:
+
+```py
+class Singleton:
+    _instance = None
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    def __init__(self):
+        pass
+
+a = Singleton()
+b = Singleton()
+assert a is b  # same instance
+```
+
+`super().__new__(cls)` creates a bare instance of `cls` (equivalent to `Object.create(cls.prototype)` in JavaScript). If `__new__` returns an instance of the class, `__init__` is called on it automatically. If it returns something else, `__init__` is skipped.
+
+Class variables accessed via `cls` inside `__new__` are correctly rewritten to `cls.prototype.varname`, matching Python's semantics.
+
+### `__class_getitem__`
+
+RapydScript supports Python's `__class_getitem__` hook, which enables subscript syntax on a class itself (`MyClass[item]`).  Define `__class_getitem__(cls, item)` in a class body to intercept `ClassName[x]`:
+
+```py
+class Box:
+    def __class_getitem__(cls, item):
+        return cls.__name__ + '[' + str(item) + ']'
+
+print(Box[int])   # Box[<class 'int'>]
+print(Box['str']) # Box[str]
+```
+
+`__class_getitem__` is an implicit `@classmethod`: the compiler strips `cls` from the JS parameter list and maps it to `this`, so calling `Box[item]` compiles to `Box.__class_getitem__(item)` with `this = Box`.
+
+Subclasses inherit `__class_getitem__` from their parent and receive the subclass as `cls`:
+
+```py
+class Base:
+    def __class_getitem__(cls, item):
+        return cls.__name__ + '<' + str(item) + '>'
+
+class Child(Base):
+    pass
+
+print(Base[42])   # Base<42>
+print(Child[42])  # Child<42>
+```
+
+Class variables declared in the class body are accessible via `cls.varname` inside `__class_getitem__`, just as with `@classmethod`.
+
+### `__init_subclass__`
+
+`__init_subclass__` is a hook that is called automatically on a base class whenever a subclass is created.  It is an implicit `@classmethod`: the compiler strips `cls` from the JS signature and maps it to `this`, so `cls` receives the newly-created subclass.
+
+```py
+class PluginBase:
+    _plugins = []
+
+    def __init_subclass__(cls, **kwargs):
+        PluginBase._plugins.append(cls)
+
+class AudioPlugin(PluginBase):
+    pass
+
+class VideoPlugin(PluginBase):
+    pass
+
+print(len(PluginBase._plugins))     # 2
+print(PluginBase._plugins[0].__name__)  # AudioPlugin
+```
+
+Keyword arguments written in the class header are forwarded to `__init_subclass__`:
+
+```py
+class Base:
+    def __init_subclass__(cls, required=False, **kwargs):
+        cls._required = required
+
+class Strict(Base, required=True):
+    pass
+
+class Loose(Base):
+    pass
+
+print(Strict._required)   # True
+print(Loose._required)    # False
+```
+
+Use `super().__init_subclass__(**kwargs)` to propagate the hook up the hierarchy:
+
+```py
+class GrandParent:
+    def __init_subclass__(cls, **kwargs):
+        cls._from_grandparent = True
+
+class Parent(GrandParent):
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)   # propagates to GrandParent
+
+class Child(Parent):
+    pass
+
+print(Child._from_grandparent)   # True
+```
+
+The hook is called after the subclass is fully set up (including `__name__`, `__qualname__`, and `__module__`), so `cls.__name__` is always the correct subclass name inside the hook.
+
+### Nested Classes
+
+A class may be defined inside another class. The nested class becomes an attribute of the outer class (accessible as `Outer.Inner`) and is also reachable via instances (`self.Inner` inside methods). This mirrors Python semantics exactly.
+
+```py
+class Molecule:
+    class Atom:
+        def __init__(self, element):
+            self.element = element
+        def __repr__(self):
+            return 'Atom(' + self.element + ')'
+
+    def __init__(self, elements):
+        self.structure = []
+        for e in elements:
+            self.structure.push(Molecule.Atom(e))
+
+water = Molecule(['H', 'H', 'O'])
+print(len(water.structure))          # 3
+print(water.structure[0].element)    # H
+print(isinstance(water.structure[0], Molecule.Atom))  # True
+```
+
+The nested class is a full class in every respect — it can have its own methods, inherit from other classes, and contain further nested classes:
+
+```py
+class Universe:
+    class Galaxy:
+        class Star:
+            def __init__(self, name):
+                self.name = name
+        def __init__(self, star_name):
+            self.star = Universe.Galaxy.Star(star_name)
+    def __init__(self, star_name):
+        self.galaxy = Universe.Galaxy(star_name)
+
+u = Universe('Sol')
+print(u.galaxy.star.name)                    # Sol
+print(isinstance(u.galaxy.star, Universe.Galaxy.Star))  # True
+```
+
+A nested class may also inherit from classes defined in the outer scope:
+
+```py
+class Animal:
+    def __init__(self, sound):
+        self.sound = sound
+
+class Zoo:
+    class Dog(Animal):
+        def __init__(self):
+            Animal.__init__(self, 'woof')
+
+fido = Zoo.Dog()
+print(fido.sound)             # woof
+print(isinstance(fido, Animal))    # True
+print(isinstance(fido, Zoo.Dog))   # True
+```
+
 ### External Classes
 
 RapydScript will automatically detect classes declared within the same scope (as long as the declaration occurs before use), as well as classes properly imported into the module (each module making use of a certain class should explicitly import the module containing that class). RapydScript will also properly detect native JavaScript classes (String, Array, Date, etc.). Unfortunately, RapydScript has no way of detecting classes from third-party libraries. In those cases, you could use the `new` keyword every time you create an object from such class. Alternatively, you could mark the class as external.
@@ -2029,6 +2709,26 @@ next(it)         # raises StopIteration
 When the iterator is exhausted and no default is given, ``StopIteration``
 is raised — matching standard Python behaviour.
 
+The two-argument form ``iter(callable, sentinel)`` repeatedly calls
+``callable`` (with no arguments) and yields each return value until it equals
+``sentinel``, at which point the iterator stops:
+
+```python
+count = [0]
+def next_val():
+    count[0] += 1
+    return count[0]
+
+list(iter(next_val, 4))   # [1, 2, 3]
+
+for val in iter(next_val, 7):
+    print(val)            # 5, 6
+```
+
+The callable may be any function or object with a ``__call__`` method.
+Sentinel comparison uses strict equality (``===``), matching Python's
+``is``-then-``==`` semantics for the common case of plain values.
+
 Generators
 ------------
 
@@ -2039,18 +2739,19 @@ def f():
 	for i in range(3):
 		yield i
 
-[x for x in f()] == [1, 2, 3]
+[x for x in f()] == [0, 1, 2]
 ```
 
 There is full support for generators including the Python 3, ```yield from```
-syntax. 
+syntax.
 
 Generators create JavaScript iterator objects. For differences between python
-and JavaScript iterators, see the section on iterators above. 
+and JavaScript iterators, see the section on iterators above.
 
-Currently, generators are down-converted to ES 5 switch statements. In the
-future, when ES 6 support is widespread, they will be converted to native
-JavaScript ES 6 generators.
+By default, generators are down-converted to ES 5 switch statements. Pass
+``--js-version 6`` to the compiler (or set ``js_version: 6`` in the embedded
+compiler options) to emit native ES 6 generator functions instead, which are
+smaller and faster.
 
 Modules
 -------
@@ -2191,7 +2892,7 @@ finally:
 ```
 
 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]. 
+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):
@@ -2236,6 +2937,45 @@ except SomeInternalError:
 
 Basically, `try/except/finally` in RapydScript works very similar to the way it does in Python 3.
 
+### Exception Groups (`except*`, Python 3.11+)
+
+RapydScript supports exception groups via the `ExceptionGroup` class and `except*` syntax. An `ExceptionGroup` bundles multiple exceptions under a single message:
+
+```py
+eg = ExceptionGroup("network errors", [
+    TimeoutError("host A timed out"),
+    TimeoutError("host B timed out"),
+    ValueError("bad address"),
+])
+raise eg
+```
+
+Use `except*` to handle exceptions by type — each handler receives a sub-group containing only the matching exceptions:
+
+```py
+try:
+    fetch_all()
+except* TimeoutError as group:
+    for e in group.exceptions:
+        print("timeout:", e)
+except* ValueError as group:
+    print("bad input:", group.exceptions[0])
+```
+
+- Each `except*` clause sees the exceptions not already matched by earlier clauses.
+- Any unmatched exceptions are automatically re-raised as a new `ExceptionGroup`.
+- A bare `except*:` (no type) catches all remaining exceptions.
+- You cannot mix `except` and `except*` in the same `try` block.
+- Plain (non-group) exceptions can also be caught with `except*`; the variable is bound to the exception itself rather than a sub-group.
+
+`ExceptionGroup` also provides `subgroup(condition)` and `split(condition)` for programmatic filtering, where `condition` is either an exception class or a predicate function:
+
+```py
+eg = ExceptionGroup("mixed", [ValueError("v"), TypeError("t")])
+ve_group = eg.subgroup(ValueError)          # ExceptionGroup of just ValueErrors
+matched, rest = eg.split(ValueError)        # (ve_group, te_group)
+```
+
 Scope Control
 -------------
 
@@ -2288,30 +3028,32 @@ Shadowing is preferred in most cases, since it can't accidentally damage outside
 Available Libraries
 -------------------
 
-One of Python's main strengths is the number of libraries available to the developer. This is something very few other `Python-in-a-browser` frameworks understand. In the browser JavaScript is king, and no matter how many libraries the community for the given project will write, the readily-available JavaScript libraries will always outnumber them. This is why RapydScript was designed with JavaScript and DOM integration in mind from the beginning. Indeed, plugging `underscore.js` in place of RapydScript's `stdlib` will work just as well, and some developers may choose to do so, after all, `underscore.js` is very Pythonic and very complete. 
+One of Python's main strengths is the number of libraries available to the developer. The large number of readily-available JavaScript libraries will always outnumber community-made Rapydscript libraries. This is why RapydScript was designed with JS and DOM integration in mind from the beginning. For example, plugging in `lodash` in place of RapydScript's `stdlib` will work fine!
 
-It is for that reason that I try to keep RapydScript bells and whistles to a minimum. RapydScript's main strength is easy integration with JavaScript and DOM, which allows me to stay sane and not rewrite my own versions of the libraries that are already available. That doesn't mean, however, that pythonic libraries can't be written for RapydScript. To prove that, I have implemented lightweight clones of several popular Python libraries and bundled them into RapydScript, you can find them in `src` directory. The following libraries are included:
+ RapydScript's main strength is easy integration with JavaScript and DOM, and easy use of libraries that are already available. That doesn't mean, however, that pythonic libraries can't be written for RapydScript. Rapydscript comes with lightweight clones of several popular Python libraries, which you can find them in `src` directory.
 
 	math                # replicates almost all of the functionality from Python's math library
 	re                  # replicates almost all of the functionality from Python's re library
 	random              # replicates most of the functionality from Python's random library
+	numpy               # NumPy-compatible array library (ndarray, ufuncs, numpy.random, numpy.linalg)
 	elementmaker        # easily construct DOM trees
 	aes                 # Implement AES symmetric encryption
 	encodings           # Convert to/from UTF-8 bytearrays, base64 strings and native strings
 	gettext             # Support for internationalization of your RapydScript app
-	operator            # a subset of python;s operator module
+	operator            # a subset of Python's operator module
 	functools           # reduce, partial, wraps, lru_cache, cache, total_ordering, cmp_to_key
 	collections         # namedtuple, deque, Counter, OrderedDict, defaultdict
+	copy                # copy (shallow), deepcopy; honours __copy__ / __deepcopy__ hooks
 	itertools           # count, cycle, repeat, accumulate, chain, compress, dropwhile, filterfalse,
 	                    # groupby, islice, pairwise, starmap, takewhile, zip_longest,
 	                    # product, permutations, combinations, combinations_with_replacement
 
-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 to implement them (it's fun to do, `re.pyj` is a good example), but I want to reemphasize that 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.
+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.
 
 Linter
 ---------
 
-The RapydScript compiler includes its own, built in linter. The linter is
+The RapydScript compiler includes its own, built-in linter. The linter is
 modeled on pyflakes, it catches instances of unused/undefined variables,
 functions, symbols, etc. While this sounds simple, it is surprisingly effective
 in practice. To run the linter:
@@ -2391,13 +3133,12 @@ RapydScript will pick up any classes you declare yourself as well as native
 JavaScript classes. It will not, however, pick up class-like objects created by
 outside frameworks. There are two approaches for dealing with those. One is via
 `@external` decorator, the other is via `new` operator when declaring such
-object. To keep code legible and consistent, I strongly prefer the use of
-`@external` decorator over the `new` operator for several reasons, even if it
-may be more verbose:
+object. The `@external` decorator is recommended over the `new` operator for 
+several reasons, even if it may be more verbose:
 
 - `@external` decorator makes classes declared externally obvious to anyone looking at your code
 - class declaration that uses `@external` decorator can be exported into a reusable module
-- developers are much more likely to forget a single instance of `new` operator when declaring an object than to forget an import, the errors due to omitted `new` keyword are also likely to be more subtle and devious to debug
+- developers are much more likely to forget a single instance of `new` operator when declaring an object than to forget an import. the errors due to omitted `new` keyword are also likely to be more subtle and devious to debug
 
 #### Embedding the RapydScript compiler in your webpage
 
@@ -2417,7 +3158,7 @@ HTML below for an example.
     <head>
         <meta charset="UTF-8">
         <title>Test embedded RapydScript</title>
-        <script charset="UTF-8" src="https://github.com/ficocelliguy/rapydscript-ns/blob/master/web-repl/rapydscript.js"></script>
+        <script charset="UTF-8" src="rapydscript.js"></script>
         <script>
 var compiler = RapydScript.create_embedded_compiler();
 var js = compiler.compile("def hello_world():\n a='RapydScript is cool!'\n print(a)\n alert(a)");
@@ -2511,9 +3252,10 @@ to an experienced Python developer. The most important such gotchas are listed
 below:
 
 - Truthiness in JavaScript is very different from Python. Empty lists and dicts
-  are ``False`` in Python but ``True`` in JavaScript. The compiler could work
-  around that, but not without a significant performance cost, so it is best to
-  just get used to checking the length instead of the object directly.
+  are ``False`` in Python but ``True`` in JavaScript. You can opt in to full
+  Python truthiness semantics (where empty containers are falsy and ``__bool__``
+  is dispatched) with ``from __python__ import truthiness``. Without that flag,
+  test the length explicitly instead of the container directly.
 
 - Operators in JavaScript are very different from Python. ``1 + '1'`` would be
   an error in Python, but results in ``'11'`` in JavaScript. Similarly, ``[1] +
@@ -2546,6 +3288,31 @@ below:
   should use a scoped flag. See the section on dictionaries above for details.
 
 
+Python Flags
+------------
+
+Python flags are scoped compiler directives that opt in to stricter Python
+semantics or language features.  In source code they are written as:
+
+```py
+from __python__ import flag_name
+```
+
+At the top level they take effect for the rest of the file; inside a function
+or class body they apply only to that scope.  Prefix a flag with `no_` to turn
+it off in a nested scope.
+
+| Flag | Description |
+|---|---|
+| `dict_literals` | `{k: v}` literals create Python `dict` objects instead of plain JS objects. |
+| `overload_getitem` | `obj[key]` dispatches to `__getitem__` / `__setitem__` / `__delitem__` on objects that define them. |
+| `overload_operators` | Arithmetic and bitwise operators (`+`, `-`, `*`, `/`, `//`, `%`, `**`, `&`, `\|`, `^`, `<<`, `>>`) dispatch to dunder methods (`__add__`, `__sub__`, etc.) and their reflected variants. Unary `-`/`+`/`~` dispatch to `__neg__`/`__pos__`/`__invert__`. |
+| `truthiness` | Boolean tests and `bool()` dispatch to `__bool__` and treat empty containers as falsy, matching Python semantics. |
+| `bound_methods` | Method references (`obj.method`) are automatically bound to their object, so they can be passed as callbacks without losing `self`. |
+| `hash_literals` | `{k: v}` creates a Python `dict` (alias for `dict_literals`; kept for backward compatibility). |
+| `jsx` | Enable JSX syntax (`<Tag attr={expr}>children</Tag>`). Required for files that contain JSX elements. |
+
+
 Monaco Language Service
 -----------------------
 
@@ -2574,7 +3341,7 @@ npm run build:ls
 node tools/build-language-service.js --out path/to/language-service.js
 ```
 
-The output is written to `web-repl/language-service.js` by default.
+The output is written to `language-service/index.js` by default.
 
 ### Basic setup
 
@@ -2607,9 +3374,11 @@ when the editor is torn down.
 | `compiler` | object | — | **Required.** The `window.RapydScript` compiler bundle. |
 | `parseDelay` | number | `300` | Debounce delay (ms) before re-checking after an edit. |
 | `virtualFiles` | `{name: source}` | `{}` | Virtual modules available to `import` statements. |
+| `stdlibFiles` | `{name: source}` | `{}` | Like `virtualFiles` but treated as stdlib — always available and never produce bad-import warnings. |
 | `dtsFiles` | `[{name, content}]` | `[]` | TypeScript `.d.ts` files loaded at startup. |
 | `loadDts` | `(name) => Promise<string>` | — | Async callback for lazy-loading `.d.ts` content on demand. |
 | `extraBuiltins` | `{name: true}` | `{}` | Extra global names that suppress undefined-symbol warnings. |
+| `pythonFlags` | string | — | Comma-separated Python flags to enable globally (e.g. `"dict_literals,overload_getitem"`). See [Python Flags](#python-flags) above. |
 
 ### Runtime API
 
@@ -2629,6 +3398,9 @@ service.loadDts('lib.dom').then(function () { console.log('DOM types loaded'); }
 // Suppress undefined-symbol warnings for additional global names
 service.addGlobals(['myFrameworkGlobal', '$']);
 
+// Get the most recently built scope map for a Monaco model (null if not yet analysed)
+var scopeMap = service.getScopeMap(editorModel);
+
 // Tear down all Monaco providers and event listeners
 service.dispose();
 ```
@@ -2752,6 +3524,13 @@ original `.py` file with working breakpoints and correct error stack frames.
 | `keep_docstrings` | bool | `false` | Keep docstrings in the output. |
 | `js_version` | number | `6` | Target ECMAScript version (5 or 6). |
 | `private_scope` | bool | `false` | Wrap the output in an IIFE. |
+| `python_flags` | string | — | Comma-separated Python flags to enable for this compilation (e.g. `"dict_literals,overload_operators"`). See [Python Flags](#python-flags) above. Flags set here override any inherited from a previous `compile()` call on a streaming compiler. |
+| `virtual_files` | `{name: source}` | — | Map of module-name → RapydScript source for modules importable via `import`. Only used when the underlying streaming compiler was created with a virtual-file context (as `web_repl()` does). |
+| `discard_asserts` | bool | `false` | Strip all `assert` statements from the output. |
+| `omit_function_metadata` | bool | `false` | Omit per-function metadata (e.g. argument names) from the output for smaller bundles. |
+| `write_name` | bool | `false` | Emit a `var __name__ = "…"` assignment at the top of the output. |
+| `tree_shake` | bool | `false` | Remove unused imported names from the output (requires stdlib imports). |
+| `filename` | string | `'<input>'` | Source filename embedded in the source map and used in error messages. |
 
 **How it works**
 
@@ -2769,7 +3548,7 @@ and assembled into the standard `mappings` field.  The implementation lives in
 
 ```bash
 node bin/web-repl-export web-repl          # rebuilds web-repl/rapydscript.js
-node tools/build-language-service.js       # rebuilds web-repl/language-service.js
+node tools/build-language-service.js       # rebuilds language-service/index.js
 ```
 
 ### Running the tests