gp-ir 0.1.0

General Platform Intermediate Representation Framework

gp-ir: General Platform Intermediate Representation Framework

gp-ir 是一个通用平台中间表示框架，用于代码生成、执行和转换。它提供了一套完整的工具链，将高级动作定义转换为中间表示（IR），然后可以执行或生成目标代码。

许可证

本项目采用 MIT 许可证:

MIT License

Copyright (c) 2023 notmmao

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

特性

• 中间表示（IR）: 提供统一的中间表示模型，支持多种操作（调用、注释等）
• 代码生成: 将 IR 转换为 Python 代码或其他目标语言
• 运行时执行: 内置执行器可在运行时解释和执行 IR
• 执行信息统一暴露: 提供 ActionResult、ExecutionState、ExecutionReport，可用于UI实时展示与报告落盘
• 扩展机制: 支持自定义上下文动作、转换器和动作模板
• 调试支持: 提供调试控制器和执行监听器
• 模块化设计: 清晰的架构分离，易于扩展和维护

安装

pip install gp-ir

快速开始

以下是一个简单的使用示例：

from gp_ir import (
    IRCall, IRComment, ExecutionPlan,
    RuntimeContext, IRExecutor,
    emit_python, wrap_python_script
)

# 构建IR节点
ir_nodes = [
    IRComment(text="开始执行测试"),
    IRCall(func="sleep", args=[1000], kwargs={}),
    IRCall(func="set_value", args=[], kwargs={"key": "a", "value": 100}),
    IRCall(func="assert_condition", args=[], kwargs={"expr": "a>= 100"}),
    IRCall(func="sleep", args=[500], kwargs={}),
    IRComment(text="测试完成"),
]

# 创建执行计划
plan = ExecutionPlan(ir_nodes=ir_nodes)

# 执行IR
ctx = RuntimeContext(
    print_callback=lambda *args: print(f"  LOG: {' '.join(str(a) for a in args)}")
)

executor = IRExecutor(ctx)
executor.run(plan)

# 生成Python代码
code = emit_python(ir_nodes)
script = wrap_python_script(code)
print(script)

更多示例请参见 examples/ 目录。

其中执行信息与报告示例可参考：

• examples/execution_report_demo.py
• examples/render_execution_report_html.py（将 JSON 报告渲染为 HTML）

架构

核心组件

• IR定义: IRNode, IRCall, IRComment, ExecutionPlan - 定义中间表示的基本元素
• 运行时: RuntimeContext, IRExecutor - 提供执行环境和执行逻辑
• 注册系统: ContextRegistry, ConverterRegistry, ActionRegistry - 支持动态扩展
• 动作定义: Action - 定义可执行的动作模板
• 代码生成: emitter, generator, template - 将IR转换为目标代码

扩展机制

框架提供了三个主要的扩展点：

1. Context扩展: 通过 ContextRegistry 注册自定义动作函数
2. Converter扩展: 通过 ConverterRegistry 注册自定义Action类型的转换函数
3. Action扩展: 通过 ActionRegistry 注册新的动作模板

项目结构

gp-ir/
├── gp_ir/                 # 核心模块
│   ├── ir.py             # IR定义
│   ├── context.py        # 运行时上下文
│   ├── executor.py       # IR执行器
│   ├── registry.py       # 扩展注册系统
│   ├── action.py         # 动作定义
│   ├── converter.py      # 转换器
│   ├── emitter.py        # 代码生成
│   ├── runner.py         # 运行器
│   ├── debug.py          # 调试工具
│   ├── generator.py      # 代码生成器
│   ├── template.py       # 代码模板
│   └── actions.json      # 内置动作配置
├── examples/             # 使用示例
├── docs/                 # 文档
└── tests/                # 测试用例

贡献

欢迎提交 Issue 和 Pull Request 来改进项目！

支持

如有问题，请在 GitHub 仓库中创建 Issue。