concurrent-c-node 0.22.1__tar.gz → 0.23.1__tar.gz

{concurrent_c_node-0.22.1 → concurrent_c_node-0.23.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: concurrent-c-node
-Version: 0.22.1
+Version: 0.23.1
 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
@@ -28,15 +28,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 +48,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,10 +65,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.
-- `%load_ext cc_node` then `%%js` — one kernel domain
-  (`cc_node.kernel()`), not a child per cell.
+- 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
@@ -73,47 +80,58 @@ 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 share **one** domain for the
-kernel, not a spawn per cell (~28ms).
+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
-%load_ext cc_node
 
+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
-const path = require('path')
-path.join('a', 'b')          // last expression comes back as Python
+console.log('hi')              # shows in the cell
+require('lodash').chunk([1, 2, 3, 4, 5], 2)
 ```
 
 ```python
 xs = [1, 2, 3, 4]
 
 %%js -b xs -t chunks
-xs.map(x => x * 2)           // wire types only; no pickle fallback
+xs.map(x => x * 2)             # wire types only; no pickle fallback
 ```
 
 | | |
 |---|---|
-| `%load_ext cc_node` | register magics; does **not** spawn until first `%%js` |
-| `%js 1+1` / `%%js` | eval on `cc_node.kernel()`; 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) |
-| `%js_reset` | `destroy()` the kernel child; next `%%js` spawns again |
-| `cc_node.kernel()` | the same domain the magics use; `create()` is still a private child |
+| `%js_reset` / `cc_node.reset()` | `destroy()` the session child; `%reset` does this too |
+| `cc_node.get()` | the session the magics use; `create()` is still a private child |
+| `cc_node.kernel()` | alias of `get()` |
+| `cc_node.require('fs')` | `get().require('fs')` |
 | `JsHandle` display | cheap `JsHandle #3` — repr does not cross the wire |
 
 `eval()` is unchanged (one RTT, no extra globals). `%%js` / `eval_cell`
@@ -151,25 +169,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)
@@ -184,6 +207,7 @@ vs pymport / ncp / pythonia.
   `destroy()`; afterwards: `bridge is closed`.
 - `eval_cell(src, bindings=)` is the notebook door (`%%js`): cwd
   `require` once, optional `globalThis` binds; `eval()` stays one RTT.
+  `get()` / `require()` / `eval()` at module level share that session.
 - Crash isolation, not a sandbox. `destroy()` is cooperative; an
   in-flight CPU-bound call finishes or you kill the child
   ([`bridge_stress.md`](https://github.com/sreekotay/concurrent-c/blob/main/stress/bridge/bridge_stress.md)).
@@ -222,9 +246,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
 
@@ -282,7 +308,7 @@ Both bridges (npm OIDC + PyPI OIDC):
 
 Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`,
 `benchmarks.vs_alts`.
-Jupyter: `%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.22.1 → concurrent_c_node-0.23.1}/README.md

@@ -13,15 +13,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 +33,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,10 +50,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.
-- `%load_ext cc_node` then `%%js` — one kernel domain
-  (`cc_node.kernel()`), not a child per cell.
+- 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
@@ -58,47 +65,58 @@ 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 share **one** domain for the
-kernel, not a spawn per cell (~28ms).
+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
-%load_ext cc_node
 
+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
-const path = require('path')
-path.join('a', 'b')          // last expression comes back as Python
+console.log('hi')              # shows in the cell
+require('lodash').chunk([1, 2, 3, 4, 5], 2)
 ```
 
 ```python
 xs = [1, 2, 3, 4]
 
 %%js -b xs -t chunks
-xs.map(x => x * 2)           // wire types only; no pickle fallback
+xs.map(x => x * 2)             # wire types only; no pickle fallback
 ```
 
 | | |
 |---|---|
-| `%load_ext cc_node` | register magics; does **not** spawn until first `%%js` |
-| `%js 1+1` / `%%js` | eval on `cc_node.kernel()`; 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) |
-| `%js_reset` | `destroy()` the kernel child; next `%%js` spawns again |
-| `cc_node.kernel()` | the same domain the magics use; `create()` is still a private child |
+| `%js_reset` / `cc_node.reset()` | `destroy()` the session child; `%reset` does this too |
+| `cc_node.get()` | the session the magics use; `create()` is still a private child |
+| `cc_node.kernel()` | alias of `get()` |
+| `cc_node.require('fs')` | `get().require('fs')` |
 | `JsHandle` display | cheap `JsHandle #3` — repr does not cross the wire |
 
 `eval()` is unchanged (one RTT, no extra globals). `%%js` / `eval_cell`
@@ -136,25 +154,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)
@@ -169,6 +192,7 @@ vs pymport / ncp / pythonia.
   `destroy()`; afterwards: `bridge is closed`.
 - `eval_cell(src, bindings=)` is the notebook door (`%%js`): cwd
   `require` once, optional `globalThis` binds; `eval()` stays one RTT.
+  `get()` / `require()` / `eval()` at module level share that session.
 - Crash isolation, not a sandbox. `destroy()` is cooperative; an
   in-flight CPU-bound call finishes or you kill the child
   ([`bridge_stress.md`](https://github.com/sreekotay/concurrent-c/blob/main/stress/bridge/bridge_stress.md)).
@@ -207,9 +231,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
 
@@ -267,7 +293,7 @@ Both bridges (npm OIDC + PyPI OIDC):
 
 Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`,
 `benchmarks.vs_alts`.
-Jupyter: `%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.22.1 → concurrent_c_node-0.23.1}/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): `%load_ext cc_node` then `%%js` — one
-kernel-scoped domain (`cc_node.kernel()`), 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
@@ -36,10 +38,12 @@ import sys
 import tempfile
 
 __all__ = [
-    "create", "kernel", "reset_kernel", "JsError", "JsHandle",
+    "create", "get", "reset", "kernel", "reset_kernel",
+    "require", "eval", "eval_cell", "import_module", "stats",
+    "JsError", "JsHandle",
     "load_ipython_extension", "unload_ipython_extension", "__version__",
 ]
-__version__ = "0.22.1"
+__version__ = "0.23.1"
 
 _NO_NODE = (
     "cc-node: no node executable (install Node, or set CC_NODE_BIN). "
@@ -161,12 +165,14 @@ class Bridge:
         # numbers in the child, so the broker learns them from the env.
         req_r, req_w = os.pipe()
         resp_r, resp_w = os.pipe()
+        preload = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                               "stdio_line.cjs")
         env = dict(os.environ,
                    CC_WIRE_IN=str(req_r), CC_WIRE_OUT=str(resp_w),
                    CC_NODE_SHM_DIR=self._shm_dir)
         try:
             self._p = subprocess.Popen(
-                [node, broker],
+                [node, "-r", preload, broker],
                 pass_fds=(req_r, resp_w),
                 env=env,
                 cwd=os.getcwd(),
@@ -645,19 +651,19 @@ def create(node=None):
     return Bridge(node=node)
 
 
-_kernel = None
+_session = None
 
 
-def kernel(node=None):
-    """Process-wide domain for notebooks. Lazy; magics share it.
-    Scripts that want a private child still call `create()`."""
-    global _kernel
-    b = _kernel
+def get(node=None):
+    """Session domain: one child for this process (the Jupyter kernel).
+    Lazy. Magics share it. `create()` is still a private child."""
+    global _session
+    b = _session
     if b is not None and not b.closed:
         if node is not None and node != b._node_bin:
             raise JsError(
-                "cc-node: kernel() already live with a different node; "
-                "reset_kernel() / %js_reset first")
+                "cc-node: get() already live with a different node; "
+                "reset() / %js_reset first")
         return b
     b = create(node=node)
     try:
@@ -665,15 +671,15 @@ def kernel(node=None):
     except Exception:
         b.destroy()
         raise
-    _kernel = b
+    _session = b
     return b
 
 
-def reset_kernel():
-    """Destroy the kernel-scoped domain. Next `kernel()` / `%%js` spawns."""
-    global _kernel
-    b = _kernel
-    _kernel = None
+def reset():
+    """Destroy the session domain. Next get() / %%js spawns."""
+    global _session
+    b = _session
+    _session = None
     if b is not None:
         try:
             b.destroy()
@@ -681,10 +687,61 @@ def reset_kernel():
             pass
 
 
+kernel = get
+reset_kernel = reset
+
+
+def require(name):
+    return get().require(name)
+
+
+def eval(src):  # noqa: A001 — session eval, pythonia-shaped
+    return get().eval(src)
+
+
+def eval_cell(src, bindings=None):
+    return get().eval_cell(src, bindings)
+
+
+def import_module(name):
+    return get().import_module(name)
+
+
+def stats():
+    return get().stats()
+
+
 def load_ipython_extension(ip):
     from .magics import load_ipython_extension as _load
     _load(ip)
+    if getattr(ip, "_cc_node_lifecycle", False):
+        return
+    ip._cc_node_lifecycle = True
+    orig = getattr(ip, "reset", None)
+    if orig is not None:
+        def _reset(*args, **kwargs):
+            reset()
+            return orig(*args, **kwargs)
+        ip.reset = _reset
 
 
 def unload_ipython_extension(ip):
-    reset_kernel()
+    reset()
+
+
+def _boot_ipython():
+    # Already in a kernel: IPython is in sys.modules. Do not import it
+    # just because the extra is installed — scripts stay spawn-free.
+    if "IPython" not in sys.modules:
+        return
+    try:
+        from IPython import get_ipython
+    except ImportError:
+        return
+    ip = get_ipython()
+    if ip is None:
+        return
+    load_ipython_extension(ip)
+
+
+_boot_ipython()

{concurrent_c_node-0.22.1 → concurrent_c_node-0.23.1}/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.22.1 → concurrent_c_node-0.23.1}/cc_node/magics.py

@@ -2,7 +2,7 @@
 from IPython.core.magic import Magics, line_cell_magic, line_magic, magics_class
 from IPython.core.magic_arguments import argument, magic_arguments, parse_argstring
 
-from . import JsError, kernel, reset_kernel
+from . import JsError, get, reset
 
 
 def _bind_map(names, ns):
@@ -30,7 +30,7 @@ class CcNodeMagics(Magics):
     @argument("code", nargs="*", help="JS source (line magic)")
     @line_cell_magic
     def js(self, line, cell=None):
-        """Eval JavaScript on the kernel-scoped domain.
+        """Eval JavaScript on the session domain (`cc_node.get()`).
 
         Line:  %js 1 + 1
         Cell:  %%js   then a body; last expression is the result.
@@ -45,20 +45,20 @@ class CcNodeMagics(Magics):
             raise JsError("cc-node: empty %js / %%js")
         ns = self.shell.user_ns
         bindings = _bind_map(args.bind, ns)
-        result = kernel().eval_cell(src, bindings or None)
+        result = get().eval_cell(src, bindings or None)
         if args.to:
             ns[args.to] = result
         return result
 
     @line_magic
     def js_reset(self, line):
-        """Destroy the kernel-scoped Node child. Next %%js spawns again."""
-        reset_kernel()
+        """Destroy the session Node child. Next %%js / get() spawns again."""
+        reset()
 
     @line_magic
     def js_stats(self, line):
-        """Handle-table size of the kernel domain (spawns if needed)."""
-        return kernel().stats()
+        """Handle-table size of the session domain (spawns if needed)."""
+        return get().stats()
 
 
 def load_ipython_extension(ip):

concurrent_c_node-0.23.1/cc_node/stdio_line.cjs

@@ -0,0 +1,13 @@
+'use strict';
+/* Long-lived child: inherited stdout is often a pipe (Jupyter, nohup).
+ * Node then block-buffers console.log until the buffer fills or exit.
+ * Blocking writes make print land in the cell as it happens. TTY is
+ * already blocking — this is a no-op there. */
+function block(s) {
+  try {
+    if (s && s._handle && typeof s._handle.setBlocking === 'function')
+      s._handle.setBlocking(true);
+  } catch (e) { /* ignore */ }
+}
+block(process.stdout);
+block(process.stderr);

{concurrent_c_node-0.22.1 → concurrent_c_node-0.23.1}/concurrent_c_node.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: concurrent-c-node
-Version: 0.22.1
+Version: 0.23.1
 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
@@ -28,15 +28,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 +48,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,10 +65,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.
-- `%load_ext cc_node` then `%%js` — one kernel domain
-  (`cc_node.kernel()`), not a child per cell.
+- 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
@@ -73,47 +80,58 @@ 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 share **one** domain for the
-kernel, not a spawn per cell (~28ms).
+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
-%load_ext cc_node
 
+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
-const path = require('path')
-path.join('a', 'b')          // last expression comes back as Python
+console.log('hi')              # shows in the cell
+require('lodash').chunk([1, 2, 3, 4, 5], 2)
 ```
 
 ```python
 xs = [1, 2, 3, 4]
 
 %%js -b xs -t chunks
-xs.map(x => x * 2)           // wire types only; no pickle fallback
+xs.map(x => x * 2)             # wire types only; no pickle fallback
 ```
 
 | | |
 |---|---|
-| `%load_ext cc_node` | register magics; does **not** spawn until first `%%js` |
-| `%js 1+1` / `%%js` | eval on `cc_node.kernel()`; 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) |
-| `%js_reset` | `destroy()` the kernel child; next `%%js` spawns again |
-| `cc_node.kernel()` | the same domain the magics use; `create()` is still a private child |
+| `%js_reset` / `cc_node.reset()` | `destroy()` the session child; `%reset` does this too |
+| `cc_node.get()` | the session the magics use; `create()` is still a private child |
+| `cc_node.kernel()` | alias of `get()` |
+| `cc_node.require('fs')` | `get().require('fs')` |
 | `JsHandle` display | cheap `JsHandle #3` — repr does not cross the wire |
 
 `eval()` is unchanged (one RTT, no extra globals). `%%js` / `eval_cell`
@@ -151,25 +169,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)
@@ -184,6 +207,7 @@ vs pymport / ncp / pythonia.
   `destroy()`; afterwards: `bridge is closed`.
 - `eval_cell(src, bindings=)` is the notebook door (`%%js`): cwd
   `require` once, optional `globalThis` binds; `eval()` stays one RTT.
+  `get()` / `require()` / `eval()` at module level share that session.
 - Crash isolation, not a sandbox. `destroy()` is cooperative; an
   in-flight CPU-bound call finishes or you kill the child
   ([`bridge_stress.md`](https://github.com/sreekotay/concurrent-c/blob/main/stress/bridge/bridge_stress.md)).
@@ -222,9 +246,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
 
@@ -282,7 +308,7 @@ Both bridges (npm OIDC + PyPI OIDC):
 
 Examples: `use_node`, `bench_wire`, `benchmarks.multi_domain`,
 `benchmarks.vs_alts`.
-Jupyter: `%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.22.1 → concurrent_c_node-0.23.1}/concurrent_c_node.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 cc_node/__init__.py
 cc_node/broker.cjs
 cc_node/magics.py
+cc_node/stdio_line.cjs
 cc_node/benchmarks/__init__.py
 cc_node/benchmarks/multi_domain.py
 cc_node/benchmarks/vs_alts.py

{concurrent_c_node-0.22.1 → concurrent_c_node-0.23.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "concurrent-c-node"
-version = "0.22.1"
+version = "0.23.1"
 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"
@@ -26,6 +26,6 @@ Documentation = "https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-nod
 packages = ["cc_node", "cc_node.examples", "cc_node.benchmarks"]
 
 [tool.setuptools.package-data]
-cc_node = ["broker.cjs"]
+cc_node = ["broker.cjs", "stdio_line.cjs"]
 "cc_node.examples" = ["*.py"]
 "cc_node.benchmarks" = ["*.py"]