Textual TUI framework for Python adds CSS renderer
textualize.io
textualize.io
I did a Show HN back in August 21: https://news.ycombinator.com/item?id=28106389
At the time, it was purely a hobby project, but a lot has happened since then. I was VC funded (nobody was more surprised than me) and since January, Textual has been my full-time gig.
This version adds a CSS renderer and more powerful layout engine, which enables some really interesting features such as live editing.
We've also added a websockets based console app for logging, which restores print style debugging when testing your TUI.
This release has documentation. Which you can find here:
https://textual.textualize.io/
Github repository:
https://github.com/Textualize/textual
Textual is still very much a work in progress, but it is way more stable now.
Textualize (the company) is currently 3 developers based in Edinburgh, Scotland. We recently hired dev no.3 and we have a fourth starting this year.
I just wanted to say that rich is a great tool that I'm very appreciative of, and __rich_repr__ is a godsend for debugging datasets without vomiting an overload of text into my terminal. Or consolidating spark's awful, multi-language stack traces. Excellent work. Textual is a lot of fun too, and I've been looking forward to this update. Thank you!
I use __rich_repr__ to make object representations more succinct[1].
This can also be used to make pretty custom exceptions. You can also use rich.Console.print_exception to output formatted stack traces, with options for including locals, suppressing certain errors, or limiting frames[2]. Pretty great for spark, which usually vomits a novella upon erring.
Also, %load_ext rich in a IPython shell to pretty print all output, exceptions or not.
[1]: https://rich.readthedocs.io/en/stable/pretty.html#rich-repr-...
[2]: https://rich.readthedocs.io/en/stable/reference/console.html...
ps: I didn't follow the latest changes, how is the keybinding aspect ? do you have single keypresses ? or key-sequences ? or even chords ? As an emacs-er I like to have semi-complicated custom keybindings. Anyway just asking, not a ticket :)
Ever since I discovered the project, I have been wondering if I could wire it up with something like Pyodide to have a Python based interface that could work on the terminal or the browser.
Edit: actually to clarify - it was probably me using it wrong, but I didn't have any good examples of what I was trying to do.
I don't mean that as any kind of insult to the people who work on this project -- I'm sure writing it in python is way more pleasant than writing in C. I'm just bummed that projects I have in mind that I intend to write in a language other than python can't use this.
https://youtu.be/Gv2I7qTux7g?t=175
If it doesn't speak the C ABI, someone's gonna rewrite it in C.
I agree with you there. I wonder how it works under the hood, especially those animated panels. I'm gonna go read the source code.
It's worth working through it even if you're not planning to build a TUI app, just to appreciate how well designed the tutorial itself is.
I would expect that this kind of infrastructure would be cheap to support and cheap to run. All the infrastructure is already there in the Linux kernel (or any other Unix-like): just charge me based on my customer's pacct (process accounting) records.
There are a lot of CRUD apps that would be just as good in a TUI as a GUI, and there are a lot of businesses built on CRUD apps.
Except...
I'm scared when I think about VC money here. One day someone is going to want a return on that investment and not sure how that will play out.
Imagine if ncurses decide to charge a license fee out of the blue...
Or perhaps more likely in this scenario, one day the framework stops getting updated, then gets rebranded as the community edition, and no longer receives important and/or timely updates.
I'm all for developers making an excellent living, just need to know my own risk factors when investing in tooling and frameworks, etc. It's hard to know here what the future will bring.
Then again, there is no really compelling alternative to this most awesome creation!
If it makes you feel better, we have a runway of years. I'm Scottish and we don't like spending money.
What's the guarantee here?
If only there was more time.
Hooking these two up would make for a neat programming experience. Best of all...if some $$ €€ were involved, it would show Python open source can be sustainable.
Do you guys have a link showing how you managed to pull those tricks? Smooth redraw and bevels around buttons for instance.
As someone who has drawn my share of simple boxes with scape sequences in the past decades, I’d love to know what you guys figured out that we missed.
Thanks and congratulations.
https://www.willmcgugan.com/blog/tech/post/ceo-just-wants-to...
For smooth scrolling, see the first item in this post:
https://www.textualize.io/blog/posts/7-things-about-terminal...
I'm also fascinated that you can discover new things from a protocol, decades old.
Are there any TS based TUI libraries that are mature and actively developed?
For those loving Textual, can I ask why you’d use this over, say, a web UI?
There’s a joy to using well made libraries and frameworks like this, but apart from that I’m having a hard time justifying this to myself for projects and keen to hear what others are using it for where it’s a better fit than other types of UI.
Ultimately though, I would like Textual to simply be the easiest way of creating a useful UI. Something that you could quickly become productive in with just Python skills. There are a lot of new Python developers that didn't come from a web background, but still need a custom UI.
I don't see it as replacing web apps. If you have the skills and you think you need a web app, then you probably should make a web app. I see it more as allowing UIs to be built that simply weren't being built before due to a lack of skills or resources.
This may become moot, because we have plans for the same API to also serve web applications.
SSH is a great option that I hadn't thought of, and that's good to know it works well over it. I have always seen web UIs being inherently easy to share as a benefit over others, but for dev-focused stuff and SSH connection isn't much harder than web access.
I wasn't thinking about full web apps, more things like status pages and other little utilities exposed on an internal server interface. I've built these for software before, and things like Fish Shell have them too. I'm not sure they require much in the way of web skills, but pure-Python would certainly be easier.
I don't know which other terminal emulators have the same feature.
I've been playing with the beta and I can't wait to build more things with it.
Thanks for all the hard work folks!
I used Sphinx for years, but mkdocs produces far better docs. Especially when combined with mkdocs-material.
I view it quite differently. Like TSDoc for TypeScript or Ruby-Doc for Ruby, there's Sphinx for Python. Using a general-purpose static site generator for Python docs feels just wrong, like you wouldn't use Wix instead of rustdoc for a Rust crate... But maybe that's just me.
> I used Sphinx for years, but mkdocs produces far better docs. Especially when combined with mkdocs-material.
IMO humans write the docs, not Sphinx or mkdocs, and human approach is what ultimately determines whether the docs are good. From this perspective Textual can absolutely have good docs, and especially since they mentioned Django as the inspiration I'm reasonably sure they will.
However, the use of documentation builder can affect how easy it is to achieve certain niceties: Sphinx with autodoc, for example, offers direct links from docs to implementation and cross-package document linking. The builder can introduce useful syntax sugar and salt: Sphinx+RST, for example, subtly encourages proper "rich" linking to actual Python units rather than using dumb identifiers everywhere (see single backtick behavior in RST vs. Markdown), which in turn forces you to write better docs (you must document units you want to cross-reference or you'll see warnings during doc generation) and think about structuring API in a way that makes it easier to document and maintain that documentation.
(On that note, I haven't seen a project anything that paralleled Django documentation by all metrics, and that one is built using Sphinx.)
So while the docs can be great regardless the choice of a build system in case of Textual IMO still breaks the familiarity pattern for Python documentation readers and contributors, breaks interoperability within Python ecosystem (no links to source or to/from third-party packages), and goes with a more limited markup language than RST for no obvious (to me) reason.
There's a spectrum on this; a lot of stuff in the async ecosystem uses mkdocs (FastAPI, etc.) for example. I'd also argue that Markdown is known by waaaaay more SWEs than Sphinx--I wrote a ton of Sphinx years ago and couldn't even tell you where to start today, but I'm fluent in Markdown because I use it everywhere. That says a lot.
Looking through the Textualize docs [0], they seem pretty good to me? It reminds me of most of the web UI toolkits I've used: components on the left, specific functions of the component you're viewing on the right. I think the advantages to Sphinx you're pointing out aren't super relevant to Textualize.
My day job's in Python, and I spend a lot of time reading through various Sphinx documentation. Sure it's possible to make a great Sphinx site, but most people just add bare minimum docstrings and leave you to figure out the rest. Like you say, people generate docs, and I don't think Sphinx has extra magic that "makes you" generate better ones.
On the contrary, I think something that does help you generate better ones is liking your doc tool. If you're not into Sphinx, you're not gonna be enthused about writing excellent docs in it. If you're into mkdocs, you'll be more motivated to do so. The best exercise is the exercise you'll do, etc. etc.
You probably want to compare RST vs. Markdown, or Sphinx vs. MkDocs. Markup language and documentation builder are apples to oranges.
> Looking through the Textualize docs [0], they seem pretty good to me? It reminds me of most of the web UI toolkits I've used: components on the left, specific functions of the component you're viewing on the right. I think the advantages to Sphinx you're pointing out aren't super relevant to Textualize.
I looked at them before I wrote my original comment. They are not bad and they follow the tutorial/topic/reference pattern as Django does. But again they don't export a Sphinx inventory so I cannot cross-reference their units in some Python project I might work on that has Textual as a dependency; their own units are barely cross-referenced within the docs (e.g. they write `App` while in RST it'd be invalid, you'd use :class:`app.App` and it'd be automatically linked to unit's docs or you have to be explicit you want a dumb code snippet with ``App``); they don't link to source code, etc.
> but most people just add bare minimum docstrings and leave you to figure out the rest
Yes, it's definitely up to documentation writers in the first place. You can use Sphinx and have bad docs.
> On the contrary, I think something that does help you generate better ones is liking your doc tool. If you're not into Sphinx, you're not gonna be enthused about writing excellent docs in it. If you're into mkdocs, you'll be more motivated to do so. The best exercise is the exercise you'll do, etc. etc.
I think it's not so black and white. If I love Sphinx, which I do, I sure as hell am not going to force it on my users if I write e.g. a Rust crate-- I'd have to love rustdoc. Same with a TypeScript project, etc. Maybe there's a super convenient and cool and easy to use documentation builder, but if it doesn't warn or fail every time I cross-reference a nonexistent unit then I shouldn't be super enthused about it if I care about documentation reader, probably.
shrug You know what I mean
You seem really hung up on cross-references as links, but I'm not that big a fan. In particular, Sphinx docs will cross-reference themselves a lot, which is super confusing to me; it makes me think "wait is there a more canonical reference than what I'm reading?", then I click it, then I'm back at the top of the page/section I was just on.
Generally I prefer (fast, good) search, and Sphinx' isn't wonderful: it's basically `grep` for docs. I don't really need that, that's what `App site:textual.textualize.io` is for in DDG/Google.
> I sure as hell am not going to force it on my users if I write e.g. a Rust crate-- I'd have to love rustdoc
I mean, "have to love" is a contradiction. My point is that when you're a FOSS dev, you have to take any motivation you can get and avoid demotivations like the plague. Like in your case, I would assume you'd think twice about switching ecosystems from Python to Rust precisely because of your strong preference for Sphinx.
Confusing file formats and documentation builders, but more importantly shrugging off miscommunication, makes me think you don't care much about documentation despite how much of it you wrote. Your position is thus unsurprising but also unlikely to inform my position (like I know it'd be pointless to argue about using static typing and running typecheckers with someone who sees ensuring code correctness as a chore).
> it makes me think "wait is there a more canonical reference than what I'm reading?"
Respect the user. If user lands on a doc section you don't know whether the user previously read everything else. You want to err on the side of more links, hitting a link and going back is quick but having to search is a major waste of time especially not knowing whether there is anything to be found in the first place. (This in particular applies to references, less so for tutorials that are intended to be read in order than jumped around.)
> I would assume you'd think twice about switching ecosystems from Python to Rust precisely because of your strong preference for Sphinx.
If I think Rust is the right tool and I want to work with Rust then I will use Rust. Documentation conventions are not much of a factor, they come with the territory, I don't see it as a demotivating chore or as a choice. Write language X? Use documentation system Y. Learn it and be satisfied with the end result.
If we are really talking about the least challenging ways to write docs then for me might be a Google Doc, should I do it? Of course I know it's bad, unsemantic, inconvenient to read and cross-link and generally completely wrong for the ecosystem so I can't possibly be motivated.
> Confusing file formats and documentation builders, but more importantly shrugging off miscommunication, makes me think you don't care much about documentation
Sorry what I meant here is what I wrote: you knew I meant ReST, and any further discussion was a waste of time. I think you're trying to weirdly score points here by pedantically insisting that there's a meaningful difference between Sphinx and ReST in the context of our conversation, but there isn't, and there's obviously no miscommunication.
I do care about documentation, but in a pragmatic sense. I've written a lot of it--primarily in Sphinx (I'm gonna keep doing this to you) and doxygen--but I've read a lot more, and as a result I'm pretty sensitive to the experience of users.
>> [Sphinx' relentless cross-referencing is confusing to me]
> Respect the user.
This is a good example. I brought up this issue I have with Sphinx as a user, and you dismissed my user experience by telling me to... respect myself? Maybe you think it's a good idea to err on the side of more links. Maybe I think it's a good idea to rely on high-level organizations and search. I don't know that there's an absolute good here. But it's worth saying that not even Wikipedia links everything it possibly can. That tracks with my experience where I find too many links to be noisy.
> Documentation conventions are not much of a factor, they come with the territory, I don't see it as a demotivating chore or as a choice. Write language X? Use documentation system Y. Learn it and be satisfied with the end result.
This seems contradictory with:
> If we are really talking about the least challenging ways to write docs then for me might be a Google Doc, should I do it? Of course I know it's bad, unsemantic, inconvenient to read and cross-link and generally completely wrong for the ecosystem so I can't possibly be motivated.
And this is exactly what I'm saying haha. I don't know why you're being so oppositional. You have strong opinions about documentation systems. If some ecosystem's default was "unsemantic, inconvenient to read and cross-link", you're saying you wouldn't be motivated. Great, then we agree! I think FOSS devs should be free to choose their own doc systems based on what motivates them too.
Let's do a study and compare Rich and Textual, which is based on Rich.
Here's a Textual class: https://textual.textualize.io/reference/events/#textual.even.... I need to find what is MessageTarget, so after some futile ctrl-f'ing I copy-paste it into search field. Suggestions show barely related results, like a code listing and another unit that references MessageTarget. Hitting Enter just drops me not onto a search results page but onto a barely related page that does not document MessageTarget at all.
Then I want to find out what Point is. I just go to Google for this. It shows me Geometry page, which seems related... Except it lands me at the top and do you know how many times "point" (and "pointer", "pointing", etc) are used on the page? Many times, which is why Google thinks it's probably the most related to Point. After a minute of ctrl-f'ing I find no docs for Point.
Note that at this point I don't even know whether either MessageTarget or Point is documented at all. If they aren't, then what a great use of my time!
Of course search engine doesn't have the slightest idea about what I need, it merely matches entered words. As you can see, search is the true grep for documentation that you are describing: dumb and barely useful by itself.
Here's a Rich class: https://rich.readthedocs.io/en/latest/reference/console.html.... they didn't even describe each parameter, but if you want to find how to instantiate (and where to import from) a ConsoleDimensions it's one click away. Same for built-in types, thanks to Intersphinx (I guess when they stop relying on typing_extensions, Literal will be hyperlinked as well).
RST nudges you towards explicitly denoting relationships between different parts of your documentation, because its default behavior is to treat a single backtick as a semantic identifier that signifies a particular unit, not just a random snippet of text. Whenever you use a backtick, it will warn you if you reference a nonexistent unit. Unlike dumb search, it actually knows what relates to what.
If you think I diss the work creators put into the library--I don't, I'm just pointing out to you why cross-reference is useful, and I wrote my original comment about their decision of documentation builder since some of them are apparently on HN.
My counterpoint here is the Google protocol buffers docs for Python [0]. Again I don't want to come down too hard on others' work, but just this front page isn't that helpful to me. For one, I don't need everything prefaced with `google.protobuf`, I know that's the package I'm looking at, and for another, the needless `google.protobuf` prefix and the attendant wrapping make the sections on the left really hard to scan.
But let's get into a specific module: timestamp_pb2 [1]. There are a grand total of two cross-references that aren't to the Python docs (which are KeyError and bool, which like, not the most helpful of cross-references). That's not a great showing.
If your argument here is that "RST nudges you towards explicitly denoting relationships between different parts of your documentation", I'm not seeing it, and I would guess these docs get a fair amount of traffic.
---
My argument here is that you're seeing features in ReST, and extrapolating characteristics about ReST docs based on those features, while ignoring real-world considerations (like developer motivation, for one). I'm sure ReST has features that seem like they would encourage doc authors to use cross-referencing more. But the docs I use are barely cross-referenced, I use DDG/Google searches for this, and pragmatically I think this is the experience of most people.
[0]: https://googleapis.dev/python/protobuf/latest/
[1]: https://googleapis.dev/python/protobuf/latest/google/protobu...
But they do! So you can!
The inventory is right here: https://textual.textualize.io/objects.inv. It's generated by mkdocstrings, the "autodoc" plugin for MkDocs. It's Sphinx compatible.
Every TUI is an enormous hack, legacy piled on top of legacy, trying to twist a simple terminal into a general purpose graphics graphics library. Frankly, a terminal shouldn't support 16 Million colors.
The thing which I really want to exist is a (relatively) simple character based GUI library. Something where "draw this character at x,y in that style", does not rely upon magic chants of escape sequences. And you can lay out a simple GUI based entirely on characters, exactly as if you were creating a TUI, without any of the baggage.