myjs 0.0.2__tar.gz

myjs-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 byteface
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

myjs-0.0.2/MANIFEST.in

@@ -0,0 +1 @@
+global-exclude __pycache__ *.py[cod]

myjs-0.0.2/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: myjs
+Version: 0.0.2
+Summary: A JavaScript interpreter for Python -- run .js against a DOM, call native C via ffi, reach the Python ecosystem
+Author-email: byteface <byteface@googlemail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/byteface/domonic-libs/tree/master/src/myjs
+Project-URL: Source, https://github.com/byteface/domonic-libs
+Project-URL: Documentation, https://github.com/byteface/domonic-libs/blob/master/docs/myjs.md
+Project-URL: Tracker, https://github.com/byteface/domonic-libs/issues
+Keywords: javascript,interpreter,ecmascript,acorn,ffi,ctypes,dom,repl,domonic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: domonic-libs>=0.0.2
+Provides-Extra: gui
+Requires-Dist: pywebview>=5.0; extra == "gui"
+Dynamic: license-file
+
+# myjs
+
+A JavaScript interpreter for Python. It runs a practical subset of ECMAScript against a server-side DOM, hands scripts an `ffi` bridge to native C libraries, and lets JavaScript reach the entire Python ecosystem.
+
+```bash
+pip install myjs
+```
+
+```bash
+myjs                 # start a REPL
+myjs script.js       # execute a file
+myjs -e "6 * 7"      # evaluate a snippet
+myjs --gui app.js    # run, then show the DOM the script built in a native window
+```
+
+```python
+import myjs
+
+myjs.eval("1 + 2 * 3")            # -> 7
+myjs.run("script.js")
+
+s = myjs.Session()                # an isolated global scope
+s.eval("const x = 21;")
+s.eval("x * 2")                   # -> 42
+```
+
+## What a script can reach
+
+- **The DOM** — `document`, `window`, and ~190 constructors (`URL`, `Headers`, `Event`, `DOMRect`, …). `document.createElement(...).appendChild(...)` builds a real object tree.
+- **An event loop** — `Promise` (with `all` / `allSettled` / `race` / `any`), `async` / `await`, `setTimeout` / `setInterval`, `queueMicrotask`. Microtasks run before timers.
+- **ES modules** — `import` / `export` from `.js` files; a bare specifier resolves to a Python module.
+- **`ffi`** — call native C libraries through `ctypes`, no compiler:
+
+  ```javascript
+  const libc = ffi.loadLibrary("c");
+  libc.abs.argtypes = [ffi.types.int];
+  libc.abs.restype  = ffi.types.int;
+  libc.abs(-42);                       // 42
+  ```
+
+- **Host bindings** — `fs`, `path`, `sh` (shell), `http` + an async `fetch`, `os` (Node-flavoured), `process`, `WebSocket` (a real RFC 6455 client), `say` / `notify` / `open`, `hash`, `atob` / `btoa`.
+- **`py`** — `py.import("numpy")`, `py.eval(...)`, `py.list(iter)` → the whole Python package index from JavaScript.
+
+The language layer passes a curated test262-style battery: closures, classes (extends / super / fields / getters-setters / private / static), destructuring, generators, labelled break, `async` / `await`, and the `Array` / `String` / `Object` / `Number` / `Math` / `JSON` / `RegExp` built-ins. Not covered: real prototype chains, `Proxy` / `Symbol`, `with`.
+
+## Language embedding
+
+```python
+s = myjs.Session(scope={"answer": 42})
+s.eval("answer * 2")              # -> 84
+```
+
+A JavaScript exception that escapes becomes `myjs.JSError` with `js_name`, `js_line`, and `js_trace` (the call stack).
+
+## How it is built
+
+`myjs` is the runtime layer on top of the [`domonic-libs`](https://pypi.org/project/domonic-libs/) `acorn` port — a faithful Python port of the [acorn](https://github.com/acornjs/acorn) parser plus a tree-walking evaluator — which in turn runs on [`domonic`](https://pypi.org/project/domonic/)'s DOM. Full reference: [docs/myjs.md](https://github.com/byteface/domonic-libs/blob/master/docs/myjs.md).
+
+MIT licensed.

myjs-0.0.2/README.md

@@ -0,0 +1,59 @@
+# myjs
+
+A JavaScript interpreter for Python. It runs a practical subset of ECMAScript against a server-side DOM, hands scripts an `ffi` bridge to native C libraries, and lets JavaScript reach the entire Python ecosystem.
+
+```bash
+pip install myjs
+```
+
+```bash
+myjs                 # start a REPL
+myjs script.js       # execute a file
+myjs -e "6 * 7"      # evaluate a snippet
+myjs --gui app.js    # run, then show the DOM the script built in a native window
+```
+
+```python
+import myjs
+
+myjs.eval("1 + 2 * 3")            # -> 7
+myjs.run("script.js")
+
+s = myjs.Session()                # an isolated global scope
+s.eval("const x = 21;")
+s.eval("x * 2")                   # -> 42
+```
+
+## What a script can reach
+
+- **The DOM** — `document`, `window`, and ~190 constructors (`URL`, `Headers`, `Event`, `DOMRect`, …). `document.createElement(...).appendChild(...)` builds a real object tree.
+- **An event loop** — `Promise` (with `all` / `allSettled` / `race` / `any`), `async` / `await`, `setTimeout` / `setInterval`, `queueMicrotask`. Microtasks run before timers.
+- **ES modules** — `import` / `export` from `.js` files; a bare specifier resolves to a Python module.
+- **`ffi`** — call native C libraries through `ctypes`, no compiler:
+
+  ```javascript
+  const libc = ffi.loadLibrary("c");
+  libc.abs.argtypes = [ffi.types.int];
+  libc.abs.restype  = ffi.types.int;
+  libc.abs(-42);                       // 42
+  ```
+
+- **Host bindings** — `fs`, `path`, `sh` (shell), `http` + an async `fetch`, `os` (Node-flavoured), `process`, `WebSocket` (a real RFC 6455 client), `say` / `notify` / `open`, `hash`, `atob` / `btoa`.
+- **`py`** — `py.import("numpy")`, `py.eval(...)`, `py.list(iter)` → the whole Python package index from JavaScript.
+
+The language layer passes a curated test262-style battery: closures, classes (extends / super / fields / getters-setters / private / static), destructuring, generators, labelled break, `async` / `await`, and the `Array` / `String` / `Object` / `Number` / `Math` / `JSON` / `RegExp` built-ins. Not covered: real prototype chains, `Proxy` / `Symbol`, `with`.
+
+## Language embedding
+
+```python
+s = myjs.Session(scope={"answer": 42})
+s.eval("answer * 2")              # -> 84
+```
+
+A JavaScript exception that escapes becomes `myjs.JSError` with `js_name`, `js_line`, and `js_trace` (the call stack).
+
+## How it is built
+
+`myjs` is the runtime layer on top of the [`domonic-libs`](https://pypi.org/project/domonic-libs/) `acorn` port — a faithful Python port of the [acorn](https://github.com/acornjs/acorn) parser plus a tree-walking evaluator — which in turn runs on [`domonic`](https://pypi.org/project/domonic/)'s DOM. Full reference: [docs/myjs.md](https://github.com/byteface/domonic-libs/blob/master/docs/myjs.md).
+
+MIT licensed.

myjs-0.0.2/VERSION

@@ -0,0 +1 @@
+0.0.2

myjs-0.0.2/pyproject.toml

@@ -0,0 +1,65 @@
+# Build config for the standalone `myjs` distribution.
+#
+# `src` here is a symlink to ../../src, so src/myjs is the single source of
+# truth and this project packages only `myjs*`. Build with `make myjs-build`
+# (or `python -m build packaging/myjs`); dev-install with `make myjs-install`.
+# The package depends on `domonic-libs` for the acorn parser + tree-walking
+# interpreter (`domonic_libs.acorn`) and, transitively, on `domonic`.
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "myjs"
+dynamic = ["version"]   # shares the repo-root VERSION (symlinked here as ./VERSION)
+description = "A JavaScript interpreter for Python -- run .js against a DOM, call native C via ffi, reach the Python ecosystem"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "byteface", email = "byteface@googlemail.com" },
+]
+requires-python = ">=3.10"
+keywords = ["javascript", "interpreter", "ecmascript", "acorn", "ffi", "ctypes", "dom", "repl", "domonic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: JavaScript",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Interpreters",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    # myjs and domonic-libs are released in lockstep from the repo-root VERSION;
+    # `make bump` keeps this floor in step.
+    "domonic-libs>=0.0.2",
+]
+
+[project.optional-dependencies]
+gui = ["pywebview>=5.0"]
+
+[project.scripts]
+myjs = "myjs.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/byteface/domonic-libs/tree/master/src/myjs"
+Source = "https://github.com/byteface/domonic-libs"
+Documentation = "https://github.com/byteface/domonic-libs/blob/master/docs/myjs.md"
+Tracker = "https://github.com/byteface/domonic-libs/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["myjs*"]
+
+[tool.setuptools.dynamic]
+version = { file = "VERSION" }

myjs-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

myjs-0.0.2/src/myjs/__init__.py

@@ -0,0 +1,65 @@
+"""myjs -- a small JavaScript interpreter for Python.
+
+It runs a practical subset of ECMAScript (via the ``domonic_libs.acorn`` port and
+its tree-walking evaluator) against domonic's server-side DOM, and hands scripts
+an ``ffi`` global for calling native C libraries through ``ctypes``.
+
+    import myjs
+
+    myjs.eval("window.console.log('hi from myjs')")
+    myjs.run("script.js")
+
+    s = myjs.Session()
+    s.eval("const x = 21;")
+    s.eval("x * 2")            # -> 42
+
+Command line: ``myjs`` starts a REPL, ``myjs file.js`` executes a file.
+"""
+
+def _read_version() -> str:
+    from pathlib import Path
+    f = Path(__file__).resolve().parents[2] / "VERSION"   # repo-root source checkout
+    if f.is_file():
+        return f.read_text().strip()
+    from importlib.metadata import PackageNotFoundError, version
+    try:
+        return version("myjs")
+    except PackageNotFoundError:
+        return "0+unknown"
+
+
+__version__ = _read_version()
+
+from ._engine import JSError, Session
+
+__all__ = ["Session", "JSError", "eval", "run", "repl", "__version__"]
+
+_shared: Session | None = None
+
+
+def _session() -> Session:
+    global _shared
+    if _shared is None:
+        _shared = Session()
+    return _shared
+
+
+def eval(src: str, *, scope: dict | None = None):
+    """Evaluate a string of JavaScript and return its completion value.
+
+    With ``scope`` a throwaway :class:`Session` is used; otherwise a process-wide
+    session persists definitions between calls.
+    """
+    return (Session(scope=scope) if scope else _session()).eval(src)
+
+
+def run(path: str, *, scope: dict | None = None):
+    """Execute a ``.js`` file. Returns its completion value."""
+    return Session(scope=scope).run_file(path)
+
+
+def repl(**kwargs) -> int:
+    """Start the interactive REPL. Returns a process exit code."""
+    from .repl import repl as _repl
+
+    return _repl(**kwargs)

myjs-0.0.2/src/myjs/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

myjs-0.0.2/src/myjs/_engine.py

@@ -0,0 +1,125 @@
+"""The myjs session: a persistent JS interpreter over domonic's DOM + ``ffi``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from domonic_libs.acorn.interpret import (
+    UNDEFINED,
+    JSThrow,
+    _Console,
+    _stringify,
+    make_interpreter,
+)
+
+from .ffi import scope as _ffi_scope
+from .host import async_fetch as _async_fetch
+from .host import scope as _host_scope
+from .host import websocket_ctor as _websocket_ctor
+
+
+class PrintConsole(_Console):
+    """Captures like the base console, and echoes each line to stdout."""
+
+    def log(self, *a):
+        super().log(*a)
+        print(self.lines[-1])
+
+    warn = error = info = debug = trace = log
+
+
+class JSError(Exception):
+    """A JavaScript exception (or syntax error) that escaped the script."""
+
+    def __init__(self, message, *, name="Error", line=None, trace=None):
+        super().__init__(message)
+        self.js_name = name
+        self.js_line = line
+        self.js_trace = trace
+
+    def __str__(self):
+        base = super().__str__()
+        where = f"  (line {self.js_line})" if self.js_line else ""
+        stack = f"\n  at {self.js_trace}" if self.js_trace else ""
+        return f"{self.js_name}: {base}{where}{stack}"
+
+
+def _reraise(exc):
+    val = getattr(exc, "value", None)
+    if isinstance(val, dict):
+        raise JSError(
+            val.get("message", ""),
+            name=val.get("name", "Error"),
+            line=getattr(exc, "js_line", None),
+            trace=getattr(exc, "js_trace", None),
+        ) from None
+    raise JSError(
+        str(exc),
+        name=type(exc).__name__,
+        line=getattr(exc, "js_line", None),
+        trace=getattr(exc, "js_trace", None),
+    ) from None
+
+
+class Session:
+    """One JS global scope. Feed it source with :meth:`eval`; state persists."""
+
+    def __init__(self, scope=None, console=None):
+        from . import __version__
+
+        extra = {**_ffi_scope(), **_host_scope(__version__)}
+        if scope:
+            extra.update(scope)
+        self.interp, self.console, self.document, self.window = make_interpreter(
+            extra_globals=extra, console=console
+        )
+        for name, value in (
+            ("fetch", _async_fetch(self.interp.loop)),
+            ("WebSocket", _websocket_ctor(self.interp.loop)),
+        ):
+            self.interp.global_env.declare(name, value)
+            self.window._own[name] = value
+
+    def eval(self, src, ecma_version=2022):
+        """Run ``src`` and return its completion value (``None`` for undefined)."""
+        try:
+            result = self.interp.run(src, ecma_version=ecma_version)
+        except (JSThrow, SyntaxError) as exc:
+            _reraise(exc)
+        return None if result is UNDEFINED else result
+
+    def run_file(self, path, ecma_version=2022):
+        p = Path(path).resolve()
+        self.interp.module_base = str(p.parent)
+        self.interp._cur_module["dir"] = str(p.parent)
+        return self.eval(p.read_text(), ecma_version=ecma_version)
+
+    @property
+    def console_lines(self):
+        return list(getattr(self.console, "lines", []))
+
+    def render_html(self):
+        """Serialise the DOM the script built into a standalone HTML document."""
+        try:
+            title = self.document.title
+        except Exception:
+            title = None
+        try:
+            root = str(self.document.documentElement)
+        except Exception:
+            root = f"<html><head></head><body>{self.document.body}</body></html>"
+        if title and isinstance(title, str) and "<title>" not in root:
+            root = root.replace("<head>", f"<head><title>{title}</title>", 1)
+        return "<!doctype html>\n" + root
+
+    @staticmethod
+    def display(value):
+        """Human-readable form of a completion value, for a REPL."""
+        if value is None or value is UNDEFINED:
+            return "undefined"
+        if isinstance(value, str):
+            return repr(value)
+        try:
+            return _stringify(value)
+        except Exception:
+            return repr(value)

myjs-0.0.2/src/myjs/cli.py

@@ -0,0 +1,87 @@
+"""``myjs`` command line: run a script, evaluate a snippet, or start a REPL."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from ._engine import JSError, PrintConsole, Session
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="myjs",
+        description="A small JavaScript interpreter on domonic's DOM, with an ffi bridge to native C.",
+    )
+    p.add_argument("script", nargs="?", help="a .js file to execute (omit for a REPL)")
+    p.add_argument("args", nargs="*", help="arguments passed to the script as globalThis.argv")
+    p.add_argument("-e", "--eval", dest="code", metavar="JS", help="evaluate a string and print the result")
+    p.add_argument("-i", "--interactive", action="store_true", help="enter the REPL after running")
+    p.add_argument("--gui", action="store_true",
+                   help="after running, show the DOM the script built in a native window")
+    p.add_argument("--version", action="version", version=f"myjs {__version__}")
+    return p
+
+
+def _open_gui(session: Session) -> int:
+    try:
+        import webview
+    except ImportError:
+        print("myjs --gui needs pywebview:  pip install 'domonic-libs[app]'", file=sys.stderr)
+        return 1
+    try:
+        title = session.eval("document.title") or "myjs"
+    except JSError:
+        title = "myjs"
+    webview.create_window(str(title) or "myjs", html=session.render_html(),
+                          width=960, height=720)
+    webview.start()
+    return 0
+
+
+def _report(exc: JSError) -> None:
+    print(exc, file=sys.stderr)
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.code is not None:
+        session = Session(console=PrintConsole())
+        try:
+            result = session.eval(args.code)
+        except JSError as exc:
+            _report(exc)
+            return 1
+        if result is not None:
+            print(result if isinstance(result, str) else session.display(result))
+        if args.interactive:
+            from .repl import repl
+            return repl(session)
+        return 0
+
+    if args.script:
+        session = Session(console=PrintConsole())
+        session.interp.global_env.declare("argv", list(args.args))
+        try:
+            session.run_file(args.script)
+        except FileNotFoundError:
+            print(f"myjs: cannot open {args.script}", file=sys.stderr)
+            return 1
+        except JSError as exc:
+            _report(exc)
+            return 1
+        if args.gui:
+            return _open_gui(session)
+        if args.interactive:
+            from .repl import repl
+            return repl(session)
+        return 0
+
+    from .repl import repl
+    return repl()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())