How not to ask for help

Posted on 2024-02-04 11:27 +0000 in Coding • Tagged with free-software, foss, help • 9 min read

My association with Textual works on two levels: on the one hand, sure, it's currently my day job; on the other hand it's a FOSS project that I'm keen to support so "free time me" tries to work with it and support others working with it too. For this reason you'll often see me being terminally1 online in the Textual Discord, trying to answer questions as they come up, every waking free moment.

Almost without exception the people who ask for help are appreciative and ask in the spirit of wanting help and wanting to work together with whoever is helping them to get an answer. That... that's actually quite a cool thing to be part of. I like the sense of community that comes from someone going "bah I'm trying to do this thing and it isn't working PLEASE HELP!".

And then... well, let's just say that sometimes the odd question will crop up that seems to be asked from a less collaborative position.

Without wanting to appear to dunk on an individual (I don't wish to), I want to break down an example that happened yesterday. For some background, I'd been AFK all day, having a wonderful time in town with a friend, shopping, lunch, a movie, that sort of thing. A nicely-chilled day where I didn't even look at the Discord notifications that had popped up on my watch and phone.

However, later on that evening, finally home and flopped on the sofa, I saw a question pop up that, while lacking any useful detail and possibly suffering a wee bit from being an XY problem, the immediate answer was clear:

BadIdentifier: 'test.udp_json_client-input' is an invalid id; identifiers must contain only letters, numbers, underscores, or hyphens, and must not begin with a number.

????????????????? a dot isn't allowed?

Like I say: it lacks context and detail, and the number of question marks doesn't really clarify much, but the core question that seems to be at play here is "is it true that a full stop can't be used as part of the ID of a widget?".

The answer is: no, it can't. There's a reason for that too, and if someone were to take a step back for a moment and think about how IDs play a part in queries and how they'd be used in a stylesheet, the reason for that might pop out. So, to help the person asking the question walk in the direction of the answer, I reply:

When you come to query that how would the parser know it’s not ID “test” combined with a class, if dot was allowed?

Before we go on, to illustrate my point, consider this ID: foo.bar. When you come to query that back, or use it in a stylesheet, how would #foo.bar look? Is it a widget with the ID foo.bar; or is it a widget with the id foo and the class bar?

As far as Textual's CSS is concerned, it would be the latter.

But at this point it didn't seem necessary to get into all that detail; I like to try and assume knowledge on the part of the person asking the question, sans any other evidence, so for the moment I'll assume a "oh, right, yeah, that's a damn good point" kind of reply. Or if not, perhaps a "I don't quite follow, could you explain?" reply, in which case I'm happy to go into all the detail.

The reply was neither:

why are element ID and classes co-mingled?

this was previously allowed so your question doesn't really make sense to me

Now I'm confused. Asking why element IDs and classes are co-mingled seems odd; but I'm used to chatting with people who don't have English as a first language so I'm going to assume it's just a wording choice; but the latter part is very odd: this has never been allowed. Or, more to the point... without any proper context I can't really appreciate what claim is being made here.

You see... I did notice a bug in Textual recently, when it came to widget IDs. Long story short: when you set your ID for the widget in your code, no actual validation of the ID was being done. This was an oversight that was fixed in the latest release.

But knowing that that's the case would be guesswork on my part; I'm also fresh at my desk after a day out; I'm probably not quite in the coding/Textual zone yet, so rather than try and guess half of the conversation, it's easier to just ask the person who is asking. So I ask them to restate the question, and give some more background.

The reply is:

the objective is to put a string like test.udp_json_client-input as the label of a tab, which previously just used the ID property. from skimming release notes, is it better to explicitly set the label, and then assign something compliant for the ID separately?

Wait... what? I thought we were talking about valid widget IDs, now we're talking about tabs and labels? Do we mean TabbeContent and the labels of a TabPane? This is a bit different. So I'm sat there trying to figure out this person's thought process so I can offer the help they're after and this follows:

okay @davep, you have a real bug. --content-tab- prefix is not ephemeral. if I create a tab and grab .id, that prefix comes with it, so if you save it for later and try to set .active, assigning .active doesn't agree that there is a tab --content-tab-thing

so I need to de-mangle the name manually before assigning .active I guess?

Wut? Like... wut? Okay, we do seem to be talking about TabbedContent, I recognise the values being mentioned here; we did some work late on last year that added some namespacing to parts of the TabbedContent widget in an effort to reduce some foot-gun situations.

But... there's no . being used in the IDs as part of that; why are we now proclaiming a bug in an unrelated PR? That's quite the leap with zero evidence. Like... sure, I'm all for being alerted to bugs and fixing them, but this doesn't seem like that.

And then there's the "so I need to..." conclusion that also seems to have no connection to the original question.

Anyone who has ever done support will recognise this situation, I'm sure. Someone has seen a problem, they've dug around a little and reached a conclusion about what the cause is, and turns up looking for help with the conclusion they've reached (very much a variant of a XY problem).

That almost never gets us where we want to go, so I do the obvious thing; I try and reboot the question; I try and get us back to the start and try and get some clarity; I try and encourage asking the question with zero assumptions:

I'm afraid I'm still not really understanding your question, as it now no longer seems to relate to what you very first asked. Perhaps you could start again, ideally with an MRE of what you're looking at and trying to do, for clarity?

I figure, whatever the problem is, it can be illustrated with like a dozen lines of code. Also, when asking people to do this, it often actually helps them rubber-duck their own problem. There's been plenty of times on Discord where someone's "found a bug" in Textual, they're asked to make an MRE of it, and they come back and go "oh, shoot, right, I did that and realised the bug was in my code". It's cool when they happens; everyone learns something.

So... no MRE comes back, but this is the reply:

I'm trying to fix multiple breakages in my application from some recent changes. Right now I can't wrap my head around what to assign a tabbed_content.active for it to work how it did before (where if you have a tab with ID sample, you can assign tabbed_content.active = "sample", but you can't do that anymore)

While not an MRE, I can work with this. It seems clear that they have a TabbedContent where they have a TabPane with the ID "sample" and they are struggling to make it the active tab by setting active to "sample". That seems hugely unlikely, this is what TabbedContent is all about, I think we'd have noticed (I'm petty sure we've got unit tests that cover this), but I'm game. I can test this. And the MRE I write will illustrate there isn't a problem.

So I reply:

Again, I can only suggest that you make an MRE of the issue you're seeing. For example, here's me making a set of tabs, the last of which has the ID "four", and I set the active to "four":

and provide the code:

from textual.app import App, ComposeResult
from textual.widgets import TabbedContent, TabPane, Label

class TabbedContentApp(App[None]):

    def compose(self) -> ComposeResult:
        with TabbedContent():
            with TabPane("One", id="one"):
                yield Label("One")
            with TabPane("Two", id="two"):
                yield Label("Two")
            with TabPane("Three", id="three"):
                yield Label("Three")
            with TabPane("Four", id="four"):
                yield Label("Four")

    def on_mount(self) -> None:
        self.query_one(TabbedContent).active = "four"

if __name__ == "__main__":
    TabbedContentApp().run()

Based on what they've most-recently said is the problem, I'm confident they'll see that this MRE is their situation in a nutshell, and we can work out from there and figure out what the problem is they're seeing and where this . in their IDs is coming from (because I'm very confident it isn't coming from the work that was done on TabbedContent).

This is good. We're getting close to heading down a good path; I can feel it!

I was wrong.

https://github.com/Textualize/textual/blob/main/src/textual/widgets/_tabbed_content.py#L513

there's no way you can deny you just added a metric ton of shenanigans with the tab ID stuff. I can't get it to work at all anymore (assigning .active), but yes I will either come up with an MRE or find the bug and let you know

So, rather than back up a wee bit, work with the MRE I wrote for them so we can take a walk through the problem, they instead decide to tell me that the PR I did last year (which still isn't implicated in any of this outwith of them seemingly assuming it's the cause of all the issues, presented with zero evidence that it is) was simply "a metric ton of shenanigans".

No!

Stop!

This is not how you ask for help.

This isn't how you ask for help from a product or service you pay for. This really isn't how you ask for help from a Free Software project, where the people who are offering you help are doing so in their free time because they want people to be able to build cool things with it.

It really isn't hard at all to show just a wee bit of respect for people's time and willingness to try and help you.

Now... I get it. I can imagine a scenario where someone has just updated Textual and their application suddenly starts throwing all sorts of weird and new errors. That happens. That happened to me on Thursday evening just gone. But that's no reason for approaching getting help like this.

The way to approach it is this: pin the problem dependency, perhaps publish a new version of your application so there's no accidental update of the dependency, then head to any of the help resources for the dependency has and work with people who want to help you to find the cause of the problem. Trust me, it'll go a lot faster if you work with them, take on board suggestions (no matter how odd they might first appear), and really don't call their code "a metric ton of shenanigans".

The conclusion to all of this? The person asking the question eventually found they were setting some widget's ID to an invalid ID; one with a . in it. So as I suspected and wanted to walk them to: they had invalid IDs all along and they only found out about this because ID validation was fixed.

Perhaps one day they'll retract the claim that my actually-unrelated code that wasn't "just" released but was from last year is "a metric ton of shenanigans". ¯\_(ツ)_/¯


  1. Geddit? GEDDIT? 


Quizzical

Posted on 2024-01-29 21:30 +0000 in Coding • Tagged with Python, terminal, textual • 2 min read

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.

Quizzical

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:

Building a new quiz

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

An example question

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:

Viewing results

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.


Orange Site Hit v0.5.0

Posted on 2024-01-17 21:36 +0000 in Coding • Tagged with Python, terminal, textual • 1 min read

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.


Orange Site Hit v0.2.0

Posted on 2024-01-07 09:50 +0000 in Coding • Tagged with Python, terminal, textual • 3 min read

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:

OSHit you have comments

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.


Orange Site Hit

Posted on 2024-01-01 10:17 +0000 in Coding • Tagged with Python, terminal, textual • 3 min read

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.

OShit

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.1

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:

The index in relaxed mode

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:

Viewing the details of a user

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:

Viewing the real meat of HackerNews

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.


  1. Yes, there are lots of clients that do all sorts of HTML-scraping of the actual website to make this possible; this ain't that. This ain't going to be that. 


Tinboard v0.4.0

Posted on 2023-12-25 10:43 +0000 in Coding • Tagged with Python, terminal, textual • 1 min read

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.

The code for copying to the clipboard

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.


Tinboard v0.3.0

Posted on 2023-12-23 08:49 +0000 in Coding • Tagged with Python, terminal, textual • 2 min read

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.


Tinboard v0.2.0

Posted on 2023-12-21 09:29 +0000 in Coding • Tagged with Python, terminal, textual • 1 min read

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:

Counts in the filters menu

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.


Tinboard

Posted on 2023-12-19 09:47 +0000 in Coding • Tagged with Python, terminal, textual • 2 min read

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 in action

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

Adding a new bookmark

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:

Auto-complete of tags

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:

Editing a bookmark

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.

Text search entry

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

A search result being shown

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.

The command palette in action

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

Help

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. :-)


Evolve Words

Posted on 2023-10-31 21:39 +0100 in Coding • Tagged with Python, evolution, biology, terminal, textual • 2 min read

This follows on from my previous post. If you've not read that, it's worth having a dive in first for the background.

The Ruby code I mention, that was written back in 2008, was actually a pair of scripts. The first one, called selection, did what visual-selection does, only visual-selection does it with a nice TUI interface: it takes a random collection of letters and symbols and evolves them into a target phrase.

As covered before: I don't remember all of the details of the conversation that was going on at the time, but I do seem to remember something along the lines of "yes, but you start out and end up with something the same length" and "nothing more complex is made" (let's gloss over the whole "complex" thing for now... well okay let's just gloss over it, end of story; this is just a fun coding exercise).

What I do remember is that the seed of an idea was planted. Fine: how about I start off with one small word, and using a list of English words as the "fitness landscape" that the mutations had to survive in, mutate a population over and over and see what happens. Would I "randomly" create known words, with fewer letters, with the same letters, with more letters?

So this version of the code randomly did three forms of mutation: it would randomly flip a letter, or randomly delete a letter, or randomly insert a random letter. It would do this over and over and eliminate words that aren't in the original list (the simple form of selecting for survival within the landscape).

Like I said last time: never going to convince anyone of anything, but fun to write some code.

This version became selection2.

So, having turned selection into a TUI application with Textual, I had to do the same with this code...

Evolve Words

As before, because it's fun to do so, this leans heavily on the worker API and textual-plotext.

If you want to check out the app itself there's a GitHub repo and it can also be installed from PyPi using pipx.