termgraph

Choose a chart class based on your data structure and goals:

The core workflow for generating a chart involves three steps: preparing data with the Data class, configuring appearance with the Args class, and initializing a chart class (such as BarChart) to call .draw().

from termgraph import Data, BarChart, StackedChart, VerticalChart, HistogramChart, Args, Colors

# Core workflow
data = Data([10, 20, 30], ["A", "B", "C"])        # Data preparation
args = Args(width=50, colors=[Colors.Blue])        # Configuration
chart = BarChart(data, args)                       # Chart creation
chart.draw()                                       # Visualization

Termgraph can be used as a CLI tool to draw graphs from data files. Data files should consist of two columns (comma or space separated): the first column for labels and the second for numeric data.

Basic usage:

termgraph [datafile]

If no filename is provided, it defaults to reading from stdin.

termgraph data/ex1.dat

To create a basic bar chart, initialize a Data object with your values and labels, then pass it to a BarChart instance and call .draw().

from termgraph import Data, BarChart, Args

# Create data
data = Data([23, 45, 56, 78, 32], ["A", "B", "C", "D", "E"])

# Create and display chart
chart = BarChart(data)
chart.draw()

Install the termgraph package using pip to use it as a command-line tool or a Python library.

pip install termgraph

Install the termgraph library using pip to use it as a Python module for terminal-based charts.

pip install termgraph

Certain chart types support additional configuration options in the Args object:

BarChart

• different_scale (bool): Use different scales for multi-series
• label_before (bool): Show labels before bars

HistogramChart

• bins (int): Number of histogram bins

VerticalChart

• vertical (bool): Enable vertical mode

All chart classes accept an Args object for configuration. Common options include:

• width (int): Chart width in characters
• title (str): Chart title
• colors (list): Colors for series
• suffix (str): Value suffix
• format (str): Value formatting string
• no_labels (bool): Hide labels
• no_values (bool): Hide values
• space_between (bool): Add space between bars

Control how numbers and labels are displayed using these parameters:

• format (str): Python format string for numeric values. Default: "{:<5.2f}".
• suffix (str): Text appended to each value (e.g., " units", "$"). Default: "".
• percentage (bool): If True, formats values as percentages (e.g., 0.75 becomes 75%). Default: False.
• no_readable (bool): If True, disables automatic conversion of large numbers to readable formats like 1K. Default: False.
• no_labels (bool): Hide row labels. Default: False.
• no_values (bool): Hide numeric values next to bars. Default: False.

Use the following parameters in the Args constructor to control the visual layout:

• width (int): The width of the chart in characters. Default: 50.
• title (str): Chart title displayed at the top. Default: None.
• colors (list): List of color codes or names for chart series. Supports termgraph.Colors constants or standard color names (e.g., "blue"). Default: None.
• custom_tick (str): Custom character for chart bars (e.g., "*", "=", or "█"). Default: "".
• space_between (bool): Add blank lines between chart rows. Default: False.
• vertical (bool): Create vertical/column charts instead of horizontal bars. Default: False.
• label_before (bool): Display labels before the bars instead of to the left with colons (e.g., "Label ████" instead of "Label: ████"). Default: False.

Use the Args class to customize the chart's appearance. Key options include:

• width: Integer for chart width.
• title: String for the chart title.
• colors: List of Colors constants.
• suffix: String appended to values.
• format: String format for values (e.g., "{:<6.0f}").
• percentage: Boolean to treat values as percentages.
• different_scale: Boolean to use different scales for each metric in multi-series charts.
• space_between: Boolean to add space between series.

from termgraph import Data, BarChart, Args, Colors

data = Data(
    data=[150, 230, 180, 290, 210],
    labels=["Jan", "Feb", "Mar", "Apr", "May"]
)

args = Args(
    width=60,
    title="Monthly Sales Report",
    colors=[Colors.Green],
    suffix=" units",
    format="{:<6.0f}"
)

chart = BarChart(data, args)
chart.draw()

Specialized options for complex chart types:

Multi-Series Options:

• stacked (bool): Create stacked bar charts. Default: False.
• different_scale (bool): Use different scales for each data series. Default: False.

Histogram Options:

• histogram (bool): Enable histogram mode. Default: False.
• bins (int): Number of bins for histogram charts. Default: 5.

# Stacked chart
args = Args(stacked=True, colors=["blue", "red"])

# Histogram
args = Args(histogram=True, bins=10)