API reference

Package overview

The top-level package re-exports the preferred public API:

Category	Symbols
Chart classes	BarChart, Heatmap, LineChart, SummaryBox, Histogram, BoxPlot, ScatterPlot, CDFChart, ComparisonBar, DivergingBar, NormalizedSpeedup, PercentileLadder, RankTable, SparklineTable, StackedBar
Shared configuration	ChartOptions, ChartBase, ColorMode
Data models	BarData, HistogramBar, LinePoint, ScatterPoint, SpeedupData, SummaryStats and chart-specific companions
Factory helpers	from_* convenience helpers for one-shot chart creation

Use Chart classes and data models and Factory helpers for the canonical symbol-level documentation.

Shared configuration and utilities

Base classes and utilities for ASCII chart rendering.

textcharts.base.outlier_severity_markers(value, scale_max)

Return 1-4 ▸ characters indicating how far value exceeds scale_max.

Thresholds are logarithmic:

≤ 2× → ▸ ≤ 5× → ▸▸ ≤ 10× → ▸▸▸ > 10× → ▸▸▸▸

Parameters:

• value (float)

• scale_max (float)

Return type:

str

textcharts.base.compute_percentile_linear(values, percentile, *, presorted=False)

Compute percentile using linear interpolation between adjacent ranks.

Parameters:

• values (Sequence[float])

• percentile (float)

• presorted (bool)

Return type:

float

textcharts.base.robust_p95(values)

Return nearest-rank P95 with positive-tail fallback for zero-heavy data.

Parameters:

values (Sequence[float])

Return type:

float

class textcharts.base.ColorMode(*values)

Bases: Enum

Terminal color capability levels.

NONE = 'none'

BASIC = 'basic'

EXTENDED = 'extended'

TRUECOLOR = 'truecolor'

class textcharts.base.TerminalCapabilities(width=80, height=24, color_mode=ColorMode.NONE, unicode_support=True, interactive=False)

Bases: object

Detected terminal capabilities.

Parameters:

• width (int)

• height (int)

• color_mode (ColorMode)

• unicode_support (bool)

• interactive (bool)

width: int = 80

height: int = 24

color_mode: ColorMode = 'none'

unicode_support: bool = True

interactive: bool = False

textcharts.base.detect_terminal_capabilities()

Detect terminal capabilities for rendering decisions.

Return type:

TerminalCapabilities

class textcharts.base.TerminalColors(color_mode=ColorMode.EXTENDED, RESET='\x1b[0m', BOLD='\x1b[1m', DIM='\x1b[2m', UNDERLINE='\x1b[4m')

Bases: object

Terminal color utilities using ANSI escape codes.

Parameters:

• color_mode (ColorMode)

• RESET (str)

• BOLD (str)

• DIM (str)

• UNDERLINE (str)

color_mode: ColorMode = 'extended'

RESET: str = '\x1b[0m'

BOLD: str = '\x1b[1m'

DIM: str = '\x1b[2m'

UNDERLINE: str = '\x1b[4m'

fg(color)

Generate foreground color escape code.

Parameters:

color (str | int)

Return type:

str

bg(color)

Generate background color escape code.

Parameters:

color (str | int)

Return type:

str

reset()

Return reset escape code.

Return type:

str

bold()

Return bold escape code.

Return type:

str

colorize(text, fg_color=None, bg_color=None)

Apply foreground and/or background color to text.

Parameters:

• text (str)

• fg_color (str | int | None)

• bg_color (str | int | None)

Return type:

str

class textcharts.base.ChartOptions(width=None, height=None, use_color=True, use_unicode=True, title=None, show_legend=True, show_values=True, theme='light', outlier_cap=None, _capabilities=None)

Bases: object

Configuration options for ASCII chart rendering.

Parameters:

• width (int | None)

• height (int | None)

• use_color (bool)

• use_unicode (bool)

• title (str | None)

• show_legend (bool)

• show_values (bool)

• theme (str)

• outlier_cap (float | None)

• _capabilities (TerminalCapabilities | None)

width: int | None = None

height: int | None = None

use_color: bool = True

use_unicode: bool = True

title: str | None = None

show_legend: bool = True

show_values: bool = True

theme: str = 'light'

outlier_cap: float | None = None

get_effective_width()

Get effective chart width, constrained to reasonable bounds.

Return type:

int

get_horizontal_block_chars()

Get appropriate horizontal block characters.

Return type:

str

get_vertical_block_chars()

Get appropriate vertical block characters.

Return type:

str

get_box_chars()

Get appropriate box drawing characters.

Return type:

dict[str, str]

get_intensity_chars()

Get appropriate intensity characters for heatmaps.

Return type:

str

get_colors()

Get terminal colors instance based on options.

Return type:

TerminalColors

get_palette()

Get the categorical palette for the configured theme.

Return type:

tuple[str, …]

get_series_fill(index)

Get fill character for a series by index.

When color is available, returns ‘█’ (color differentiates series). When color is off, returns a unique fill character per series.

Parameters:

index (int)

Return type:

str

get_series_marker(index)

Get legend marker character for a series by index.

When color is available, returns ‘■’ (color differentiates series). When color is off, returns a unique marker character per series.

Parameters:

index (int)

Return type:

str

class textcharts.base.ChartBase(options=None, subtitle=None, title=None, subject=None)

Bases: ABC

Abstract base class for ASCII chart renderers.

Parameters:

• options (ChartOptions | None)

• subtitle (str | None)

• title (str | None)

• subject (str | None)

subtitle: str | None

abstractmethod render()

Render the chart as a string.

Return type:

str