> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockx.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Executor

> 嵌入式 Python 宿主、运行时桥接与 EVM 函数执行。

## 职责与边界

Python Executor 在 CPython 宿主进程中运行用户函数。它接收 Worker 派发的函数执行工作，并通过宿主桥接路由挂起的后端操作。EVM 查询携带函数提供的链与区块。

编程流程见[编写 EVM 数据函数](/zh/guides/write-functions)。本页说明执行组件。

## 代码位置

| BlockX 仓库中的来源 | 职责 |
| - | - |
| `pyhost/src/main.c`、`pyhost/src/embed.c` | 宿主启动与嵌入式解释器 |
| `pyhost/src/sched.c`、`pyhost/src/coro.c` | 宿主调度与协程支持 |
| `pyhost/src/bridge.c`、`pyhost/src/proto.c` | 宿主桥接与协议处理 |
| `python/blockx_runtime/` | 函数入口、模块加载与后端桥接 |
| `python/blockx_audit/` | 静态源码审计与能力表 |
| `internal/worker/adapters/executor/` | Worker 侧宿主进程与连接管理 |

## 核心类型与接口

| 接口 | 作用 |
| - | - |
| `bxpy_coro` | 为驻留的调用持有独立原生栈与 `PyThreadState` |
| `bxpy_coro_park` / `bxpy_coro_resume` | 挂起跨边界操作，并在所属解释器线程恢复 |
| `bxpy_cross` | 在挂起期间保存桥接操作的输入、输出与失败 |
| `execute` / `release_task` / `release_tasks` | 执行单次请求，并释放已完成任务的命名空间 |
| `CallContext` / `call_scope` | 跟踪调用身份、调试状态、参数及配对的上下文进入与退出 |
| `ModuleRegistry.load_callable` | 按摘要加载源码，并从命名空间返回解析后的入口 |
| `resolve_entry_name` | 让源码审计与运行时加载共用入口选择规则 |
| `HostProvider` | 通过宿主桥接实现 SDK 读取、写入、子调用与协作式休眠 |
| `host.io_value` / `host.io_json` / `host.io_rpc` | 跨宿主边界传递后端请求 |
| `host.fetch_source` / `host.subcall` | 获取函数源码并派发子调用 |
| `wire.pack` | 在宿主编码前应用 Python 返回值转换规则 |
| `NodeRPCBridgeProvider` | 通过 `host.io_rpc` 路由 EVM 节点请求 |
| `EVM` | 函数可见的对象，携带链与区块上下文 |
| `install_noderpc_bridge` | 安装运行时的逐链桥接 provider |

`python/blockx_runtime/host.py` 定义面向 Python 的宿主桥接。审计代码可用的能力名称维护在 `python/blockx_audit/tables.py`。

## 数据流 / 执行流程

1. Worker 向 Executor 宿主派发函数及其参数。
2. 运行时加载函数定义并调用入口。
3. 状态读取与合约查询经 `NodeRPCBridgeProvider` 传递链和请求参数。
4. Worker IO 处理后端请求，宿主恢复计算。
5. 函数返回输出，Worker 收集结果并交给选定 Writer Plugin。

函数的 EVM 对象提供读取上下文。任务的函数代码快照固定定义，与数据读取使用的区块相互独立。

## 函数加载与入口解析

`ModuleRegistry` 按摘要缓存编译后的源码，并维护每个任务的命名空间。它可以通过 `host.fetch_source` 获取缺失源码。释放任务时移除其命名空间；函数身份与版本选择见 [Function Code View](/zh/components/function-code)。

`python/blockx_audit/tables.py` 中的 `resolve_entry_name` 提供共用的选择规则。运行时将其应用于 `entrySelector`：

1. 选择器的最后一段如果命中符合条件的顶层函数，就使用该函数。
2. 否则使用 `_`，它可以是函数定义，也可以是指向顶层函数的别名。
3. 否则按源码顺序使用第一个符合条件的公开顶层函数。
4. 如果都不存在，则解析为 `_`，并在加载时报告缺少可调用入口。

命名入口规则不能选择以 `__` 开头的名称或危险内建名称。公开函数回退规则跳过以 `_` 开头的名称和危险内建名称。审计绑定检查会拒绝对已有 `_` 定义重新绑定的别名。

## 返回值序列化

`python/blockx_runtime/wire.py` 先转换 Python 值，宿主再将其打包为值程序。Worker 将值程序转换为结果携带的 JSON。

| Python 值 | 输出行为 |
| - | - |
| `int`，包括 `2**256 - 1` | 保留整数，不收窄为浮点值 |
| `datetime` | RFC 3339；无时区值与 `timezone.utc` 使用 `Z`，其他带时区值保留偏移量；保留非零微秒 |
| `date` | ISO 日期字符串 |
| Dataclass 实例 | 通过 `dataclasses.asdict` 转换；优先返回普通字典 |
| 非有限 `float` | JSON `null` |
| 不支持的值，例如 `set` | 编码失败并返回 `terminal_encode_failed`，标记为不可重试 |

计算过程中将 EVM `uint256` 值保留为 Python 整数。消费方也必须无精度损失地解码 JSON 整数。协议转换不会额外授予审计函数导入权限或能力。

## 状态与生命周期

Worker 管理 Executor 宿主进程及其连接。运行时初始化安装桥接并准备函数执行。函数源码加载和版本身份与 [Function Code View](/zh/components/function-code) 协作。

### 挂起与恢复不变量

原生宿主在一个解释器线程上驻留多个调用，每次运行一个协程。修改调度或桥接时，需要保持以下不变量：

| 不变量 | 实现约束 |
| - | - |
| 调用在执行期间持续持有自己的原生栈与 `PyThreadState` | `bxpy_coro_resume` 要求所属 OS 线程与解释器 GIL |
| 挂起请求在恢复前保持有效 | `bxpy_cross` 及其借用的输入保留在协程栈上 |
| 后端等待将控制权交还调度器 | IO、源码获取、子调用与休眠挂起协程；预算读取、检查点与日志就地执行 |
| 响应只恢复当前等待 | `handle_resume` 检查调用状态与请求 ID，忽略过期响应 |
| 调用上下文成对进入与退出 | `call_scope` 压入和弹出同一个 `CallContext`；栈不匹配时报错 |
| 复用不能继承上次调用的执行状态 | `bxpy_coro_reset` 清理逐调用状态，检查执行已经退栈，并分配新身份 |

调度器跟踪 `CS_QUEUED`、`CS_RUNNABLE`、`CS_RUNNING`、`CS_WAIT_IO`、`CS_WAIT_FUNCTION_CODE`、`CS_WAIT_SUBCALL`、`CS_WAIT_SLEEP` 和 `CS_DONE`。取消与截止时间由宿主调度器裁定，运行时编码对应终态。EVM 后端响应在既有调用上下文中恢复等待的函数。

## 配置

| 设置 | 作用 |
| - | - |
| `EXECUTOR_HOST_BIN` | 宿主可执行文件，默认为 `blockx-pyhost` |
| `PYTHON_BIN` | 审计进程使用的解释器 |
| `PYTHONPATH` | 运行时模块与已安装的函数依赖 |
| `EXECUTOR_COUNT` | Executor 进程数量 |

宿主嵌入 CPython `3.14` 或更高版本。按照[快速开始](/zh/quickstart)构建，并提供虚拟环境的包目录。

## 扩展点

通过运行时桥接和对应后端适配器增加函数可见能力。修改允许的函数接口时，同步更新审计能力表。验证链与区块上下文原样传递到后端请求。

## 测试

BlockX 仓库中的以下测试覆盖桥接集成、入口选择、模块命名空间及返回值转换，按需使用宿主替身：

```bash theme={null}
cd python
.venv/bin/python -m unittest \
  tests.test_runtime_leafage tests.test_noderpc_bridge \
  tests.test_runtime_entry tests.test_runtime_module_registry tests.test_runtime_wire
```

宿主与进程测试还覆盖原生执行边界，共享环境准备位于 `internal/testutil/pyhost.go`。

## 相关文档

* [EVM 计算模型](/zh/concepts/evm-computation)
* [Call 执行子系统](/zh/components/call-execution)
* [后端适配器](/zh/components/backend-adapter)
* [内部协议](/zh/architecture/protocols)

BlockX 仓库中的设计参考：`docs/specs/function-code-python-whitelist.md`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.