{"id":13478225,"url":"https://github.com/Textualize/textual-plotext","last_synced_at":"2025-03-27T07:30:52.746Z","repository":{"id":196612157,"uuid":"693048148","full_name":"Textualize/textual-plotext","owner":"Textualize","description":"A Textual widget wrapper library for Plotext","archived":false,"fork":false,"pushed_at":"2024-11-30T19:25:02.000Z","size":557,"stargazers_count":144,"open_issues_count":3,"forks_count":6,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-27T07:08:12.194Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Textualize.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-18T08:38:58.000Z","updated_at":"2025-03-26T22:59:50.000Z","dependencies_parsed_at":"2023-10-02T13:11:03.152Z","dependency_job_id":"b01fb6d4-d5bb-4edf-a974-4c6bc488df0b","html_url":"https://github.com/Textualize/textual-plotext","commit_stats":{"total_commits":255,"total_committers":3,"mean_commits":85.0,"dds":0.03529411764705881,"last_synced_commit":"9fa23e7c486c69654b85445fe90bcb53c218925b"},"previous_names":["textualize/textual-plotext"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Textualize%2Ftextual-plotext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Textualize%2Ftextual-plotext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Textualize%2Ftextual-plotext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Textualize%2Ftextual-plotext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Textualize","download_url":"https://codeload.github.com/Textualize/textual-plotext/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245798267,"owners_count":20673902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T16:01:54.226Z","updated_at":"2025-03-27T07:30:52.687Z","avatar_url":"https://github.com/Textualize.png","language":"Python","readme":"# textual-plotext\n\n![PlotextPlot in action](https://raw.githubusercontent.com/Textualize/textual-plotext/main/textual-plotext-example.png)\n\nA Textual widget wrapper for the [Plotext plotting\nlibrary](https://github.com/piccolomo/plotext).\n\n## Introduction\n\nThe library makes one widget available: `PlotextPlot`. This widget provides\na `plt` property, which should be used where you would normally use `plt` as\nseen in the Plotext documentation.\n\nLet's take [the first\nexample](https://github.com/piccolomo/plotext/blob/master/readme/basic.md#scatter-plot)\nfrom [the Plotext README](https://github.com/piccolomo/plotext#readme):\n\n```python\nimport plotext as plt\ny = plt.sin() # sinusoidal test signal\nplt.scatter(y)\nplt.title(\"Scatter Plot\") # to apply a title\nplt.show() # to finally plot\n```\n\nThe Textual equivalent of this (including everything needed to make this a\nfully-working Textual application) is:\n\n```python\nfrom textual.app import App, ComposeResult\n\nfrom textual_plotext import PlotextPlot\n\nclass ScatterApp(App[None]):\n\n    def compose(self) -\u003e ComposeResult:\n        yield PlotextPlot()\n\n    def on_mount(self) -\u003e None:\n        plt = self.query_one(PlotextPlot).plt\n        y = plt.sin() # sinusoidal test signal\n        plt.scatter(y)\n        plt.title(\"Scatter Plot\") # to apply a title\n\nif __name__ == \"__main__\":\n    ScatterApp().run()\n```\n\nThe main differences to note are:\n\n- We're not directly importing `plotext`.\n- We use `PlotextPlot.plt` rather than `plt`.\n- We don't call Plotext's `show` method, `PlotextPlot` takes care of this.\n\n## Installation\n\nThe library can be installed from PyPi:\n\n```sh\n$ pip install textual-plotext\n```\n\nOnce installed you can quickly test the library by running the demo:\n\n```sh\n$ python -m textual_plotext\n```\n\nThe demo app includes many of the examples shown in the Plotext README.\n\n## Longer example\n\nFor a longer example of how to use the `PlotextPlot` widget, take a look at\n[`examples/textual_towers_weather.py`](./examples/textual_towers_weather.py).\nAs a bonus it also shows an example of using Textual's [worker\nAPI](https://textual.textualize.io/guide/workers/) to create a [threaded\nworker](https://textual.textualize.io/guide/workers/#thread-workers) to pull\nthe data from the backend.\n\n## What is supported?\n\nThe following utility functions are provided (via `PlotextPlot.plt`):\n\n- `plt.sin`\n- `plt.square`\n- `plt.colorize`\n- `plt.uncolorize`\n\n## What isn't supported?\n\nSome functions are not supported at all; mainly those that would not make\nsense inside a Textual application. These include:\n\n- `plt.interactive`\n- `plt.script_folder`\n- `plt.parent_folder`\n- `plt.join_paths`\n- `plt.save_text`\n- `plt.read_data`\n- `plt.write_data`\n- `plt.download`\n- `plt.delete_file`\n- `plt.test`\n- `plt.time`\n- `plt.test_data_url`\n- `plt.test_bar_data_url`\n- `plt.test_image_url`\n- `plt.test_gif_url`\n- `plt.test_video_url`\n- `plt.test_youtube_url`\n\nThe following properties and sub-modules also aren't exposed because they\ntoo are designed for REPL-based interactive use and don't lend themselves to\nbeing used in a Textual application:\n\n- `plt.doc`\n- `plt.markers`\n- `plt.colors`\n- `plt.styles`\n- `plt.themes`\n\nAlso, currently, there is no support for [GIF\nplots](https://github.com/piccolomo/plotext/blob/master/readme/image.md#gif-plot) or\n[playing\nvideos](https://github.com/piccolomo/plotext/blob/master/readme/video.md);\none or both could follow at some point in the future.\n\n## What functions are no-ops?\n\nSome functions are supported as calls but are redefined to be\nnon-operations; these are the sorts of code that wouldn't generally have a\nnegative side-effect but which don't make sense for a Textual application.\nThese include:\n\n- `plt.clear_terminal`\n- `plt.show`\n- `plt.save_fig`\n\n## Themes\n\nPlotext has [a system of\nthemes](https://github.com/piccolomo/plotext/blob/master/readme/aspect.md#themes).\nThe themes provided by Plotext are supported by `PlotextPlot`. However, some\nof those themes use \"ANSI colors\" and so may end up looking different\ndepending on which terminal you use, and what terminal theme is in use (if\nyour terminal supports themes); the issue here is that your plots may look\nvery different in different environments.\n\nTo help with this `textual-plotext` provides an additional set of copies of\nthose themes, all prefixed with `textual-`, that use full RGB coloring to\nensure that, when using a given Plotext theme, it will look the same\neverywhere.\n\nIn addition to the Plotext themes, `textual-plotext` also adds two themes\ncalled:\n\n- `textual-design-dark`\n- `textual-design-light`\n\nThese are two similar themes designed to look good in dark mode and light\nmode respectively. Out of the box, `PlotextPlot` will use these and will\nswitch between them when your [Textual application switches between dark and\nlight mode](https://textual.textualize.io/api/app/#textual.app.App.dark). If\nyou wish to turn off this behaviour, simply set the `auto_theme` property of\nyour plot to `False`.\n\n## Known issues\n\nAt the moment, due to what appears to be a bug in Plotext when it comes to\nrepeated calls to `show` or `build`[^1] for a plot with x or y scales set to\n`\"log\"`, it isn't possible to easily build such a plot. In other words, even\nin the REPL with Plotext itself, a session such as this:\n\n```python\n\u003e\u003e\u003e import plotext as plt\n\u003e\u003e\u003e plt.xscale(\"log\")\n\u003e\u003e\u003e plt.plot(plt.sin(periods=2, length=10**4))\n\u003e\u003e\u003e plt.show()\n\u003cplot is drawn in the terminal here\u003e\n\u003e\u003e\u003e plt.show()\n```\n\nresults in a `ValueError: math domain error`.\n\nThere is a workaround for this, which will work for Plotext use in general\nand would also work nicely in a Textual app. After the first `show` or\n`build`, set the problematic scale back to `\"linear\"`. So the REPL session\nshould above would become:\n\n```python\n\u003e\u003e\u003e import plotext as plt\n\u003e\u003e\u003e plt.xscale(\"log\")\n\u003e\u003e\u003e plt.plot(plt.sin(periods=2, length=10**4))\n\u003e\u003e\u003e plt.show()\n\u003cplot is drawn in the terminal here\u003e\n\u003e\u003e\u003e plt.xscale(\"linear\")     # Note this here!\n\u003e\u003e\u003e plt.show()\n\u003cplot is drawn in the terminal here\u003e\n\u003e\u003e\u003e plt.show()\n\u003cplot is drawn in the terminal here\u003e\netc...\n```\n\nIn a Textual app, this would mean adding (assuming the `xscale` was the\nproblem here) this at the end of the code to create the plot:\n\n```python\n_ = self.plt.build()\nself.plt.xscale(\"linear\")\n```\n\n## Need more help?\n\nIf you need help with this library, or with anything relating to Textual,\nfeel free to come join the [Textualize](https://www.textualize.io/)\n[devs](https://www.textualize.io/about-us/) [on\nDiscord](https://discord.gg/Enf6Z3qhVr) or [the other places where we\nprovide support](https://textual.textualize.io/help/).\n\n[^1]: Repeated calls to `build` will happen when the `PlottextPlot` widget\n    needs to `render` the plot again, on resize for example.\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTextualize%2Ftextual-plotext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTextualize%2Ftextual-plotext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTextualize%2Ftextual-plotext/lists"}