The Boardflare Python API

Complete API reference for the boardflare (bf) package.

The boardflare (bf) package provides reactive workbook integration, table selection, and worksheet formula publishing for Marimo notebooks.

All names are exported directly under boardflare (usually imported as import boardflare as bf).

bf.inputs

bf.inputs(**named_specs: str | Reference | SelectionSpec)

Create a reactive workbook-input widget and return its Marimo wrapper.

Declare workbook dependencies as keyword arguments. Keep the returned widget displayed in a cell, and read synchronized values by name in downstream cells (e.g. inputs["sales"]). A notebook may declare at most one bf.inputs() widget.

Args: **named_specs: Named inputs where each value is: - A string range reference (e.g. "A1:C10" or "Sheet!TaxRate"). - A configured reference via bf.ref(reference, headers=True). - An active table selection via bf.selection(...), yielding a pandas DataFrame of the visible row at the active cell.

Returns: A Marimo UI Anywidget. Access materialized inputs with dictionary subscript syntax: inputs[name]. Do not use attribute access (e.g. inputs.name).

bf.publish

bf.publish(*, outputs: Mapping[str, Any] | None=None, functions: Mapping[str, Callable[..., Any]] | None=None)

Publish live output values and callable Python functions to worksheet formulas.

Must be displayed in a cell so the Anywidget retains its connection to the host. Values are consumed in Excel via =BF.OUTPUT("name") and functions are invoked via =BF.FUNCTION("name", arg1, ...).

Args: outputs: Mapping of output names to values (DataFrames, Series, lists, scalars). Scalars return in a single cell; DataFrames, Series, and 1D/2D arrays spill. functions: Mapping of function names to Python callables. Supported signatures include positional parameters with trailing defaults, optional *args, keyword-only parameters that have defaults, and sync or async callables. Required keyword-only parameters and **kwargs are rejected.

Returns: A marimo UI element. Read the live consumer formulas from publication.consumers; publication.value raises RuntimeError.

bf.ref

bf.ref(reference: str, *, headers: bool=False) -> Reference

Configure a reactive workbook reference for bf.inputs.

Use a plain reference string when no options are needed. bf.ref(...) is useful when the binding needs options such as headers=True and can be passed to bf.inputs().

Args: reference: Range address (e.g. "Sales!A1:D20") or defined name. headers: When True, treats the first row as column headers and materializes a rectangular range as a pandas DataFrame. When False (default), returns a scalar for one cell or a DataFrame with numbered columns for several.

Cells whose number format is a date or date-time arrive as datetime.datetime (a date-only cell is midnight), in a DataFrame as datetime64[ns] columns, never as Excel serial numbers. Time-only cells arrive as datetime.time. Cells with any other format arrive as numbers, so an unformatted date is a serial float.

Returns: A Reference specification to pass to bf.inputs(...).

bf.selection

bf.selection(table: str) -> SelectionSpec

Configure an active workbook table selection input for bf.inputs.

Args: table: Excel workbook table name.

Returns: A SelectionSpec to pass to bf.inputs(...). When read through the inputs widget (e.g. inputs["selected"]), returns a pandas DataFrame with the table’s headers as columns and at most one row: the row of the user’s active cell (the cell the cursor is on), even when a larger range is highlighted. The result is empty (an empty DataFrame with those columns) when the active cell is outside the table’s body rows or columns, on another sheet, on the header or total row, or on a hidden or filtered row. Filtering that hides the active row does not refresh the result until the next selection change. If the table does not exist in the workbook, it produces an input error (not an empty DataFrame).

Returned Object Interfaces and Methods

In addition to top-level module functions, Boardflare Anywidgets and return objects provide the following interfaces:

Inputs Widget (returned by bf.inputs(...))

  • Display the returned widget as the cell’s last expression so its communications channel with the workbook host remains connected.
  • Access synchronized input values with dictionary subscript syntax: inputs["name"]. Attribute access (e.g. inputs.name) is not supported.
  • At most one bf.inputs(...) widget is allowed per notebook. Calling bf.inputs(...) a second time raises RuntimeError("Only one bf.inputs(...) is allowed per notebook; use one bf.inputs(...) with all inputs").
  • A bare table name includes the header row, so use bf.ref("TableName", headers=True) for named columns.
  • Reading a selection input (configured via bf.selection("TableName")) returns a pandas DataFrame with the table’s headers as column names and at most one row: the row of the user’s active cell (the cell the cursor is on), even when a larger range is highlighted. It is empty (an empty DataFrame with those columns, never None) when the active cell is outside the table’s body rows or columns, on another sheet, on the header or total row, or on a hidden or filtered row. The cursor must be on a table cell; cells beside the table select no row. If the table does not exist in the workbook, it produces an input error (not an empty DataFrame).
  • Selection rows carry values, not positions (use column values like picked["id"], not index alignment). Filtering that hides the active row does not refresh the result until the next selection change.

Publication Object (returned by bf.publish(...))

  • Display the publication element as the cell’s last expression so its connection to the workbook host remains connected.
  • publication.consumers: Inspect active worksheet formula consumers for published outputs (=BF.OUTPUT("name")) and functions (=BF.FUNCTION("name", ...)).
  • publication.value: Raises RuntimeError.

For complete usage patterns and code examples, see Workbook Design.