ddp_utils.console.table

import ddp_utils.console.table

Render configurable terminal tables standalone or inside a console layout.

The module stores headers and rows, builds plain terminal lines, and delegates all ANSI styling to the shared styler. Sentinel-aware configuration preserves whether each value was explicitly supplied even when it equals its default.

Examples

Print a small standalone table:

from ddp_utils.console.table import TableView

TableView(headers=["Name", "State"], rows=[["Job", "Ready"]]).print()

class ddp_utils.console.table.TableConfig(title: Any = UNSET, title_color: Any = UNSET, title_style: Any = UNSET, header_color: Any = UNSET, header_style: Any = UNSET, border_color: Any = UNSET, column_separator: Any = UNSET, header_separator_joiner: Any = UNSET, empty_text: Any = UNSET, empty_color: Any = UNSET)

Bases: object

Independent configuration for TableView.

Keeps both:

• concrete values;

• explicitness metadata.

Examples

Configure a titled compact table:

config = TableConfig(title="Results", column_separator="  ")

Configure table appearance while retaining explicit-field intent.

Omitted UNSET arguments receive class defaults. Supplied arguments are recorded as explicit for later merge operations.

Parameters

Name	Type	Description
title	str | None	Optional table title.
title_color	str	Title foreground color.
title_style	str	Title text style.
header_color	str	Header foreground color.
header_style	str	Header text style.
border_color	str	Header separator color.
column_separator	str	Text placed between cells.
header_separator_joiner	str	Text joining per-column header rules.
empty_text	str	Placeholder rendered when no columns or rows exist.
empty_color	str	Empty-placeholder color.

Examples

Define custom headers and empty-state styling:

config = TableConfig(
    header_color="cyan",
    empty_text="No results",
    empty_color="yellow",
)

is_explicit(name: str) → bool

Return True if the field was explicitly provided / overridden.

Parameters

Name	Type	Description
name	str	Configuration field name.

Returns

Type	Description
bool	True when the field was explicitly assigned.

Examples

Test whether a title came from the caller:

explicit = config.is_explicit("title")

copy() → TableConfig

Return a full copy preserving values and explicitness metadata.

Returns

Type	Description
TableConfig	Independent configuration with copied explicit-field metadata.

Examples

Derive settings without mutating the original:

derived = config.copy()

to_kwargs() → Dict[str, Any]

Return config as kwargs payload including explicitness metadata.

Returns

Type	Description
Dict[str, Any]	Field mapping plus reserved __explicit_fields__ metadata.

Examples

Preserve intent through a merge round-trip:

clone = TableConfig().merge(**config.to_kwargs())

merge(**overrides) → TableConfig

Return a merged config copy.

None values are ignored for backward compatibility.

Parameters

Name	Description
**overrides	Known field values and optional explicitness metadata; unknown and None values are ignored.

Returns

Type	Description
TableConfig	New merged configuration.

Examples

Replace only title and header color:

derived = config.merge(title="Current", header_color="cyan")

class ddp_utils.console.table.TableView(headers: Sequence[str] | None = None, rows: Sequence[Sequence[object]] | None = None, console: Console | None = None, layout: ConsoleLayout | None = None, title: str | None = None, config: TableConfig | None = None, title_color: str | None = None, title_style: str | None = None, header_color: str | None = None, header_style: str | None = None, border_color: str | None = None, column_separator: str | None = None, header_separator_joiner: str | None = None, empty_text: str | None = None, empty_color: str | None = None)

Bases: object

Plain-text table component for standalone or layout-bound use.

Examples

Bind a results table to a live layout:

table = TableView(
    headers=["Case", "Status"],
    layout=layout,
    title="Results",
)

Initialize table data, styling, and optional layout attachment.

Parameters

Name	Type	Description
headers	Optional[Sequence[str]]	Initial column labels converted to strings.
rows	Optional[Sequence[Sequence[object]]]	Initial row values converted to strings.
console	Optional[Console]	Output console, defaulting to the shared singleton.
layout	Optional[ConsoleLayout]	Optional layout that owns this table as a block renderer.
title	Optional[str]	Table title override.
config	Optional[TableConfig]	Base table configuration.
title_color	Optional[str]	Title color override.
title_style	Optional[str]	Title style override.
header_color	Optional[str]	Header color override.
header_style	Optional[str]	Header style override.
border_color	Optional[str]	Header separator color override.
column_separator	Optional[str]	Inter-column text override.
header_separator_joiner	Optional[str]	Header-rule joiner override.
empty_text	Optional[str]	Empty-table placeholder override.
empty_color	Optional[str]	Empty-table placeholder color override.

Examples

Create a standalone table with initial data:

table = TableView(
    headers=["Name", "Count"],
    rows=[["Files", 3]],
    title="Summary",
)

set_headers(headers: Sequence[object]) → None

Replace the table’s column headers and re-render.

Parameters

Name	Type	Description
headers	Sequence[object]	Replacement column labels converted to strings.

Examples

Replace columns after discovering a schema:

table.set_headers(["Case", "Status"])

set_rows(rows: Sequence[Sequence[object]]) → None

Replace all table rows and re-render.

Parameters

Name	Type	Description
rows	Sequence[Sequence[object]]	Complete replacement row collection.

Examples

Replace the rendered dataset:

table.set_rows([["A", "Ready"], ["B", "Pending"]])

add_row(row: Sequence[object]) → None

Append a single row and re-render.

Parameters

Name	Type	Description
row	Sequence[object]	Cell values appended after string conversion.

Examples

Append one processed result:

table.add_row([case_number, "Complete"])

clear_rows() → None

Remove all rows and re-render.

Examples

Return the view to its empty state:

table.clear_rows()

configure(config: TableConfig | None = None, **kwargs) → None

Merge new settings into the table’s configuration and re-render.

Parameters

Name	Type	Description
config	TableConfig | None	Replacement base configuration, or current settings.
**kwargs		Field overrides applied through TableConfig.merge().

Examples

Change title and separators at runtime:

table.configure(title="Updated", column_separator="  ")

get_config() → TableConfig

Return a copy of the current table configuration.

Returns

Type	Description
TableConfig	Independent configuration copy.

Examples

Reuse current styling for another table:

config = table.get_config()

set_title(title: str | None) → None

Set the table’s title and re-render.

Parameters

Name	Type	Description
title	str | None	Replacement title, or None to hide it.

Examples

Display a new dataset name:

table.set_title("Active cases")

set_title_style(color: str | None = None, style: str | None = None) → None

Set the title’s color and/or text style and re-render.

Parameters

Name	Type	Description
color	str | None	Optional replacement title color.
style	str | None	Optional replacement title style.

Examples

Emphasize a warning table title:

table.set_title_style(color="yellow", style="bold")

set_header_style(color: str | None = None, style: str | None = None) → None

Set the header row’s color and/or text style and re-render.

Parameters

Name	Type	Description
color	str | None	Optional replacement header color.
style	str | None	Optional replacement header text style.

Examples

Render headers in bold cyan:

table.set_header_style(color="cyan", style="bold")

set_border_style(color: str | None = None) → None

Set the border color and re-render.

Parameters

Name	Type	Description
color	str | None	Optional replacement separator color.

Examples

Dim the header rule:

table.set_border_style("bright_black")

set_separators(column_separator: str | None = None, header_separator_joiner: str | None = None) → None

Set the column separator and/or header separator joiner characters and re-render.

Parameters

Name	Type	Description
column_separator	str | None	Optional text between cells.
header_separator_joiner	str | None	Optional text joining column rules.

Examples

Use a compact space-separated layout:

table.set_separators("  ", "  ")

set_empty_view(text: str | None = None, color: str | None = None) → None

Set the placeholder text and/or color shown when the table has no rows.

Parameters

Name	Type	Description
text	str | None	Optional replacement empty-state text.
color	str | None	Optional replacement empty-state color.

Examples

Explain why no rows are displayed:

table.set_empty_view("No matching cases", color="yellow")

render_lines() → List[str]

Render the full table as visible lines.

Returns

Type	Description
List[str]	Styled title, header, rule, and row lines; an empty table produces one styled placeholder line.

Examples

Capture rendered lines for a layout or test:

lines = table.render_lines()

print() → None

Standalone print into the global console output stream.

Examples

Emit a standalone snapshot:

table.print()

refresh() → None

Trigger a re-render on the attached layout, if any.

Examples

Request layout repaint after external state changes:

table.refresh()

close() → None

Detach the table from its layout, removing its renderer.

Examples

Remove a live table before closing its layout:

table.close()