> ## 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

> Python reference for Function calls, Pipelines, task inputs, and result handlers.

BlockX combines compute functions with triggers, inputs, and result writes. Use these driver interfaces in Notebooks by default; `function.call()` also supports reuse inside a Function. See the [source](https://github.com/Chaintable/blockx-py) for full implementations and low-level interfaces.

## Synchronous Function calls

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

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

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

`function_id` is a saved Function ID, and `*args` are positional arguments. This example returns `1.5` after you create the example function in [Create a Function](/guides/functions/create).

`timeout` is in seconds. In a Notebook, it controls the call deadline. Inside a Function, nested calls are bounded by the parent's remaining deadline; increasing a child timeout cannot extend the whole execution.

Failures raise `FunctionInvokeError`, with commonly used attributes `code`, `message`, `retryable`, and `call_id`. See [Error codes](/reference/error-codes).

## Function descriptor

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

| Parameter     | Description                                      |
| ------------- | ------------------------------------------------ |
| `source_code` | Inline Python source with `_` as the entry point |
| `function_id` | Saved Function ID                                |
| `name`        | Optional name                                    |
| `mode`        | Currently supports `inline`                      |

Provide source code or a Function ID. This object describes a function for task configuration; constructing it does not execute or save the function.

## Pipelines and triggers

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

| Parameter  | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| `table`    | Source table ID or object                                        |
| `func`     | Python callable, `Function` object, or Function ID               |
| `params`   | Positional argument list; use `SOURCE_ROW` for the source record |
| `operator` | Filter expression built with `blockdb.filter()`                  |
| `code`     | Direct source code, used instead of `func`                       |

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

`triggers` requires at least one source. `target_table` identifies the destination. `depends` lists block tables needed by the computation and does not pass them to the function automatically. `condition` configures conditional writes to a Normal Table.

| Method                                                 | Parameters                                                               | Behavior and return value                                 |
| ------------------------------------------------------ | ------------------------------------------------------------------------ | --------------------------------------------------------- |
| `backfill(block_start, block_end=None, progress=None)` | Inclusive height range; without an end, uses available upstream progress | Backfills and returns `BackfillResult`                    |
| `update()`                                             | No required arguments                                                    | Fills target gaps, then continuously processes new events |

Common `BackfillResult` attributes:

| Attribute       | Meaning                                                            |
| --------------- | ------------------------------------------------------------------ |
| `ok`            | Whether all submission stages succeeded                            |
| `done_blocks`   | Number of successfully processed blocks                            |
| `written_rows`  | Counted written rows                                               |
| `failed_ranges` | Failed ranges as `(start_height, end_height, error_code, message)` |

Large backfills may submit asynchronous batch writes. Confirm target write jobs and consensus separately. See [Build a Pipeline](/guides/notebooks/build-pipeline) for a complete runnable configuration.

## Custom tasks

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

`func` accepts a Function ID, callable, or `Function` object. `callList` is a list of positional argument lists, each producing one call.

```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))
```

Success prints `[1.5, 2.0]`. Raw result order is not guaranteed to match input order. Include a business ID in returned values when you need to associate results with inputs.

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

Returns an unsubmitted `Task`. `task.submit(timeout=None)` submits and waits, returning `TaskResult`; `timeout` is in seconds. Async Python code can use `await task.submit_async(timeout=...)`.

| `TaskResult` attribute     | Meaning                                     |
| -------------------------- | ------------------------------------------- |
| `task_result.success`      | Whether the task succeeded                  |
| `task_result.failure_code` | Failure code                                |
| `task_result.retryable`    | Whether the failure is marked retryable     |
| `handler_result`           | Content returned by the result handler      |
| `error`                    | Error identifier, usually `None` on success |

## Block task inputs

| Configuration                                             | Parameters and purpose                                                       |
| --------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `BlockTableCallConfig(block=None, triggerSources=None)`   | Read source tables for one block; `block` supplies ID, height, and timestamp |
| `BlockBundleCallConfig(number=None, triggerSources=None)` | Configure reads for a block bundle; `number` is the bundle number            |
| `BlockBundleCallConfigTemplate(triggerSources=None)`      | Generate per-bundle configurations during backfill                           |

Each entry in `triggerSources` uses `table`, `func`, `params`, and an optional `operator`. `SOURCE_ROW` marks the position of the source record in the arguments.

## Result handlers

| Handler                                                              | Parameters                                            | Write contract                                           |
| -------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------- |
| `ReturnValueHandler()`                                               | None                                                  | Collect return values for the Notebook                   |
| `NormalTableWriteHandler(targetTable, condition=None)`               | Target Normal Table and optional condition            | Returned records include primary key and business fields |
| `TimeTableWriteHandler(targetTable)`                                 | Target Time Table                                     | Returned records contain `id`, `time_at`, and `value`    |
| `BlockTableWriteHandler(targetTable, block=None, block_bundle=None)` | Target block table and single-block or bundle context | Write results and corresponding block progress           |

For block handlers, `block` and `block_bundle` represent different submission forms and should not be mixed. Standard Pipelines choose handlers based on target table type.

## Backfill helpers

`bundle_height_range(bundle_id)` returns the height range covered by a bundle. `backfill_block_bundles()` supports custom bundle backfills with `BlockBundleCallConfigTemplate` and a write handler. See [GitHub](https://github.com/Chaintable/blockx-py) for lower-level configuration and `LocalTestService`.