concurrent-c-node 0.23.0__tar.gz → 0.23.2__tar.gz

{concurrent_c_node-0.23.0 → concurrent_c_node-0.23.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: concurrent-c-node
-Version: 0.23.0
+Version: 0.23.2
 Summary: JavaScript and npm packages from Python over the Concurrent-C bridge: one spawned Node child per domain, host-controlled lifetime.
 License: MIT
 Project-URL: Repository, https://github.com/sreekotay/concurrent-c
@@ -18,6 +18,13 @@ Requires-Dist: ipython>=7; extra == "jupyter"
 Call Node (and npm packages) from Python.
 Native types, exceptions, callbacks, and async all cross the boundary.
 
+## Why use this
+
+Call real Node from Python — `require`, native addons, npm — not a JS
+engine in-process. One child, shm for bulk, `from cc_node import require`
+in Jupyter/Colab with no `%load_ext`. pythonia is the packaged peer; this
+is faster on the wire and honest about bulk and callbacks.
+
 Part of [Concurrent-C](https://github.com/sreekotay/concurrent-c) — a
 strict C11-superset preprocessor: `.ccs` lowers to plain C and compiles
 with your host C compiler. (This bridge itself is pure Python stdlib —
@@ -28,15 +35,19 @@ bridge):
 [JS / Python interop](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).
 
 ```python
-import cc_node
-
-js = cc_node.create()                # always a child `node` process
-_ = js.require('lodash')             # cwd node_modules
+from cc_node import require          # one session child (lazy)
+_ = require('lodash')                # cwd node_modules
 _.chunk([1, 2, 3, 4, 5], 2)          # [[1, 2], [3, 4], [5]]
+```
 
+A private child (`create()`) is still there when you want N Nodes or
+an explicit lifetime — not required for the first call.
+
+```python
+import cc_node
+js = cc_node.create()                # a private Node, not the session
 semver = js.require('semver')
 semver.satisfies('1.2.3', '^1.0.0')  # True
-
 js.destroy()                         # or: with cc_node.create() as js:
 ```
 
@@ -44,12 +55,13 @@ The other direction (Python from Node):
 [`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
 (in-process by default; vs pymport / ncp / pythonia in that README).
 
-Every `create()` here is a separate Node — real addons, crash isolation,
-measurable wire. N domains = N processes.
+Every `create()` is a separate Node — real addons, crash isolation,
+measurable wire. N domains = N processes. `require()` / `get()` share
+one session for the process (the Jupyter kernel).
 
 | | this package | CC hosted (`cc_js_new(false, …)`) |
 |---|---|---|
-| API | `cc_node.create()` | `.ccs` program |
+| API | `require()` / `create()` | `.ccs` program |
 | Where | child `node` | libnode in-process |
 | Hot call | ~105µs RTT | sub-µs (needs libnode) |
 | Bulk | shm (~9.5ms / 8MB) | in-process |
@@ -60,11 +72,12 @@ measurable wire. N domains = N processes.
 
 - Always a child `node`. A call blocks until JS answers; thenables wait
   in the child. No `{ async: true }`.
+- `from cc_node import require` is the session. `create()` is a private
+  child. `reset()` / `%js_reset` / `%reset` / atexit tear the session down.
 - Scalars / `None` materialize; empty `{}` stays a handle; everything
   else is a `JsHandle` until `str()` / attrs / a call.
-- `import cc_node` then `%%js` or `cc_node.get()` — one session, not a
-  child per cell. `%load_ext` still works (idempotent).
-- `cc_node.require('path')` is `get().require('path')`.
+- Notebook: `import cc_node` registers `%%js` (no `%load_ext`). Same
+  session as `require()`.
 - `eval()` is one RTT, no extra globals. `%%js` / `eval_cell` install
   cwd `require` once.
 - `--bind` is `Object.assign(globalThis, …)` of names you name (wire
@@ -74,35 +87,36 @@ measurable wire. N domains = N processes.
 
 ```
 pip install concurrent-c-node                 # needs node on PATH
-pip install 'concurrent-c-node[jupyter]'      # magics (IPython)
+pip install 'concurrent-c-node[jupyter]'      # IPython (%%js); require() does not need this
 python -m cc_node.examples.use_node
 python -m cc_node.examples.bench_wire
 python -m cc_node.benchmarks.multi_domain
-python -m cc_node.benchmarks.vs_alts          # vs DIY node / pythonmonkey / mini-racer
+python -m cc_node.benchmarks.vs_alts          # vs pythonia / DIY node / pythonmonkey / mini-racer
 ```
 
 ## Jupyter / Colab
 
-Colab and the usual Jupyter kernel are **Python** — this package. Same
-calling convention as a script: a cell blocks until Node answers;
-thenables wait in the child. Magics and `get()` share **one** session
-for the kernel, not a spawn per cell (~28ms). Child `console.log`
-lands in the cell (inherited stdio, line-buffered).
+Same verb as pythonia: `require`. No `%load_ext`, no `create()`, no
+`destroy()` for the happy path. One session child for the kernel;
+`console.log` lands in the cell.
 
 ```python
 %pip install concurrent-c-node
 # if `node` is missing (typical Colab):
 !apt-get install -y nodejs
 
-import cc_node                 # magics register; no %load_ext
-path = cc_node.require('path')
-path.join('a', 'b')            # 'a/b'
+from cc_node import require
+require('lodash').chunk([1, 2, 3, 4, 5], 2)
 ```
 
+`import cc_node` also registers `%%js` (IPython already running; the
+`[jupyter]` extra is only if you want magics without IPython already
+installed).
+
 ```python
 %%js
 console.log('hi')              # shows in the cell
-require('path').join('a', 'b') # last expression comes back as Python
+require('lodash').chunk([1, 2, 3, 4, 5], 2)
 ```
 
 ```python
@@ -114,9 +128,10 @@ xs.map(x => x * 2)             # wire types only; no pickle fallback
 
 | | |
 |---|---|
-| `import cc_node` | registers magics; does **not** spawn until first `%%js` / `get()` / `require()` |
-| `%load_ext cc_node` | same, idempotent |
-| `%js 1+1` / `%%js` | eval on `cc_node.get()`; last expression is the result |
+| `from cc_node import require` | session `require`; spawns on first call |
+| `import cc_node` | registers magics; does **not** spawn until first `require()` / `%%js` |
+| `%load_ext cc_node` | same, idempotent; not required |
+| `%js 1+1` / `%%js` | eval on the same session; last expression is the result |
 | `-b xs` / `--bind xs,n` | publish those Python names on `globalThis` for the cell |
 | `-t chunks` / `--to` | store the result in the notebook namespace |
 | `%js_stats` | handle-table size (spawns if needed) |
@@ -161,25 +176,30 @@ Colab is not that. There, default `create()` blocks the kernel thread —
 Wire: line-JSON on dedicated fds (stdio stays yours). Bulk spill: private
 0700 dir, 0600 files, removed with the bridge.
 
-### Vs pythonmonkey / mini-racer / DIY node
+### Vs pythonia / pythonmonkey / mini-racer / DIY node
 
-Most “JS from Python” libraries are **not Node**. Bulk is a **sum** over
-1M floats (`.length` on an in-process wrapper is free and lies). Snapshot:
+Most “JS from Python” libraries are **not Node**. pythonia (PyPI
+[`javascript`](https://pypi.org/project/javascript/), JSPyBridge) is the
+packaged peer that is: `require()` on import, one child. Bulk is a
+**sum** over 1M floats (`.length` on an in-process wrapper is free and
+lies). Snapshot:
 [`cc_node_vs_alts_20260813.txt`](https://github.com/sreekotay/concurrent-c/blob/main/perf/baselines/cc_node_vs_alts_20260813.txt)
 · harness: [`benchmarks/vs_alts.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/cc_node/benchmarks/vs_alts.py).
 
-| | cc-node | DIY JSON stdio | `node -e` each | pythonmonkey | mini-racer |
-|---|---|---|---|---|---|
-| identity RTT | **20µs** | 39µs | 25ms | **<1µs** | 114µs |
-| callback | **36µs** | — | — | 1µs | — |
-| 8MB typed / list | **6.2ms shm** / 359ms | — / 197ms | — | — / 630ms proxy | — / 78ms |
-| `require('fs')` | yes | yes | yes | no | no |
-| process | child `node` | child `node` | new process/call | SpiderMonkey in-process | V8 isolate |
+| | cc-node | pythonia | DIY JSON stdio | `node -e` each | pythonmonkey | mini-racer |
+|---|---|---|---|---|---|---|
+| identity RTT | **20µs** | 42µs | 19µs | 23ms | **<1µs** | 104µs |
+| callback | **40µs** | 106µs | — | — | 1µs | — |
+| 8MB typed / list | **7.5ms shm** / 266ms | — / 481ms | — / 155ms | — | — / 609ms | — / 78ms |
+| `require('fs')` | yes | yes | yes | yes | no | no |
+| process | child `node` | child `node` | child `node` | new process/call | SpiderMonkey in-process | V8 isolate |
 
 Tiny scalars: pythonmonkey’s in-process SM beats a child. Real Node
 (`require('fs')`, native addons, callbacks, stdout stays yours): this
-package. Isolated `node -e` per call is ~1000× a persistent child.
-Optional engines SKIP if not importable — not package deps.
+package — ~2× pythonia on identity, shm for bulk, Python callables are
+sync (pythonia’s JS side sees a Promise). Isolated `node -e` per call is
+~1000× a persistent child. Optional engines SKIP if not importable —
+not package deps.
 
 The other direction (Python from Node):
 [`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
@@ -233,9 +253,11 @@ total(array.array('d', range(1_000_000)))
 ## Common issues
 
 **`Cannot find module`.** `require` / `import` resolve from the Python
-process cwd (`node_modules` next to your program), not from this wheel’s
-site-packages. `npm install lodash` in the project directory is the fix;
-or `create(node=…)` / `CC_NODE_BIN` when the wrong Node is on `PATH`.
+process cwd (`node_modules` next to your notebook or program), not from
+this wheel’s site-packages, and this package does **not** `npm install`
+on a miss (pythonia does). `npm install lodash` in that directory is
+the fix; or `create(node=…)` / `CC_NODE_BIN` when the wrong Node is on
+`PATH`.
 
 ### Empty `{}` stays a handle
 
@@ -293,7 +315,7 @@ Both bridges (npm OIDC + PyPI OIDC):
 
 Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`,
 `benchmarks.vs_alts`.
-Jupyter: `import cc_node` then `%%js` (or `%load_ext cc_node`).
+Jupyter: `from cc_node import require` (or `import cc_node` then `%%js`).
 Stress: [`stress/bridge/`](https://github.com/sreekotay/concurrent-c/tree/main/stress/bridge).  
 Own hot path in C/CC → native module (40–90ns) —
 [JS / Python interop](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).

{concurrent_c_node-0.23.0 → concurrent_c_node-0.23.2}/README.md

@@ -3,6 +3,13 @@
 Call Node (and npm packages) from Python.
 Native types, exceptions, callbacks, and async all cross the boundary.
 
+## Why use this
+
+Call real Node from Python — `require`, native addons, npm — not a JS
+engine in-process. One child, shm for bulk, `from cc_node import require`
+in Jupyter/Colab with no `%load_ext`. pythonia is the packaged peer; this
+is faster on the wire and honest about bulk and callbacks.
+
 Part of [Concurrent-C](https://github.com/sreekotay/concurrent-c) — a
 strict C11-superset preprocessor: `.ccs` lowers to plain C and compiles
 with your host C compiler. (This bridge itself is pure Python stdlib —
@@ -13,15 +20,19 @@ bridge):
 [JS / Python interop](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).
 
 ```python
-import cc_node
-
-js = cc_node.create()                # always a child `node` process
-_ = js.require('lodash')             # cwd node_modules
+from cc_node import require          # one session child (lazy)
+_ = require('lodash')                # cwd node_modules
 _.chunk([1, 2, 3, 4, 5], 2)          # [[1, 2], [3, 4], [5]]
+```
 
+A private child (`create()`) is still there when you want N Nodes or
+an explicit lifetime — not required for the first call.
+
+```python
+import cc_node
+js = cc_node.create()                # a private Node, not the session
 semver = js.require('semver')
 semver.satisfies('1.2.3', '^1.0.0')  # True
-
 js.destroy()                         # or: with cc_node.create() as js:
 ```
 
@@ -29,12 +40,13 @@ The other direction (Python from Node):
 [`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
 (in-process by default; vs pymport / ncp / pythonia in that README).
 
-Every `create()` here is a separate Node — real addons, crash isolation,
-measurable wire. N domains = N processes.
+Every `create()` is a separate Node — real addons, crash isolation,
+measurable wire. N domains = N processes. `require()` / `get()` share
+one session for the process (the Jupyter kernel).
 
 | | this package | CC hosted (`cc_js_new(false, …)`) |
 |---|---|---|
-| API | `cc_node.create()` | `.ccs` program |
+| API | `require()` / `create()` | `.ccs` program |
 | Where | child `node` | libnode in-process |
 | Hot call | ~105µs RTT | sub-µs (needs libnode) |
 | Bulk | shm (~9.5ms / 8MB) | in-process |
@@ -45,11 +57,12 @@ measurable wire. N domains = N processes.
 
 - Always a child `node`. A call blocks until JS answers; thenables wait
   in the child. No `{ async: true }`.
+- `from cc_node import require` is the session. `create()` is a private
+  child. `reset()` / `%js_reset` / `%reset` / atexit tear the session down.
 - Scalars / `None` materialize; empty `{}` stays a handle; everything
   else is a `JsHandle` until `str()` / attrs / a call.
-- `import cc_node` then `%%js` or `cc_node.get()` — one session, not a
-  child per cell. `%load_ext` still works (idempotent).
-- `cc_node.require('path')` is `get().require('path')`.
+- Notebook: `import cc_node` registers `%%js` (no `%load_ext`). Same
+  session as `require()`.
 - `eval()` is one RTT, no extra globals. `%%js` / `eval_cell` install
   cwd `require` once.
 - `--bind` is `Object.assign(globalThis, …)` of names you name (wire
@@ -59,35 +72,36 @@ measurable wire. N domains = N processes.
 
 ```
 pip install concurrent-c-node                 # needs node on PATH
-pip install 'concurrent-c-node[jupyter]'      # magics (IPython)
+pip install 'concurrent-c-node[jupyter]'      # IPython (%%js); require() does not need this
 python -m cc_node.examples.use_node
 python -m cc_node.examples.bench_wire
 python -m cc_node.benchmarks.multi_domain
-python -m cc_node.benchmarks.vs_alts          # vs DIY node / pythonmonkey / mini-racer
+python -m cc_node.benchmarks.vs_alts          # vs pythonia / DIY node / pythonmonkey / mini-racer
 ```
 
 ## Jupyter / Colab
 
-Colab and the usual Jupyter kernel are **Python** — this package. Same
-calling convention as a script: a cell blocks until Node answers;
-thenables wait in the child. Magics and `get()` share **one** session
-for the kernel, not a spawn per cell (~28ms). Child `console.log`
-lands in the cell (inherited stdio, line-buffered).
+Same verb as pythonia: `require`. No `%load_ext`, no `create()`, no
+`destroy()` for the happy path. One session child for the kernel;
+`console.log` lands in the cell.
 
 ```python
 %pip install concurrent-c-node
 # if `node` is missing (typical Colab):
 !apt-get install -y nodejs
 
-import cc_node                 # magics register; no %load_ext
-path = cc_node.require('path')
-path.join('a', 'b')            # 'a/b'
+from cc_node import require
+require('lodash').chunk([1, 2, 3, 4, 5], 2)
 ```
 
+`import cc_node` also registers `%%js` (IPython already running; the
+`[jupyter]` extra is only if you want magics without IPython already
+installed).
+
 ```python
 %%js
 console.log('hi')              # shows in the cell
-require('path').join('a', 'b') # last expression comes back as Python
+require('lodash').chunk([1, 2, 3, 4, 5], 2)
 ```
 
 ```python
@@ -99,9 +113,10 @@ xs.map(x => x * 2)             # wire types only; no pickle fallback
 
 | | |
 |---|---|
-| `import cc_node` | registers magics; does **not** spawn until first `%%js` / `get()` / `require()` |
-| `%load_ext cc_node` | same, idempotent |
-| `%js 1+1` / `%%js` | eval on `cc_node.get()`; last expression is the result |
+| `from cc_node import require` | session `require`; spawns on first call |
+| `import cc_node` | registers magics; does **not** spawn until first `require()` / `%%js` |
+| `%load_ext cc_node` | same, idempotent; not required |
+| `%js 1+1` / `%%js` | eval on the same session; last expression is the result |
 | `-b xs` / `--bind xs,n` | publish those Python names on `globalThis` for the cell |
 | `-t chunks` / `--to` | store the result in the notebook namespace |
 | `%js_stats` | handle-table size (spawns if needed) |
@@ -146,25 +161,30 @@ Colab is not that. There, default `create()` blocks the kernel thread —
 Wire: line-JSON on dedicated fds (stdio stays yours). Bulk spill: private
 0700 dir, 0600 files, removed with the bridge.
 
-### Vs pythonmonkey / mini-racer / DIY node
+### Vs pythonia / pythonmonkey / mini-racer / DIY node
 
-Most “JS from Python” libraries are **not Node**. Bulk is a **sum** over
-1M floats (`.length` on an in-process wrapper is free and lies). Snapshot:
+Most “JS from Python” libraries are **not Node**. pythonia (PyPI
+[`javascript`](https://pypi.org/project/javascript/), JSPyBridge) is the
+packaged peer that is: `require()` on import, one child. Bulk is a
+**sum** over 1M floats (`.length` on an in-process wrapper is free and
+lies). Snapshot:
 [`cc_node_vs_alts_20260813.txt`](https://github.com/sreekotay/concurrent-c/blob/main/perf/baselines/cc_node_vs_alts_20260813.txt)
 · harness: [`benchmarks/vs_alts.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/cc_node/benchmarks/vs_alts.py).
 
-| | cc-node | DIY JSON stdio | `node -e` each | pythonmonkey | mini-racer |
-|---|---|---|---|---|---|
-| identity RTT | **20µs** | 39µs | 25ms | **<1µs** | 114µs |
-| callback | **36µs** | — | — | 1µs | — |
-| 8MB typed / list | **6.2ms shm** / 359ms | — / 197ms | — | — / 630ms proxy | — / 78ms |
-| `require('fs')` | yes | yes | yes | no | no |
-| process | child `node` | child `node` | new process/call | SpiderMonkey in-process | V8 isolate |
+| | cc-node | pythonia | DIY JSON stdio | `node -e` each | pythonmonkey | mini-racer |
+|---|---|---|---|---|---|---|
+| identity RTT | **20µs** | 42µs | 19µs | 23ms | **<1µs** | 104µs |
+| callback | **40µs** | 106µs | — | — | 1µs | — |
+| 8MB typed / list | **7.5ms shm** / 266ms | — / 481ms | — / 155ms | — | — / 609ms | — / 78ms |
+| `require('fs')` | yes | yes | yes | yes | no | no |
+| process | child `node` | child `node` | child `node` | new process/call | SpiderMonkey in-process | V8 isolate |
 
 Tiny scalars: pythonmonkey’s in-process SM beats a child. Real Node
 (`require('fs')`, native addons, callbacks, stdout stays yours): this
-package. Isolated `node -e` per call is ~1000× a persistent child.
-Optional engines SKIP if not importable — not package deps.
+package — ~2× pythonia on identity, shm for bulk, Python callables are
+sync (pythonia’s JS side sees a Promise). Isolated `node -e` per call is
+~1000× a persistent child. Optional engines SKIP if not importable —
+not package deps.
 
 The other direction (Python from Node):
 [`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
@@ -218,9 +238,11 @@ total(array.array('d', range(1_000_000)))
 ## Common issues
 
 **`Cannot find module`.** `require` / `import` resolve from the Python
-process cwd (`node_modules` next to your program), not from this wheel’s
-site-packages. `npm install lodash` in the project directory is the fix;
-or `create(node=…)` / `CC_NODE_BIN` when the wrong Node is on `PATH`.
+process cwd (`node_modules` next to your notebook or program), not from
+this wheel’s site-packages, and this package does **not** `npm install`
+on a miss (pythonia does). `npm install lodash` in that directory is
+the fix; or `create(node=…)` / `CC_NODE_BIN` when the wrong Node is on
+`PATH`.
 
 ### Empty `{}` stays a handle
 
@@ -278,7 +300,7 @@ Both bridges (npm OIDC + PyPI OIDC):
 
 Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`,
 `benchmarks.vs_alts`.
-Jupyter: `import cc_node` then `%%js` (or `%load_ext cc_node`).
+Jupyter: `from cc_node import require` (or `import cc_node` then `%%js`).
 Stress: [`stress/bridge/`](https://github.com/sreekotay/concurrent-c/tree/main/stress/bridge).  
 Own hot path in C/CC → native module (40–90ns) —
 [JS / Python interop](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).

{concurrent_c_node-0.23.0 → concurrent_c_node-0.23.2}/cc_node/__init__.py

@@ -1,9 +1,11 @@
 """cc-node: JavaScript (and every npm package) from Python.
 
-    import cc_node
-    js = cc_node.create()                 # an Isolation Domain: one node child
-    _ = js.require('lodash')              # resolved from YOUR cwd's node_modules
+    from cc_node import require
+    _ = require('lodash')                 # session child; cwd node_modules
     _.chunk([1, 2, 3, 4, 5], 2)           # [[1, 2], [3, 4], [5]]
+
+    import cc_node
+    js = cc_node.create()                 # a private child, not the session
     js.destroy()
 
 The mirror of the cc-python bridge, same rules pointed the other way:
@@ -19,8 +21,8 @@ Handles never cross domains; every door after destroy() answers
 articulately; destroy is idempotent and `with cc_node.create() as js:`
 scopes it.
 
-Notebooks (Jupyter / Colab): `import cc_node` then `%%js` or
-`cc_node.get()` — one session domain, same calling convention.
+Notebooks (Jupyter / Colab): `from cc_node import require` or
+`import cc_node` then `%%js` — one session, same calling convention.
 """
 import array
 import atexit
@@ -41,7 +43,7 @@ __all__ = [
     "JsError", "JsHandle",
     "load_ipython_extension", "unload_ipython_extension", "__version__",
 ]
-__version__ = "0.23.0"
+__version__ = "0.23.2"
 
 _NO_NODE = (
     "cc-node: no node executable (install Node, or set CC_NODE_BIN). "

{concurrent_c_node-0.23.0 → concurrent_c_node-0.23.2}/cc_node/benchmarks/vs_alts.py

@@ -6,8 +6,9 @@ Real Node (this package)
     `require('fs')`, native addons, the npm in cwd, crash isolation.
     Honest alternatives: drive a `node` child yourself. Spawn-per-call
     (`node -e`) is what people write first. A persistent JSON-stdio loop
-    is the DIY that actually competes. PyExecJS was that, abandoned.
-    `pythonodejs` claims an embed; treat as optional if importable.
+    is the DIY that actually competes. pythonia (PyPI `javascript`,
+    JSPyBridge) is the packaged peer with the same DX — `require()` on
+    import, one child. PyExecJS was eval-a-string; abandoned.
 
 A JS engine inside CPython (not Node)
     pythonmonkey — SpiderMonkey + CommonJS `require` of *pure JS*.
@@ -218,6 +219,77 @@ def bench_cc_node():
     js.destroy()
 
 
+def bench_pythonia():
+    """JSPyBridge: PyPI `javascript`, npm twin `pythonia`. Real Node child.
+    A Python callable the JS side sees is a Promise (await in the child)."""
+    try:
+        t0 = time.perf_counter()
+        from javascript import eval_js, require
+        eval_js("return 1")
+        _result("pythonia.spawn_ms", round((time.perf_counter() - t0) * 1000))
+    except ImportError:
+        _result("pythonia.rtt_us", "SKIP not installed")
+        _cap("pythonia.require_path", False, "not installed")
+        _cap("pythonia.require_fs", False, "not installed")
+        return
+
+    f = eval_js("return (x) => x")
+    f(1)
+    dt = _time_loop(500, f)
+    _result("pythonia.rtt_us", _us(dt, 500))
+
+    try:
+        g = eval_js(
+            "return async (cb) => { const v = await cb(21); return v * 2 }")
+        if g(lambda x: x + 1) != 44:
+            raise RuntimeError("callback mismatch")
+        dt = _time_loop(200, lambda _i: g(lambda x: x + 1))
+        _result("pythonia.callback_roundtrip_us", _us(dt, 200))
+        _cap("pythonia.python_callback", True,
+             "JS sees a Promise; await in the child")
+    except Exception as e:
+        _result("pythonia.callback_roundtrip_us",
+                "SKIP %s" % type(e).__name__)
+        _cap("pythonia.python_callback", False, str(e)[:80])
+
+    _result("pythonia.bulk_8mb_shm_ms", "SKIP JSON IPC, no shm")
+    try:
+        biglist = _bulk_list()
+        sm = eval_js("return " + SUM_JS)
+        got = sm(biglist)
+        expect = _bulk_sum_expect(biglist)
+        if abs(float(got) - expect) > 1e-3:
+            raise RuntimeError("pythonia bulk sum mismatch")
+        t0 = time.perf_counter()
+        for _ in range(3):
+            sm(biglist)
+        _result("pythonia.bulk_8mb_json_list_ms",
+                round((time.perf_counter() - t0) / 3 * 1000))
+    except Exception as e:
+        _result("pythonia.bulk_8mb_json_list_ms",
+                "SKIP %s" % type(e).__name__)
+
+    _cap("pythonia.require_path",
+         require("path").join("a", "b") == "a/b")
+    fd, tmp = tempfile.mkstemp()
+    try:
+        os.write(fd, b"hi")
+        os.close(fd)
+        got = require("fs").readFileSync(tmp, "utf8")
+        _cap("pythonia.require_fs", got == "hi")
+    finally:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+    try:
+        then = eval_js(
+            "return async (x) => { await Promise.resolve(); return x * 2 }")
+        _cap("pythonia.thenable", then(21) == 42)
+    except Exception as e:
+        _cap("pythonia.thenable", False, str(e)[:80])
+
+
 def bench_diy_stdio():
     t0 = time.perf_counter()
     diy = DiyStdio()
@@ -408,6 +480,7 @@ def main():
         print("SKIP need node on PATH")
         return 1
     bench_cc_node()
+    bench_pythonia()
     bench_diy_stdio()
     bench_spawn_each()
     bench_pythonmonkey()

{concurrent_c_node-0.23.0 → concurrent_c_node-0.23.2}/concurrent_c_node.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: concurrent-c-node
-Version: 0.23.0
+Version: 0.23.2
 Summary: JavaScript and npm packages from Python over the Concurrent-C bridge: one spawned Node child per domain, host-controlled lifetime.
 License: MIT
 Project-URL: Repository, https://github.com/sreekotay/concurrent-c
@@ -18,6 +18,13 @@ Requires-Dist: ipython>=7; extra == "jupyter"
 Call Node (and npm packages) from Python.
 Native types, exceptions, callbacks, and async all cross the boundary.
 
+## Why use this
+
+Call real Node from Python — `require`, native addons, npm — not a JS
+engine in-process. One child, shm for bulk, `from cc_node import require`
+in Jupyter/Colab with no `%load_ext`. pythonia is the packaged peer; this
+is faster on the wire and honest about bulk and callbacks.
+
 Part of [Concurrent-C](https://github.com/sreekotay/concurrent-c) — a
 strict C11-superset preprocessor: `.ccs` lowers to plain C and compiles
 with your host C compiler. (This bridge itself is pure Python stdlib —
@@ -28,15 +35,19 @@ bridge):
 [JS / Python interop](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).
 
 ```python
-import cc_node
-
-js = cc_node.create()                # always a child `node` process
-_ = js.require('lodash')             # cwd node_modules
+from cc_node import require          # one session child (lazy)
+_ = require('lodash')                # cwd node_modules
 _.chunk([1, 2, 3, 4, 5], 2)          # [[1, 2], [3, 4], [5]]
+```
 
+A private child (`create()`) is still there when you want N Nodes or
+an explicit lifetime — not required for the first call.
+
+```python
+import cc_node
+js = cc_node.create()                # a private Node, not the session
 semver = js.require('semver')
 semver.satisfies('1.2.3', '^1.0.0')  # True
-
 js.destroy()                         # or: with cc_node.create() as js:
 ```
 
@@ -44,12 +55,13 @@ The other direction (Python from Node):
 [`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
 (in-process by default; vs pymport / ncp / pythonia in that README).
 
-Every `create()` here is a separate Node — real addons, crash isolation,
-measurable wire. N domains = N processes.
+Every `create()` is a separate Node — real addons, crash isolation,
+measurable wire. N domains = N processes. `require()` / `get()` share
+one session for the process (the Jupyter kernel).
 
 | | this package | CC hosted (`cc_js_new(false, …)`) |
 |---|---|---|
-| API | `cc_node.create()` | `.ccs` program |
+| API | `require()` / `create()` | `.ccs` program |
 | Where | child `node` | libnode in-process |
 | Hot call | ~105µs RTT | sub-µs (needs libnode) |
 | Bulk | shm (~9.5ms / 8MB) | in-process |
@@ -60,11 +72,12 @@ measurable wire. N domains = N processes.
 
 - Always a child `node`. A call blocks until JS answers; thenables wait
   in the child. No `{ async: true }`.
+- `from cc_node import require` is the session. `create()` is a private
+  child. `reset()` / `%js_reset` / `%reset` / atexit tear the session down.
 - Scalars / `None` materialize; empty `{}` stays a handle; everything
   else is a `JsHandle` until `str()` / attrs / a call.
-- `import cc_node` then `%%js` or `cc_node.get()` — one session, not a
-  child per cell. `%load_ext` still works (idempotent).
-- `cc_node.require('path')` is `get().require('path')`.
+- Notebook: `import cc_node` registers `%%js` (no `%load_ext`). Same
+  session as `require()`.
 - `eval()` is one RTT, no extra globals. `%%js` / `eval_cell` install
   cwd `require` once.
 - `--bind` is `Object.assign(globalThis, …)` of names you name (wire
@@ -74,35 +87,36 @@ measurable wire. N domains = N processes.
 
 ```
 pip install concurrent-c-node                 # needs node on PATH
-pip install 'concurrent-c-node[jupyter]'      # magics (IPython)
+pip install 'concurrent-c-node[jupyter]'      # IPython (%%js); require() does not need this
 python -m cc_node.examples.use_node
 python -m cc_node.examples.bench_wire
 python -m cc_node.benchmarks.multi_domain
-python -m cc_node.benchmarks.vs_alts          # vs DIY node / pythonmonkey / mini-racer
+python -m cc_node.benchmarks.vs_alts          # vs pythonia / DIY node / pythonmonkey / mini-racer
 ```
 
 ## Jupyter / Colab
 
-Colab and the usual Jupyter kernel are **Python** — this package. Same
-calling convention as a script: a cell blocks until Node answers;
-thenables wait in the child. Magics and `get()` share **one** session
-for the kernel, not a spawn per cell (~28ms). Child `console.log`
-lands in the cell (inherited stdio, line-buffered).
+Same verb as pythonia: `require`. No `%load_ext`, no `create()`, no
+`destroy()` for the happy path. One session child for the kernel;
+`console.log` lands in the cell.
 
 ```python
 %pip install concurrent-c-node
 # if `node` is missing (typical Colab):
 !apt-get install -y nodejs
 
-import cc_node                 # magics register; no %load_ext
-path = cc_node.require('path')
-path.join('a', 'b')            # 'a/b'
+from cc_node import require
+require('lodash').chunk([1, 2, 3, 4, 5], 2)
 ```
 
+`import cc_node` also registers `%%js` (IPython already running; the
+`[jupyter]` extra is only if you want magics without IPython already
+installed).
+
 ```python
 %%js
 console.log('hi')              # shows in the cell
-require('path').join('a', 'b') # last expression comes back as Python
+require('lodash').chunk([1, 2, 3, 4, 5], 2)
 ```
 
 ```python
@@ -114,9 +128,10 @@ xs.map(x => x * 2)             # wire types only; no pickle fallback
 
 | | |
 |---|---|
-| `import cc_node` | registers magics; does **not** spawn until first `%%js` / `get()` / `require()` |
-| `%load_ext cc_node` | same, idempotent |
-| `%js 1+1` / `%%js` | eval on `cc_node.get()`; last expression is the result |
+| `from cc_node import require` | session `require`; spawns on first call |
+| `import cc_node` | registers magics; does **not** spawn until first `require()` / `%%js` |
+| `%load_ext cc_node` | same, idempotent; not required |
+| `%js 1+1` / `%%js` | eval on the same session; last expression is the result |
 | `-b xs` / `--bind xs,n` | publish those Python names on `globalThis` for the cell |
 | `-t chunks` / `--to` | store the result in the notebook namespace |
 | `%js_stats` | handle-table size (spawns if needed) |
@@ -161,25 +176,30 @@ Colab is not that. There, default `create()` blocks the kernel thread —
 Wire: line-JSON on dedicated fds (stdio stays yours). Bulk spill: private
 0700 dir, 0600 files, removed with the bridge.
 
-### Vs pythonmonkey / mini-racer / DIY node
+### Vs pythonia / pythonmonkey / mini-racer / DIY node
 
-Most “JS from Python” libraries are **not Node**. Bulk is a **sum** over
-1M floats (`.length` on an in-process wrapper is free and lies). Snapshot:
+Most “JS from Python” libraries are **not Node**. pythonia (PyPI
+[`javascript`](https://pypi.org/project/javascript/), JSPyBridge) is the
+packaged peer that is: `require()` on import, one child. Bulk is a
+**sum** over 1M floats (`.length` on an in-process wrapper is free and
+lies). Snapshot:
 [`cc_node_vs_alts_20260813.txt`](https://github.com/sreekotay/concurrent-c/blob/main/perf/baselines/cc_node_vs_alts_20260813.txt)
 · harness: [`benchmarks/vs_alts.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/cc_node/benchmarks/vs_alts.py).
 
-| | cc-node | DIY JSON stdio | `node -e` each | pythonmonkey | mini-racer |
-|---|---|---|---|---|---|
-| identity RTT | **20µs** | 39µs | 25ms | **<1µs** | 114µs |
-| callback | **36µs** | — | — | 1µs | — |
-| 8MB typed / list | **6.2ms shm** / 359ms | — / 197ms | — | — / 630ms proxy | — / 78ms |
-| `require('fs')` | yes | yes | yes | no | no |
-| process | child `node` | child `node` | new process/call | SpiderMonkey in-process | V8 isolate |
+| | cc-node | pythonia | DIY JSON stdio | `node -e` each | pythonmonkey | mini-racer |
+|---|---|---|---|---|---|---|
+| identity RTT | **20µs** | 42µs | 19µs | 23ms | **<1µs** | 104µs |
+| callback | **40µs** | 106µs | — | — | 1µs | — |
+| 8MB typed / list | **7.5ms shm** / 266ms | — / 481ms | — / 155ms | — | — / 609ms | — / 78ms |
+| `require('fs')` | yes | yes | yes | yes | no | no |
+| process | child `node` | child `node` | child `node` | new process/call | SpiderMonkey in-process | V8 isolate |
 
 Tiny scalars: pythonmonkey’s in-process SM beats a child. Real Node
 (`require('fs')`, native addons, callbacks, stdout stays yours): this
-package. Isolated `node -e` per call is ~1000× a persistent child.
-Optional engines SKIP if not importable — not package deps.
+package — ~2× pythonia on identity, shm for bulk, Python callables are
+sync (pythonia’s JS side sees a Promise). Isolated `node -e` per call is
+~1000× a persistent child. Optional engines SKIP if not importable —
+not package deps.
 
 The other direction (Python from Node):
 [`concurrent-c-python`](https://www.npmjs.com/package/concurrent-c-python)
@@ -233,9 +253,11 @@ total(array.array('d', range(1_000_000)))
 ## Common issues
 
 **`Cannot find module`.** `require` / `import` resolve from the Python
-process cwd (`node_modules` next to your program), not from this wheel’s
-site-packages. `npm install lodash` in the project directory is the fix;
-or `create(node=…)` / `CC_NODE_BIN` when the wrong Node is on `PATH`.
+process cwd (`node_modules` next to your notebook or program), not from
+this wheel’s site-packages, and this package does **not** `npm install`
+on a miss (pythonia does). `npm install lodash` in that directory is
+the fix; or `create(node=…)` / `CC_NODE_BIN` when the wrong Node is on
+`PATH`.
 
 ### Empty `{}` stays a handle
 
@@ -293,7 +315,7 @@ Both bridges (npm OIDC + PyPI OIDC):
 
 Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`,
 `benchmarks.vs_alts`.
-Jupyter: `import cc_node` then `%%js` (or `%load_ext cc_node`).
+Jupyter: `from cc_node import require` (or `import cc_node` then `%%js`).
 Stress: [`stress/bridge/`](https://github.com/sreekotay/concurrent-c/tree/main/stress/bridge).  
 Own hot path in C/CC → native module (40–90ns) —
 [JS / Python interop](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).

{concurrent_c_node-0.23.0 → concurrent_c_node-0.23.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "concurrent-c-node"
-version = "0.23.0"
+version = "0.23.2"
 description = "JavaScript and npm packages from Python over the Concurrent-C bridge: one spawned Node child per domain, host-controlled lifetime."
 readme = "README.md"
 requires-python = ">=3.8"