Posts tagged with "textual"

I've just made a wee update to textual-fspicker, my dialog library for Textual which adds FileOpen, FileSave and SelectDirectory dialogs. There's no substantial change to the workings of the library itself, but I have added something it's been lacking for a long time: documentation!

Well... that's not quite true, it's always had documentation. I'm an avid writer of Python docstrings and I make a point of always writing them for every class, function, method or global value as I write the code. As such the low-level "API" documentation has always been sat there ready to be published somehow, eventually.

Meanwhile the description for how to use the library was mostly a pointer to some example code inside the README. Not ideal, and something I really wanted to improve at some point.

Given I'm still on a bit of a coding spree in my spare time, I finally decided to get round to using the amazing mkdocstrings, in conjunction with mkdocs, to get some better documentation up an running.

The approach I decided to take with the documentation was to have a page that gave some general information on how to use the library and then also generate low-level documentation for the all the useful content of the library from the docstrings. While latter isn't really useful to anyone wanting to use the library in their own applications, it could be useful to anyone wanting to understand how it hangs together at a lower-level, perhaps because they want to contribute to or extend the library in some way.

While writing some of the general guide took a bit of work, of course, the work to get the documentation up and running and generating was simple enough. The effort comes down to 3 rules in the Makefile for the project:

##############################################################################
# Documentation.
.PHONY: docs
docs:                    # Generate the system documentation
    $(mkdocs) build

.PHONY: rtfm
rtfm:                    # Locally read the library documentation
    $(mkdocs) serve

.PHONY: publishdocs
publishdocs: docs        # Set up the docs for publishing
    $(run) ghp-import --push site

The rtfm target is useful for locally-serving the documentation so I can live preview as I write things and update the code. The publishdocs target is used to create and push a gh-pages branch for the repository, resulting in the documentation being hosted by GitHub.

A wee problem¶

NOTE: I've since found out there's an easier way of fixing the issue.

This is, however, where I ran into a wee problem. I noticed that the locally-hosted version of the documentation looked great, but the version hosted on GitHub Pages was... not so great. I was seeing a load of text alignment issues, and also whole bits of text just not appearing at all.

Here's an example of what I was seeing locally:

and here's what I was seeing being served up from GitHub Pages:

As you can see, in the "bad" version the func label is missing from the header, and the Parameters and Returns tables look quite messy.

I spent a little bit of time digging and, looking in Safari's console, I then noticed that I was getting a 404 on a file called _mkdocstrings.css in the assets folder. Problem found!

Only... was it though? If I looked in the gh-pages local branch the file was there (and with fine permissions). If I looked in the remote branch, it was there too. Thinking it could be some odd browser problem I even tried to grab the file back from the command line and it came back 404 as well.

At this point it was getting kind of late so I decided I must have screwed up somehow but I should leave it for the evening and head to bed. Before doing so though I decided to drop a question into the mkdocstrings discussions to see if anyone could see where I'd messed up.

As it turns out, it looked like I hadn't messed up and the reply from the always super-helpful Timothée was, in effect, "yeah, that should work fine". At least I wasn't the only one confused.

Fast forward to this morning and, with breakfast and coffee inside me, I decided to try and methodically get to the bottom of it. I wrote up the current state of understanding and looked at what might be the common cause. The thing that stood out to me was that this was a file that started with an underscore, so I did a quick search for "github pages underscore" and right away landed on this result.

Bingo!

That had to be it!

A little bit of testing later and sure enough, the documentation hosted on GitHub Pages looked exactly like the locally-hosted version.

So, TIL: by default sites hosted by GitHub Pages will pretend that any asset that starts with an underscore doesn't exist, unless you have a .nojekyll in the root of the repository, on the gh-pages branch (or whatever branch you decide to serve from).

To make this all work I added .nojekyll to docs/source and added this to mkdocs.yml:

exclude_docs: |
  !.nojekyll

All done!

And now I've worked out a simple workflow for using mkdocs/mkdocstrings for my own Python projects, in conjunction with GitHub Pages, I guess I'll start to sprinkle it over other projects too.

The run of writing new terminal-based tools that I want still keeps going. First there was Braindrop, then there was Peplum, and now, released today, there's Hike.

Hike is yet another terminal-based Markdown browser. While it's far from the first, and unlikely to be the last, it's mine and it looks and works exactly how I need. Perhaps it'll be your sort of thing too?

This initial release has a bunch of handy features, including things like:

• A command line where file names, URLs and commands can be entered.
• A persistent history for the command line.
• A local file browser.
• A simple bookmarking system.
• A browsing history.
• Commands for quickly loading and viewing files held on GitHub, GitLab, Codeberg and Bitbucket.

As there's a lot to discover in the application, I've tried to make the help screen as comprehensive as possible:

and there's also the command palette to help with discovering commands and the keys that are associated with them:

Once again, themes are supported so no matter your taste you should find something that's easy on your eyes:

Hike is licensed GPL-3.0 and available via GitHub and also via PyPi. If you have an environment that has pipx installed you should be able to get up and going with:

pipx install hike

It can also be installed with Homebrew by tapping davep/homebrew and then installing hike:

brew tap davep/homebrew
brew install hike

Expect to see more updates in the near future; this is very much an ongoing tinker project.

I seem to be back in the swing of writing handy (for me) little terminal-based applications again. Having not long since released Braindrop (which I'm still working on and tinkering with; it'll get more features in the near future, for sure), I had an idea for another tool I'd like to have: something for looking through, searching, and filtering Python PEPs.

As with anyone who is interested in what's happening with Python itself, I subscribe to the RSS feed of the latest Python PEPs, but I also wanted something that would let me look back at older ones in a way that worked "just so" ("just so" being "what feels right for me", of course). Having finished the main work on Braindrop I realised that the general layout of its UI would work here, as would the filtering and searching approach I used.

From this idea Peplum was born!

In this first release I've simply concentrated on all things to do with grabbing the list of PEPs and presenting them in a useful way; adding various forms of filtering them; adding the ability to search the metadata; that sort of thing. I aim to keep developing this out over the next few weeks and months, adding things like the ability to make notes, to locally view the text of a PEP, perhaps even to mark PEPs as unread and read, etc.

As I mentioned earlier, much of the design was driven by what I did with Braindrop, so once again I've tried my very best to make it keyboard-friendly and as much as possible keyboard-first. This sometimes means having to work against how Textual works, but generally that isn't too tricky to do. I'm once again making heavy use of the command palette and also ensuring that all commands that have corresponding keyboard bindings are documented in the help screen.

There's enough common code between Peplum and Braindrop, when it comes to this aspect of building a Textual application, that I'm minded to spin it out into a little library of its own. I'm going to sit on this code for a wee while and see how it develops, but I can see me taking this approach with future applications and doing this will stop the need to copy and paste.

It might also be useful to others building with Textual.

Also as with Braindrop, themes are a thing, and the theme setting is sticky so you can set it the once and stick with that you like. Here's some examples:

That's a small selection of the themes, with more to explore.

While working on this project I managed to find a couple more bugs in Textual, including a fun way to get transparent backgrounds to get out of sync and also a way to get an easy crash out of OptionList if it's set to width: auto.

What was even more fun was I sort of discovered a bug in the Python PEP API. Thanks to Hugo noticing my "huh, weird" post on Fosstodon, there's now an issue for it as well as a PR in the works. In retrospect I should have raised an issue myself; instead I fell into that "they obviously know what they're doing so it must be like this for a reason" trap.

Lesson relearned: it's always better to ask and get an answer, than to assume a thing is how it is for a reason you don't know; which I guess is a version of Linus' law really.

So that's v0.1.0 out in the wild. I'm pleased with how it's turned out and there's more to come. It's licensed GPL-3.0 and available via GitHub and also via PyPi. If you have an environment that has pipx installed you should be able to get up and going with:

pipx install peplum

It can also be installed with Homebrew by tapping davep/homebrew and then installing peplum:

brew tap davep/homebrew
brew install peplum

I'm going to be making good use of this and working on it more; I hope it's useful to someone else. :-)

A touch over a year ago I did the initial work on an application called Tinboard, a terminal-based client for the Pinboard bookmarking service. I had a lot of fun building it and it was an application that I used on a near-daily basis. However, around August last year I realised it was time for me to move on from Pinboard and try something new; based on various recommendations I settled on Raindrop.

As mentioned in the other blog post, Raindrop offered more or less everything I had with Pinboard and so the move was fairly straightforward. The one thing that was missing though was an application similar to Tinboard.

So, late on last year, with my winter break approaching, I decided to start from scratch and build a "Tinboard for Raindrop", which I'm calling Braindrop.

This was going to be a bit of an adventure too. Since being laid off from Textualize earlier in 2024 I'd not been following its development quite as closely as I used to, and had also run into some issues and bugs with it since that time; moreover, as well as various bugs appearing, some breaking changes had also been made. As such this was going to be a process where I'd wrap my head around what's happened with the framework over the prior six months or so.

Given all this, over the past couple of weeks I've been spending a few hours a day doing some for-pleasure coding and v0.1.0 of Braindrop is the result.

As much as possible I've tried to keep the look and feel similar to that of Tinboard, while also doing my best to avoid some of the "ah, I wish I hadn't done it this way" design decisions I'd made. As of the time of writing I'm very pleased with the result.

One thing I did want to do is ensure that the application was as keyboard-friendly as possible, while also still allowing use of the mouse. Textual can sometimes get that wrong and I ran into an example of this while trying to ensure that there's good in-application help. Somewhat recently Textual added a built-in help system which, sadly, can't easily be used by and navigated by someone using the keyboard. So instead I've recreated the help system I built into Tinboard, while adopting the documentation standard that Textual had settled on (which, coincidentally, was kind of similar to what I did in Tinboard to start with).

As with Tinboard, I've also made sure to make full use of the command palette, with every action that makes sense having a keyboard hotkey as well as a command in the palette. I also took things a little further and made sure that the hotkeys are shown in the command palette for easier discovery.

I've also made sure that Textual's new theme system is available for easy use; so out goes dark/light mode toggling and in comes a collection of different themes. Here's a wee selection as an example:

That's a small selection of the themes, with more to explore.

There's a few more things I want to do before I consider the application v1.0-ready, but it's already in use by me and working well. As I decide what else I want to add to it I'm building up a list of TODO items.

Given that my day job these days is quite varied, isn't quite so coding-intensive, and isn't always related to all things Python, it's actually been fun to sit down and hack up a pure Python application from scratch again. It's also helped me discover a couple or so fresh bugs in Textual (which I've reported, of course) and given me the opportunity to PR some trivial fixes as I've noticed typos and stuff as I go.

Anyway; that's v0.1.0 out in the wild. I'm pleased with how it's turned out and there's more to come. It's licensed GPL-3.0 and available via GitHub and also via PyPi. If you have an environment that has pipx installed you should be able to get up and going with:

pipx install braindrop

It can also be installed with Homebrew by tapping davep/homebrew and then installing braindrop:

brew tap davep/homebrew
brew install braindrop

I hope this is useful to someone else. :-)

I've just released Tinboard v0.14.0. This release adds a feature that a user requested, where you can set the default values for the privacy and read-later status of a new bookmark:

So, any time you create a new bookmark, the edit dialog will use those values by default. It's a feature that makes perfect sense but I didn't think to add it early on because... well, I set the defaults to my preference.

Tinboard can be installed with pip or (ideally) pipx from PyPi. It can also be installed with Homebrew by tapping davep/homebrew and then installing tinboard:

brew tap davep/homebrew
brew install tinboard

The source is available on GitHub.

Tinboard has turned into a tool I use pretty much every day; it's probably my most-used Textual/Python-developed application at this point. This is causing me to think more and more about how I can add things to it that are related to the core purpose, but are also outside of the main "interface with Pinboard" thing.

A thing with keeping bookmarks for a long time is that some of them go stale, go away. Some will just plain 404, others the whole site will disappear. If I find myself going back to a bookmark and seeing this is the case, I'll hit the Wayback Machine and see if there's an archive there.

So I got to thinking: what if I add the ability to perform this check into Tinboard itself? So I did just that.

Now, in the application, if you press w with a bookmark highlighted, it will check with the Wayback Machine to see if the bookmark is in the archive. If it isn't you see this:

On the other hand, if it is in the archive, you'll see something like this:

I sense this is going to be the first step in a couple of features related to this. I'm thinking that I may go on to add a "swap the URL for this bookmark with the Wayback Machine archive URL" feature, which will be handy for those bookmarks that have one away, and it would also be useful to look at the options for a "please archive a copy of this bookmark" feature.

But, for now, v0.12.0 is available and has this handy (for me anyway) first step.

Tinboard can be installed with pip or (ideally) pipx from PyPi. It can also be installed with Homebrew by tapping davep/homebrew and then installing tinboard:

brew tap davep/homebrew
brew install tinboard

The source is available on GitHub.

Back in the very early days of the Textual adventure, within the first month or so of working on the framework, we had a period of dogfooding. One of the projects I wrote during that time was a little tool I called PISpy.

The initial version was pretty much a quick hack; during that dogfooding period I did my best to try and develop a new project every couple of days. Since then I've let PISpy descend into bit rot.

In the last week or so I've turned my attention back to it and made an effort to tidy up the code, tidy it some more, and some more, and even some more.

This morning I put the finishing touches to these changes and released v0.6.0.

PISpy can be installed with pip or (ideallty) pipx from PyPI. It can also be installed with Homebrew by tapping davep/homebrew and then installing pispy:

brew tap davep/homebrew
brew install pispy

The source is available on GitHub.

While my time working on Textual might have come to an end, my time working with Textual hasn't. Three days back I experimented with Textual's newly-added "inline mode":

In doing so I extended the application so that it's possible to run tinboard add and quickly enter a new bookmark and then carry on in the terminal, without needing to "go fullscreen". I'll admit it's of limited use, but it seemed like a good shakedown of the feature and in working on it I was able to discover a couple of bugs (#4385, #4403).

The effect of this is this:

Tinboard can be installed with pip or (ideally) pipx from PyPi. It can also be installed with Homebrew by tapping davep/homebrew and then installing tinboard:

brew tap davep/homebrew
brew install tinboard

The source is available on GitHub.

While I have been on the receiving end of redundancy once before, that was after 21 years of service at a company that, while it was in part about software development, I would never have called it a "tech" company.

So, as of today, I can finally say that the "tech layoffs" came for me and I'm one of 67% of employees being let go from a tech startup.

Achievement unlocked, I guess?

To be clear: I'm not annoyed about this, I'm not even shocked about this; I planned for this from the off and realised and recognised the gamble I was taking back in 2022.

I am disappointed about this. Not in a "I'm disappointed in you" kind of way, but disappointed for all involved and what it says about how FOSS projects are funded and maintained.

It's been an interesting journey, and it's been a privilege to do something I've been wanting to do since the 1990s, when I first read the GNU Manifesto and subsequently watched the free software and open source movements develop and grow: work on FOSS for a living. In doing this I've developed my thoughts about the feasibility of such an endeavour, I've refined how I feel about working in very small teams, I've learnt a lot of useful lessons I'm going to draw on in the future (keeping a journal of my experience has been a great move; I have a lot of notes and thoughts written down that I'll be reviewing and distilling for myself over the coming weeks).

Most of all: it's been an absolute blast working on something that people are actually using to build cool things, and to provide help and guidance to those people when they've needed it.

So... what happens now? Well, of course, right now, I'm looking for a new position. If you're reading this and you are looking for someone who's kinda handy with Python and a bunch of other languages and who loves learning new stuff, or if you know someone who is looking for such a person, do drop me a line!

As for what happens with Textual, and my involvement with it...

Well, what happens with Textual is Will's call, of course. As for my involvement with it: I care about FOSS and I care about Textual; I also care about the folk who have been kind enough to use their time to explore it, test it, build with it, commit to it and make neat stuff with it. My intention, as long as free time allows, is to carry on being involved, both on GitHub and in the Discord server.

It's my sincere hope that, as a community of FOSS-friendly developers, we see Textual over the 1.0 line and beyond.

But all that starts next week. It's a bank holiday weekend and I think I might have deserved a run, a bit of mucking about in VR, a beer, and just a wee bit of down time.

Over the past year and a half I've written a lot of Python code, and a lot of that Python code has been Textual applications; most of those Textual applications have been very quick demonstration or test applications built to help support someone asking for help; some of them have been less-trivial applications written in my own time and for my own use and amusement. Of them I'd say there are two near-daily-drivers, and a couple that I either have more plans for, or like to maintain just for the hell of it.

Those latter applications are all ones that I've deployed to PyPI, and because of that are all ones that I've recommenced be installed using pipx. During that time though I've had half an inclination to make them installable via Homebrew. While probably not installable from the core Homebrew repository¹, at least installable from a "tap"² that's under my own GitHub account or something.

To this end I've had a blog post about packaging Python apps for Homebrew saved in Pinboard for a while now, and every time I look at it I think "this is a lot of faff, maybe later". Today was that "later".

As it turned out, it was way easier than I first realised. The evolution of today pretty much went like this:

Deciding to use a single repository as the "tap"¶

The blog post above seemed to suggest that for every application repository you want a tap for, you probably want a parallel homebrew--prefixed repository. This in turn would suggest that every time someone wants to install one of your tools, they'd need to add a new tap³. As I looked at it this seemed like way too much faff, so in the end I decided to create a single repository that I'd keep all my formula files in. The naming of homebrew-homebrew meant that the tap name would simply be davep/homebrew.

Simple and clean, I think: things for homebrew, things that can be installed via homebrew, that come from davep. To add the tap it's simply:

brew tap davep/homebrew

Ensuring that all my applications and libraries publish source¶

Although it seems that it might be (possibly, maybe, perhaps, who can tell?) deprecated, it looked like homebrew-pypi-poet was a tool I'd need to do all the heavy work on making the formula file. A quick test threw up a problem where it was complaining that my test package (one of my own applications) didn't have an sdist. Sure enough, through nothing more than never having bothered to make it happen, the source of my libraries and applications wasn't been uploaded to PyPI when I published.

So I went through some of my repositories and fixed that, making patch releases as I went.

Making a Makefile to let me be lazy¶

The next thing to do was to figure out the most lazy way of building the formula files. From what I could see the main steps to making all of this work were:

• Make a venv and activate it
• Install homebrew-pypi-poet
• Install the package you want to package for Homebrew
• Run poet to make the formula

Seemed simple enough. For all sorts of lazy reasons I still tend to use pipenv to get things done quickly, and that seemed to work fine here too. I'm also a fan of PIPENV_VENV_IN_PROJECT=true which makes things clean and tidy, so I figured a rule in a Makefile like this:

clean:
        rm -rf .venv
        rm -f Pipfile Pipfile.lock
        pipenv --python 3.12
        pipenv install --dev homebrew-pypi-poet

would be fine to make a clean venv ready to build the formula, and then I'd have a rule for the package itself that depended on the above, like this:

oshit: clean
        pipenv install oshit
        pipenv run poet -f oshit > Formula/oshit.rb

Fixing the package description¶

The above was great, and worked really well. But there was one issue that I could see: the resulting formula file always had this desc inside it:

desc "Shiny new formula"

From what I could see there was no way to tell poet what I wanted the description to be, and neither did I want to have to remember to edit that line each time I regenerated the formula file. So sed to the rescue then I guess, with this sort of thing:

sed -i '' 's/Shiny new formula/The actual text I want/' Formula/coolapp.rb

The result¶

The result of all of this is that I now have a repository that I or anyone else can use as a tap to be able to install my stuff using the brew command. So now if you want a little Hacker News reader for the terminal but you don't want to be messing with installing pipx and the like, but you do use brew on your machine, it's just this:

brew tap davep/homebrew
brew install oshit

Fingers crossed it all "just works" when I next upgrade one of those packages. I will, of course, have to remember to go into davep/homebrew-homebrew and make the-app for the relevant application, and then commit and push the changes, but that's really not too difficult to remember and do.

Hopefully it'll then all just work.