rapydscript-ns 0.9.1 → 0.9.3

package/README.md

@@ -592,30 +592,64 @@ RapydScript supports Python's ``/`` and ``*`` parameter separators:
 	greet("Bob", greeting="Hi")             # Hi, Bob!
 	greet("Carol", punctuation=".")         # Hello, Carol.
 	greet("Dave", greeting="Hey", punctuation="?")  # Hey, Dave?
-
-	# name is positional-only: greet(name="Alice") would silently ignore the kwarg
-	# punctuation is keyword-only: must be passed as punctuation="."
 ```
 
 The two separators can be combined, and each section can have its own default
 values.  All combinations supported by Python 3.8+ are accepted.
 
-RapydScript is lenient: passing a positional-only parameter by keyword will not
-raise a ``TypeError`` at runtime (the named value is silently ignored), and
-passing a keyword-only parameter positionally will not raise an error either.
-This is consistent with RapydScript's general approach of favouring
-interoperability over strict enforcement.
+By default RapydScript is lenient about argument conventions (to favour
+JavaScript interoperability).  Enable strict Python-style enforcement with the
+``type_enforcement`` flag described below.
 
 The Monaco language service correctly shows ``/`` and ``*`` separators in
 signature help and hover tooltips.
 
-One difference between RapydScript and Python is that RapydScript is not as
-strict as Python when it comes to validating function arguments. This is both
-for performance and to make it easier to interoperate with other JavaScript
-libraries. So if you do not pass enough arguments when calling a function, the
-extra arguments will be set to undefined instead of raising a TypeError, as in
-Python. Similarly, when mixing ``*args`` and optional arguments, RapydScript
-will not complain if an optional argument is specified twice.
+### Argument type enforcement
+
+``from __python__ import type_enforcement`` activates Python-compatible runtime
+argument checking for every function defined in that scope:
+
+| Check | Behaviour |
+|---|---|
+| Too many positional arguments | ``TypeError`` |
+| Missing required positional argument | ``TypeError`` |
+| Positional-only arg passed as a keyword argument | ``TypeError`` |
+| Missing required keyword-only argument | ``TypeError`` |
+| Argument value does not match its type annotation | ``TypeError`` |
+
+```py
+from __python__ import type_enforcement
+
+def greet(name, /, greeting="Hello", *, punctuation="!"):
+    return greeting + ", " + name + punctuation
+
+greet("Alice")                          # Hello, Alice!
+greet("Bob", greeting="Hi")             # Hi, Bob!
+greet("Carol", punctuation=".")         # Hello, Carol.
+
+greet(name="Dave")      # TypeError: positional-only arg 'name' passed as kwarg
+greet("Eve")            # TypeError: missing required keyword-only argument 'punctuation'
+                        #   (only when punctuation has no default)
+
+def add(a: int, b: int) -> int:
+    return a + b
+
+add(1, 2)       # 3
+add("x", 2)    # TypeError: argument 'a' must be int
+```
+
+The flag applies to the function definitions that follow it in scope — it does
+not retroactively affect imported functions or functions defined before the
+import.  It can be combined with any other ``from __python__ import`` flag.
+
+The Monaco language service also reports violations **statically** for
+calls to locally-defined enforced functions, underlining the problem at the
+call site with an error marker.
+
+One difference compared to un-enforced RapydScript: without
+``type_enforcement``, missing arguments become ``undefined`` (JavaScript
+default) instead of raising ``TypeError``, and positional/keyword-only
+conventions are not checked.
 
 When creating callbacks to pass to other JavaScript libraries, it is often the
 case that the external library expects a function that receives an *options
@@ -1343,6 +1377,49 @@ ba.clear()                    # remove all bytes
 ba += bytearray([7, 8])       # in-place concatenation
 ```
 
+### `long` — arbitrary-precision integers
+
+RapydScript provides a `long` builtin backed by JavaScript's native `BigInt`,
+giving you arbitrary-precision integers beyond the safe range of JS `Number`.
+
+```python
+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
+```
+
+#### Precision beyond JS Number
+
+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)
+```
+
+#### Operator overloading
+
+`//`, `%`, and `**` require `overload_operators` (on by default) to emit the
+BigInt-aware helpers rather than the raw JS operators.  If you have explicitly
+disabled operator overloading with `from __python__ import no_overload_operators`,
+`//` will call `Math.floor(a / b)` which throws a `TypeError` at runtime for
+`long` values.
+
+#### Browser / environment support
+
+`BigInt` is supported in all modern browsers (Chrome 67+, Firefox 68+, Safari
+14+, Node.js 10.3+).  Code using `long` will not run in Internet Explorer.
+
 ### `issubclass`
 
 `issubclass(cls, classinfo)` checks whether a class is a subclass of another
@@ -3046,6 +3123,34 @@ By default, generators are down-converted to ES 5 switch statements. Pass
 compiler options) to emit native ES 6 generator functions instead, which are
 smaller and faster.
 
+### Async generators (`async def` with `yield`)
+
+Async generators — `async def` functions that contain `yield` — are also
+supported, with the same syntax as Python:
+
+```py
+async def stream(urls):
+    for url in urls:
+        body = await fetch(url)
+        yield body
+
+async def main():
+    async for body in stream(['/a', '/b']):
+        print(body)
+```
+
+Calling an async-generator function returns an async iterator immediately
+(not a `Promise`). Each `.next()` call returns a `Promise` that resolves to a
+`{value, done}` record, matching the JS async-iterator protocol. Manual
+iteration via `await it.next()` and `await it.asend()` works (`.asend` is
+aliased to `.next`, mirroring Python's async-generator API). Whole iterators
+are best consumed with `async for x in iter:`, which compiles to JS
+`for await ... of`.
+
+`async for` is an ES2018 feature, so it is always emitted in modern form
+regardless of `--js-version`. The runtime must support `Symbol.asyncIterator`
+(Node 10+, Chrome 63+, Firefox 57+, Safari 11.1+).
+
 Modules
 -------
 
@@ -3059,6 +3164,16 @@ You can import things from modules, just like you would in python:
 from mypackage.mymodule import something, something_else
 ```
 
+Multi-line parenthesized imports (Python 3.10+ style) are fully supported, including trailing commas:
+
+```py
+from mypackage.mymodule import (
+    something,
+    something_else as alias,
+    another_thing,
+)
+```
+
 When you import modules, the RapydScript compiler automatically generates a
 single large JavaScript file containing all the imported packages/modules and
 their dependencies, recursively. This makes it very easy to integrate the
@@ -3349,6 +3464,7 @@ One of Python's main strengths is the number of libraries available to the devel
 	                    # groupby, islice, pairwise, starmap, takewhile, zip_longest,
 	                    # 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
 
 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.
 
@@ -3618,6 +3734,7 @@ with no flags enabled, pass ``--legacy-rapydscript`` on the command line.
 | `overload_getitem` | `obj[key]` dispatches to `__getitem__` / `__setitem__` / `__delitem__` on objects that define them. On by default. |
 | `overload_operators` | Arithmetic and bitwise operators (`+`, `-`, `*`, `/`, `//`, `%`, `**`, `&`, `\|`, `^`, `<<`, `>>`) dispatch to dunder methods (`__add__`, `__sub__`, etc.) and their reflected variants. Unary `-`/`+`/`~` dispatch to `__neg__`/`__pos__`/`__invert__`. On by default. |
 | `strict_arithmetic` | When `overload_operators` is active, incompatible operand types (e.g. `int + str`) raise `TypeError` instead of silently coercing as JavaScript would. On by default; disable with `from __python__ import no_strict_arithmetic` to revert to JavaScript coercion behaviour. Internal RapydScript library code is unaffected. |
+| `python_modulo` | The `%` operator follows Python semantics: the result takes the sign of the divisor (`-7 % 3 == 2`, `7 % -3 == -2`). On by default. Custom `__mod__` / `__rmod__` are dispatched even without `overload_operators`. Disable with `from __python__ import no_python_modulo` to revert to raw JS remainder. Has no effect when `overload_operators` is active (the operator dispatch path always uses Python semantics). |
 | `truthiness` | Boolean tests and `bool()` dispatch to `__bool__` and treat empty containers as falsy, matching Python semantics. On by default. |
 | `bound_methods` | Method references (`obj.method`) are automatically bound to their object, so they can be passed as callbacks without losing `self`. On by default. |
 | `hash_literals` | `{k: v}` creates a Python `dict` (alias for `dict_literals`; kept for backward compatibility). On by default. |
@@ -3688,7 +3805,7 @@ when the editor is torn down.
 | `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. |
+| `extraBuiltins` | `string[]` | `[]` | 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
@@ -3838,7 +3955,6 @@ original `.py` file with working breakpoints and correct error stack frames.
 | `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. |
@@ -3886,7 +4002,7 @@ Python Feature Coverage
 | `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) |
+| `with A() as a, B() as b:` / `with (A() as a, B() as b):`                                                                                                                                                                                                    | Multiple context managers in one statement (flat or parenthesized 3.10+ form); exits in LIFO order (Python-correct); multi-line and trailing comma supported |
 | `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 |
@@ -3904,10 +4020,13 @@ Python Feature Coverage
 | `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 |
+| Argument type enforcement (`from __python__ import type_enforcement`)                                                                                                                                                                                          | Activates runtime `TypeError` for wrong argument count, positional-only kwargs, missing required keyword-only args, and type-annotated arg mismatches; Monaco language service reports violations statically at call sites |
 | 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 |
+| `async def` with `yield` (async generators)                                                                                                                                                                                                                   | Combining `async def` with `yield` produces an async generator. Calling it returns an async iterator immediately; `.next()` / `.asend()` return `Promise` objects, matching Python's `__anext__` / `asend` API (`.send` and `.asend` are aliased to `.next`). `await` may appear before, between, or after `yield`. Compiled to a sync wrapper around `async function*`. |
+| `async for x in iter:`                                                                                                                                                                                                                                        | Drives async iterators (`Symbol.asyncIterator`) and async generators. Compiles to native `for await ... of` (ES2018) regardless of `--js-version`. Works with sync iterables that yield Promises as well. |
 | `+=`, `-=`, `*=`, `/=`, `//=`, `**=`, `%=`, `&=`, `\|=`, `^=`, `<<=`, `>>=`                                                                                                                                                                                   | 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 |
@@ -3922,7 +4041,7 @@ Python Feature Coverage
 | 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 |
+| 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 |
 | `zip(strict=True)`                                                                                                                                                                                                                                            | Raises `ValueError` when iterables have different lengths; equal-length iterables work normally |
@@ -3951,6 +4070,7 @@ Python Feature Coverage
 | `dict \| dict` and `dict \|= dict` (Python 3.9+)                                                                                                                                                                                                              | Dict merge via `\|` creates a new merged dict (right-side values win); `\|=` updates in-place. Active via `overload_operators` + `dict_literals` (both on by default). |
 | `__format__` dunder                                                                                                                                                                                                                                           | `format()`, `str.format()`, and f-strings all dispatch to `__format__`; default `__format__` auto-generated for classes (returns `__str__()` for empty spec, raises `TypeError` for non-empty spec); `!r`/`!s`/`!a` transformers bypass `__format__` correctly |
 | `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. |
+| Multi-line parenthesized `from … import (…)` with optional trailing comma                                                                                                                                                                                     | Each imported name (with optional `as` alias) may appear on its own line; a trailing comma before `)` is accepted — identical to Python syntax |
 | `__import__(name[, globals, locals, fromlist, level])`                                                                                                                                                                                                        | Runtime lookup in the compiled module registry (`ρσ_modules`). Without `fromlist` (or empty `fromlist`) returns the top-level package, matching Python's semantics. `ImportError` / `ModuleNotFoundError` raised for unknown modules. **Constraint**: the module must have been statically imported elsewhere in the source so it is present in `ρσ_modules`. |
 | `ImportError`, `ModuleNotFoundError`                                                                                                                                                                                                                          | Both defined as runtime exception classes; `ModuleNotFoundError` is a subclass of `ImportError` (same as Python 3.6+). |
 | `bytes(source[, encoding[, errors]])` and `bytearray(source[, encoding[, errors]])`                                                                                                                                                                           | Full Python semantics: construction from integer (n zero bytes), list/iterable of ints (0–255), string + encoding (`utf-8`, `latin-1`, `ascii`), `Uint8Array`, or another `bytes`/`bytearray`. Key methods: `hex([sep[, bytes_per_sep]])`, `decode(encoding)`, `fromhex(s)` (static), `count`, `find`, `rfind`, `index`, `rindex`, `startswith`, `endswith`, `join`, `split`, `replace`, `strip`, `lstrip`, `rstrip`, `upper`, `lower`, `copy`. `bytearray` adds: `append`, `extend`, `insert`, `pop`, `remove`, `reverse`, `clear`, `__setitem__` (single and slice). Slicing returns a new `bytes`/`bytearray`. `+` concatenates; `*` repeats; `==` compares element-wise; `in` tests integer or subsequence membership; `isinstance(x, bytes)` / `isinstance(x, bytearray)` work; `bytearray` is a subclass of `bytes`. `repr()` returns `b'...'` notation. `Uint8Array` values may be passed anywhere a `bytes`-like object is accepted. |
@@ -3958,6 +4078,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+). |
 | `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. |
@@ -4041,7 +4162,7 @@ Modules with a `src/lib/` implementation available are marked ✅. All others ar
 | `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`; 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`   | ✅           | Base64 and encoding helpers; partial `base64` coverage                                        |
+| `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`                                              |
 | `functools`   | ✅           | `reduce`, `partial`, `wraps`, `lru_cache`                                                     |
 | `itertools`   | ✅           | Common iteration tools                                                                        |
@@ -4055,19 +4176,22 @@ Modules with a `src/lib/` implementation available are marked ✅. All others ar
 | `datetime`    | ✅           | `date`, `time`, `datetime`, `timedelta`, `MINYEAR`, `MAXYEAR` in `src/lib/datetime.pyj`; construction, `isoformat()`, `fromisoformat()`, `today()`/`now()`, `combine()`, arithmetic (via `__add__`/`__sub__`; operators need `overload_operators`), comparisons, `replace()`, `strftime()` (%Y %m %d %H %M %S %f %A %a %B %b %j %p %I %%); no tzinfo/timezone support |
 | `json`        | ✅           | `dumps()`, `loads()`, `dump()`, `load()`, `JSONDecodeError` in `src/lib/json.pyj`; `indent`, `sort_keys`, `separators`, `dflt` (Python's `default`) callback, `object_hook`, `object_pairs_hook`, `parse_float`, `parse_int` supported; backed by the JS `JSON` global; note: `default` is a JS reserved word — use `dflt=` instead |
 | `io`          | ✅           | `StringIO`, `BytesIO`, `UnsupportedOperation` in `src/lib/io.pyj`; `read([size])`, `readline([size])`, `readlines([hint])`, `write()`, `writelines()`, `seek(pos[, whence])`, `tell()`, `truncate([pos])`, `getvalue()`, `close()`, `closed`; context manager support; `readable()`, `writable()`, `seekable()` return True; `newline` parameter accepted for API compatibility |
-| `string`      | ❌           | Character constants, `Template`, `Formatter` not available                                    |
+| `base64`      | ✅           | `b64encode(s[, altchars])`, `b64decode(s[, altchars][, validate])`, `standard_b64encode`, `standard_b64decode`, `urlsafe_b64encode`, `urlsafe_b64decode`, `b32encode`, `b32decode([casefold][, map01])`, `b16encode`, `b16decode([casefold])`, `encodebytes`, `decodebytes`, `Error` in `src/lib/base64.pyj`; pure-JS implementation, works in browser and Node; all encode functions return `bytes` |
+| `string`      | ✅           | Character constants (`ascii_letters`, `ascii_lowercase`, `ascii_uppercase`, `digits`, `hexdigits`, `octdigits`, `punctuation`, `whitespace`, `printable`), `Template` ($-substitution with `substitute(mapping)` and `safe_substitute(mapping)`), `Formatter` (`format(*args)`, `vformat(fmt, args, kwargs)`, `format_field`, `convert_field`, `get_value`, `get_field`, `parse`) in `src/lib/string.pyj`; `Formatter.format()` accepts positional args — for named-field substitution use `vformat(fmt, [], {'key': val})`; `Template.substitute()` and `safe_substitute()` accept a dict (or plain object) |
+| `html`        | ✅           | `escape(s[, quote=True])`, `unescape(s)`, `HTMLParser` (event-driven parser; subclass and override `handle_starttag`, `handle_endtag`, `handle_data`, `handle_comment`, `handle_decl`, etc.) in `src/lib/html.pyj`; full HTML4 + common HTML5 named entity table; `convert_charrefs=True` by default (entities in text and attributes auto-decoded); `html.parser` sub-module not available as a separate import — use `from html import HTMLParser` |
+| `asyncio`     | ✅           | `sleep()`, `gather()`, `create_task()`, `ensure_future()`, `run()`, `shield()`, `wait_for()`, `wait()`, `iscoroutine()`, `iscoroutinefunction()`, `current_task()`, `all_tasks()`, `get_event_loop()`, `get_running_loop()`, `new_event_loop()` in `src/lib/asyncio.pyj`; synchronization primitives: `Lock`, `Event`, `Semaphore`, `BoundedSemaphore`, `Queue`, `LifoQueue`, `PriorityQueue`; exceptions: `CancelledError`, `TimeoutError`, `InvalidStateError`, `QueueEmpty`, `QueueFull`; `async def` / `await` syntax compiles to native JS async functions; `async def` with `yield` (async generators) and `async for` are supported (see "Async generators" section); `asyncio.run(coro)` returns the Promise (cannot block in JS); `async with` is not supported — use `.acquire()`/`.release()` directly |
+| `urllib`      | ✅           | `urllib.parse`: `quote()`, `unquote()`, `quote_plus()`, `unquote_plus()`, `urlencode()`, `urlsplit()` → `SplitResult`, `urlparse()` → `ParseResult`, `urlunsplit()`, `urlunparse()`, `urljoin()`, `parse_qs()`, `parse_qsl()` in `src/lib/urllib/parse.pyj`; `urllib.error`: `URLError`, `HTTPError` in `src/lib/urllib/error.pyj`; `urllib.request`: `urlopen(url[, data[, timeout]])` returns a Promise wrapping the Fetch API in `src/lib/urllib/request.pyj` — use with `await` in an async function; `SplitResult`/`ParseResult` expose `.scheme`, `.netloc`, `.path`, `.query`, `.fragment` plus `.hostname`, `.port`, `.username`, `.password` and `.geturl()`; backed by the JS `URL` constructor and `encodeURIComponent`/`decodeURIComponent`; RFC 3986 unreserved characters (`A-Z a-z 0-9 - _ . ~`) never encoded |
+| `bisect`      | ✅           | `bisect_left(a, x[, lo[, hi[, key]]])`, `bisect_right(a, x[, lo[, hi[, key]]])`, `bisect` (alias for `bisect_right`), `insort_left(a, x[, lo[, hi[, key]]])`, `insort_right(a, x[, lo[, hi[, key]]])`, `insort` (alias for `insort_right`) in `src/lib/bisect.pyj`; pure binary-search implementation matching Python semantics; optional `lo`/`hi` bounds for sub-slice search; optional `key` function (Python 3.10+ API) applied to array elements only — `x` must be directly comparable to `key(a[i])` results |
+| `http`        | ✅           | `http`: `HTTPStatus` class with integer constants for all standard status codes (`OK=200`, `NOT_FOUND=404`, `IM_A_TEAPOT=418`, etc.) in `src/lib/http/__init__.pyj`; `http.client`: `HTTPConnection(host[, port[, timeout]])`, `HTTPSConnection(host[, port[, timeout]])`, `HTTPResponse` (`.status`, `.reason`, `.headers`, `.url`, `getheader(name[, default])`, `getheaders()`, `read()` → Promise, `json()` → Promise), `HTTPException`, `NotConnected`, `InvalidURL`, `RemoteDisconnected`, `HTTP_PORT=80`, `HTTPS_PORT=443` in `src/lib/http/client.pyj`; `http.cookies`: `SimpleCookie` (dict-like cookie container with `load(rawdata)`, `output([header, sep])`, `items()`, `keys()`, `values()`), `Morsel` (`.key`, `.value`, `.coded_value`, `OutputString()`, `output([header])`), `CookieError` in `src/lib/http/cookies.pyj`; `getresponse()` wraps the Fetch API and returns a Promise — use with `await`; non-2xx responses are returned normally (check `resp.status` yourself, unlike `urllib.request`); `http.server` not available |
+| `csv`         | ✅           | `reader(csvfile[, dialect][, **fmtparams])`, `writer(csvfile[, dialect][, **fmtparams])`, `DictReader(f[, fieldnames[, restkey[, restval[, dialect, ...]]]])`, `DictWriter(f, fieldnames[, restval[, extrasaction[, dialect, ...]]])` in `src/lib/csv.pyj`; `Dialect`, `excel`, `excel_tab`, `unix_dialect` classes; `register_dialect`, `unregister_dialect`, `get_dialect`, `list_dialects`, `field_size_limit`; `QUOTE_MINIMAL`, `QUOTE_ALL`, `QUOTE_NONNUMERIC`, `QUOTE_NONE` constants; `Error` exception; backed by pure-JS parser with full support for quoted fields (including multi-line), custom delimiters, `skipinitialspace`, double-quote escaping, escape characters; accepts list-of-strings, file-like objects (with `.read()`), or any iterable; note: `csv.Error` shadows the native JS Error if imported via `from csv import Error` in web-repl mode — catch via `Exception` instead |
+| `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` |
 | `inspect`     | ❌           | `signature`, `getmembers`, `isfunction` etc. not available                                    |
-| `asyncio`     | ❌           | Event loop, `gather`, `sleep`, `Queue`, `Task` wrappers not available; use `async`/`await`    |
 | `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`)            |
 
 ---
@@ -4080,7 +4204,7 @@ Features that exist in RapydScript but behave differently from standard Python:
 |---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `is` / `is not` | Object identity | Strict equality `===` / `!==`, which is not object/pointer comparison for JS primitives  |
 | `//` floor division on floats | `math.floor(a/b)` always | uses `Math.floor` - same result for well-behaved floats                                                                                                                                                                    |
-| `%` on negative numbers | Python modulo (always non-negative) | JS remainder (can be negative)                                                                                                                                                                                             |
+| `%` 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)                                                                                                                                                                    |
 | 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.                                                                                                |
@@ -4093,7 +4217,7 @@ Features that exist in RapydScript but behave differently from standard Python:
 | 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)                                                                                      |
 | `dict` key ordering | Insertion order guaranteed (3.7+) | Depends on JS engine (V8 preserves insertion order in practice)                                                                                                                                                            |
 | 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                                                                            |
-| `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                                                                                                                                |
+| `parenthesized with (A() as a, B() as b):` | Multiple context managers in parenthesized form (3.10+) | Fully supported; multi-line and trailing comma accepted; semantics identical to the flat form |
 
 ---
 

package/TODO.md

@@ -1,19 +1,34 @@
 
 ### 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
-- `.replace(str, str)` replaces only the first occurrence.
-- eval is js
 
-- rework tests to use jest
+- vscode plugin based on language service?
 
-- omit_function_metadata breaks imports - it needs to be changed to only affect imported modules, maybe?
 
-- 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
 
-- examples of using js libraries in rapydscript in readme?
+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 [the python io.stringIO and io.bytesio library ] to rapydscript. It should have the same syntax as the Python implementation, and be transpiled into equivalent javascript. Please ensure with unit tests that it transpiles and the output JS runs correctly, and that the language service correctly handles it in parsed code. Please make sure it works in the web-repl too. Please also update the README if it has any outdated info about this, and the PYTHON_FEATURE_COVERAGE report. Please also add a simple example to the bottom of the TODO document using this feature (make no other changes to that file).
+main()
+```