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.

I just realised that it's been a while since I last posted an update about tinboard. This is probably my most-used Textual-based application, and one I'm constantly tinkering with, and just this morning I published v0.10.0.

Often the changes are small tweaks or fixes to how it works, sometimes they're simply updates to the version of Textual used, making use of some new feature or other; I've yet to add another "major" feature so far. They will come, but so far the ideas I have for the application haven't actually felt that necessary. Although I say so myself it does what I need it to do and it does it really well.

So, as a quick catch-up of what's changed since v0.4.0 (which was the last version I posted about):

• v0.5.0 was released 2024-01-04; this included all the tags of a bookmark when doing full-text searching.
• v0.6.0 was released 2024-01-10; it fixed a small bug where the tag suggestion facility got confused by trailing spaces in the input field.
• v0.7.0 was released 2024-02-02; this updated the minimum Textual version to v0.48.2 and removed all the custom changes to the Textual TextArea widget, making use of the updates to TextArea that version of Textual made available.
• v0.8.0 was released 2024-02-18; this fixed a crash on startup caused by a newer release of Textual (the fault was in tinboard; the update to Textual helped reveal the problem).
• v0.9.0 was released 2024-02-29; it simply added support for using Esc at the top level of the application to quit (I like to camp on Esc to GTFO).

Then, just now, I released v0.10.0. This release makes full use of some work I recently did to enhance Textual's CommandPalette widget, which added a "discover" system. The change in tinboard is that all of the command palette providers now have discover methods too. The result of this change is that when you open the command palette in tinboard (ctrl+p) you can see every possible command right away.

Tinboard can be installed with pip or (ideally) pipx from PyPi. The source is available on GitHub.

I feel like I'm on a bit of a roll when it comes to building applications for the terminal at the moment; while I'm still tinkering and improving tinboard and OSHit, I had the urge to tackle another idea that's been on my TODO list for a while.

This is something I did for Emacs back in 2017 and I felt it was a perfect candidate for a Textual-based project. It's a terminal-based trivia quiz game, using the Open Trivia Database as the source of questions.

I've just published an early version to PyPI; it still needs some polish and I have a few other ideas for it, but as it stands I feel it's a fun little game to mess around with.

The idea is pretty straightforward: you can run it up and create lots of different quizzes, there are various parameters you can use to create lots of different kinds of challenges:

Once you're created a quiz, you can run it and answer away:

Right now the idea is that you answer by pressing either 1, 2, 3 or 4 (or just 1 or 2 for true/false questions); when I get a moment I'll also enable mouse support for selecting an answer too (honestly I feel keyboard-answering feels far more natural).

Once the quiz is done you can review your answers and see which were right and which were wrong:

As I say: there's a bunch of other things I want to add to this (keeping track of scores, adding session token support to reduce the chances of repeat questions, etc), but this felt like a good spot to make a v0.1.0 available if anyone else wanted to have a play.

Anyway, if this sounds like your sort of thing, it can be installed with pip or (ideally) pipx from PyPi. The source is available over on GitHub.

PS: Now you can see why I made textual-countdown.

Just a wee catch-up post about OSHit, my terminal-based HackerNews browser. Over the past couple of weeks I've made some small changes, so I thought I'd make mention of what I've done.

As of v0.5.0, which I released earlier today, I've:

• Added a quick way of following links while viewing a comment. While a comment is highlighted you can press l to follow a link; if there's more than one link in the comment a menu will be shown and you can select which one to follow.
• Added support for viewing polls. Polls seem to be few and far between on HackerNews, so when I published the first version of OSHit I didn't have one to hand to test any code against. Eventually one turned up and broke OSHit (on purpose; I wanted to see when that happened) so I could then add the code to load polls and show them. Right now it just shows scores; I might do actual charts at some point.
• Added optional item numbers in the lists; turned on/off with F4.

So far all small things, but handy little improvements. There's still a nice TODO list in the README and I will slowly work through it. Along with tinboard these are two applications that have absolutely turned into "daily drivers", so they're going to get a lot of tweaking over the next few weeks, probably even months.

This is actually the second release of OSHit since I first announced it a week back, and I'll get to that other release in a moment.

I've just published v0.2.0, which isn't a very substantial release, but which bumps the required version of Textual to v0.47.1 and has some fun with the new nested CSS feature.

Underlying the point of this release was me taking a "real world" application of mine and nesting as much of the CSS within it as possible, in part to get a feel for how and when it's useful, but also to give it a proper test in a "proper" application. In doing so I think I've found one bug.

Dogfooding is always a good idea.

The main visible change in this release is I've played around with the look of the comments dialog a bit:

I'm still narrowing this down, but I think I prefer this look to what I started out with.

Another change I made was also to the comments dialog. Before, if you performed the "expand comments" action on a comment card that already had its comments expanded, it would move focus to the first child comment; this was a deliberate choice that felt right at the time. Having used the app for a few days now I've realised that making it an open/close toggle is far more useful. So that's what I've done.

Now... as for the previous release I mentioned above. That was a fun one.

Back when I released v0.1.0 some joker decided that it would be fun to submit the blog post about it to the Orange Site. The comments there went as you'd expected:

• Some riffed off the opening paragraph, ignoring the tool itself.
• Some riffed off the opening paragraph in self-reflective way.
• Some riffed off the opening paragraph in a "I never see the problem" way.
• One or two did the usual "why even bother building that when $TOOL_OF_CHOICE exists?" dance to show their terminal purity.
• One or two posted genuinely useful links to other similar projects.
• The biggest tree of comments was kind of a fight.

One comment caught my eye though; someone reported having a problem running it. My initial thought on reading it was "my dude, seriously, you're going to report the problem in some random comment on HN rather than raise an issue with the author?!?".

For once I was wrong to be so cynical.

So, yeah, that was the reminder I needed that I'd been intentionally reckless while writing the original code, and hadn't gone back to the API code I'd written and made it behave before doing the initial release.

All of which is to say: if you run into a problem with some FOSS project, be like @mihaitodor. Issue that thing so the developer gets to know about it; don't assume they'll be reading some random comment section, social media site or Discord server!

That and don't make 500+ HTTP requests at once; that might not end well for some.

I know I'm not alone in having a relationship with the orange site that is... weird. I generally dislike the culture there, it's almost impossible to read any of the comments without being frustrated about the industry I work in or am adjacent to and some of the people who inhabit it; but as a link aggregator of stuff I might find interesting... I honestly can't think of anywhere better. So, yes, I've been a fairly avid reader of HackerNews for many years, and have even had an account there for over 4 years.

Given this, for a wee while now, I've been meaning to knock up a terminal-based client for it using Textual.

So after work on Tinboard settled down I got the urge to start a new pet project (not abandoning Tinboard, I'm still going to be tweaking and extending it of course) and finally knocking up that client seemed like the one.

Orange Site Hit is the result.

It's worth making clear from the very start: this is a read-only reader. There is no logging in, there is no voting, there is no posting of things. This is a client built with their own API and it doesn't provide such a thing; at least not now and despite me seeing past promises that this will change, there's no API for doing that sort of thing.¹

The idea of this application is you can run it up in the terminal, check the top, best and latest from the categories provided by the API, perhaps dive off into your web browser if needed, and then got on with other things.

It's there for when you're in the terminal you just need your hit of the orange site.

The main screen of the app revolves around the index of items, most of which are going to be stories. You can see an example of that above. For people who prefer things to be slightly less cramped, I've also added a "relaxed layout" mode too:

From the index you can head off into your web-browser by hitting Enter on any item; if the item is a story that links to somewhere that link will be opened; if it's something more like AskHN, or a job, it'll open the related page on HackerNews itself.

Pressing u with an item selected will let you view the details for the user who posted the item:

If you're the sort of person who wants to torture themselves by reading the comments (oh come on we all do it!), there's a comment reader/navigator too. With an item selected press c and the comment dialog will open:

I think the navigation within that dialog is fine; although I can see some scope for improvement. At the moment it uses a widget-per-comment (actually, it's at least 4 widgets per comment), which is fine and Textual handles that without an issue, even on items with lots of comments, but longer-term I can see me having some fun using the line API to build a super-efficient comment presentation and navigation widget.

That's it for now; it feels like a good v0.1.0 spot to be in. There are a bunch of things I still want to do with it (better cleaning up of the text, perhaps with some markup support so links get handled, etc; plus lots of ways of searching for stuff), but I felt it was in a place where I could start using it.

Anyway, if this sounds like your sort of thing, it can be installed with pip or (ideally) pipx from PyPi. The source is available over on GitHub.

Although it's not planned this way, so far it looks like I'm on a "every other day" release cycle with Tinboard right now! Today's release is a small but handy one, I think.

Thanks to the handy little library pyperclip I've added:

• The ability to copy a bookmark's URL to the clipboard.
• URL field autofill if you go to add a new bookmark and the clipboard appears to have a valid URL in it.

At the moment the copy facility is just a straightforward copy of the URL, nothing else. At some point I may add an extended copy option, which will open a dialog with a bunch of options of what to copy from the bookmark, and perhaps also how to format it or something. Like, often, if I'm copying a bookmark's URL, it's because I want to paste it into some Markdown document, or some location that will handle Markdown markup.

Perhaps that'll turn up in v0.5.0 in a couple of days? ;-)

Tinboard can be installed with pip or (ideally) pipx from PyPi. The source is available on GitHub.

It looks like I'm in a wee period of small incremental changes and release of Tinboard. This morning I've release v0.3.0, which has a couple of small but useful changes.

The first is more of a cosmetic thing. The Footer widget in Textual is handy for showing the current keyboard bindings in a given context, but it can get massively cluttered very quickly (we do have plans to revisit this); in Tinboard this clutter creep was turning into a thing.

So I've removed almost every binding from being displayed in the Footer, and have placed an emphasis on the user pressing F1 to get context-sensitive help, and have also left the most useful bindings in the footer with very minimal descriptions.

Given that this is a keyboard-first application, and I've tried to make the bindings easy to remember, I think it's going to make more sense to do it like this, and will make for a tidier UI too.

There is one disadvantage here of course: by removing the display of bindings from the footer, the mouse-heavy user becomes disadvantaged; if a particular binding doesn't have a UI feature that favours the mouse to cover it too there's no way to initiate that action with the mouse. I'm going to think on this a little. Again, Tinboard is designed for me first and foremost, and my preference is to be keyboard-first when using the application; but finding a good compromise would be advantageous when it comes to advising people asking about Textual application design.

The second change is a simple but useful one. I've added a toggle of the sort order of the tags menu in the left-hand column (bound to F4). Right now it simply toggles between alphabetical order, or bookmark count order (most to least). At some point I might make it more of a cycle than a toggle, but this serves my purposes for now.

Tinboard can be installed with pip or (ideally) pipx from PyPi. The source is available on GitHub.

Following on from the initial full release a couple of days ago, I've just released v0.2.0 of Tinboard. There's just one small change in this, but I think it's a really useful one.

In the top-left corner of the screen there's a menu of main filters, letting you switch between seeing all bookmarks, or a combination of read, unread, public, private, etc... In using the application I quickly realised that it would be handy to have bookmark counts in that menu.

So I added that:

These counts are a little different from those in the tags list, in that they always show the number of matching bookmarks amongst all recorded bookmarks, not just those currently on display (and so subject to any sort of filter that's in play).

I think this is the right approach here. I know for sure that that's what I want from this, and I am writing this for me after all...

What's handy about this is that it makes it easier for me to see how many bookmarks haven't been tagged, and also how many I haven't looked back over and marked as read. This is already helping me get to untagged-zero.

Tinboard can be installed with pip or (ideally) pipx from PyPi. The source is available on GitHub.

Over the past few weeks I've been working on a new pet project, in part done as a Textual "dogfooding" project, but also because this is a tool I've been wanting for a while now: a terminal-based client for the Pinboard bookmarking service.

The dogfooding side of the development has been helping, uncovering a couple of fun bugs in Textual; plus the act of building this has let me try out a few of the newer features we've recently added to the framework.

What's really important though is this is a tool I actually wanted, and I'm using pretty often. I've written a lot of Textual-based applications over the past year, most small examples, some quite a bit bigger, but none of them really form part of my daily workflow. This changes with Tinboard.

Tinboard is designed as a fully-featured client, allowing for the creation of new Bookmarks, complete with tag suggestion support:

Not only are tag suggestions pulled from Pinboard, but entry of tags can auto-complete, taking completions from both the suggested tags and also tags used amongst your own bookmarks:

That feature was really easy to add thanks to the Suggester API.

Thanks to the recently-added TextArea widget the add/edit dialog allows for proper full editing of the extended text description of the bookmark too:

One caveat here is a lack of word-wrapping; but this will be arriving in an update to Textual early in the new year.

As well as all the usual add/edit/delete facilities, Tinboard is also designed to make it pretty easy to find bookmarks too. There are filtering options for seeing all read/unread, public/private and tagged/untagged bookmarks; this makes bookmark management really easy for me because I can filter for all the untagged and private bookmarks, which are likely the ones that need editing and expanding on, and tidy up my bookmark library.

There is also, of course, full text search too.

When a filter or search is in operation, the related tags and the like react too:

Another thing I've made a point of doing in Tinboard is leaning pretty hard on the Command Palette. No functionality is only available by it (I've done my best to make sure that keyboard is the primary input device here, with keyboard shortcuts for as much as possible). Initially I approached this as a "for the sake of completeness" feature, but already I'm finding that it's a pretty quick method of pulling up a tag filter.

To help make all the features as discoverable possible, I've also ensured there's a pretty comprehensive help screen:

Anyway; that's v0.1.0 out in the wild. I'm pleased with how it's turned out and there's a few more things I'd like to add. 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 tinboard

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