cfx.display

Formatting helpers for rendering Config instances as text or HTML tables.

This module is intentionally not re-exported from the top-level package. Import directly when needed:

from cfx.display import make_table, as_table

Public API

textwrap_cell, textwrap_row

Text/terminal table cell and row helpers.

wrap_cell, wrap_row

HTML tag helpers with optional attribute support.

make_table

Unified table builder - produces either a fixed-width text table or an HTML <table> from a list of (config, name, value, doc) rows.

as_table

Full config renderer for __str__ (format "text") and _repr_html_ (format "html").

as_inline_string

Compact ClassName(k=v, ...) one-liner for __repr__.

config_tree

Tree diagram of a config hierarchy with wrapped docstrings.

table_rows

Extract (field_name, current_value, doc) 3-tuples from a flat config.

flat_table_rows

Extract (class_name, field_name, value, doc) 4-tuples recursively.

Functions

textwrap_cell(text, max_w)	Reformat a paragraph to fit into no more than max_w columns.
textwrap_row(row, max_widths)	Given a list of paragraphs, wraps each paragraph at max_widths columns.
wrap_cell(content[, tag, attrs])	Wrap content in an HTML tag.
wrap_row(cells[, tag, attrs])	Wrap a list of strings in an HTML tag.
table_rows(cfg)	Extract (field_name, current_value, doc) tuples from cfg.
flat_table_rows(cfg)	Extract (class_name, key, value, doc) tuples from cfg recursively.
config_tree(cfg[, width, _cont, _branch])	Render a compact tree diagram of a config hierarchy.
make_table(rows[, format, max_config_width, ...])	Format (config, name, value, doc) rows as a text or HTML table.
as_table(cfg[, format, table_attrs])	Render a Config instance as a full text or HTML table.
as_inline_string(cfg)	Render a Config instance as a compact ClassName(k=v, ...) string.

Module Contents

cfx.display.textwrap_cell(text, max_w)

Reformat a paragraph to fit into no more than max_w columns.

By default, tabs in ‘text’ are expanded with string.expandtabs(), and all other whitespace characters (including newline) are converted to space. An empty string produces a single-element list [""] so that callers never receive an empty list.

Parameters:

textstr

Cell content to wrap.

max_wint

Maximum line width in characters.

Returns:

wrappedlist[str]

cfx.display.textwrap_row(row, max_widths)

Given a list of paragraphs, wraps each paragraph at max_widths columns.

Parameters:

rowtuple[str]

Cell strings, one per column.

max_widthstuple[int]

Column width limits, one per column.

Returns:

wrapped: list[list[str]]

One list-of-lines per column.

cfx.display.wrap_cell(content, tag='td', attrs=None)

Wrap content in an HTML tag.

Given a string and a tag, returns <tag> content </tag>. The attributes, when provided, are unrolled as html tag attributes, f.e.: <tag id=1> content </tag>

Parameters:

contentstr

Inner HTML content.

tagstr, optional

HTML element name. Default "td".

attrsdict or None, optional

Mapping of attribute name to value appended to the opening tag, e.g. {"class": "cfg-key", "id": "n_sigma"}.

Returns:

wrapped: str

String of the format: <tag [attrs]>content</tag>.

cfx.display.wrap_row(cells, tag='tr', attrs=None)

Wrap a list of strings in an HTML tag.

Parameters:

cellsiterable[str]

Cell HTML strings to concatenate inside the row.

tagstr, optional

HTML element name. Default "tr".

attrsdict or None, optional

Mapping of attribute name to value, e.g. {"class": "cfg-row"}.

Returns:

wrapped: str

String of the format: <tag [attrs]> cells... </tag>.

cfx.display.table_rows(cfg)

Extract (field_name, current_value, doc) tuples from cfg.

Parameters:

cfgConfig

Any Config instance.

Returns:

rows: list[tuple]

3-tuples of (key, formatted_value, doc).

cfx.display.flat_table_rows(cfg)

Extract (class_name, key, value, doc) tuples from cfg recursively.

Walks cfg and all nested sub-configs depth-first, prepending the class name as a leading column so all fields across the whole hierarchy can be rendered in a single unified table.

Parameters:

cfgConfig

Any Config instance, flat or nested.

Returns:

rowslist[tuple]

4-tuples of (class_name, key, formatted_value, doc).

cfx.display.config_tree(cfg, width=79, _cont='', _branch='')

Render a compact tree diagram of a config hierarchy.

Each node shows the class name and its docstring (preserved as-is, not reflowed). Sub-configs are connected with unicode box-drawing characters.

Parameters:

cfgConfig

Root config instance.

widthint, optional

Kept for API compatibility; no longer used internally. Default 79.

_contstr

Internal: continuation prefix for docstring lines and child prefixes. Do not pass manually.

_branchstr

Internal: prefix for this node’s first line (e.g. "├─ "). Do not pass manually.

Returns:

treestr

Multi-line tree string.

cfx.display.make_table(rows, format='text', max_config_width=25, max_key_width=20, max_value_width=25, max_desc_width=50, table_attrs=None)

Format (config, name, value, doc) rows as a text or HTML table.

Parameters:

rowslist[tuple]

Each tuple is (config_class, key, value, description).

formatstr, optional

"text" for a fixed-width terminal table; "html" for a <table> string. Default "text".

max_config_widthint, optional

Max width for the Config column. Ignored in HTML mode.

max_key_widthint, optional

Max width for the Key column. Ignored in HTML mode.

max_value_widthint, optional

Max width for the Value column. Ignored in HTML mode.

max_desc_widthint, optional

Max width for the Description column. Ignored in HTML mode.

table_attrsdict or None, optional

HTML attributes added to the <table> tag, e.g. {"class": "my-table", "id": "pipeline-config"}. Only used when format="html". Default None.

Returns:

table: str

Fixed-width text table or <table>...</table> HTML string.

cfx.display.as_table(cfg, format='text', table_attrs=None)

Render a Config instance as a full text or HTML table.

Produces a tree diagram of the config hierarchy (with wrapped docstrings) followed by a single unified table with a leading Config column. Works for flat, nested, and mixed flat+nested configs.

Parameters:

cfgConfig

The config instance to render.

formatstr, optional

"text" for a terminal table; "html" for an HTML block. Default "text".

table_attrsdict or None, optional

HTML attributes for the <table> tag, e.g. {"class": "my-table", "id": "pipeline-config"}. Only used when format="html". Default None.

Returns:

tablestr

Tree diagram followed by the unified field table.

cfx.display.as_inline_string(cfg)

Render a Config instance as a compact ClassName(k=v, ...) string.

Parameters:

cfgConfig

The config instance to render.

Returns:

cfgstrstr

Single-line representation of a config.