Plotille

Common errors

• TypeError: plot() got an unexpected keyword argument 'color_mode'

  cause Attempting to use the `color_mode` argument with `plotille.plot` or `plotille.Figure` functions/methods in versions 4.0.0 or later.
  fix The `color_mode` argument was renamed to `mode` in v4.0.0. Change `color_mode='rgb'` to `mode='rgb'` or similar, depending on your intended color handling.

• ValueError: X and Y must have the same number of entries.

  cause The input arrays (or lists) for X and Y coordinates have different lengths, which is not allowed for plotting functions like `plotille.plot` or `plotille.scatter`.
  fix Ensure that your `X` and `Y` data sequences have the exact same number of elements before passing them to a `plotille` function.

• UnicodeEncodeError: 'charmap' codec can't encode character '\u2800' in position X: character maps to <undefined>

  cause Your terminal or environment is not configured to correctly display Unicode braille characters (U+2800 onwards) or the output stream's encoding is not UTF-8.
  fix Ensure your terminal emulator supports UTF-8 encoding and is configured to use it. In Python, you can often mitigate this by setting `PYTHONIOENCODING=utf-8` in your environment or explicitly encoding output (though terminal configuration is preferred). Using `linesep='\n'` can sometimes help, but the core issue is terminal encoding.

Warnings

• breaking Python 2.7 support was dropped in Plotille v5.0.0. Projects still using Python 2.7 must use Plotille v4.x or earlier.
  Fix: Upgrade to Python 3.10+ or downgrade plotille to a version <= 4.x.
• breaking The API for handling colors in `Dots`, `Canvas`, and `Figure` changed significantly in v4.0.0. The `color_mode` argument was renamed to `mode` in many cases, and a `color_kwargs` argument was introduced for finer control over color functions.
  Fix: Review your color-related code for `Dots`, `Canvas`, and `Figure`. Adapt to using `mode` instead of `color_mode` and pass keyword arguments for color functions via `color_kwargs`.
• gotcha Plotille's rendering relies on specific terminal properties (monospaced braille characters, ANSI escape codes for colors). Plots may appear misaligned, garbled, or without colors in non-compliant terminal emulators or IDE output panes that don't correctly interpret these features.
  Fix: Run your applications in a true terminal emulator (e.g., Alacritty, iTerm2, Kitty, Windows Terminal, gnome-terminal) with a font that has good support for Unicode braille characters (e.g., Cascadia Code, Unscii). Avoid running directly in IDE output consoles if alignment issues occur.
• gotcha Customizing time-based X-axis labels for real-time or complex time series plots can be challenging. The library's internal tick calculation might not always align perfectly with desired datetime formats or intervals.
  Fix: For fine-grained control over datetime axes, explore `x_ticks_fkt` and `register_label_formatter` as described in the documentation or GitHub issues (e.g., issue #57) to provide custom formatting functions for axis labels.

Install

• pip install plotille Install latest version

Imports

• plot
  wrong:

  from plotille import plot
  plot(X, Y)

  correct:

  import plotille
  plotille.plot(X, Y)

  While `from plotille import plot` works, the official documentation and examples generally prefer `import plotille` and accessing functions/classes as attributes (e.g., `plotille.plot`, `plotille.Figure`).
• Figure
  wrong:

  from plotille.figure import Figure
  fig = Figure()

  correct:

  import plotille
  fig = plotille.Figure()

  The `Figure` class is exposed directly under the top-level `plotille` module.

Quickstart

This quickstart demonstrates how to create a simple line plot using `plotille.plot` and a more customizable plot using the `plotille.Figure` class. It plots sine and cosine functions in the terminal.

import plotille
import numpy as np

X = np.linspace(0, 2*np.pi, 100)
Y = np.sin(X)

print(plotille.plot(X, Y, width=70, height=20,
                     X_label='Angle', Y_label='Sine Value',
                     linesep='\n'))

# Example with Figure class
fig = plotille.Figure()
fig.width = 70
fig.height = 20
fig.x_label = 'Angle'
fig.y_label = 'Cosine Value'
fig.plot(X, np.cos(X), label='cos(x)', lc='blue')
print(fig.show())