Metadata-Version: 2.5
Name: dolphindb-extension
Version: 0.1.0a7
Summary: Visual DolphinDB connection management for JupyterLab and Jupyter Notebook.
Project-URL: Homepage, https://github.com/realhuhu/dolphindb-extension
Project-URL: Repository, https://github.com/realhuhu/dolphindb-extension
Project-URL: Issues, https://github.com/realhuhu/dolphindb-extension/issues
Project-URL: Changelog, https://github.com/realhuhu/dolphindb-extension/blob/main/CHANGELOG.md
Author-email: realhuhu <2661467107@qq.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ddb,dolphindb,jupyter,jupyterlab,notebook
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Database :: Front-Ends
Requires-Python: >=3.10
Requires-Dist: jupyter-server<3,>=2.13
Requires-Dist: keyring<26,>=25
Provides-Extra: notebook
Requires-Dist: dolphindb<4,>=3.0.6; extra == 'notebook'
Requires-Dist: ipython<10,>=8; extra == 'notebook'
Description-Content-Type: text/markdown

# dolphindb-extension

将 [DolphinDB VS Code 插件](https://github.com/dolphindb/vscode-extension) 的能力迁移到 Jupyter，
支持 DolphinDB 脚本开发和 Notebook 中的 DDB 代码执行。

**当前版本为 `0.1.0a7`。** 在 Jupyter 侧边栏中新增、编辑、删除、测试和切换
DolphinDB 连接，查看当前连接、节点名称和服务器版本；提供 Settings Editor、DOS 编辑与独立会话，以及 Notebook 中的
`%ddb` / `%%ddb` 执行和 Python 返回值赋值，并在这些编辑区域复用上游语言服务；DOS 支持断点与单步调试。

## 可视化配置连接

1. 安装插件后重启 Jupyter。在 JupyterLab 中点击左侧海豚 D 与连接节点图标的 **DolphinDB 连接**
   按钮；在 Notebook 7 中打开一个 Notebook，通过 **View → Activate Command Palette**
   搜索并运行 `DolphinDB: 管理连接`，面板会显示在右侧。此命令也可用于 JupyterLab。
2. 点击 **新增连接**，填写连接名称、服务器 IP / 域名、端口、用户名和密码。
   可设置 1–60 秒连接超时；服务器开启 SSL 时，勾选 **使用 SSL 加密连接**。
3. 点击 **测试连接** 验证登录和节点信息，点击 **保存连接** 保存配置。
4. 在列表中点击 **连接** 或 **切换连接**。只有新连接成功后才断开旧连接，
   切换失败时原连接保持可用。当前连接区提供 **断开连接** 按钮。
5. 使用 **编辑** 更新配置，密码留空会保留已有密码，也可明确清除。
   **删除** 会移除配置、已保存的密码并断开对应连接，不修改数据库中的数据。

连接地址由 **Jupyter 服务所在机器** 访问，并通过经过 Jupyter 身份验证的 WebSocket
转发至 DolphinDB。服务器需支持 WebSocket 接口（与原 VS Code 插件相同）。
连接侧栏保留上次选择，作为 DOS 的默认连接；尚未运行的文件也可单独选择其他连接。
刷新页面后已创建的 DOS 会话会恢复，连接侧栏本身不会重新建立全局连接。

普通连接配置保存在 Jupyter 配置目录的 `dolphindb-extension/connections.json`
中，可运行 `jupyter --config-dir` 查看根目录；Windows 上通常为
`%USERPROFILE%\.jupyter\dolphindb-extension\connections.json`。
首次使用新默认目录时，会从旧 Jupyter 数据目录复制已有配置，保留原文件和已保存密码的
凭据标识；新目录已有配置时不会覆盖。显式设置的配置目录继续使用原路径。
已发布的 `0.1.0a2` 使用 Jupyter 数据目录。

密码默认只存在 Jupyter 服务内存中，重启服务后需重新输入。勾选 **记住密码** 时使用
服务器的系统凭据库（keyring）；无可用凭据库的无头 Linux 环境仍可使用会话密码。
密码不写入 JSON 配置、Notebook 或浏览器本地存储；只有建立连接时会经身份验证的接口
临时传给浏览器内的 DolphinDB SDK。编辑已有连接的地址、账号或密码会断开侧栏的测试连接，
已运行 DOS 的连接快照及会话保持不变。

可通过 `--DolphinDBExtensionApp.connections_dir=/path/to/profiles` 指定配置目录。
旧参数 `DolphinDBExtensionApp.data_dir` 继续兼容；两个参数同时设置时，新参数优先。
JupyterHub 应使用每个用户独立的服务和数据目录。

## Settings Editor（当前开发版）

在 JupyterLab 的 **Settings → Settings Editor** 中搜索 **DolphinDB**，或点击连接侧栏
顶部的齿轮按钮。命令面板也提供 `DolphinDB: 设置`。
通过该入口打开设置时会收起左侧面板，为表单留出空间；点击数据库图标可再次展开连接侧栏。

| 设置分组 | 可配置项 | 生效方式 |
| --- | --- | --- |
| 新增连接默认值 | 端口、用户名、连接超时、SSL | 用于随后打开的新增连接表单 |
| 侧栏显示 | 排序、地址与详情显隐、搜索框、首次自动打开数据库与变量面板、窄窗口收起左侧栏 | 显隐即时更新；自动打开仅用于尚未保存面板布局的首次文档，手动收起后保持收起，刷新后遵循 Jupyter 布局 |
| 代码提示与模块 | 模块目录、文档语言、自动补全、悬浮文档、自动参数提示、代码诊断 | 已打开的编辑器同步开关；关闭自动参数提示仍可手动调用 |
| 数字显示 | 实际精度，或 0–20 位小数 | 浏览器、结果表格和变量预览即时更新 |
| 数据浏览器 | 默认每页 100 行、50 列，可设置 1–1000 行、1–200 列 | 用于新浏览器和新结果；已打开浏览器保留自己的分页状态 |
| 预览 | 表预览行数、变量与表结构悬浮开关、悬浮延迟 | 后续预览使用新值；关闭开关会撤销当前悬浮框和待显示请求 |
| 执行结果 | 自动滚动、新记录默认展开 | DOS 结果同步更新；保留记录手动折叠和文档内全部折叠的选择 |
| 运行 | 批量运行遇错停止或继续 | 使用开始批量运行时的设置，弹窗会说明当前策略 |
| 高级 | 变量预览字节上限、结果缓存数量与预算、DOS 历史数量与帧预算、Notebook 元数据超时 | 预览及缓存用于后续访问；历史在下次运行或重新打开会话时应用 |

已有连接和正在编辑的表单保留各自配置。默认值不包含密码；连接列表及密码仍通过侧栏管理。
设置由 Jupyter 的 `ISettingRegistry` 保存，支持 Settings Editor 的恢复默认值、JSON 编辑，
以及管理员的 `overrides.json`。Notebook 7 读取同一设置服务；如其界面没有 Settings Editor，
请在使用同一设置目录的 JupyterLab 中修改后刷新 Notebook。

用户设置文件位于 JupyterLab 的用户设置目录中：
`dolphindb-extension/settings.jupyterlab-settings`。默认根目录通常为
`<jupyter_config_dir>/lab/user-settings`，也可由 `JUPYTERLAB_SETTINGS_DIR` 或服务配置指定。
测试启动脚本使用独立的 `.qa/settings/`，避免修改日常使用的 JupyterLab 设置。

JSON 用户覆盖示例（未列出的字段继续使用默认值）：

```json
{
  "connectionDefaults": { "timeout": 20 },
  "sidebar": { "sortOrder": "name", "showConnectionAddress": false, "alwaysShowSearch": true },
  "dataBrowser": { "pageSize": 50, "columnPageSize": 20 },
  "preview": { "tableRows": 200, "hoverDelay": 500 },
  "advanced": { "cacheEntries": 30, "metadataTimeout": 15 }
}
```

`schema/settings.json` 定义分组、说明、默认值和校验范围；`frontend/settings.ts` 提供统一的
类型、默认值解析和变更信号。后续执行、编辑器或结果展示插件可依赖 `IExtensionSettings`
服务，新增配置时按功能增加 schema 分组和对应类型，再订阅 `changed` 更新界面。
保持已有字段及插件 ID `dolphindb-extension:settings` 稳定，以保留用户配置。

## DOS 调试

**DolphinDB 调试（仅 DOS）** 按钮默认位于右侧“数据库与变量”按钮下方，使用 D + 虫子图标；`.ipynb` 不提供此调试入口。
调试复用官方 VS Code 插件的 `debug` WebSocket 协议和编码，要求 DolphinDB Server
支持调试协议（2.00.10.1 / 1.30.22.1 及以上）。连接仍通过 Jupyter 身份验证后的代理。

1. 打开 `.dos`，在文件工具栏选择连接，点击行号左侧设置断点，或按 **F9** 切换当前行断点。
2. 点击文件工具栏 **调试**，或按 **F5**。使用当前编辑内容启动独立调试会话；
   首次运行前使用此文件选定的连接，已有普通执行会话时沿用其连接快照。
   侧栏的调试按钮执行下拉框选中的 DOS；文件工具栏和 F5 执行当前编辑器中的 DOS。
3. 命中断点后，当前行高亮，侧栏显示调用栈、当前栈帧变量、源码和调试输出。
   点击栈帧切换变量作用域；变量右侧的预览按钮在数据浏览器中打开该暂停时刻的数据快照。
   导入模块的源码从调试服务器读取，支持在只读源码视图中设置断点。
   新一轮调试会关闭上一轮的模块源码窗口，重新打开时读取当前连接的源码。
4. **F5** 继续、**F10** 逐过程、**F11** 进入函数、**Shift + F11** 跳出函数；
   面板也提供暂停、异常时暂停、重新调试和停止按钮。**Shift + F5** 停止，
   **Ctrl + Shift + F5** 用最新内容重新调试。
5. 调试期间此文件只读，暂停普通运行和连接切换；停止后恢复编辑。
   每个 DOS 的调试会话互相独立，调试变量与普通执行会话变量分开。
   可在“正在运行的内核和终端”的 **DolphinDB 调试会话** 中停止单个或全部调试。

文件断点和异常暂停选项使用 Jupyter 的 `IStateDB` 保存，不写入 DOS 源码。
关闭该 DOS 的最后一个编辑视图会停止调试；刷新/关闭浏览器会断开调试连接。
普通 DOS 执行会话的恢复机制保持不变。当前服务端协议不提供条件断点、监视表达式或变量赋值。

## DOS 文件与独立会话（当前开发版）

在 JupyterLab Launcher 中点击 **新建 DOS 文件**，或在命令面板搜索同名命令；
文件浏览器右键也提供创建入口。`.dos` 使用 Jupyter 原生文本编辑器，支持保存、
重命名、撤销及语法高亮。高亮直接使用原 VS Code 插件的 DolphinDB SDK TextMate 语法
和 VS Code 的 TextMate / Oniguruma 引擎，覆盖日期时间、数值后缀、函数调用、属性、
运算符、符号字符串、转义字符及跨行注释和字符串。配色随 Jupyter 明暗主题切换，
对应 VS Code 默认 Light+ / Dark+；Notebook 中的 `%ddb` / `%%ddb` 使用同一套规则。
高亮引擎随插件打包，无需访问外部 CDN。

| 操作 | 入口 / 快捷键 |
| --- | --- |
| 运行整个文件 | 工具栏「运行文件」 / Ctrl + Shift + Enter |
| 运行选区，没有选区时运行当前行 | 「运行选中/当前行」 / Ctrl + Enter |
| 运行当前行并移至下一行 | Shift + Enter |
| 代码提示 | 自动弹出或 Ctrl + Space；Tab 接受候选并切换代码片段占位符 |
| 函数文档和签名 | 鼠标悬浮函数名；输入参数时自动显示签名；Ctrl + Shift + Space 手动触发 |
| 跳转到定义 | F12；支持当前文档和工作区模块 |
| 跳转到符号 | 命令面板「DolphinDB: 跳转到符号」 |
| 批量运行 | 工具栏或命令面板「批量运行 DOS 文件」，在原生多选框中选择文件后依次执行（Ctrl / Shift 多选） |
| 中断代码 | 工具栏「中断」；使用上游 getConsoleJobs / cancelConsoleJob 流程 |

批量运行列出已打开以及文件浏览器选中的 DOS 文件，执行开始时读取代码快照，
每个文件使用自己的连接和会话；默认遇到错误停止后续文件，可在设置中改为继续。命令面板的
「DolphinDB: 停止后续批量运行」可取消剩余文件，当前代码需通过「中断」停止。
中断沿用 SDK 的 urgent 通道，由 DolphinDB 在循环或子任务边界响应；单次 `sleep()` 等
操作可能需要等其返回。详见 [DolphinDB 作业管理](https://docs.dolphindb.com/zh/tutorials/job_management_tutorial.html)。

首次运行前，工具栏右侧的连接选择器可自由切换，默认采用连接侧栏中上次选择的连接
（尚无默认选择时采用第一个配置）。Database 面板预览该连接可见的数据库和表，变量面板为空。
**第一次提交用户代码后，文件的连接固定**，包括代码报错的情况。连接失败时不会锁定文件。
后续执行复用该文件的 DolphinDB 会话；A 文件定义的普通变量不会出现在 B 文件中。
用户显式创建的共享表、DFS 表等仍遵循 DolphinDB 自身的共享规则。

数据库和变量面板随当前 DOS 文件或 Notebook 切换。点击数据库的表名，在编辑器光标处插入
`loadTable("dfs://数据库路径", "表名")`；点击表名右侧的眼睛按钮，在弹窗中预览数据（默认前 100 行，可配置）。
鼠标停留在表名后，悬浮显示字段名、类型及可用的附加信息和备注（默认延迟 350 ms，可配置；最多前 100 个字段）。
结构预览只查询元数据，运行前可用，不会固定连接；切换连接、执行或刷新面板后会更新缓存。
变量面板沿用 VS Code 插件的 **本地变量 / 共享变量 → 数据形式** 分组，显示标量、向量、
词典、表格等类别；面板和分组显示变量数与总内存，变量行显示类型、元素数或行列数及内存。
分组支持折叠，执行后保留折叠状态；搜索时展开匹配分组，清空搜索后恢复原状态。
鼠标停留 350 ms 后使用原生提示框预览变量：表格、矩阵按行列显示，向量、集合、数对显示索引和值，
词典显示键值对，复用执行结果的原生可排序表格。浮层最多显示前 10 行、8 个数据列；
默认沿用上游 10 KiB 上限，可在高级设置调整，大变量仅显示摘要。
预览在当前文档的会话中读取，不执行编辑器代码、不追加执行结果；同一份变量快照内复用预览，
重新执行或刷新变量后失效。点击变量仍将名称插入原光标位置。
DOS 文件底部显示表格、普通结果、
print 输出和错误行号；新输出到达时自动滚动到底部，持续 print 也会跟随。
点击 **执行结果** 可收起整个面板，编辑器会占用释放的空间；工具栏提供 **全部折叠** 和 **全部展开**。
每个文件分别记忆面板和历史结果的折叠状态，新增结果、持续打印、切换或重新打开编辑器不会展开已折叠的内容。
全部折叠后新结果也保持折叠；全部展开恢复新结果默认展开。折叠偏好保存在当前页面，刷新浏览器后恢复默认。
手动折叠或展开历史结果不会跳到底部；只有展开的最新结果收到新输出时才自动跟随。
变量刷新沿用上游对可变对象的保护，只读取标量和 pair 的值，其他变量显示类型和大小，避免让向量或表失去 ownership。

DOS 和 Notebook 工具栏共用连接选择器、会话状态和 **关闭会话**，关闭前会提示释放 DDB 变量。
两者复用 Jupyter 的 `ReactiveToolbar`、`ToolbarButton` 和 `HTMLSelect`，空间不足时通过原生溢出菜单访问操作。
执行结果通过 `OutputArea` / rendermime 显示；表预览使用原生可排序 `Table`，点击列标题可切换排序。
排序基于 SDK / pandas 的原始列值，保留负数、小数、INT64 和 Decimal 精度；表头排序仅影响当前页，不改变服务器数据。
工具栏末尾的 **显示数据库与变量** 按钮可展开右侧面板，包括默认收起侧栏的 Notebook 7。
数据库、变量区域复用 Jupyter Debugger 的原生折叠面板，可拖动分隔条调整高度、分别滚动，
收起一块后另一块占用剩余空间；切换文档时保留折叠状态，面板和数据库树展开立即响应。
数据库和变量项使用原生 `TreeView` / `TreeItem`，支持方向键导航和 Enter 操作；连接表单、搜索框和选择弹窗也复用 Jupyter 组件。
点击变量可将名称插入 DOS 编辑器或 Notebook 当前代码单元格的光标处；有选区时替换选区。变量、表名插入和表预览采用 250ms
防抖，等待期间切换文档、单元格或光标会取消插入，预览请求处理中也不会重复发送。
在 **正在运行的内核和终端 → DolphinDB 会话** 中，可查看 DOS 和 Notebook 的连接及运行状态、
重新打开文件、关闭单个或所有 DDB 会话。Notebook 会话按 Python 内核去重，关闭 DDB 会话保留 Python 内核和变量。
关闭编辑器和刷新页面不会关闭服务端会话；
文件重命名后仍使用原会话。关闭会话后变量释放，该文件下次运行可重新选择连接。
网络连接真正断开时显示「已断开」，不会自动重建会话或重试代码；重启 Jupyter 会结束所有会话。

会话由 Jupyter Server 内存管理，原始结果通过官方 SDK 解析，不需要额外 Node.js 运行时。
每个会话默认保留最近 20 次执行及约 8 MiB 编码输出用于页面恢复，可在高级设置调整，超限会提示省略。
服务端校验 Jupyter 身份和 `dolphindb-extension:dos-sessions` 权限；不同登录身份不能接管
对方会话，同一个 DOS 会话同时只允许一个页面连接。JupyterHub 使用用户独立的 Jupyter 服务。

## 数据浏览器、结构和图表（当前开发版，尚未发布）

DOS 结果支持内嵌数据浏览器，点击结果工具栏的 **在独立标签页查看** 可打开完整视图。
Notebook 的展示行为按语句区分：

- 单元格最后一个表达式直接调用 `%ddb` / `%%ddb` 时，自动显示自定义组件，例如 `xxx\n%ddb ...`。
- `aaa = %ddb ...` 返回 `session.run` 的原始 Python 对象；之后直接显示 `aaa` 使用 Python / pandas 原生组件。
- `ddb_show(对象)` 或 `%ddb_show 对象` 显式展示任意 Python 对象，包括普通 Python 创建的 DataFrame、数组、列表、词典和从 DDB 取得的对象。
  表格、矩阵、张量等按类型展示，其他对象显示文本表示。该命令不重新执行 DDB 代码、不固定或切换连接。
- `%%ddb -o aaa` 只保存原始对象，之后显示 `aaa` 仍使用原生组件；调用 `ddb_show(aaa)` 可显式切换展示方式。

扩展加载后可直接调用 `ddb_show`，也可通过 `from dolphindb_extension import ddb_show` 导入。
已有同名 Python 变量不会被覆盖，此时可使用 `%ddb_show` 或自行导入。
两者也可点击变量右侧的眼睛按钮打开浏览标签页。数据库表的 **更多操作**
菜单提供完整表浏览入口，眼睛按钮用于快速预览（默认前 100 行）。

- 表、向量、数对、集合、词典和矩阵支持完整分页：每页 10–1,000 行，可跳转页码、首页和末页；
  宽表及矩阵默认按 50 列翻页，可在设置中调整。词典、ANY 向量和数组向量可逐层展开，表可以逐列查看，顶部路径可返回上层。
- 张量显示类型和维度，逐维选择切片，再分页查看叶节点。DOS 使用 SDK 的 shape、strides 和字节序，
  保留 64 位整数；Notebook 使用 Python SDK 返回的 NumPy 数组。
- 自动绘制折线、柱状、条形、面积、饼图、散点、直方图、K 线和三维曲面；支持图例、缩放、恢复视图及图像下载，
  并保留堆叠与多 Y 轴。图表库随插件打包、按需加载，使用 Jupyter 明暗主题。
- 数据库和表的 **更多操作 → 查看完整结构** 展示服务器返回的全部 schema 属性，包括 `colDefs`、
  分区方案、引擎、排序键及压缩配置；嵌套字典和字段表可以继续展开。可在首次执行前查看，保持连接可切换。
- 表菜单提供 `select`、`update`、`delete`、`truncate`、`loadTable` 和 `schema` 语句生成。
  模板使用实际字段和分区列，填写条件后自行执行；菜单操作只向原文档光标插入文本。
- 在 **Settings Editor → DolphinDB → 数字显示 → 小数位数** 统一选择 **实际精度** 或 **0–20 位小数**，
  所有已打开的 DOS 结果、DDB 自定义输出、数据浏览器、图表与变量预览即时更新；普通 Python 输出遵循 Python / pandas 自己的显示设置。
  只改变浮点数和 Decimal 的显示，排序和 `%ddb` 的返回对象保持原值；大整数、Decimal128 不经 JS Number 转换。

实时浏览始终使用打开它的文档会话。后续执行后可刷新数据；关闭或更换原会话时会明确提示重新打开。
分页、结构查询和预览不会追加执行历史。Notebook 使用 IPython 的原生 magic 转换和 AST 扩展点识别独立调用与赋值，不注册全局格式化器；
`aaa = %ddb ...` 仍取得 `session.run` 返回的原生 Python 对象，之后直接显示 `aaa` 也保持原生表示。

执行结果浏览缓存默认保留最近 20 个对象，以约 64 MiB 为淘汰预算，可在高级设置调整，最新结果始终保留；Notebook 缓存在原 Python 内核，
DOS 缓存在浏览器。仅自定义展示保留浏览缓存，接收 `%ddb` 返回值不会额外缓存对象。
缓存过期后浏览器分页提示重新展示，Notebook 原生输出不依赖这份缓存。
表、向量和矩阵从会话按页读取；结构、图表及无法在服务器切片的张量在刷新时读取并缓存完整对象。
图表类型、张量及 schema 字段取决于服务器和官方 SDK 的支持，旧服务器不提供的功能不会由插件伪造。

高级设置默认限制变量悬浮预览为 10 KiB、DOS 历史为 20 次与 8 MiB 帧数据、Notebook 元数据读取为 4 秒。
前端和服务端共同验证配置范围；清理历史或缓存不会修改 DolphinDB 会话变量。
升级扩展后，服务端历史配置需要新的 Jupyter 服务进程，Notebook 后端配置需要加载新版扩展的 Python 内核；
正常使用中修改设置不需要重启服务或内核。

## Notebook 中嵌入 DDB（当前开发版）

在 **Python 内核所在环境**安装当前开发版的 `notebook` extra（包含官方 DolphinDB Python SDK
和 IPython）；本仓库开发环境使用 `uv sync --extra notebook`。Jupyter 服务与内核使用不同环境时，
两边都需安装当前开发版插件，内核环境还需安装该 extra。

打开 Notebook 后，插件会自动注册 `%ddb` / `%%ddb`，工具栏提供 **DDB 单元格**、连接选择器和
**关闭会话**。点击 **DDB 单元格**会插入代码单元格，以 `%%ddb` 开头，支持 DolphinDB
语法高亮；使用 Notebook 自带的 Shift + Enter 或运行按钮执行。
使用 **重启内核并运行全部**时，会先恢复 DDB 连接配置，再按 Notebook 原有顺序提交代码。
扩展通过 Jupyter 的 `INotebookCellExecutor` 服务保证自动加载和连接配置消息先于用户单元格，
然后调用 Jupyter 原生执行逻辑。执行适配器不读取或解析单元格源码；`%ddb` / `%%ddb`、赋值和错误由
IPython 处理。未配置 DDB 或缺少内核扩展时，普通 Python 与其他 magic 仍可运行，DDB 错误显示在执行它的单元格中。
元数据查询与单元格共用内核执行队列，不会在后台子内核并发访问同一 DDB 会话。
查询排队等待长时间单元格时不计入元数据执行超时；断线重连后自动刷新数据库与变量。
若同时安装了其他替换此服务的扩展，
需要选择其中一个执行器插件。

此分层参考 [JupySQL 的 magic 注册和参数处理](https://github.com/ploomber/jupysql/blob/e4b695ac8cf40849bd4ce98388432a1875ad1828/src/sql/magic.py)、
[JupySQL 表格的数据排序与 comm 通信](https://github.com/ploomber/jupysql/blob/e4b695ac8cf40849bd4ce98388432a1875ad1828/src/sql/widgets/table_widget/table_widget.py)，
以及 [jupysql-plugin 的 Jupyter 编辑器扩展](https://github.com/ploomber/jupysql-plugin/blob/c3af36708261761b36e591a0913dd9f794ca3702/src/editor/index.ts)。
`%%ddb -o` / `--out` 使用 IPython 的 `magic_arguments`，可通过 `%ddb?` 查看参数帮助；DolphinDB 语义和会话仍由官方 SDK 与原 VS Code 算法提供。

单行代码可直接显示结果，也可赋给 Python 变量：

```python
aaa = %ddb 1 + 1
print(aaa)  # 2

prices = %ddb table(1..3 as id, 10.5 11.2 12.3 as price)
prices["price"].mean()  # 返回的 prices 是 pandas.DataFrame
```

`%%ddb` 必须位于单元格第一行，其后内容原样作为 DolphinDB 脚本执行：

```text
%%ddb
t = table(1..3 as id, 10.5 11.2 12.3 as price)
print("DolphinDB ready")
select * from t
```

多行代码的最终返回值可通过 `-o` / `--out` 保存到 Python 命名空间：

```text
%%ddb -o aaa
select id, price from t where price > 11
```

随后在普通 Python 单元格使用 `aaa`。这些返回值直接来自官方
[`Session.run`](https://docs.dolphindb.com/en/pydoc/BasicOperations/Session/OtherParams.html)，
保留标量、NumPy 数组、pandas DataFrame、日期时间等 SDK 原生类型，不经过 JSON 或字符串转换。
代码中的 `$`、花括号、引号不会被 IPython 变量插值修改。`print()` 经 SDK 的会话消息回调
显示在当前单元格中，执行错误通过 Notebook 标准错误输出显示。

首次运行前默认使用侧栏选择的连接，也可通过 Notebook 工具栏单独切换。第一次执行建立该
Python 内核的 DolphinDB 会话并固定连接，后续 `%ddb` 和 `%%ddb` 共用会话变量；代码报错也保留会话。
关闭 Notebook 页面或刷新浏览器后，Python 内核和 DDB 会话仍可复用。执行 `%ddb_close` 或点击
**关闭会话**释放 DDB 会话后可重新选连接；已有 Python 返回值变量仍保留在内核中。
右侧数据库与变量面板在首次运行前预览所选连接的数据库；执行后自动显示该 Python 内核的 DDB
会话变量，并在执行结束后刷新。表名点击插入 `loadTable(...)`，眼睛按钮按配置预览数据（默认前 100 行），预览不固定连接。
关闭或重启 Python 内核会结束其 DDB 会话，也可以在 **正在运行的内核和终端 → DolphinDB 会话** 中只关闭 DDB 会话。
会话列表通过 Jupyter comm 查询已有会话，关闭 Notebook 页面或刷新后仍能发现；未运行 DDB 的 Notebook 不会列入。
如果两个 Notebook 显式共用同一个 Python 内核，它们也共用该 DDB 会话；DOS 文件会话保持独立。

Notebook 由 Python 内核通过原生 TCP / SSL 连接 DolphinDB，内核所在机器需要能访问配置的地址；
连接及执行超时遵循官方 Python SDK 默认值，侧栏的 WebSocket 连接超时不用于限制查询执行时间。
密码通过经过身份验证的 Jupyter API 和内核 comm 临时传递，不写入单元格、Notebook 元数据、
输出或执行历史。仅存在 Jupyter 服务内存中的密码也可使用。

在独立 IPython 环境或需要手动加载时，可以运行：

```python
%load_ext dolphindb_extension
%ddb_connect "连接名称"
aaa = %ddb 1 + 1
%ddb_close
```

手动选择读取 Jupyter 配置目录中的已保存连接和系统凭据库；可用 `DOLPHINDB_CONNECTIONS_DIR`
环境变量指定自定义连接目录。服务内存中的临时密码需通过 Notebook 工具栏传入。
`%ddb_connect` 不带参数时显示当前连接和状态，不显示密码。

## 代码提示与模块（当前开发版）

`.dos`、`%%ddb` 正文以及 `aaa=%ddb ...` 中的 DDB 部分使用同一套语言服务。普通 Python
区域继续使用 Jupyter 的 Python 补全；Python 字符串和注释中的 `%ddb` 不会被识别为 DDB。

| 能力 | 实现与使用方式 |
| --- | --- |
| 内置提示 | 与上游相同的 `DocsProvider`、模糊匹配、函数、关键字和常量资料 |
| 函数帮助 | 中英文完整 Markdown 文档、示例和参数签名；随光标更新当前参数 |
| 本地代码 | 上游作用域分析、函数参数及局部变量、函数注释、定义跳转和符号列表 |
| 代码片段 | 上游 `def` 函数片段及函数参数占位符，Tab / Shift + Tab 切换 |
| 模块 | `use` 模块名、`module::function`、自动插入 `use`、跨文件函数文档及 F12 |
| SQL 与会话 | 当前会话变量、内存表字段、DFS 数据库和表、catalog / schema、SQL 上下文及 `loadTable` 参数 |
| 模块诊断 | 上游缺失模块诊断，以编辑器警告显示 |

模块索引通过 Jupyter Contents 服务读取 `.dos` 文件，包含已打开但尚未保存的修改。
Settings Editor 的 **模块目录**使用相对 Jupyter 文件根目录的路径，留空时扫描当前文档所在目录
及其子目录；修改磁盘文件后最多等待 15 秒，或运行「DolphinDB: 刷新模块索引」。模块文件需具有
`module 模块名` 声明。模块补全及自动导入只修改编辑器代码；实际运行 `use` 时，模块仍需存在于
DolphinDB 服务端的模块搜索路径中。

Notebook 会合并各 DDB 单元格的静态符号，F12 可跳到其他单元格；运行时提示读取当前 Python
内核拥有的 DDB 会话。DOS 提示读取该文件的独立会话。首次执行前，元数据预览允许继续切换连接，
首次执行后使用固定会话；编辑器内容不会作为任意表达式提交给数据库以获取提示。
运行中或元数据权限不足时，静态提示仍可用，动态候选可能暂不可用。

这里迁移的是固定上游版本已有的语言算法。缺失模块诊断不等同于完整语法或类型检查；其他
VS Code 功能（例如调试器和所有数据交互视图）的整体进度见下表。

## 迁移进度

目标是覆盖原 VS Code 插件的全部功能，并增加 Notebook 集成；以下为主要迁移范围：

- [x] 在 Jupyter 侧边栏配置、管理和切换 DolphinDB 连接。
- [x] 创建、编辑 `.dos` 文件，并像选择 Python 内核一样选择执行连接。
- [x] 执行文件、选中代码或当前行，批量运行、显示运行状态并支持中断。
- [x] 每个 DOS 独立会话、首次执行后固定连接，并接入 Jupyter 正在运行面板。
- [x] 在 Python Notebook 中通过 `%ddb` / `%%ddb` 执行 DDB，并获取原生 Python 返回值。
- [x] DOS 和 Notebook 的语法高亮、代码补全、函数文档和活动参数签名。
- [x] 上游作用域、代码片段、SQL 上下文、模块补全与自动导入、定义跳转及缺失模块诊断。
- [x] 显示执行结果、`print()` 输出和错误信息。
- [x] 浏览数据库、表和各文件的会话变量，预览表格。
- [ ] 向量/矩阵交互视图及 CSV 导出。
- [x] DOS 独立调试面板、断点、单步、调用栈、变量预览、异常暂停和调试会话管理。

面向 JupyterLab 4 和 Jupyter Notebook 7；Notebook magic 当前支持 Python / IPython 内核。

## 安装

需要 Python 3.10 或更高版本，以及 JupyterLab 4 / Notebook 7。
Python 包已包含预构建前端，安装使用时无需 Node.js。
使用 `notebook` 可选依赖同时安装 Notebook magic 所需的 DolphinDB Python SDK 与 IPython：

```shell
pip install "dolphindb-extension[notebook]==0.1.0a7"
```

仅使用 DOS 编辑器和连接管理时，可以省略 `[notebook]`。

包的 Python 导入名称为 `dolphindb_extension`：

```python
from dolphindb_extension import __version__

print(__version__)
```

## 本地开发

使用 [uv](https://docs.astral.sh/uv/) 管理 Python 环境、锁文件和构建。
开发环境固定为 Python 3.12，运行时最低支持 Python 3.10。

```shell
git clone --recurse-submodules https://github.com/realhuhu/dolphindb-extension.git
cd dolphindb-extension
uv sync --locked --extra notebook
npm ci
uv run --extra notebook python scripts/sync_upstream.py --check
uv run --extra notebook python scripts/sync_language.py --check
uv run --extra notebook python scripts/sync_dataview.py --check
uv run --extra notebook python scripts/sync_debugger.py --check
npm exec tsc
uv run --extra notebook jupyter-builder build .
npm test
uv run --extra notebook pytest
uv build --no-sources
uvx twine check --strict dist/*
```

源码构建和前端测试需要 Node.js 22.18+ 和 npm。首次 `uv sync` 会自动构建前端；开发过程中修改
TypeScript 后运行 `npm exec tsc` 和 `uv run jupyter-builder build .`。
也可将 uv 环境激活后直接运行 `npm run build`。
构建后运行 `uv sync --extra notebook --reinstall-package dolphindb-extension`，重启 Jupyter 并刷新页面。

服务端位于 `src/dolphindb_extension/`，侧边栏位于 `frontend/`，样式位于 `style/`。
GitHub Actions 检查源码复用的一致性、服务端 API、认证、二进制转发、构建产物及独立安装。
使用 `uv run --extra notebook python scripts/dev_server.py` 可启动独立的本机测试环境（端口 8890），
配置、登录令牌和日志保存在被 Git 忽略的 `.qa/` 下，测试工作区与项目源码分离。

## 复用上游源码

`upstream/vscode-extension` 是固定提交的 Git submodule。连接初始化、登录状态、节点信息、
集群信息和版本查询等 9 个方法由 `scripts/sync_upstream.py` 从上游 `src/connector.ts`
提取，`src/commons.ts` 的共享定义原样复制。仅替换浏览器入口、移除 VS Code 界面副作用，
并补充严格类型；来源、提交及适配记录见 `frontend/upstream/provenance.json`。
`src/commands.ts` 的实际执行表达式（包括 `line://` 行号与 print 监听）和 4 个数据库
辅助函数也经该脚本提取，见 `frontend/upstream/execution.ts`。
`scripts/sync_language.py` 提取上游语言服务的符号分析、补全、SQL 上下文、定义、悬浮与诊断
算法，记录固定提交与每个源文件的 SHA-256，见 `frontend/upstream/language/provenance.json`。
适配层用 Jupyter Contents 和各文档/内核的会话元数据替换 VS Code 的全局服务，使用
CodeMirror 和 Jupyter 编辑器扩展注册接口展示提示，无需启动 Node 语言服务器。
内置文档和签名直接使用上游同款 `DocsProvider`、`docs.zh.json` / `docs.en.json` 和语言关键字表。
`scripts/sync_dataview.py` 提取 `src/dataview/obj.tsx` 的 `get_chart_option`，保留原图表系列构造，
替换主题颜色和浏览器辅助函数，并修正空数据、常量直方图和零成交量 K 线边界。
来源及适配记录见 `frontend/upstream/dataview-provenance.json`。浏览器分页沿用上游查询方式，
表操作模板适配自 `src/commands.ts` 的 `table_action` / `get_clause`，UI 使用 Jupyter 原生组件。
`scripts/sync_debugger.py` 提取调试协议的二进制编解码函数，记录源码哈希和适配范围，
见 `frontend/upstream/debugger-provenance.json`；调试面板复用 Jupyter 的调用栈、断点和变量组件。
通信和数据类型解析直接使用上游锁定的 `dolphindb@3.1.41`。服务端仅识别连接、打印和结果
的消息边界以保留会话及输出，不实现另一套 DolphinDB 数据类型编解码器。

更新上游时先更新 submodule，再运行 `uv run python scripts/sync_upstream.py`、
`uv run python scripts/sync_language.py`、`uv run python scripts/sync_dataview.py` 和
`uv run python scripts/sync_debugger.py`，
检查差异并重新构建。完整 VS Code 的 TreeView、编辑器等 API 由 Jupyter 适配；其他功能
将在后续迁移中继续复用上游模块。构建产物包含所需代码，安装时不需要下载 submodule。

## 发布

同步更新 `pyproject.toml` 与 `package.json` 中的版本（例如 `0.1.0a7` 对应
`0.1.0-alpha.7`）、`package-lock.json` 和 `CHANGELOG.md`，运行 `uv lock`，
重新构建前端，再在干净的 `dist/` 目录中构建和检查产物。提交代码并创建对应版本的 Git 标签后发布。

```shell
uv auth login https://upload.pypi.org --username __token__
uv publish
```

登录时在交互提示中输入 PyPI API token。凭据保存在 uv 的本机凭据存储中，
不应写入源码、提交记录或构建产物。

## 许可证

采用 [Apache License 2.0](LICENSE)。复用的 DolphinDB VS Code 源码保留上游许可，
详见 [NOTICE](NOTICE)；第三方依赖遵循各自许可证。
