Package: textual-plotext
textual-plotextA Textual widget wrapper for thePlotext plotting
library.IntroductionThe library makes one widget available:PlotextPlot. This widget provides
apltproperty, which should be used where you would normally usepltas
seen in the Plotext documentation.Let's takethe first
examplefromthe Plotext README:importplotextasplty=plt.sin()# sinusoidal test signalplt.scatter(y)plt.title("Scatter Plot")# to apply a titleplt.show()# to finally plotThe Textual equivalent of this (including everything needed to make this a
fully-working Textual application) is:fromtextual.appimportApp,ComposeResultfromtextual_plotextimportPlotextPlotclassScatterApp(App[None]):defcompose(self)->ComposeResult:yieldPlotextPlot()defon_mount(self)->None:plt=self.query_one(PlotextPlot).plty=plt.sin()# sinusoidal test signalplt.scatter(y)plt.title("Scatter Plot")# to apply a titleif__name__=="__main__":ScatterApp().run()The main differences to note are:We're not directly importingplotext.We usePlotextPlot.pltrather thanplt.We don't call Plotext'sshowmethod,PlotextPlottakes care of this.InstallationThe library can be installed from PyPi:$pipinstalltextual-plotextOnce installed you can quickly test the library by running the demo:$python-mtextual_plotextThe demo app includes many of the examples shown in the Plotext README.Longer exampleFor a longer example of how to use thePlotextPlotwidget, take a look atexamples/textual_towers_weather.py.
As a bonus it also shows an example of using Textual'sworker
APIto create athreaded
workerto pull
the data from the backend.What is supported?The following utility functions are provided (viaPlotextPlot.plt):plt.sinplt.squareplt.colorizeplt.uncolorizeWhat isn't supported?Some functions are not supported at all; mainly those that would not make
sense inside a Textual application. These include:plt.interactiveplt.script_folderplt.parent_folderplt.join_pathsplt.save_textplt.read_dataplt.write_dataplt.downloadplt.delete_fileplt.testplt.timeplt.test_data_urlplt.test_bar_data_urlplt.test_image_urlplt.test_gif_urlplt.test_video_urlplt.test_youtube_urlThe following properties and sub-modules also aren't exposed because they
too are designed for REPL-based interactive use and don't lend themselves to
being used in a Textual application:plt.docplt.markersplt.colorsplt.stylesplt.themesAlso, currently, there is no support forGIF
plotsorplaying
videos;
one or both could follow at some point in the future.What functions are no-ops?Some functions are supported as calls but are redefined to be
non-operations; these are the sorts of code that wouldn't generally have a
negative side-effect but which don't make sense for a Textual application.
These include:plt.clear_terminalplt.showplt.save_figThemesPlotext hasa system of
themes.
The themes provided by Plotext are supported byPlotextPlot. However, some
of those themes use "ANSI colors" and so may end up looking different
depending on which terminal you use, and what terminal theme is in use (if
your terminal supports themes); the issue here is that your plots may look
very different in different environments.To help with thistextual-plotextprovides an additional set of copies of
those themes, all prefixed withtextual-, that use full RGB coloring to
ensure that, when using a given Plotext theme, it will look the same
everywhere.In addition to the Plotext themes,textual-plotextalso adds two themes
called:textual-design-darktextual-design-lightThese are two similar themes designed to look good in dark mode and light
mode respectively. Out of the box,PlotextPlotwill use these and will
switch between them when yourTextual application switches between dark and
light mode. If
you wish to turn off this behaviour, simply set theauto_themeproperty of
your plot toFalse.Known issuesAt the moment, due to what appears to be a bug in Plotext when it comes to
repeated calls toshoworbuild[^1] for a plot with x or y scales set to"log", it isn't possible to easily build such a plot. In other words, even
in the REPL with Plotext itself, a session such as this:>>>importplotextasplt>>>plt.xscale("log")>>>plt.plot(plt.sin(periods=2,length=10**4))>>>plt.show()<plotisdrawnintheterminalhere>>>>plt.show()results in aValueError: math domain error.There is a workaround for this, which will work for Plotext use in general
and would also work nicely in a Textual app. After the firstshoworbuild, set the problematic scale back to"linear". So the REPL session
should above would become:>>>importplotextasplt>>>plt.xscale("log")>>>plt.plot(plt.sin(periods=2,length=10**4))>>>plt.show()<plotisdrawnintheterminalhere>>>>plt.xscale("linear")# Note this here!>>>plt.show()<plotisdrawnintheterminalhere>>>>plt.show()<plotisdrawnintheterminalhere>etc...In a Textual app, this would mean adding (assuming thexscalewas the
problem here) this at the end of the code to create the plot:_=self.plt.build()self.plt.xscale("linear")Need more help?If you need help with this library, or with anything relating to Textual,
feel free to come join theTextualizedevson
Discordorthe other places where we
provide support.[^1]: Repeated calls tobuildwill happen when thePlottextPlotwidget
needs torenderthe plot again, on resize for example.