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:
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 types1 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
as plt and then call functions via
plt, you instead use the
property made available by the widget.
You don't even need to call the
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.