py-elk

中文 | English

面向 Python 的原生图布局引擎，目标是实现 Eclipse Layout Kernel（ELK）的布局能力，并对齐 JavaScript 版本 elkjs 的公开接口和 ELK JSON 数据格式。

0.1.0 原生 Python 实现。 默认注册 12 个算法、243 个选项、8 个类别，包含完整 Layered 策略及 196 个 Python 模块。差分、独立几何、平台和安装证据分别记录实际适用范围；注册数量不表示所有输入与选项组合均已验证。活动源码与执行方法见当前实施状态。旧 E07/E08 的 0–8 节点等切片边界仅描述历史验收，不再是当前公共入口的能力限制。

PyPI 发行名为 py-visactor-elk，Python 导入名为 pyelk：

python -m pip install py-visactor-elk==0.1.0

实际发布及下载验证状态见 发行说明。

项目目标

E09 实验接口支持 await elk.layout(graph, {"logging": True, "measureExecutionTime": True})：日志树采集自真实处理器调用，根 logging 为保留字段，嵌套业务同名字段保留。executionTime 延续固定 elkjs 的整数 wall 毫秒差乘1000再乘1e-9，不能当作普通秒或CPU时间。运行示例见 diagnostics.py，精确规则见 ADR0008；本轮最终验收仍以状态页和同包证据为准。

• 在 Python 中实现布局算法；运行布局不依赖 Node.js、Java、浏览器或对 elkjs 的子进程调用。
• 兼容 elkjs 的 ELK 入口、异步布局调用、元数据查询、选项命名及输入输出字段。
• 实现 layered 的分层、节点定位、边路由、端口与层级图，以及另外 11 个布局算法；按实际验证范围记录结果。
• 通过固定版本的 JavaScript 参考实现建立差分测试，持续记录支持范围和数值差异。
• 适用于流程图、数据流图，以及 py-mermaid 等上层图形项目的布局后端；本项目只计算几何信息，不承担渲染。
• py-mermaid 后续将布局后端替换成 py-elk，以本项目的 elkjs 0.12.1 为唯一行为基线，不建立旧 ELK 版本的兼容分支。

对齐基线

基线在 2026-11-02 核验。升级参考版本时必须更新基线记录、重新生成样例并审查差异，不直接跟随上游开发分支。

真实默认注册元数据为 12 个算法、243 个选项、8 个类别，均保留在兼容清单。历史切片与当前完整实现的证据分别记录，不由元数据数量推导所有行为均已验证。64 个 elkjs 源文件（含 14 个 Mocha 文件）是来源索引，不是断言通过数。精确外部Java构建仍未核实；当前移植使用独立审查的固定生成worker，见来源说明。

开始开发

以下命令在项目根目录使用 CPython 3.11+ 执行。先创建并激活独立环境，再安装当前本地包；正式发布状态见发行说明。

python -m venv .venv

激活环境后：

python -m pip install -e ".[dev]"
python scripts/iteration/implementation_interfaces.py --source-dir src --out test-runs/start-imports.json
python examples/show_scope.py

开发期按变更选择检查，最终完整验收才使用 scripts/check.py。可选来源检查 scripts/upstream.py fetch/check 需要 Git 和首次下载网络；Node 只用于开发参考采集，不是运行时依赖。独立结构检查不代表算法正确性或发行验收。 已提供真实官方布局采集、完整差分、独立几何、确定性和负控制脚本，新会话见 布局校验手册。

基本调用

以下例子可在当前本地包执行。当前实现、验证范围和宿主差异见状态页及接口合同：

import asyncio
from pyelk import ELK

async def main():
    elk = ELK({"defaultLayoutOptions": {"elk.algorithm": "layered"}})
    graph = {
        "id": "root",
        "children": [
            {"id": "a", "width": 40, "height": 30},
            {"id": "b", "width": 40, "height": 30},
        ],
        "edges": [{"id": "ab", "sources": ["a"], "targets": ["b"]}],
    }
    try:
        print(await elk.knownLayoutAlgorithms())
        result = await elk.layout(graph, {"layoutOptions": {
            "elk.algorithm": "layered", "elk.direction": "RIGHT"
        }})
        print(result)
    finally:
        elk.terminateWorker()

if __name__ == "__main__":
    asyncio.run(main())

保留defaultLayoutOptions、layoutOptions和camelCase方法名；logging/timing仅接受bool，缺省为false，true采集真实执行诊断。实际CPU布局在Python spawn子进程执行，每实例单工作槽、FIFO队列；取消、超时与关闭会回收工作进程。max_pending=16限制运行加排队总数（可配1–64），timeout=None可改为包含排队/启动的总期限秒数；不承诺硬内存配额。默认实例的三项查询返回 12 个算法、243 个选项、8 个类别；按构造参数限制算法注册时，查询反映实例范围。目录注册、解析能力和具体几何效果的验证等级分开记录，不能仅由查询结果推导所有参数组合均已通过。原始输入保持不变，实例空闲时可跨多次asyncio.run复用；详见E08手册。

文档

• 接口对齐要求与兼容矩阵：API、数据模型、选项、算法、异常与验收标准。
• 开发计划：里程碑、架构、差分测试方案和首批任务。
• 上游基线记录：可供后续测试工具读取的版本和来源信息。
• 新会话入口、完整实施方案、逐项任务。
• Python实现策略、具体迭代计划、机器进度索引：当前采用先完成全部功能迁移、再统一校验修复和独立发行的顺序；完成状态以机器索引为准。
• 并行协作规范：每轮root+A/B/V、独占文件、交接/反审与复盘改进。
• 原生合同与比较profile、E07复盘、E08分工：来源、实现、反审与下一轮改进。
• 首个正式包范围：先完成独立基础版并发布正式 0.1.0，再单独进行 py-mermaid 集成。
• 测试与发布、当前状态、py-mermaid 集成。
• 源码与元数据、可运行范围示例、许可状态。

实现状态

实现状态必须以测试证据更新。名称相同或能够返回坐标，并不代表算法行为或坐标已经与 elkjs 一致。

上游与许可

本仓库是独立的 Python 实现项目，不是 ELK 官方发行版。项目自行编写的代码使用 MIT。ELK 移植文件保留 EPL-2.0 OR GPL-3.0-or-later、来源及版权，Apache 辅助代码保留其许可与归属。发行包使用混合来源表达式 MIT AND (EPL-2.0 OR GPL-3.0-or-later) AND Apache-2.0；具体范围见 第三方通知。