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

# blockx-py

> Function 调用、Pipeline、任务输入和结果处理器的 Python 接口参考。

BlockX 将计算函数与触发、输入和结果写入组合起来。以下驱动接口默认在 Notebook 中使用；函数内复用逻辑可使用 `function.call()`。[源码](https://github.com/Chaintable/blockx-py)提供完整实现和低层接口。

## 同步调用 Function

### `function.call(function_id, *args, timeout=...)`

```python theme={null}
from blockx import function

amount = function.call('demo.usdc_amount', 1500000)
print(amount)
```

`function_id` 为已保存的 Function ID，`*args` 按参数顺序传入；示例返回 `1.5`，前提是已按[创建 Function](/zh/guides/functions/create)创建示例函数。

`timeout` 单位为秒。在 Notebook 中控制调用期限；在 Function 内部调用其他函数时，受父调用的剩余期限限制，不能通过增加子调用超时来延长整次执行。

失败时抛出 `FunctionInvokeError`，常用属性为 `code`、`message`、`retryable` 和 `call_id`。处理方式见[错误码](/zh/reference/error-codes)。

## Function 描述对象

### `Function(source_code=None, function_id='', name='', mode='inline')`

| 参数            | 说明                   |
| ------------- | -------------------- |
| `source_code` | 内联 Python 源码，入口为 `_` |
| `function_id` | 已保存的 Function ID     |
| `name`        | 可选名称                 |
| `mode`        | 当前支持 `inline`        |

至少提供源码或 Function ID。该对象用于任务配置，不会在构造时执行或保存函数。

## Pipeline 与触发源

### `Trigger(table, func=None, params=None, operator=None, code=None)`

| 参数         | 说明                                         |
| ---------- | ------------------------------------------ |
| `table`    | 触发源表 ID 或表对象                               |
| `func`     | Python callable、`Function` 对象或 Function ID |
| `params`   | 位置参数列表，使用 `SOURCE_ROW` 放置源记录               |
| `operator` | 通过 `blockdb.filter()` 构建的筛选表达式             |
| `code`     | 直接提供源码时使用，与 `func` 选择一种                    |

### `Pipeline(triggers, target_table, depends=None, condition=None)`

`triggers` 至少包含一个触发源；`target_table` 指定目标表。`depends` 是计算所需的区块依赖表列表，不自动传入函数。`condition` 用于普通表的条件写入。

| 方法                                                     | 参数                           | 行为与返回值                 |
| ------------------------------------------------------ | ---------------------------- | ---------------------- |
| `backfill(block_start, block_end=None, progress=None)` | 包含两端的高度范围；省略结束高度时以可处理的上游进度为界 | 回填后返回 `BackfillResult` |
| `update()`                                             | 无必填参数                        | 补齐目标表缺口，然后持续处理新事件      |

`BackfillResult` 的常用属性：

| 属性              | 含义                                 |
| --------------- | ---------------------------------- |
| `ok`            | 所有提交阶段是否成功                         |
| `done_blocks`   | 成功处理的区块数                           |
| `written_rows`  | 统计的写入行数                            |
| `failed_ranges` | 失败区间列表，每项为 `(起始高度, 结束高度, 错误码, 信息)` |

大范围回填的批量写入可能异步执行，应另外确认目标表的写任务和共识进度。可直接运行的完整配置见[构建 Pipeline](/zh/guides/notebooks/build-pipeline)。

## 自定义任务

### `InputsCallConfig(func=None, callList=None)`

`func` 接受 Function ID、callable 或 `Function` 对象；`callList` 是位置参数列表的列表，每个子列表触发一次调用。

```python theme={null}
from blockx import InputsCallConfig, ReturnValueHandler, TaskBuilder

config = InputsCallConfig(
    func='demo.usdc_amount',
    callList=[[1500000], [2000000]],
)
task = TaskBuilder.build(config, ReturnValueHandler())
result = task.submit(timeout=30)
if not result.task_result.success:
    raise RuntimeError(result.error)
print(sorted(result.handler_result))
```

成功时输出 `[1.5, 2.0]`。原始结果顺序不保证对应输入顺序，需要关联时在返回值中携带业务 ID。

### `TaskBuilder.build(call_config, handler)`

返回尚未提交的 `Task`。`task.submit(timeout=None)` 提交并等待，返回 `TaskResult`；`timeout` 单位为秒。异步 Python 代码可使用 `await task.submit_async(timeout=...)`。

| `TaskResult` 属性            | 含义                 |
| -------------------------- | ------------------ |
| `task_result.success`      | 任务是否成功             |
| `task_result.failure_code` | 失败代码               |
| `task_result.retryable`    | 是否标记为可重试           |
| `handler_result`           | 结果处理器返回的内容         |
| `error`                    | 错误标识，成功时通常为 `None` |

## 区块任务输入

| 配置对象                                                      | 参数与用途                         |
| --------------------------------------------------------- | ----------------------------- |
| `BlockTableCallConfig(block=None, triggerSources=None)`   | 按一个区块读取源表，`block` 提供 ID、高度和时间 |
| `BlockBundleCallConfig(number=None, triggerSources=None)` | 按区块批次配置读取，`number` 为批次编号      |
| `BlockBundleCallConfigTemplate(triggerSources=None)`      | 由回填流程为各批次生成配置                 |

`triggerSources` 的每项使用 `table`、`func`、`params` 和可选 `operator`。`SOURCE_ROW` 表示源记录所在的参数位置。

## 结果处理器

| 处理器                                                                  | 参数              | 写入约定                          |
| -------------------------------------------------------------------- | --------------- | ----------------------------- |
| `ReturnValueHandler()`                                               | 无               | 收集函数返回值并交回 Notebook           |
| `NormalTableWriteHandler(targetTable, condition=None)`               | 目标普通表、可选条件      | 返回记录应包含主键及业务字段                |
| `TimeTableWriteHandler(targetTable)`                                 | 目标时间表           | 返回记录包含 `id`、`time_at`、`value` |
| `BlockTableWriteHandler(targetTable, block=None, block_bundle=None)` | 目标区块表及单区块或批次上下文 | 写入结果及对应区块进度                   |

区块处理器的 `block` 与 `block_bundle` 对应不同提交形式，不应混用。标准 Pipeline 根据目标表类型选择处理器。

## 回填辅助接口

`bundle_height_range(bundle_id)` 返回批次包含的高度范围。`backfill_block_bundles()` 用于自定义批次回填，配合 `BlockBundleCallConfigTemplate` 和写入处理器使用。低层配置和测试能力 `LocalTestService` 见 [GitHub](https://github.com/Chaintable/blockx-py)。