README | API | CLI | SPEC | CHANGELOG

vistab

vistab is a lightweight Python library for creating beautiful text-based ASCII/Unicode tables. It comes out-of-the-box with support for fluid terminal formatting (ANSI escape sequences), coordinate-based discrete cell styling, and guarantees consistent string lengths across languages and scripts (RTL and LTR) and color variations. (See the Showcase for a one-glance demo of everything.)

Using vistab from Python? Import the Vistab class (see the API reference). A command-line entry point also exists, but the CLI is for ad-hoc terminal/CSV use only. In code, do not shell out to the vistab command: import and use the API.

from vistab import Vistab

t = Vistab(header=["Name", "Age"])
t.add_row(["Sarah", 27])
t.set_cols_align(["l", "r"])
print(t.draw())

Key Features

• Lightweight Native Core: Built on the Python standard library with wcwidth for accurate string widths.
• Color-Aware Word Wrapping: Wraps table content over embedded ANSI format sequences without corrupting geometries.
• Coordinate Styling API: Style rows, columns, headers, or specific cells via clean method chaining.
• Hierarchical Configuration: Load table paddings and themes from localized configurations (vistab.toml).
• Data-Aware Engine: Auto-wraps text, infers data types, and parses CSV formats natively.
• RTL-safe rendering: Arabic/Hebrew and other right-to-left text is isolated so it does not flip the table grid, while still reading correctly inside its cell. On by default; toggle with set_bidi() (or --no-bidi).

Showcase

The fastest way to see what vistab can do is the built-in flagship demo, which renders one table exercising the headline capabilities at once (column spanning in both headers and data rows, a theme, CJK/Thai/Arabic/Hebrew scripts with correct widths, inline ANSI color, and color-aware word wrapping):

vistab show showcase

The demo also prints the Python that builds it. Right-to-left scripts (Arabic, Hebrew) are kept from flipping the grid via Unicode LTR isolates; disable that with --no-bidi, and disable color with --no-color, if your terminal needs it.

Detailed Documentation

Looking for an exhaustive configuration breakdown or command-line parser bindings?

• Vistab Python API Reference (the primary interface: all objects, data formatting algorithms, and properties)
• Command-Line (CLI) Manual (secondary, for ad-hoc terminal/CSV use: mapping raw CSV structures and terminal limits)

Installation

You can install vistab directly via pip:

pip install vistab

Note: For complex Asian/CJK full-width character wrapping support, install the optional component using pip install vistab[cjk].

Quick Start

Getting started with vistab is simple. Initialize a Vistab instance, set up column alignments and paddings, and append your rows.

from vistab import Vistab

table = Vistab(style="round-header", padding=1)
# Left, Right, Center alignment
table.set_cols_align(["l", "r", "c"])
# Top, Middle, Bottom vertical alignment
table.set_cols_valign(["t", "m", "b"])

table.add_rows([
    ["Name", "Age", "Nickname"],
    ["Ms\nSarah\nJones", 27, "Sarah"],
    ["Mr\nJohn\nDoe", 45, "Johnny"],
    ["Dr\nEmma\nBrown", 34, "Em"]
])

print(table.draw())

Output:

Note on Web Rendering: We display the raw output below as an image because some package registries (like PyPI) enforce code-block font stacks (e.g., Source Code Pro) that lack glyphs for Unicode Extended Box Drawing characters. When falling back to secondary system fonts for characters like ╭ or ╪, the physical grid mathematically misaligns. On your local terminal (and on full-featured renderers like GitHub or BitBucket) the actual text output mathematically aligns perfectly!

Built-in Styles

To view available styles, run:

vistab show styles

Cookbook Examples

Vistab's fluent API lets you chain layout and formatting mutations cleanly without intermediate variables.

1. Data Modification & Sorting

Replace datasets or sort rows by column index without Pandas overhead:

table = Vistab(style="round", padding=1)

# Sort the array tracking the second column (col_idx=1) descending...
table.set_rows(my_messy_csv_data, header=True).sort_by(1, reverse=True)

2. Output Formatting & Safe Dimensional Windows

Constrain table outputs to fit terminal dimensions when logging large datasets:

# Force-limit outputs protecting CLI limits! 
table.set_max_rows(10).set_max_cols(5)

3. Data Formatting & Precision

You can apply data overrides directly to lock precision across specific columns:

# Force all floats to evaluate to precisely two digits
table.set_precision(2)

# Pass formatting arrays coercing columns sequentially
# a=auto, t=text, i=int, f=float, e=sci
table.set_cols_dtype(["a", "t", "f", "i"])

# Bypass the global precision using inline modifiers
# Here, col 2 maps `f4` (float + precision 4 digits)
table.set_cols_dtype("a,t,f4,i")

When evaluated, the a (automatic) datatype parses columns by inferring numeric types (scientific -> float -> integer), creating uniform alignment.

The single-letter codes are: a (auto), t (text), i (int), I (int with thousands separators, e.g. 1,234,567), f (float), F (float with thousands separators, e.g. 123,456.79), e (scientific), E (scientific with thousands separators). Numeric codes take an optional precision suffix (f2, F2, e4).

Thousands separators with decimals, currency, and custom formats

For grouped decimals (123,456.79), use the F code (float with thousands separators), e.g. set_cols_dtype(["F2"]) or --dtype "F2" on the CLI. I groups integers only.

There is no built-in currency type. For dollars ($123,456.79) or any other currency or custom format, pass a callable for that column. vistab does not guess a locale; you supply the symbol and placement, so every currency is supported by construction:

# Grouped float with 3 decimals -> "123,456.789"  (or just: set_cols_dtype(["F3"]))
table.set_cols_dtype([lambda v: f"{float(v):,.3f}"])

# US dollars -> "$123,456.79"
table.set_cols_dtype([lambda v: f"${float(v):,.2f}"])

# Euro / Swedish krona / Indian rupee: you choose symbol and placement
table.set_cols_dtype([lambda v: f"\u20ac{float(v):,.2f}"])     # \u20ac123,456.79
table.set_cols_dtype([lambda v: f"{float(v):,.2f}\u00a0kr"])   # 123,456.79 kr
table.set_cols_dtype([lambda v: f"\u20b9{float(v):,.2f}"])     # \u20b9123,456.79

# Accounting style: negatives in parentheses
table.set_cols_dtype([lambda v: (f"(${abs(float(v)):,.2f})" if float(v) < 0 else f"${float(v):,.2f}")])

A callable receives the raw cell value and returns the formatted string, so any Python format specification (grouping, precision, sign, fill/width) is available. Callables are a library-API feature; the CLI --dtype flag supports only the single-letter codes above.

Right-to-left text (Arabic, Hebrew)

When a cell contains right-to-left script, vistab wraps each cell's content in Unicode isolates so the terminal does not reorder the whole line and flip the columns; the RTL text still reads correctly right-to-left inside its cell. This is on by default and costs nothing for tables with no RTL content. Disable it (for terminals that mishandle isolates) with the library API or the CLI:

table.set_bidi(False)   # library: turn off RTL isolation

vistab data.csv --no-bidi

4. Shorthand Styling & Native Formatting

You don't need to pass massive syntax strings to evaluate layout injections:

# Conditionally highlight physical elements:
for i, condition in enumerate(my_events):
    table.color_row(i, bg="red" if condition == 'CRITICAL' else None)

# Make the header globally bold instantly:
table.bold_header()

5. Column Spanning (Colspan)

You can easily define cells that span multiple horizontal columns inline using ColSpan or programmatically:

from vistab import Vistab, ColSpan

table = Vistab(style="light")
# Inline colspan in headers and rows:
table.set_header(["Name", ColSpan("Details Block", 2), "Status"])
table.add_row(["Alice", ColSpan("Age: 25, Paris", 2), "Active"])

# Or programmatic post-ingestion spanning:
# table.set_cell_span(row_idx, col_idx, colspan, combine=" ")
# table.set_header_span(col_idx, colspan, combine=" ")

print(table.draw())

[!NOTE] Spanning Alignment Caveat: Column spans are defined and calculated per-row. To align a spanned column group across the entire table, you must apply the span to each row (either inline via ColSpan or programmatically via set_cell_span()). Plain data rows that do not span will render their own interior vertical separators, resulting in visual column misalignment under merged cells. You can pass the combine parameter (e.g., combine=", ") to merge existing non-empty row values safely when spanning.

Coordinate-Based Cell Styling

vistab supports a fluent, declarative API to inject background colors, foreground colors, and text styles (like bolding and underlining) targeting specific grids, ranging from individual cells, whole rows, columns, headers, or borders.

You can view this demonstration yourself by running vistab show anatomy:

Coordinate-Based Word Wrapping (Nested Tables)

If you need absolute structural control over spatial layouts (for example, if you are embedding pre-rendered ASCII tables inside the cells of another Vistab) you can bypass the internal word-wrapping engine entirely using coordinate mapping.

By setting wrap=False on specific axes, Vistab guarantees it will preserve your structural spacing verbatim without snapping or aggressively pruning layouts:

# Globally bypass word-wrapping for the entire table
table.set_table_wrap(False)

# Or target specific structural coordinates
table.set_row_wrap(0, False)
table.set_col_wrap(2, False)
table.set_cell_wrap(0, 1, False)

If a cell bypassed with wrap=False exceeds table.max_width, Vistab uses a constraint router (table.on_wrap_conflict = "warn") that drops trailing characters while reconstructing your internal ANSI styling sequences to prevent terminal boundary collapse.

Streaming & Caveat Emptor Pipeline Constraints

For extremely large or infinitely generating files, you can stream data iteratively using the --stream flag to bypass native memory buffering constraints:

$ cat large_dataset.csv | vistab --stream

[!WARNING] Caveat Emptor System Limitations: When executing highly constrained pipeline commands requiring complete structured arrays logically (i.e. --sort-by), Vistab relies on the host OS executing standard mapping limits naturally. Pipelining infinite streams containing no terminated newlines (like cat /dev/zero) will unconditionally lock system buffers, triggering OS native Out-Of-Memory (OOM) failures similarly to standard POSIX sort behaviors. No artificial memory caps are injected structurally.

Hierarchical Configuration System

Stop re-typing your constructor arguments! vistab actively scans your execution environment for two distinct configuration architectures:

1. Default Fallbacks (vistab.toml / config.toml)

It evaluates paths sequentially, merging configurations: [./vistab.toml, ./.vistab.toml, ./.config/vistab.toml, ~/.config/vistab/config.toml, ~/.config/vistab.toml, ~/.vistab.toml].

You can generate a default configuration file into the global user profile directly using the CLI:

vistab --create-config

2. Custom Aesthetic Themes (themes.json)

You can lock in CLI layout arguments by saving custom styles into ~/.config/vistab/themes.json using the --save-theme directive. Once saved, these aesthetics become addressable on your machine using --theme.

# Safely capture a global background wash + custom last row colors 
vistab data.csv --table-bg-color bright_black --last-row-color magenta --save-theme my_custom_theme

# Execute the saved layout on another dataset modularly universally!
vistab another_data.csv --theme my_custom_theme

Built-in Themes

vistab comes with predefined themes including ocean, forest, graphite, orchid, and sunflower.

You can view the built-in themes (which you can alter and save as new themes) by running:

vistab show themes

Custom Themes

Let's create a test table:

cat > ~/test.csv << EOF
# ,Nam,Scor,Stat,Val
1,Al,12,Good,0.1
2,Bob,3,Bad,1.1
3,Cat,67,Ugly,1.2
4,Dan,12,Okay,3.0
5,Eve,15,Fine,0.4
6,Will,18,Meh,9.1
7,Pat,21,Great,10.2
8,Kim,24,Super,4.9
9,Sam,27,Awesome,5.9
10,Jo,30,Amazing,0.1
EOF

Running:

vistab ~/test.csv --theme ocean-rows-index

produces:

You may then change that theme by running:

vistab ~/test.csv --theme ocean-rows-index --no-hlines \
    --header-bg-color cyan --last-row-bg-color red --last-row-color black \
    --col0-bg-color green

Which results in:

To see how to generate that specific output using code, you can run:

vistab ~/test.csv --theme ocean-rows-index --no-hlines \
    --header-bg-color cyan --last-row-bg-color red --last-row-color black \
    --col0-bg-color green --show-code

Which will output the code you need to generate that table look and feel:

import vistab

custom_theme = {
    "style": "round-header",
    "decorations": 11,
    "header": {
        "fg": "bright_white",
        "bg": "cyan",
        "bold": true
    },
    "border": {
        "fg": "bright_blue"
    },
    "col_0": {
        "fg": "bright_white",
        "bg": "green",
        "bold": true
    },
    "row_-1": {
        "fg": "black",
        "bg": "red"
    },
    "alt_rows": [
        {
            "fg": "white",
            "bg": "black"
        },
        {
            "fg": "bright_white",
            "bg": "bright_black"
        }
    ]
}

table = vistab.Vistab().set_theme(custom_theme)

# ... map inputs and execute drawing
print(table.draw())

OR you can save it for later use using the --save-theme flag:

vistab ~/test.csv --theme ocean-rows-index --no-hlines \
    --header-bg-color cyan --last-row-bg-color red --last-row-color black \
    --col0-bg-color green --save-theme my_custom_theme

You should see something like:

[SUCCESS] Saved layout globally as 'my_custom_theme' in /home/USER/.config/vistab/themes.json

You can now use it on the command line like this:

vistab ~/test.csv --theme my_custom_theme

Or in code like this:

import vistab

table = vistab.Vistab().set_theme("my_custom_theme")

# ... map inputs and execute drawing
print(table.draw())

Discovering Output Colors (CLI)

Because terminal color renderings vary across different user host profiles and color palettes, vistab comes packaged with a native matrix test exposing every foreground, background, and styling text option you can safely deploy.

You can view the palette directly on the console by executing:

vistab show colors

ANSI Color Layout Support

A major benchmark advantage of vistab is native, invisible terminal styling support. Common ASCII libraries frequently break their visual wrapper alignments when raw terminal colors are embedded because they incorrectly count invisible geometry bytes.

You can view a comprehensive color-wrapping conformance test demonstrating dynamic alignment across complex CJK blocks by executing:

vistab show capabilities

Advanced Formatting (Datatypes)

vistab can infer and parse formatting rules by passing data types, controlling precision for scientific floats and integers.

from vistab import Vistab

table = Vistab(style="ascii")
table.set_cols_dtype(['t', 'f', 'e', 'i', 'a']) 
table.set_cols_align(["l", "r", "r", "r", "l"])

table.add_rows([
    ["text", "float", "exp", "int", "auto"],
    ["alpha", "23.45", 543, 100, 45.67],
    ["beta", 3.1415, 1.23, 78, 56789012345.12],
    ["gamma", 2.718, 2e-3, 56.8, .0000000000128]
])

Limitations & Known Gaps

1. Sorting vs. Streaming: Vistab's --stream capability processes inputs infinitely, rendering data row-by-row on the fly. However, attempting to sort the stream (--sort-by) requires the engine to cache the entire dataset in physical memory. Streaming extremely large files combined with --sort-by will trigger an Out of Memory event.
2. Terminal Boundaries: The max_width string constraint wraps data accurately according to integer text lengths. If structural tables are placed into boundaries too thin to support physical text cells (e.g., width=2), the engine will throw a ValueError rather than attempting to print physically broken graphics.

Detailed API Reference

For the complete list of endpoints, configuration schemas, parameters, and wrapping constraints available in vistab: Please refer to the absolute granular Vistab Core API Documentation

License

This project is licensed under the Apache License 2.0. See LICENSE and NOTICE for details.

---

README | API | CLI | SPEC | CHANGELOG

---

License, Attribution & Citation

vistab is licensed under the Apache License 2.0 (see LICENSE and NOTICE).

Attribution (required). Under Apache-2.0 §4(d), any distribution of this software or a derivative work must retain the NOTICE file and display its attribution reasonably prominently. Concretely, derived/redistributed works must include the following, visibly, in the project README (or equivalent top-level documentation) and in any "About"/credits screen the software presents:

Based on the original vistab by Gabriele G. R. Fariello (https://github.com/fariello/vistab).

Citation. If you use vistab in academic or scholarly work, please cite it. GitHub's "Cite this repository" button (backed by CITATION.cff) provides ready-to-use formats. A suggested citation:

Fariello, Gabriele G. R. vistab. 2026. https://github.com/fariello/vistab

The attribution and citation requests impose no warranty or liability on the author; the software is provided "AS IS" per the LICENSE.