python-ascii-plotter

Small pure-Python ASCII plotting utility for rendering numeric sequences and (x, y) data directly in a terminal.

The project is a Python 3 port of the original aplotter.py by Imri Goldberg. It currently consists of a single module, aplotter.py.

Features

• Plot a single numeric sequence against its index
• Plot explicit x and y sequences
• Draw approximate slopes with ASCII line characters
• Optional axes and axis-bound labels
• No third-party dependencies

Requirements

• Python 3

Installation

Install in editable mode from the repo root:

pip install -e .

That exposes an aplotter command via the console script declared in pyproject.toml.

Quick Start

Render a sequence against its index:

from aplotter import Plotter

values = [0, 1, 4, 9, 16, 25]
plotter = Plotter()
print(plotter.plot_single(values))

Render explicit x and y values:

from aplotter import Plotter

x = list(range(-5, 6))
y = [n * n for n in x]

plotter = Plotter(x_size=40, y_size=12)
print(plotter.plot_double(x, y))

Use the convenience function:

import aplotter

aplotter.plot(
    range(-5, 6),
    [n * n for n in range(-5, 6)],
    x_size=40,
    y_size=12,
)

Use the CLI with positional y values:

aplotter 0 1 4 9 16 25 --x-size 40 --y-size 12

Use the CLI with explicit x and y values:

aplotter --x -5 -4 -3 -2 -1 0 1 2 3 4 5 --y-values 25 16 9 4 1 0 1 4 9 16 25

Configuration

Plotter accepts these keyword arguments:

• x_size: plot width in characters, default 80
• y_size: plot height in characters, default 20
• draw_axes: draw axes when 0 is inside the visible range, default True
• plot_labels: draw min/max labels near the axes, default True
• plot_slope: connect adjacent points with ASCII slope characters, default True
• dot: base character for plotted points, default *
• x_margin: horizontal padding ratio around the data, default 0.05
• y_margin: vertical padding ratio around the data, default 0.1
• newline: line separator used when returning the rendered string, default "\n"

plot_double() also accepts optional bounds:

• min_x
• max_x
• min_y
• max_y

API

Plotter.plot_single(seq, min_x=None, max_x=None, min_y=None, max_y=None)

• Treats seq as y values and uses range(len(seq)) for x

Plotter.plot_double(x_seq, y_seq, min_x=None, max_x=None, min_y=None, max_y=None)

• Plots matching x and y sequences
• Raises ValueError if the sequences are empty or have different lengths

plot(*args, **flags)

• Convenience wrapper that prints directly to stdout
• Supports either plot(y_seq, ...) or plot(x_seq, y_seq, ...)

main(argv=None)

• CLI entry point used by the aplotter console script
• Supports either positional y values or --x with --y-values

Running Tests

python -m unittest -v

Notes

• This is a terminal-oriented plotting helper, not a replacement for graphical plotting libraries.
• Multi-series plotting is not implemented.
• The module is currently distributed as a single file rather than a packaged library.