docs(view): show kernel state and Marqdo value passing
Rewrite the static foreign walkthrough without stdin-driven examples. It now demonstrates session_set from an ordinary Marqdo table, persistent kernel state across evaluations, and a foreign.session view plan sharing state across cells. Static export executes those cells and embeds the real outputs.
This commit is contained in:
1 parent
e4387259ba
commit
05d48f68a4
3 files changed
+148
-273
No files matched your search
@@ -1,23 +1,32 @@
|
||||
---
|
||||
title: Foreign kernels v2 — Python analysis in view
|
||||
description: A complete Python data walkthrough with probe, JSON calls, parallel fan-out, persistent state and view cells
|
||||
description: Kernel state, Marqdo-to-kernel values and view cells — without a stdin-only demo
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
This page is both a readable document and a runnable program. It uses the same file to show the foreign-kernel features added in v2: language probing, structured records, JSON in/out, parallel fan-out, a persistent Python kernel, and an explicit state bridge. The same source can also be opened in view as interactive cells.
|
||||
|
||||
The data is intentionally small and deterministic, so every number below can be reproduced by running the page.
|
||||
This page shows the foreign runtime as a language feature: a persistent kernel, explicit state from Marqdo values, and view cells that share kernel state. It never asks the reader to type JSON into stdin.
|
||||
|
||||
---
|
||||
|
||||
The input.
|
||||
Probe the interpreter first. The result is ordinary Marqdo data.
|
||||
|
||||
`orders` =
|
||||
**python = > foreign.probe lang="python"**
|
||||
|
||||
| @ | region | amount |
|
||||
|---|--------|--------|
|
||||
> print text=[ok](`python`)
|
||||
> print text=[version](`python`)
|
||||
|
||||
---
|
||||
|
||||
Marqdo values into a kernel.
|
||||
|
||||
The `订单` table is a normal Marqdo value. `foreign.session_set` copies it into the Python kernel as JSON; no shell and no stdin.
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 区域 | 金额 |
|
||||
|---|------|------|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
@@ -25,39 +34,73 @@ The input.
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
---
|
||||
**内核会话 = > foreign.session_open lang="python"**
|
||||
|
||||
Probe Python before using it.
|
||||
**> foreign.session_set id=`内核会话` name="orders" value=`订单`**
|
||||
|
||||
**python = > foreign.probe lang="python"**
|
||||
**total = > foreign.session_eval id=`内核会话` source="round(sum(float(row['金额']) for row in orders), 2)"**
|
||||
|
||||
> print text=[ok](`python`)
|
||||
> print text=[version](`python`)
|
||||
> print text=[result](`total`)
|
||||
|
||||
The probe record also carries `cmd`, `path` and `error`, so a site can explain a missing interpreter instead of producing a blank cell.
|
||||
The low-level kernel session is managed entirely by `foreign`; the table crossed the boundary as an explicit JSON copy.
|
||||
|
||||
---
|
||||
|
||||
A JSON call. Python reads the table as JSON, groups it, and writes one JSON result.
|
||||
Kernel state persists.
|
||||
|
||||
`analyze` =
|
||||
Two evaluations share the same kernel. The second sees the first variable.
|
||||
|
||||
**> foreign.session_eval id=`内核会话` source="values = [3, 4, 5]"**
|
||||
|
||||
**square_sum = > foreign.session_eval id=`内核会话` source="sum(value * value for value in values)"**
|
||||
|
||||
> print text=[result](`square_sum`)
|
||||
|
||||
**> foreign.session_close id=`内核会话`**
|
||||
|
||||
This is kernel state, not a one-shot process. It is created, queried and closed through `foreign`.
|
||||
|
||||
---
|
||||
|
||||
View cells share state.
|
||||
|
||||
`foreign.session` declares a view session from ordinary tables. The table names are free; this document uses `分析内核` and `分析单元`.
|
||||
|
||||
`分析内核` =
|
||||
|
||||
| @ | 名称 | 语言 |
|
||||
|---|------|------|
|
||||
| 1 | 分析 | python |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| @ | 单元 | 内核 |
|
||||
|---|------|------|
|
||||
| 1 | 准备 | 分析 |
|
||||
| 2 | 计算 | 分析 |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
|
||||
`准备` =
|
||||
```python
|
||||
orders = [
|
||||
{"区域": "华东", "金额": 120},
|
||||
{"区域": "华东", "金额": 300},
|
||||
{"区域": "华南", "金额": 90},
|
||||
{"区域": "华南", "金额": 140},
|
||||
{"区域": "华北", "金额": 220},
|
||||
{"区域": "西部", "金额": 80},
|
||||
]
|
||||
```
|
||||
|
||||
`计算` =
|
||||
```python
|
||||
import json
|
||||
import statistics
|
||||
import sys
|
||||
|
||||
raw = sys.stdin.read()
|
||||
rows = json.loads(raw) if raw.strip() else [
|
||||
{"region": "华东", "amount": 120},
|
||||
{"region": "华东", "amount": 300},
|
||||
{"region": "华南", "amount": 90},
|
||||
{"region": "华南", "amount": 140},
|
||||
{"region": "华北", "amount": 220},
|
||||
{"region": "西部", "amount": 80},
|
||||
]
|
||||
by_region = {}
|
||||
for row in rows:
|
||||
by_region.setdefault(row["region"], []).append(float(row["amount"]))
|
||||
for row in orders:
|
||||
by_region.setdefault(row["区域"], []).append(float(row["金额"]))
|
||||
|
||||
summary = []
|
||||
for region, values in sorted(by_region.items()):
|
||||
@@ -73,121 +116,15 @@ for region, values in sorted(by_region.items()):
|
||||
|
||||
print(json.dumps({
|
||||
"regions": summary,
|
||||
"total": round(sum(float(row["amount"]) for row in rows), 2),
|
||||
"count": len(rows),
|
||||
"total": round(sum(float(row["金额"]) for row in orders), 2),
|
||||
"count": len(orders),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
**result = > foreign.call code=`analyze` input=`orders`**
|
||||
`查看` consumes the `会话` handle. Run All runs `准备` then `计算` in the same Python kernel; the static export runs the same cells at build time and embeds their real outputs.
|
||||
|
||||
> print text=[count](`result`)
|
||||
> print text=[total](`result`)
|
||||
> print text=[region]([1]([regions](`result`)))
|
||||
> print text=[mean]([1]([regions](`result`)))
|
||||
The important language point:
|
||||
|
||||
A call is JSON-in / JSON-out: the table is encoded on stdin, and the final stdout value is parsed into Marqdo values.
|
||||
Tables are values passed to `foreign.session`. Kernel state lives in `foreign`. View only renders the handle and its cells. `run` still executes the same document as a program.
|
||||
|
||||
---
|
||||
|
||||
The same work as a structured record. `invoke` keeps stdout, stderr, exit code and timing even when the program fails.
|
||||
|
||||
**record = > foreign.invoke code=`analyze` input=`orders` output="json"**
|
||||
|
||||
> print text=[ok](`record`)
|
||||
> print text=[code](`record`)
|
||||
> print text=[ms](`record`)
|
||||
|
||||
Here `result` is already a parsed value, while `stdout` remains available for logging.
|
||||
|
||||
---
|
||||
|
||||
Persistent Python state. The first evaluation imports a module and creates a list; the second evaluation sees both.
|
||||
|
||||
**session = > foreign.session_open lang="python"**
|
||||
|
||||
**first = > foreign.session_eval id=`session` source="import math\nvalues = [3, 4, 5]"**
|
||||
|
||||
**second = > foreign.session_eval id=`session` source="round(math.sqrt(sum(value * value for value in values)), 3)"**
|
||||
|
||||
> print text=[result](`second`)
|
||||
|
||||
The kernel is strict and serial: evaluations do not interleave, and a timeout kills the process group.
|
||||
|
||||
---
|
||||
|
||||
The explicit state bridge. Values cross as JSON copies, never as shared object references.
|
||||
|
||||
**> foreign.session_set id=`session` name="threshold" value=2.5**
|
||||
|
||||
**threshold = > foreign.session_get id=`session` name="threshold"**
|
||||
|
||||
> print text=`threshold`
|
||||
|
||||
**> foreign.session_close id=`session`**
|
||||
|
||||
No implicit mirroring: if a variable is not pushed or pulled, the other side does not see it.
|
||||
|
||||
---
|
||||
|
||||
Parallel fan-out. Every input gets its own process; failures are isolated and order is preserved.
|
||||
|
||||
`increment` =
|
||||
```python
|
||||
import json
|
||||
import sys
|
||||
|
||||
raw = sys.stdin.read()
|
||||
value = json.loads(raw) if raw.strip() else 1
|
||||
print(json.dumps(value + 1))
|
||||
```
|
||||
|
||||
`numbers` =
|
||||
|
||||
| value |
|
||||
|-------|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
**bumped = > foreign.call_many code=`increment` inputs=`numbers` concurrency=4**
|
||||
|
||||
> print text=`bumped`
|
||||
|
||||
---
|
||||
|
||||
Cells in view. Named kernels and a cell order are ordinary bound tables, not fence metadata or YAML config.
|
||||
|
||||
```text
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | shared analysis |
|
||||
| 复核 | python | | isolated review |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | generate orders |
|
||||
| 计算指标 | 分析 | regions and totals |
|
||||
| 独立复核 | 复核 | read the JSON report |
|
||||
```
|
||||
|
||||
|
||||
`marqdo view` consumes the foreign-owned `会话` handle and renders Run All, Step, per-cell kernel switching, a journal, dirty reload and a state panel. Without that handle, cells are stateless one-shot runs. There is no separate interactive command; `marqdo run` still executes the same file as one program.
|
||||
|
||||
---
|
||||
|
||||
Why this stays readable.
|
||||
|
||||
| Layer | What the reader sees |
|
||||
|---|---|
|
||||
| Markdown | headings, prose, tables and fenced code |
|
||||
| Program | assignments, calls and return values |
|
||||
| Knowledge | frontmatter, links, task pages and generated catalog entries |
|
||||
|
||||
The foreign layer does not add syntax to the language. A fence is still a fence; a table is still a table.
|
||||
|
||||
For the lower-level API and safety defaults, read [`../../lib/foreign.mq.md`](../../lib/foreign.mq.md) and [`../../doc/design/foreign-kernel.md`](../../doc/design/foreign-kernel.md).
|
||||
There is no separate notebook CLI, no stdin requirement in this example, and no hidden language switch.
|
||||
+69
-132
@@ -1,18 +1,27 @@
|
||||
---
|
||||
title: 外联内核 v2 — Python 分析(view 单元)
|
||||
description: 从 probe、JSON 调用、并行扇出、持久状态到显式桥与 view 交互单元的完整 Python 示例
|
||||
description: 内核态、Marqdo 值传入与 view 单元 —— 不依赖 stdin 的完整示例
|
||||
导入 外联:lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这一页既是可读文档,也是可运行程序。它用同一份文件展示 v2 的外联内核能力:语言探测、结构化记录、JSON 进出、并行扇出、持久 Python 内核,以及显式状态桥。同一份源也可以在 view 中作为交互单元打开。
|
||||
|
||||
数据故意保持小而确定,因此下面每个数字都可以通过运行本页复现。
|
||||
这一页把外联运行时当作语言能力来展示:持久内核、从 Marqdo 值显式传入状态,以及共享内核状态的 view 单元。读者不需要向 stdin 输入 JSON。
|
||||
|
||||
---
|
||||
|
||||
输入数据。
|
||||
先探测解释器。结果仍然是普通 Marqdo 数据。
|
||||
|
||||
**python = > 外联.探测 语言="python"**
|
||||
|
||||
> 打印 内容=[ok](`python`)
|
||||
> 打印 内容=[version](`python`)
|
||||
|
||||
---
|
||||
|
||||
Marqdo 值进入内核。
|
||||
|
||||
`订单` 表是普通 Marqdo 值。`外联.会话设值` 把它作为 JSON 复制进 Python 内核;没有 shell,也没有 stdin。
|
||||
|
||||
`订单` =
|
||||
|
||||
@@ -25,29 +34,56 @@ description: 从 probe、JSON 调用、并行扇出、持久状态到显式桥
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
---
|
||||
**内核会话 = > 外联.会话开启 语言="python"**
|
||||
|
||||
先探测 Python。
|
||||
**> 外联.会话设值 标识=`内核会话` 名称="orders" 值=`订单`**
|
||||
|
||||
**python = > 外联.探测 语言="python"**
|
||||
**合计 = > 外联.会话求值 标识=`内核会话` 源码="round(sum(float(row['金额']) for row in orders), 2)"**
|
||||
|
||||
> 打印 内容=[ok](`python`)
|
||||
> 打印 内容=[version](`python`)
|
||||
> 打印 内容=[result](`合计`)
|
||||
|
||||
探测记录还带 `cmd`、`path` 与 `error`,所以站点可以解释“解释器缺失”,而不是显示一个空白单元。
|
||||
低层内核会话完全由 `外联` 管理;表格以显式 JSON 拷贝跨过边界。
|
||||
|
||||
---
|
||||
|
||||
JSON 调用。Python 把表读成 JSON,按区域聚合,再写出一个 JSON 结果。
|
||||
内核态是持续的。
|
||||
|
||||
`分析` =
|
||||
两次求值共享同一个内核。第二次能看到第一次创建的变量。
|
||||
|
||||
**> 外联.会话求值 标识=`内核会话` 源码="values = [3, 4, 5]"**
|
||||
|
||||
**平方和 = > 外联.会话求值 标识=`内核会话` 源码="sum(value * value for value in values)"**
|
||||
|
||||
> 打印 内容=[result](`平方和`)
|
||||
|
||||
**> 外联.会话关闭 标识=`内核会话`**
|
||||
|
||||
这是内核态,不是一次性进程。它由 `外联` 创建、查询和关闭。
|
||||
|
||||
---
|
||||
|
||||
view 单元共享状态。
|
||||
|
||||
`外联.会话` 从普通表格声明一个 view 会话。表名完全自由;本页用 `分析内核` 和 `分析单元`。
|
||||
|
||||
`分析内核` =
|
||||
|
||||
| @ | 名称 | 语言 |
|
||||
|---|------|------|
|
||||
| 1 | 分析 | python |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| @ | 单元 | 内核 |
|
||||
|---|------|------|
|
||||
| 1 | 准备 | 分析 |
|
||||
| 2 | 计算 | 分析 |
|
||||
|
||||
`会话` = > 外联.会话 内核表=`分析内核` 单元表=`分析单元`
|
||||
|
||||
`准备` =
|
||||
```python
|
||||
import json
|
||||
import statistics
|
||||
import sys
|
||||
|
||||
raw = sys.stdin.read()
|
||||
rows = json.loads(raw) if raw.strip() else [
|
||||
orders = [
|
||||
{"区域": "华东", "金额": 120},
|
||||
{"区域": "华东", "金额": 300},
|
||||
{"区域": "华南", "金额": 90},
|
||||
@@ -55,8 +91,15 @@ rows = json.loads(raw) if raw.strip() else [
|
||||
{"区域": "华北", "金额": 220},
|
||||
{"区域": "西部", "金额": 80},
|
||||
]
|
||||
```
|
||||
|
||||
`计算` =
|
||||
```python
|
||||
import json
|
||||
import statistics
|
||||
|
||||
by_region = {}
|
||||
for row in rows:
|
||||
for row in orders:
|
||||
by_region.setdefault(row["区域"], []).append(float(row["金额"]))
|
||||
|
||||
summary = []
|
||||
@@ -73,121 +116,15 @@ for region, values in sorted(by_region.items()):
|
||||
|
||||
print(json.dumps({
|
||||
"regions": summary,
|
||||
"total": round(sum(float(row["金额"]) for row in rows), 2),
|
||||
"count": len(rows),
|
||||
"total": round(sum(float(row["金额"]) for row in orders), 2),
|
||||
"count": len(orders),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
**结果 = > 外联.调用 代码=`分析` 输入=`订单`**
|
||||
`查看` 消费 `会话` 句柄。Run All 会在同一个 Python 内核里先跑 `准备` 再跑 `计算`;静态导出在构建时走同一批单元,并把真实输出嵌入页面。
|
||||
|
||||
> 打印 内容=[count](`结果`)
|
||||
> 打印 内容=[total](`结果`)
|
||||
> 打印 内容=[region]([1]([regions](`结果`)))
|
||||
> 打印 内容=[mean]([1]([regions](`结果`)))
|
||||
语言上的重点:
|
||||
|
||||
调用是 JSON 进 / JSON 出:表编码到 stdin,stdout 的最后一个值再解析成 Marqdo 值。
|
||||
表是值,传给 `外联.会话`。内核态归 `外联` 管理。view 只渲染句柄和单元。`run` 仍然把同一份文档当程序执行。
|
||||
|
||||
---
|
||||
|
||||
同样的工作也可以保留成结构化记录。`执行` 即使进程失败也保留 stdout、stderr、退出码与耗时。
|
||||
|
||||
**记录 = > 外联.执行 代码=`分析` 输入=`订单` 输出="json"**
|
||||
|
||||
> 打印 内容=[ok](`记录`)
|
||||
> 打印 内容=[code](`记录`)
|
||||
> 打印 内容=[ms](`记录`)
|
||||
|
||||
这里 `result` 已经是解析后的值,同时 `stdout` 仍可用于日志。
|
||||
|
||||
---
|
||||
|
||||
持久 Python 状态。第一次求值导入模块并创建列表;第二次求值仍能看到两者。
|
||||
|
||||
**会话 = > 外联.会话开启 语言="python"**
|
||||
|
||||
**第一次 = > 外联.会话求值 标识=`会话` 源码="import math\nvalues = [3, 4, 5]"**
|
||||
|
||||
**第二次 = > 外联.会话求值 标识=`会话` 源码="round(math.sqrt(sum(value * value for value in values)), 3)"**
|
||||
|
||||
> 打印 内容=[result](`第二次`)
|
||||
|
||||
内核严格串行:求值不会交错,超时会杀掉进程组。
|
||||
|
||||
---
|
||||
|
||||
显式状态桥。值以 JSON 拷贝跨越边界,永远不是共享对象引用。
|
||||
|
||||
**> 外联.会话设值 标识=`会话` 名称="threshold" 值=2.5**
|
||||
|
||||
**阈值 = > 外联.会话取值 标识=`会话` 名称="threshold"**
|
||||
|
||||
> 打印 内容=`阈值`
|
||||
|
||||
**> 外联.会话关闭 标识=`会话`**
|
||||
|
||||
没有隐式镜像:没有 push / pull 的变量,另一边看不到。
|
||||
|
||||
---
|
||||
|
||||
并行扇出。每个输入都有独立进程;失败互相隔离,顺序保持不变。
|
||||
|
||||
`加一` =
|
||||
```python
|
||||
import json
|
||||
import sys
|
||||
|
||||
raw = sys.stdin.read()
|
||||
value = json.loads(raw) if raw.strip() else 1
|
||||
print(json.dumps(value + 1))
|
||||
```
|
||||
|
||||
`数值` =
|
||||
|
||||
| value |
|
||||
|-------|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
**加一后 = > 外联.批量调用 代码=`加一` 输入表=`数值` 并发=4**
|
||||
|
||||
> 打印 内容=`加一后`
|
||||
|
||||
---
|
||||
|
||||
view 中的单元。命名内核和单元顺序都是普通绑定表,不是 fence 元数据或 YAML 配置。
|
||||
|
||||
```text
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | 共享分析 |
|
||||
| 复核 | python | | 独立复核 |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 生成订单 |
|
||||
| 计算指标 | 分析 | 区域与总额 |
|
||||
| 独立复核 | 复核 | 读取 JSON 报告 |
|
||||
```
|
||||
|
||||
|
||||
`marqdo view` 消费 foreign 拥有的 `会话` 句柄,渲染 Run All、Step、切换内核、journal、dirty reload 和状态面板。没有该句柄时,单元是无状态的一次性运行。没有单独的交互命令;`marqdo run` 仍把同一份文件当单个程序执行。
|
||||
|
||||
---
|
||||
|
||||
为什么它仍然可读。
|
||||
|
||||
| 层 | 读者看到什么 |
|
||||
|---|---|
|
||||
| Markdown | 标题、叙述、表格与围栏代码 |
|
||||
| 程序 | 赋值、调用与返回值 |
|
||||
| 知识 | frontmatter、链接、任务页与生成的 catalog 条目 |
|
||||
|
||||
外联层没有给语言新增语法。围栏还是围栏,表还是表。
|
||||
|
||||
底层 API 与安全默认值见 [`../../lib/外联.mq.md`](../../lib/外联.mq.md) 与 [`../../doc/design/foreign-kernel.md`](../../doc/design/foreign-kernel.md)。
|
||||
没有单独的 notebook CLI,这个示例不依赖 stdin,也没有隐藏的语言切换。
|
||||
+2
-1
@@ -94,6 +94,7 @@ fn static_cell_outputs(
|
||||
parts.push(error);
|
||||
}
|
||||
}
|
||||
let has_body = !parts.is_empty();
|
||||
let mut meta = Vec::new();
|
||||
if let Some(code) = record_field(&rec, "code").and_then(|v| match v {
|
||||
Value::Int(n) => Some(n),
|
||||
@@ -114,7 +115,7 @@ fn static_cell_outputs(
|
||||
if !meta.is_empty() {
|
||||
parts.push(format!("— {}", meta.join(" · ")));
|
||||
}
|
||||
let text = if parts.is_empty() {
|
||||
let text = if !has_body {
|
||||
"(no output)".to_string()
|
||||
} else {
|
||||
parts.join("\n\n")
|
||||
|
||||
Reference in new issue
Block a user