Posts tagged with "PyPI"

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 was quite late discovering Pinboard; by the looks of things I created my account and paid my first subscription for it in early 2019. Since then I've been a pretty avid user and found it really useful. I've even written a couple of clients for it (one for Emacs and one for the terminal).

During that time it's had its fair share of hiccups and outages, but on the whole I've found it a stable and useful service.

The service does have its detractors, and concerns over its long-term stability and how well it's maintained are fairly common. I half paid attention to these, and had started to think about where I might go if there was an issue.

While maintaining and syncing bookmarks isn't exactly a difficult or unsolved problem, and while it's also true that it could be fun to roll my own solution, there are a couple of things I need that would make building my own approach a bit of a chore.

Things important to me are:

• An extension for any random browser I might find myself using
• A good mobile client for at least iOS and iPadOS
• A good API so I can write my own tools if I need to
• A clean and focused backend website

I kept these things in mind and kept an eye out but I'd never really felt the need to actively start looking around.

Then I stumbled on this after posting about another Pinboard outage.

That... yeah, that was the final push I needed to start to think seriously about where to move and how.

A couple of people suggested Raindrop, and from what I could tell it was coming up as a pretty popular service that some Pinboard users were migrating to. I had a look and it wasn't quite what I was after; but close.

You see, there's two things I really like about Pinboard that Raindop didn't seem to cover:

• Simple support for "this shit is unread". I see things, I share to whatever Pinboard app I have on my phone or tablet, etc, and then I review some time later (normally in Tinboard).
• Support for Private and Public pins. I've liked having a feed of bookmarks I can let people see and Raindrop doesn't have this.

I looked around at some blogs that talked about Pinboard vs Raindrop and didn't see any that really dived into this particular aspect of migrating; I also asked a couple of folk who'd made the move about this and they didn't really have any insight (mainly because they didn't care about those particular uses).

One thing I did notice though was that Raindrop does support making individual collections public. So, if I was willing to sacrifice any other uses for collections (a bookmark in Raindrop can only be in one collection), I could simply have a Public and a Private collection and import pins into the appropriate one. Also, unread pins could be left out of the collections and I could use that to signify unread status.

This seemed fine as I'm heavy on the tags anyway.

Now... Raindrop has a pretty comprehensive import facility built in. I gave it a try with Pinboard's backup file and it worked really well. That is... really well except it just threw away the public/private/unread aspect of the pins. There was only one thing for it then: I had to write my own importer!

Which brings me to Paindrop. It's a quick hack but it does the job, and it does the import just how I wanted. The result of the first test was pretty much spot on (in this image I'm comparing what Raindrop says vs what Tinboard says I have in Pinboard):

Usage is pretty straightforward. You create Public and Private collections in Raindrop, you create an app in Raindrop and get the access token, you grab your Pinboard access token and then:

paindrop example:xxxxxxxxxxxxxxxxxxxx xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

where the first parameter is the Pinboard access token and the second the Raindrop access token.

If all goes well, after a few moments, the importer should finish and you should find that all of your pins have migrated to Raindrop, all public pins are in the Public collection and all private pins are in the Private collection. Any pins that were marked as unread will be Unsorted.

Note that if you used different names for your public and private collections you can pass those names to paindrop with the --public and --private switches.

If you're looking to move your bookmarking history out of Pinboard and want to keep the same sort of structure I had I hope Paindrop will be useful to you too.

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

brew tap davep/homebrew
brew install paindrop

The source is available on GitHub.

PS: As for the name... originally it was pin2rain but then Darren Burns pointed out the obvious and it had to happen.

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.

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.

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.

Last week I was wrestling with some Textual code, trying to get something to lay out on the screen "just so". On the whole this isn't too tricky at all, and for those times where it might feel tricky there's some advice available on how to go about it. But in this case I was trying to do a couple of "on the edge" things and one thing I really needed to know was what particular part of the display was being "caused" by what container or widget¹.

Now, at the moment anyway, Textual doesn't have a full-blown devtools with all the bells and whistles; not like in your average web browser. It does have a devtools, but not with all the fancy DOM-diving stuff the above would have needed.

What I needed was the equivalent of print-debugging but with a point-and-ask interface. Now, I actually do often do print-debugging with Textual apps only I use notify; this time though notify wasn't going to cut it.

I needed something that would let me point at a widget and say "show me stuff about this". Something that happens when the mouse hovers over a widget. Something like... a tooltip!

So that was easy:

def on_mount(self) -> None:
    for widget in [self, *self.query("*")]:
        widget.tooltip = "\n".join(
            f"{node!r}" for node in widget.ancestors_with_self
        )

Suddenly I could hover my mouse over a bit of space on the screen and get a "traceback" of sorts for what "caused" it.

I posted this little hack to #show-and-tell on the Discord server and someone mentioned it would be handy if it also showed the CSS for the widget too. That was simple enough because every widget has a styles.css property that is the CSS for the widget, as a string.

After that I didn't think much more about it; until today.

Looking back, one thing I realised is that adding the CSS information on_mount wasn't quite good enough, as it would only show me the state of CSS when the mount happened, not at the moment I inspect the widget. I needed the tooltip to be dynamic.

Thing is... Textual tooltips can't be functions (which would be the obvious approach to make it dynamic); so there was no way to get this on-the-fly behaviour I wanted.

Except there was! The type of tooltip is RenderableType. So that means I could assign it an object that is a Rich renderable; that in turn means I could write a __rich__ method for a class that wraps a widget and then reports back what it can see every time it's called.

In other words, via one step of indirection, I could get the "call a function each time" approach I was after!

It works a treat too.

All of which is a long-winded way of saying I now have a print-debug-level DOM inspector tool for when I'm building applications with Textual:

If this sounds handy to you, you can grab the code too. Install it into your development environment with pip:

pip install textual-dominfo

and then attach it to your app or screen or some top-level widget you're interested in via on_mount; for example:

def on_mount(self) -> None:
    from textual_dominfo import DOMInfo
    DOMInfo.attach_to(self)

and then hover away with that mouse cursor and inspect all the things! Whatever you do though, don't make it part of your runtime, and don't keep it installed; just make it a development dependency.

The source can be found over on GitHub and the package is, as mentioned above, over on PyPi.