Announcing textual-plotext

It's no surprise that a common question on the Textual Discord server is how to go about producing plots in the terminal. A popular solution that has been suggested is Plotext. While Plotext doesn't directly support Textual, it is easy to use with Rich and, because of this, we wanted to make it just as easy to use in your Textual applications.

With this in mind we've created textual-plotext: a library that provides a widget for using Plotext plots in your app. In doing this we've tried our best to make it as similar as possible to using Plotext in a conventional Python script.

Take this code from the Plotext README:

import plotext as plt
y = plt.sin() # sinusoidal test signal
plt.scatter(y)
plt.title("Scatter Plot") # to apply a title
plt.show() # to finally plot

The Textual equivalent of this (including everything needed to make this a fully-working Textual application) is:

from textual.app import App, ComposeResult

from textual_plotext import PlotextPlot

class ScatterApp(App[None]):

    def compose(self) -> ComposeResult:
        yield PlotextPlot()

    def on_mount(self) -> None:
        plt = self.query_one(PlotextPlot).plt
        y = plt.sin() # sinusoidal test signal
        plt.scatter(y)
        plt.title("Scatter Plot") # to apply a title

if __name__ == "__main__":
    ScatterApp().run()

When run the result will look like this:

Aside from a couple of the more far-out plot types¹ you should find that everything you can do with Plotext in a conventional script can also be done in a Textual application.

Here's a small selection of screenshots from a demo built into the library, each of the plots taken from the Plotext README:

A key design goal of this widget is that you can develop your plots so that the resulting code looks very similar to that in the Plotext documentation. The core difference is that, where you'd normally import the plotext module as plt and then call functions via plt, you instead use the plt property made available by the widget.

You don't even need to call the build or show functions as textual-plotext takes care of this for you. You can see this in action in the scatter code shown earlier.

Of course, moving any existing plotting code into your Textual app means you will need to think about how you get the data and when and where you build your plot. This might be where the Textual worker API becomes useful.

We've included a longer-form example application that shows off the glorious Scottish weather we enjoy here at Textual Towers, with an application that uses workers to pull down weather data from a year ago and plot it.

If you are an existing Plotext user who wants to turn your plots into full terminal applications, we think this will be very familiar and accessible. If you're a Textual user who wants to add plots to your application, we think Plotext is a great library for this.

If you have any questions about this, or anything else to do with Textual, feel free to come and join us on our Discord server or in our GitHub discussions.

---

1. Right now there's no animated gif or video support. ↩