UI Tables

Declarative table builder that formats Rich tables from defaults, presets, and runtime overrides. TableBuilder uses the standard config cascade so dashboards can swap layouts without touching application code.

Tip

See Tables for the feature guide.

Quick overview

  • Defaults emit a two-column key/value table with SIMPLE box and cyan headers.

  • Presets such as inventory and metrics tweak titles, line styles, and header colors; extend via ui.tables.presets.

  • Data can be provided as sequences of mappings (data=[...]) or explicit rows= sequences.

  • Column definitions support dotted keys (metadata.region), width hints, justification, and custom styles. Runtime columns= overrides replace everything configured in presets.

  • print_table_async mirrors the panel API for asyncio contexts.

Configuration snippet

ui:
    tables:
        defaults:
            table:
                box: "SIMPLE"
                show_header: true
                header_style: "bold cyan"
            columns:
                - header: "Key"
                  key: "key"
                  style: "bold white"
                - header: "Value"
                  key: "value"
        presets:
            inventory:
                table:
                    title: "Inventory"
                    box: "SIMPLE_HEAVY"
                    show_lines: true
                columns:
                    - header: "Component"
                      key: "component"
                      style: "bold"
                    - header: "Version"
                      key: "version"
                      style: "cyan"
                    - header: "Status"
                      key: "status"
                      justify: "center"

Usage patterns

Default key/value table

from kstlib.ui.tables import TableBuilder

builder = TableBuilder()
table = builder.render_table(data=[{"key": "status", "value": "running"}])
builder.print_table(data=[{"key": "retries", "value": 2}])

Inventory preset

inventory = [
    {"component": "cache", "version": "1.2.3", "status": "ok"},
    {"component": "watchdog", "version": "0.1.0", "status": "pending"},
]
TableBuilder().print_table(kind="inventory", data=inventory)

Runtime column overrides

columns = (
    {"header": "Service", "key": "name", "style": "bold white"},
    {"header": "Region", "key": "metadata.region", "style": "cyan"},
)
services = (
    {"name": "matcher", "metadata": {"region": "eu-west-1"}},
    {"name": "notifier", "metadata": {"region": "us-east-2"}},
)
TableBuilder().print_table(columns=columns, data=services, table={"title": "Service Map"})

Embedding in panels

from kstlib.ui import PanelManager, TableBuilder

builder = TableBuilder()
panel_manager = PanelManager()
payload = builder.render_table(kind="metrics", data=[{"key": "latency", "value": "43ms"}])
panel_manager.print_panel(kind="summary", payload=payload)

Module reference

Config-driven helpers for rendering Rich tables.

class kstlib.ui.tables.TableBuilder(config=None, console=None)[source]

Bases: object

Render Rich tables from configuration presets.

Tables follow the same configuration cascade used across kstlib: kwargs > config preset > defaults. Column definitions can be specified in defaults, presets, or passed at runtime. Data may be provided as a sequence of mappings or explicit row sequences.

Example

Render a simple table with data dictionaries:

>>> from kstlib.ui.tables import TableBuilder
>>> builder = TableBuilder()
>>> data = [{"key": "Name", "value": "Alice"}, {"key": "Age", "value": "30"}]
>>> table = builder.render_table(data=data)
>>> table.row_count
2

Using a preset and custom columns:

>>> columns = [
...     {"header": "Metric", "key": "metric"},
...     {"header": "Value", "key": "val", "justify": "right"},
... ]
>>> data = [{"metric": "CPU", "val": "42%"}]
>>> table = builder.render_table("metrics", data=data, columns=columns)
__init__(self, config: 'Mapping[str, Any] | Box | None' = None, console: 'Console | None' = None) → 'None' -> None[source]

Store optional console and resolve configuration cascade.

render_table(self, kind: 'str | None' = None, *, data: 'Sequence[Mapping[str, Any]] | None' = None, rows: 'Sequence[Sequence[Any]] | None' = None, columns: 'Sequence[Mapping[str, Any]] | None' = None, **overrides: 'Any') → 'Table' -> Table[source]

Build a Table instance according to the configuration cascade.

Parameters:

  • kind (str | None) – Name of the preset to apply.

  • data (Sequence[Mapping[str, Any]] | None) – Sequence of mapping-like objects used to populate the table.

  • rows (Sequence[Sequence[Any]] | None) – Explicit rows as iterables; bypasses automatic extraction.

  • columns (Sequence[Mapping[str, Any]] | None) – Runtime column definitions. Replaces configured columns when provided.

  • **overrides (Any) – Additional overrides applied on top of the resolved config.

Returns:

Configured Rich Table instance.

Raises:

TableRenderingError – If neither data nor rows can populate the table.

Return type:

Table

print_table(self, kind: 'str | None' = None, *, data: 'Sequence[Mapping[str, Any]] | None' = None, rows: 'Sequence[Sequence[Any]] | None' = None, columns: 'Sequence[Mapping[str, Any]] | None' = None, console: 'Console | None' = None, **overrides: 'Any') → 'Table' -> Table[source]

Render and print a table synchronously.

async print_table_async(self, kind: 'str | None' = None, *, data: 'Sequence[Mapping[str, Any]] | None' = None, rows: 'Sequence[Sequence[Any]] | None' = None, columns: 'Sequence[Mapping[str, Any]] | None' = None, console: 'Console | None' = None, **overrides: 'Any') → 'Table' -> Table[source]

Render and print a table from an async context using a worker thread.