19 Feb 2021

feedPlanet Twisted

Moshe Zadka: Virtual Buffet Line

Many people have written about the logistical challenges of food in a conference. You trade off not just, as Chris points out, expensive food versus terrible food, but also the challenges of serving the food to everyone at once.

One natural method of crowd control is the buffet line. People shuffling slowly through the line, picking food items, allows for a natural choke-point that avoids overwhelming table and staff availability. It is unpleasant to have to walk slowly, at the pace of the slowest decision maker, while hungry.

As humans do, one tries to make the best of a bad situation. All of the people in the conference share some common interests, and many of them have interesting tales besides. A common way of entertaining yourself in the line is to strike up a conversation with the random person before or ahead of you. Indeed, this has led me to hear some fascinating things: tales of incidents, new libraries, or just interesting perspectives.

With a global pandemic looming, responsible folks have either cancelled conferences or led virtual conferences. Virtual conferences, especially while a global pandemic ravages the world, are nowhere as good as the real thing.

One of my favorite things in conferences is the so-called hallway track, where we stand and chat about common interests. Friendly and inclusive people stand in the "pac-man" shape, so that people can join the conversation. I have learned a lot from these random conversations.

As humans do, one tries to make the best of a bad situation. While we are stuck at home, at least lunch time is easy. When you want to eat, order a delivery or step into the kitchen and food, chosen by you, is available. No shuffling. No waiting.

So far, no conference has tried to have a virtual buffet line, where people are forced to virtually wait in a line before eating. True, the random conversations are gone, but they have always been a coping mechanism, not the intent. If the pandemic continues, however, I am not sure this will remain true.

Conferences have already tried to "recreate" many of the constraints foisted upon physical conferences by the uncaring laws of physics in order to make them feel more "real". This rarely helps the "realism" but often creates new, unexpected problem.

One conference platform allows for "virtual coffee tables" where 2-10 people (depending on the table) can sit. Once the table is "full", nobody else can join the conversation. Table-mates can speak via text, video, or audio.

The reason real hallway tables are set for 2-10 people is because of physical constraints and avaialbility of furniture. There was no careful design of which combination of 2-10-sized tables makes for an "optimal" experience.

Further, this is not even a good recreation. With real tables, space is somewhat negotiable. An extra person can fit in if the seated people will let them. People can see the conversation. People can trade-off a subtle "how eaves-droppy" they want to be. You can stand next to the table for a long time, but possibly perceived as weird. You can pass by quickly, catch a whiff of the conversation. You can hear from afar, but only distorted highlights

These things mean, for example, someone seated at a table trying to harass a table-mate chances being seen and caught by random people. While we hope that this is not the only thing preventing people from harassing, this is a useful social enforcement tool. However, the "virtual tables" are more like "virtual isolation rooms". Stuck inside one with an unpleasant person means they can say and do what they will with no fear of witnesses.

How does Code of Conduct enforcement happens? How do vulnerable demographics feel about that?

Attempting to recreate a physical experience in a virtual world is doomed to failure, unless you have sophisticated science-fictional-level virtual reality and physics simulation. However, as a culture, we have adapted to video chats, video webinars, text chats and more. We figured out social conventions and norms, and how to enforce them.

When designing a virtual conference, concentrating on "physical fidelity" is a fool's errand. Instead, figure out what kind of pleasant virtual experiences you want to supply, how to enforce those norms you want to enforce, and how to communicate expected standards to the attendees.

Just like physical conferences can be different, virtual conferences can be different. Pre-recorded or live talks, video distribution platforms, chatting platforms, and more, need to be chosen carefully. Optimize for a good conference, not a conference that feels like an in-person conference.

19 Feb 2021 3:00am GMT

11 Feb 2021

feedPlanet Twisted

Hynek Schlawack: Hardening Your Web Server’s SSL Ciphers

There are many wordy articles on configuring your web server's TLS ciphers. This is not one of them. Instead, I will share a configuration that scores a straight "A" on Qualys's SSL Server Test in 2020.

11 Feb 2021 12:00am GMT

04 Jan 2021

feedPlanet Twisted

Hynek Schlawack: Testing & Packaging

How to ensure that your tests run code that you think they are running, and how to measure your coverage over multiple tox runs (in parallel!).

04 Jan 2021 12:00am GMT

12 Dec 2020

feedPlanet Twisted

Moshe Zadka: DRY is a Trade-Off

DRY, or Don't Repeat Yourself is frequently touted as a principle of software development. "Copy-pasta" is the derisive term applied to a violation of it, tying together the concept of copying code and pasta as description of software development bad practices (see also spaghetti code).

It is so uniformly reviled that some people call DRY a "principle" that you should never violate. Indeed, some linters even detect copy-paste so that it can never sneak into the code. But copy-paste is not a comic-book villain, and DRY does not come bedecked in primary colors to defeat it.

It is worthwhile to know why DRY started out as a principle. In particular, some for some modern software development practices, violating DRY is the right thing to do.

The main problem with repeating a code chunk is that if a bug is found, there is more than one place where it needs to be fixed. On the surface of it, this seems like a reasonable criticism. All code has bugs, those bugs will be fixed, why not minimize the cost of fixing them?

As with all engineering decisions, following DRY is a trade-off. DRY leads to the following issues:

Loss of locality

The alternative to copy-pasting the code is usually to put it in a function (or procedure, or a subroutine, depending on the language), and call it. This means that when reading through the original caller, it is less clear what the code does.

When you are debugging, this means we need to "Step into" the function. While stepping into, it is non-trivial to check the original variables. If you are doing "print debugging", this means finding the original source for the function and adding relevant print statements there.

Especially when DRY is pointed out and reactions are instinctive, the function might have some surprising semantics. For example, mutating contents of local variables is sensible in code. When you move this code to a function as a part of a straightforward DRY refactoring, this means that now a function is mutating its parameters.

Overgeneralized code

Even if the code initially was the same in both places, there is no a-priori guarantee that it will stay this way. For example, one of those places might be called frequently, and so would like to avoid logging too many details. The other place is called seldom, and those details are essential to trouble-shooting frequent problems.

The function that was refactored now has to support an extra parameter: whether to log those details or not. (This parameter might be a boolean, a logging level, or even a logging "object" that has correct levels set up.)

Since usually there is no institutional memory to undo the DRY refactoring, the function might add more and more cases, eventually almost being two functions in one. If the "copy-pasta" was more extensive, it might lead to extensive over-generalization: each place needs a slightly different variation of the functionality.

Coordination issues

Each modification of the "common" function now requires testing all of its callers. In some situations, this can be subtly non-trivial.

For example, if the repetition was across different repositories, now updates means updating library versions. The person making the change might not even be aware of all the callers. The callers only find out when a new library version is used in their code.

Ownership issues

When each of those code segments were repeated, ownership and responsibility were trivial. Whoever owned the surrounding code also owned the repeated segment.

Now that the code has been moved elsewhere, to a "shared" location, ownership can often be muddled. When a bug is found, who is supposed to fix it? What happens if that "bug" is already relied on by another use?

Especially in case with reactive DRY refactoring, there is little effort given to specifying the expected semantics of the common code. There might be some tests, but the behavior that is not captured by tests might still vary.


Having a common library which different code bases can be relied on is good. However, adding functions to such a library or libraries should be done mindfully. A reviewer comment about "this code duplicates the functionality already implemented here" or, even worse, something like pylint code duplication detector, does not have that context or mindfulness.

It is better to acknowledge the duplication, perhaps track it via a ticket, and let the actual "DRY" application take place later. This allows gathering more examples, thinking carefully about API design, and make sure that ownership and backwards compatibility issues have been thought of.

Deduplicating code by putting common lines into functions, without careful thought about abstractions, is never a good idea. Understanding how to abstract correctly is essentially API design. API design is subtle, and difficult to do well. There are no easy short-cuts, and developing expertise in it takes a long time.

Because API design is such a complex skill, it is not easy to give general guidelines except one: wait. Rushing into an API design does not make a good API, even if the person rushing is an expert.

12 Dec 2020 4:00am GMT

30 Nov 2020

feedPlanet Twisted

Glyph Lefkowitz: Faster

I've often heard Henry Ford quoted as saying:

"If I had asked people what they wanted, they would have said faster horses."

Despite the fact that he probably didn't actually say that, it does neatly encapsulate a certain approach to product development. And it's one that the modern technology industry loves to lionize.

There's a genre of mythologized product development whereby wholly unique and novel products spring, fully-formed, Athena-like, from the foreheads of Zeusian industrialists like Jobs, or Musk, or Bezos. This act of creation requires no input from customers. Indeed, the myths constructed about the iconic products associated with these industrialists often gloss over or outright ignore the work of their hundreds of thousands of employees, not to mention long years of iteration along with legions of early-adopter customers.

Ford's other major area of contribution to public discourse was, of course, being a big ol' Nazi, just writing so much Nazi stuff that he was one of Hitler's heroes.1

This could be a coincidence, of course; lots of prominent thinkers in the past were absolutely hideous racists, anti-semites, slave owners and worse; these terrible ideas were often products of the time, and the people who held them sometimes nevertheless had other ideas worth examining.

But I think that this sentiment reflects a wider underlying infatuation with authoritarian ideology. At its core, the idea is that the uniquely gifted engineer is just better than their users, fundamentally smarter, more able to discern their true needs, more aware of the capabilities of the technology that we alone are familiar with. Why ask the little people, they can't possibly know what they really need.

While we may blithely quote this sort of thing, when you look at the nuts and bolts of the technology industry, the actual practice of the industry has matured past it. Focus groups and user research are now cornerstones of interaction design. We know that it's pure hubris to think that we can predict the way that users react with; you can't just wing it.

But, I hadn't heard a similarly pithy encapsulation of an empathetic approach that keeps the user in the loop and doesn't condescend to them, until today. The quote came up, and my good friend Tristan Seligmann responded with this:

If you ask your users questions that they don't have the skills to answer - like "how can we improve your horse?" - they will give you bad answers; but the solution to this is to ask better questions, not to ask no questions.

Tristan Seligmann

That, fundamentally, is the work-product of a really good engineer. Not faster horses or faster cars:

Better questions.

  1. Pro tip: don't base your design ethos on Nazi ideas.

30 Nov 2020 7:03am GMT

20 Sep 2020

feedPlanet Twisted

Moshe Zadka: Fifty Shades of Ver

Computers work on binary code. If statements take one path: true, or false. For computers, bright lines and clear borders make sense.

Humans are more complicated. What's an adult? When are you happy? How mature are you? Humans have fuzzy feelings with no clear delination.

I was more responsible as a ten year old than as a three year old. At 13, I reached the age when I was responsible for following Jewish law myself. At 18, the legal system trusted me to could drink alcohol and drive, and trusted me that I will keep the two activities distinct. In the US, you cannot become a senator before you are 30.

At what age are you responsible "enough"?

Software is written by humans, not computers. Humans with feelings, hopes, and dreams. We cry, we strive, we feel accomplished at times, and disappointed at others.

If you were designing a version system for computers, SemVer, or "Semantic Versioning", would make perfect sense. Each part number in a three-part version number is given a specific, distinct, definition:

But software is not made by computers. It is made by humans.

Start small

A journey of a thousand miles begins with a single step. The first version of the Linux kernel printed As and Bs to the screen. The first version of Python didn't have modules. SemVer, to its credit, acknowledges that.

In versions like 0.x.y. SemVer defines the semantics:

Anything MAY change at any time. The public API SHOULD NOT be considered stable.

When something is small and fragile, it should be able to change. Every UNIX programmer knows the story of why Makefile treats tabs and spaces differently. In retrospect, causing a dozen of people a small amount of pain would probably have been better than staying with the problem.

Once the software is mature enough, the SemVer reasoning goes, just release 1.0.0 and commit to API stability.

Grow slowly

Given the amount of projects that have stayed on ZeroVer for a long time (or forever!) the assumption that commiting to API stability once the project matures is easy seems to not pan out.

Remember: software is written by humans. Fuzzy humans, in complicated social structures, who work together as best they can, using brains evolved to figure out politics in a fifty-person tribe in order to stay alive.

Once a social structure is in place and working, changing it is hard. In the ZeroVer days, there was no reason to figure out which changes broke API compatibility. There was no reason to clearly delinate which parts are "public" API and which are not. After all, there was no need.

Switching out of ZeroVer requires building all of this. Not switching out of ZeroVer does not require complicated social engineering. It is not surprising that it is hard. It's almost as if humans work better with slow changes, and not sudden revolutions.

Small commitments

Lately, I have been frustrated with some aspects of my life. COVID-19 did not cause them, but helped bring them into sharp focus. As the least embarassing example to admit in a public forum, I realized that while my book shelves are so full of books that shoving another one requires my 80s-kids Tetris skills, I have not read a single fiction book in the last three years. I used to be a voracious reader!

How do you change habits? I used to read, easily, 200 pages of fiction a day in my 20s. I have not gotten worse at reading. I could commit to reading 200 pages a day, and track my progress. If you have ever done that, you know what the outcome is. Every day, you look at the task, and you decide it is too big. You never begin.

Instead, I decided I will read 20 pages a day, and feel good about it. Feel good? I even decided to reward myself for every week where I hit this goal five out seven days.

The result? The last few weeks, I have been consistently been reading 20 pages a day, missing only one or two days.

When you are not good at something, as a person or as a group, and you want to get better, small commitments frequently achieved are the way to go.

SemVer does not work that way. It is all or nothing. SemWay or the Highway. Perhaps it is better to have a versioning system for humans, not a fictional alien race, if we assume software will keep being written by humans.

Deprecation policy

It is an easy change to say that no single change can "just" break an API. One change to deprecate, and one change to break. This is straightforward to verify. It is reasonable to have a policy for exceptions, but document the exceptions carefully.

Note that this change does not help potential users all that much by itself. After all, two PRs in close succession can land, and there is no reasonable upgrade path.

Should we feel good about making a small change that does not help anyone? Absolutely. Because it is small, and it is on the right path.

Now that this change becomes ingrained in the developer group, we can start mandating a minimum time between deprecation and breakage. At first, we can have a 0day policy: you can break, as long as the deprecated software has been released. This causes more releases to happen, making the team better at releasing. It helps users only minimally. However, at least with careful version pinning, there is an upgrade path.

Now, we can start making the number 0 a bit bigger. First, a week. Then, a month. Eventually, a quarter or a year. If the project is big, the number might be different for different parts.

But at that point, the project has a clear deprecation policy. A deprecation policy that can slowly grow the more mature the project is. Not a binary, true/false, mature/new. Shades of maturity. Levels of reliability.

The calendar

A minute has 60 seconds. An hour has 60 minutes. A day has 24 hours. Our time measurement system is still based on the Babylonian base-60 system, though the actual digits used by the Babylonians are studied only by specialists.

Humans organize their lives by their calendar. Kids learn that their birthday happens when they are a year older. Every seven days, we have a weekend. Every month, utility bills need to be paid.

Humans make plans that depend on time. They wait for their tax refund on April 15th to make purchases.

A time-based deprecation policy takes advantage of those skills. If the time between deprecation and breakage is one week, then the policy is clear: better make sure to upgrade weekly. If it is one year, do it when returning from the end-of-year holidays. If the policy is incompatible with the expected value of the maintenance effort, then this can be known in advance. This might mean that that dependency is not mature enough to be used.

Versioning for adults

A versioning scheme needs to remember two things:

  • The people writing the software are humans
  • The people using the software are humans

If there is one thing that humans are good at, it is communicating with other humans. Humans can communicate feelings, fuzzy boundaries, and plans for the future.

Calendar-based versioning, and a clear deprecation policy, give them the ability to communicate those. Not in a way that is suitable for computers. Not in a way that will help your dependency-resolver decide which version is "compatible". But in a way that lets you communicate with people about your needs in a mature way, and figuring out whether you can work together, or part on friendly terms.


If the main consumer of version numbers was the dependency resolver, and the producer of version number was a top-down military structure used to following orders, SemVer would work well.

For real software projects, used by humans, depending on documents written by humans for humans, and often "managed" in extremely loose ways, even for commercial projects, let alone volunteer-led ones, a versioning system that helps adults work with adults is best.


20 Sep 2020 5:00am GMT

18 Sep 2020

feedPlanet Twisted

Itamar Turner-Trauring: From YAGNI to YDNIY

How do you ship a product on schedule? One useful approach is applying the You Ain't Gonna Need It principle, or YAGNI for short: leave out all the things that seem nice-to-have, but you have no proof you actually need.

But beyond the things you don't need, there are still plenty of features you pretty clearly do need… but are not blockers on releasing your product. So beyond YAGNI, there's also YDNIY: You Don't Need It Yet.

Let's see an example of this principle in practice, visualize the principle as a flowchart, and then compare it to another popular acronymed concept, the Minimum Viable Product.

A real world example: shipping a new memory profiler

In March 2020 I shipped the initial release of a new memory profiler for Python, Fil.

Here's how it changed over time in terms of features, from May to August 2020:

All of the features I added in later releases were clearly necessary from the start; YAGNI did not apply. Lots of people use macOS, the target audience of data scientists and scientists often use Conda and Jupyter, all those memory allocation APIs are used in the real world, and so on.

But even a tool that only runs complete programs on Linux, and only tracks the most popular memory allocation APIs, is still useful to some people.

If I had waited until all those features were implemented to ship an initial release, all the people who used the profiler during the first four months of its existence would have had to keep using worse tools. And with every release, the number of people for whom the tool is useful has grown.

Unlike YAGNI, YDNIY doesn't mean you don't implement a feature-you just delay it so that you can release something now.

The YAGNI and YDNIY algorithm

Features that are not clearly necessary can be dropped based on the YAGNI principle. And if the product is still useful without the feature, you can delay that feature based on the YDNIY principle.

In flowchart form:

Is the feature clearly needed? Is the product usable without it? Yes YAGNI No Implement it now No YDNIY Yes Implement it later


The Minimum Viable Product, or MVP, is another acronym that might seem like it means the same thing as YDNIY. But as defined by its originator, Eric Ries, an MVP has a different goal, and actually adds on more work.

Specifically, Ries defines an MVP as "that version of a new product which allows a team to collect the maximum amount of validated learning about customers with the least effort." He goes on to explain that a "MVP is quite annoying, because it imposes extra overhead. We have to manage to learn something from our first product iteration. In a lot of cases, this requires a lot of energy invested in talking to customers or metrics and analytics."

To put it another way, the goal of the MVP is to learn about users or customers, whereas the goal of YAGNI and YDNIY is to get something useful into users' hands as quickly as possible.

Tired of scrambling to get your job done?

If you were productive enough, you could take the afternoon off, confident you'd produced high value work. Not to mention having an easier time finding a new job when you need one.

Learn the secret skills of productive programmers.

18 Sep 2020 4:00am GMT

24 Aug 2020

feedPlanet Twisted

Glyph Lefkowitz: Nice Animations with Twisted and PyGame

One of my favorite features within Twisted - but also one of the least known - is LoopingCall.withCount, which can be used in applications where you have some real-time thing happening, which needs to keep happening at a smooth rate regardless of any concurrent activity or pauses in the main loop. Originally designed for playing audio samples from a softphone without introducing a desync delay over time, it can also be used to play animations while keeping track of their appropriate frame.

LoopingCall is all around a fun tool to build little game features with. I've built a quick little demo to showcase some discoveries I've made over a few years of small hobby projects (none of which are ready for an open-source release) over here: DrawSnek.

This little demo responds to 3 key-presses:

  1. q quits. Always a useful thing for full-screen apps which don't always play nice with C-c :).
  2. s spawns an additional snek. Have fun, make many sneks.
  3. h introduces a random "hiccup" of up to 1 full second so you can see what happens visually when the loop is overburdened or stuck.

Unfortunately a fully-functioning demo is a bit lengthy to go over line by line in a blog post, so I'll just focus on a couple of important features for stutter- and tearing-resistant animation & drawing with PyGame & Twisted.

For starters, you'll want to use a very recent prerelease of PyGame 2, which recently added support for vertical sync even without OpenGL mode; then, pass the vsync=1 argument to set_mode:

screen = pygame.display.set_mode(
    (640 * 2, 480 * 2),
    pygame.locals.SCALED | pygame.locals.FULLSCREEN,

To allow for as much wall-clock time as possible to handle non-drawing work, such as AI and input handling, I also use this trick:

def drawScene():
    screen.fill((0, 0, 0))
    for drawable in self.drawables:
    return deferToThread(pygame.display.flip)

LoopingCall(drawScene).start(1 / 62.0)

By deferring pygame.display.flip to a thread1, the main loop can continue processing AI timers, animation, network input, and user input while blocking and waiting for the vertical blank. Since the time-to-vblank can easily be up to 1/120th of a second, this is a significant amount of time! We know that the draw won't overlap with flip, because LoopingCall respects Deferreds returned from its callable and won't re-invoke you until the Deferred fires.

Drawing doesn't use withCount, because it just needs to repeat about once every refresh interval (on most displays, about 1/60th of a second); the vblank timing is what makes sure it lines up.

However, animation looks like this:

def animate(self, frameCount):
    self.index += frameCount
    self.index %= len(self.images)

We move the index forward by however many frames it's been, then be sure it wraps around by modding it by the number of frames.

Similarly, the core2 of movement looks like this:

def move(self, frameCount):
    self.sprite.x += frameCount * self.dx
    self.sprite.y += frameCount * self.dy

Rather than moving based on the number of times we've been called, which can result in slowed-down movement when the framerate isn't keeping up, we jump forward by however many frames we should have been called at this point in time.

One of these days, maybe I'll make an actual game, but in the meanwhile I hope you all enjoy playing with these fun little basic techniques for using Twisted in your game engine.

  1. I'm mostly sure that this is safe, but, it's definitely the dodgiest thing here. If you're going to do this, make sure that you never do any drawing outside of the draw() method.

  2. Hand-waving over a ton of tedious logic to change direction before we go out of bounds...

24 Aug 2020 2:50am GMT

23 Aug 2020

feedPlanet Twisted

Glyph Lefkowitz: Never Run ‘python’ In Your Downloads Folder

One of the wonderful things about Python is the ease with which you can start writing a script - just drop some code into a .py file, and run python my_file.py. Similarly it's easy to get started with modularity: split my_file.py into my_app.py and my_lib.py, and you can import my_lib from my_app.py and start organizing your code into modules.

However, the details of the machinery that makes this work have some surprising, and sometimes very security-critical consequences: the more convenient it is for you to execute code from different locations, the more opportunities an attacker has to execute it as well...

Python needs a safe space to load code from

Here are three critical assumptions embedded in Python's security model:

  1. Every entry on sys.path is assumed to be a secure location from which it is safe to execute arbitrary code.
  2. The directory where the "main script" is located is always on sys.path.
  3. When invoking python directly, the current directory is treated as the "main script" location, even when passing the -c or -m options.

If you're running a Python application that's been installed properly on your computer, the only location outside of your Python install or virtualenv that will be automatically added to your sys.path (by default) is the location where the main executable, or script, is installed.

For example, if you have pip installed in /usr/bin, and you run /usr/bin/pip, then only /usr/bin will be added to sys.path by this feature. Anything that can write files to that /usr/bin can already make you, or your system, run stuff, so it's a pretty safe place. (Consider what would happen if your ls executable got replaced with something nasty.)

However, one emerging convention is to prefer calling /path/to/python -m pip in order to avoid the complexities of setting up $PATH properly, and to avoid dealing with divergent documentation of how scripts are installed on Windows (usually as .exe files these days, rather than .py files).

This is fine - as long as you trust that you're the only one putting files into the places you can import from - including your working directory.

Your "Downloads" folder isn't safe

As the category of attacks with the name "DLL Planting" indicates, there are many ways that browsers (and sometimes other software) can be tricked into putting files with arbitrary filenames into the Downloads folder, without user interaction.

Browsers are starting to take this class of vulnerability more seriously, and adding various mitigations to avoid allowing sites to surreptitiously drop files in your downloads folder when you visit them.1

Even with mitigations though, it will be hard to stamp this out entirely: for example, the Content-Disposition HTTP header's filename* parameter exists entirely to allow the the site to choose the filename that it downloads to.

Composing the attack

You've made a habit of python -m pip to install stuff. You download a Python package from a totally trustworthy website that, for whatever reason, has a Python wheel by direct download instead of on PyPI. Maybe it's internal, maybe it's a pre-release; whatever. So you download totally-legit-package.whl, and then:

~$ cd Downloads
~/Downloads$ python -m pip install ./totally-legit-package.whl

This seems like a reasonable thing to do, but unbeknownst to you, two weeks ago, a completely different site you visited had some XSS JavaScript on it that downloaded a pip.py with some malware in it into your downloads folder.


Demonstrating it

Here's a quick demonstration of the attack:

~$ mkdir attacker_dir
~$ cd attacker_dir
~/attacker_dir$ echo 'print("lol ur pwnt")' > pip.py
~/attacker_dir$ python -m pip install requests
lol ur pwnt

PYTHONPATH surprises

Just a few paragraphs ago, I said:

If you're running a Python application that's been installed properly on your computer, the only location outside of your Python install or virtualenv that will be automatically added to your sys.path (by default) is the location where the main executable, or script, is installed.

So what is that parenthetical "by default" doing there? What other directories might be added?

Anything entries on your $PYTHONPATH environment variable. You wouldn't put your current directory on $PYTHONPATH, would you?

Unfortunately, there's one common way that you might have done so by accident.

Let's simulate a "vulnerable" Python application:

# tool.py
    import optional_extra
except ImportError:
    print("extra not found, that's fine")

Make 2 directories: install_dir and attacker_dir. Drop this in install_dir. Then, cd attacker_dir and put our sophisticated malware there, under the name used by tool.py:

# optional_extra.py
print("lol ur pwnt")

Finally, let's run it:

~/attacker_dir$ python ../install_dir/tool.py
extra not found, that's fine

So far, so good.

But, here's the common mistake. Most places that still recommend PYTHONPATH recommend adding things to it like so:

export PYTHONPATH="/new/useful/stuff:$PYTHONPATH";

Intuitively, this makes sense; if you're adding project X to your $PYTHONPATH, maybe project Y had already added something, maybe not; you never want to blow it away and replace what other parts of your shell startup might have done with it, especially if you're writing documentation that lots of different people will use.

But this idiom has a critical flaw: the first time it's invoked, if $PYTHONPATH was previously either empty or un-set, this then includes an empty string, which resolves to the current directory. Let's try it:

~/attacker_dir$ export PYTHONPATH="/a/perfectly/safe/place:$PYTHONPATH";
~/attacker_dir$ python ../install_dir/tool.py
lol ur pwnt

Oh no! Well, just to be safe, let's empty out $PYTHONPATH and try it again:

~/attacker_dir$ export PYTHONPATH="";
~/attacker_dir$ python ../install_dir/tool.py
lol ur pwnt

Still not safe!

What's happening here is that if PYTHONPATH is empty, that is not the same thing as it being unset. From within Python, this is the difference between os.environ.get("PYTHONPATH") == "" and os.environ.get("PYTHONPATH") == None.

If you want to be sure you've cleared $PYTHONPATH from a shell (or somewhere in a shell startup), you need to use the unset command:

~/attacker_dir$ python ../install_dir/tool.py
extra not found, that's fine

Setting PYTHONPATH used to be the most common way to set up a Python development environment; hopefully it's mostly fallen out of favor, with virtualenvs serving this need better. If you've got an old shell configuration that still sets a $PYTHONPATH that you don't need any more, this is a good opportunity to go ahead and delete it.

However, if you do need an idiom for "appending to" PYTHONPATH in a shell startup, use this technique:

export PYTHONPATH="${PYTHONPATH:+${PYTHONPATH}:}new_entry_1"
export PYTHONPATH="${PYTHONPATH:+${PYTHONPATH}:}new_entry_2"

In both bash and zsh, this results in

$ echo "${PYTHONPATH}"

with no extra colons or blank entries on your $PYTHONPATH variable now.

Finally: if you're still using $PYTHONPATH, be sure to always use absolute paths!

Related risks

There are a bunch of variant unsafe behaviors related to inspecting files in your Downloads folder by doing anything interactive with Python. Other risky activities:

Get those scripts and notebooks out of your downloads folder before you run 'em!

But cd Downloads and then doing anything interactive remains a problem too:

Remember that ~/Downloads/ isn't special; it's just one place where unexpected files with attacker-chosen filenames might sneak in. Be on the lookout for other locations where this is true. For example, if you're administering a server where the public can upload files, make extra sure that neither your application nor any administrator who might run python ever does cd public_uploads.

Maybe consider changing the code that handles uploads to mangle file names to put a .uploaded at the end, avoiding the risk of a .py file getting uploaded and executed accidentally.


If you have tools written in Python that you want to use while in your downloads folder, make a habit of preferring typing the path to the script (/path/to/venv/bin/pip) rather than the module (/path/to/venv/bin/python -m pip).

In general, just avoid ever having ~/Downloads as your current working directory, and move any software you want to use to a more appropriate location before launching it.

It's important to understand where Python gets the code that it's going to be executing. Giving someone the ability to execute even one line of arbitrary Python is equivalent to giving them full control over your computer!

Why I wrote this article

When writing a "tips and tricks" article like this about security, it's very easy to imply that I, the author, am very clever for knowing this weird bunch of trivia, and the only way for you, the reader, to stay safe, is to memorize a huge pile of equally esoteric stuff and constantly be thinking about it. Indeed, a previous draft of this post inadvertently did just that. But that's a really terrible idea and not one that I want to have any part in propagating.

So if I'm not trying to say that, then why post about it? I'll explain.

Over many years of using Python, I've infrequently, but regularly, seen users confused about the locations that Python loads code from. One variety of this confusion is when people put their first program that uses Twisted into a file called twisted.py. That shadows the import of the library, breaking everything. Another manifestation of this confusion is a slow trickle of confused security reports where a researcher drops a module into a location where Python is documented to load code from - like the current directory in the scenarios described above - and then load it, thinking that this reflects an exploit because it's executing arbitrary code.

Any confusion like this - even if the system in question is "behaving as intended", and can't readily be changed - is a vulnerability that an attacker can exploit.

System administrators and developers are high-value targets in the world of cybercrime. If you hack a user, you get that user's data; but if you hack an admin or a dev, and you do it right, you could get access to thousands of users whose systems are under the administrator's control or even millions of users who use the developers' software.

Therefore, while "just be more careful all the time" is not a sustainable recipe for safety, to some extent, those of us acting on our users' behalf do have a greater obligation to be more careful. At least, we should be informed about the behavior of our tools. Developer tools, like Python, are inevitably power tools which may require more care and precision than the average application.

Nothing I've described above is a "bug" or an "exploit", exactly; I don't think that the developers of Python or Jupyter have done anything wrong; the system works the way it's designed and the way it's designed makes sense. I personally do not have any great ideas for how things could be changed without removing a ton of power from Python.

One of my favorite safety inventions is the SawStop. Nothing was wrong with the way table saws worked before its invention; they were extremely dangerous tools that performed an important industrial function. A lot of very useful and important things were made with table saws. Yet, it was also true that table saws were responsible for a disproportionate share of wood-shop accidents, and, in particular, lost fingers. Despite plenty of care taken by experienced and safety-conscious carpenters, the SawStop still saves many fingers every year.

So by highlighting this potential danger I also hope to provoke some thinking among some enterprising security engineers out there. What might be the SawStop of arbitrary code execution for interactive interpreters? What invention might be able to prevent some of the scenarios I describe below without significantly diminishing the power of tools like Python?

Stay safe out there, friends.


Thanks very much to Paul Ganssle, Nathaniel J. Smith, Itamar Turner-Trauring and Nelson Elhage for substantial feedback on earlier drafts of this post.

Any errors remain my own.

  1. Restricting which sites can drive-by drop files into your downloads folder is a great security feature, except the main consequence of adding it is that everybody seems to be annoyed by it, not understand it, and want to turn it off.

23 Aug 2020 6:47am GMT

21 Aug 2020

feedPlanet Twisted

Moshe Zadka: Universal Binary

I have written before about my Inbox Zero methodology. This is still what I practice, but there is a lot more that helps me.

The concept behind "Universal Binary" is that the only numbers that make sense asymptotically are zero, one, and infinity. Therefore, in order to prevent things from going off into infinity, there needs to be processes that keep everything to either zero or one.



One TODO List

I have a single list that tracks everything I needed to do. Be it a reminder to put a garbage bin in the car or work on upgrading a dependency in production, everything goes in the same place.

Sometimes this will not be where all the information is. Many of the things I need to do for work, for example, require a link to our internal issue tracking system. For open source tickets, I have a GitHub link.

But the important thing is that I don't go to GitHub or our internal ticketing system to figure out what I need to do. I have a single TODO list

Since I have one TODO list, it gets a lot of things. If my wife asks me to run an errand, it becomes a task. In my one-on-one meeting with my manager, if I make a commitment, it becomes a task. If a conference e-mails me to suggest I participate in the CFP, it becomes a task. The tasks accumulate fast.

Currently, I feel like I'm on top of things and not behind on anything. In this calm, smooth sailing situation, I have around 200 tasks in my list. If every time I opened my list, I would have to look through 200 items to figure out what I am doing, I would get frustrated.

Instead, I have appropriate filters on it. "Today and not related to work" when I am at home relaxing. "Overdue and related to work" when I get to the office in the morning, to see I dropped anything on the floor. "Things that are either not related to work or need to be done at home and due soon" for when I'm at home catching up in the evening.

As I mentioned, I use TODOist. I think it's perfectly reasonable. However, there are a lot of equally reasonable alternatives. What's not reasonable is anything that does not let you tag and filter.

One Calendar

I have gotten all my calendars feeding into a single pane of glass, which color-codes the source. My calendars include:

  • Work calendar (the feeding removes sensitive information)
  • A Trello board with the Calendar power-up for co-ordinating events with my family.
  • TODOist's due date/time calendar.
  • Personal calendar invites.
  • My "Daily schedule", which is where I try to document my plans for each hour I am awake, by day of the week.

I have a daily morning task to review the calendar for the day.

One Time Tracker

I use Toggl. The coolest feature in Toggl is that the Firefox button integration integrates with TODOist and GitHub, so I have a button that says "start working on this". Some of the things I do are not tracked at tasks. As a horrible work-around, I have a Microsoft TO-DO pinned tab. This does not violate the "One TODO list" motto, because these are not tasks I ever plan to accomplish. This are simply things I can activate as a "thing I am doing" with one click: for example, "dinner" or "figuring out next task".

Since as long as I am alive I am doing "something", my time tracker is always supposed to be ticking. I also have a daily task to go over the tracked items and fix spelling and add appropriate metadata so that I have less pressure to do so when I start tasks.

Zero Notes

A note is just some information that has no place. Everything should have a proper place. If I want to take down some information and not sure what is its proper place, then it goes in the TODO list. The action item is "figure out where to put this."

I have a links file, where I put links. I have a recipes GitHub repo, where I put recipes. I have a "Notes" folder in Dropbox, but the only notes that go there are things that I need to be able to see immediately on my phone. This means that every note should have an expiry date, and after that they can be archived.

During the beforetimes, I would have flight information for trips there, and the like. In these times, sadly, this folder is mostly empty until the world is right again.

Zero Unpinned Tabs

Firefox has an amazing feature called "pinned tabs". Pinned tabs are always left-most, and only have their icon showing up. My pinned tabs include my E-mail, my Calendar, WhatsApp, TODOist, and the Microsoft To-Do hack.

Other tabs get closed. Since many of my tasks generate a lot of open tabs, when cross-referencing documentation, this is an easy reminder. Whenever I can't see all tab titles, I close everything unpinned. Anything that I hesitate to close gets converted to a task with the TODOist browser extension and then closed.

Zero E-mails

I have daily tasks to empty out my personal and work inbox. Anything that can't be emptied in the time I allocated to doing that gets converted to a task.

Zero Floating Tasks

Tasks get created in "Inbox" with no "due date". There is a daily task have that list have zero items. Items can be non-floating by being assigned to a project and having one of three things be true:

  • It's marked @when:time_permitting, which is effectively equivalent to "Archived".
  • It's marked @status:subtask, which means it is part of a bigger task where it is managed.
  • It's marked with a specific day I plan to do it ("due date", but it does not actually mean "due date").

(Work in Progress) One Report

I am working on having one report that pulls via API integration from Toggl, TODOist, and FastMail Calendar (CalDav) details for the past week and summarizes them. For example, how many things did I do without a task? Did they make sense? What was my calendar saying I did at the time?

I have a rough prototype, so now it is mostly debugging the logic to make sure I am getting everything I expect and cleaning up the Look And Feel so I can see as much as possible on one screen. I am using Jupyter for that.


For some people, "small amounts of chaos" is a reasonable goal. But for me, it's zero or infinity Funneling everything to one TODO box allows emptying all the others. Funneling everything to one calendar means only checking in one place "what am I supposed to be doing".

21 Aug 2020 4:45am GMT

17 Aug 2020

feedPlanet Twisted

Itamar Turner-Trauring: Find that bug! Using a search engine as a programmer

Most bugs you encounter have been encountered by others before you; most programming problems you face have been faced by others as well. And many of those people have written down details about what they've learned-in issue trackers, documentation, and blog posts.

All you have to do is find this information.

Typing a phrase in to your search engine of choice will sometimes take you straight to the right answer. But quite often, the results aren't helpful.

No need to give up, though: there are still plenty of ways you can productively keep searching.

Use site-specific search too

It's easy to believe that search engines have all the answers right at the top, but they actually hide quite a lot of content deep in their results. And some obscure content never gets indexed at all, which is unfortunate when it's the obscure content that you need to find.

So instead of just using a search engine, use the local search engine of the project issue tracker, the documentation, StackOverflow, and so on.

For example, let's saying you're using Eliot, a somewhat obscure Python logging library I maintain, and you want to use it with the Pandas library. Unfortunately, you get an error, so you search Google for the text of the error: eliot dataframe is not json serializable. Now, there is an actual issue in Eliot's GitHub issue tracker with this exact error message-but as of August 2020 Google doesn't return it, probably because it didn't bother to index that page.

But if you were to use the search form on the Eliot GitHub project's issues page, you would find the issue that mentions this particular error. In this case, as in many others, the search engine isn't actually indexing everything: you have no choice but to use the local search engine.

Local search engines often have the additional benefit of allowing more structured search, for example:

You still want to use a search engine

A software project's documentation and issue tracker are a great place to start searching, but sometimes you'll find solutions elsewhere.

For example, if you have a problem with library A, it might be that project B had the same issue, and you can find a workaround in their issue tracker. Or perhaps someone wrote a handy blog post on the issue-or they might have other related content. And that related content can also be useful.

Read results that don't answer your question

Often you'll encounter results that solve a similar but not identical problem. Read those pages anyway.

First, because you'll learn more about the shape of the problem, broad approaches, and how the underlying software works.

Second, because you might find suggestions of new places to search.

Third, because this will give you an opportunity to apply your close reading skills and learn more domain-specific jargon. You can then use this jargon to widen, narrow, and vary your search.

Note: This article is an excerpt from my book, The Secret Skills of Productive Programmers, which also has a chapter on close reading.

Narrow and widen your search

Let's say you've tried an initial search engine search, and you got a huge swath of unrelated results. For example, if I use Google in private mode to search for eliot, I get many entries about the poet T.S. Eliot.

Given too many results, you need to focus in: add a keyword or two that will help narrow the results to those you care about. In this example, searching for eliot logging find the actual Python library; searching for eliot python also helps.

Again, the jargon you've found along the way will help you know what to add.

If your search is too specific, you can do the opposite, removing some unnecessary keywords.

Try lots of variations by using jargon

Even if your initial searches don't work, you shouldn't give up: now is the time to start using synonyms and alternative phrasings. You are using a certain phrase to describe the problem, but other people might conceptualize it a different way, and use different phrases.

If you can rephrase the search you are likely to find many results you haven't seen before. For example, let's say you're using the Pandas dataframe library for Python and you're running out of memory. If you search for pandas too much memory, pandas out of memory, pandas large files, and pandas out of core will give you some overlapping results, but each returns some results you won't get from other phrases.

The last term comes from "out-of-core computation", a computer science term for algorithms that process data that doesn't fit in memory. How might you learn about that phrase? By collecting jargon as you go along.

Search for errors the right way

When searching for errors, you need to copy/paste enough that you're identifying the specific error, but not too much such that the search engine can't find any matching results. For example:

Traceback (most recent call last):
  File "/home/itamarst/flask/app.py", line 2446, in wsgi_app
    response = self.full_dispatch_request()
  File "/home/itamarst/flask/app.py", line 1951, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/home/itamarst/flask/app.py", line 1820, in handle_user_exception
    reraise(exc_type, exc_value, tb)
  File "/home/itamarst/flask/_compat.py", line 39, in reraise
    raise value
  File "/home/itamarst/flask/app.py", line 1949, in full_dispatch_request
    rv = self.dispatch_request()
  File "/home/itamarst/flask/app.py", line 1935, in dispatch_request
    return self.view_functions[rule.endpoint](**req.view_args)
  File "flask1.py", line 18, in index
    return _counter + "\n"
TypeError: unsupported operand type(s) for +: 'Counter' and 'str'

Different languages will have different formatting, but the basic idea is that the lines that includes directories are specific to your computer. Searching for /home/itamarst is not going to get good results!

Searching for the last line might work:

TypeError: unsupported operand type(s) for +: 'Counter' and 'str'

Or maybe the last two lines, if that line is from code I downloaded and didn't write myself:

    return _counter + "\n"
TypeError: unsupported operand type(s) for +: 'Counter' and 'str'

Or perhaps I want to understand the generic error, rather than this particular instance:

TypeError: unsupported operand type(s) for +:

Or perhaps I think this is a problem in the Flask library rather than my code, in which case I might search for:

flask TypeError: unsupported operand type(s) for +: 'Counter' and 'str'

Typically the important information will be either at the beginning or the end of the error traceback or stacktrace.

(Thanks to Jason Swett for suggesting this technique.)

Finally, be careful

One issue with searching for random solutions on the web is that the proposed solution is sometimes wrong or broken. I've seen people propose insecure solutions on StackOverflow, and then get upvoted by other people who don't know any better.

Just because the solution seems to work doesn't mean it's correct: you still have to think, do some additional research to validate the proposal, and probably write some tests too.

Want more ways to become a more productive programmer? This article is an excerpt from my book, The Secret Skills of Productive Programmers.

Tired of scrambling to get your job done?

If you were productive enough, you could take the afternoon off, confident you'd produced high value work. Not to mention having an easier time finding a new job when you need one.

Learn the secret skills of productive programmers.

17 Aug 2020 4:00am GMT

02 Aug 2020

feedPlanet Twisted

Glyph Lefkowitz: Lenses

I suffer from ADHD.

photo of a man with his head in his hands Photo by Taylor Young on Unsplash

I want to be clear: when I say I suffer from this disorder, I am making a self-diagnosis. I've obliquely referred to suffering from ADHD in previous posts, but rarely at any length. The main reason for my avoidance of the topic is that it still makes me super uncomfortable to write publicly about a "self-diagnosis", since there's a tremendous amount of Internet quackery thanks to amateur diagnosticians.

This despite the fact that I've known for the past 15 years that I have ADHD.

I am absolutely not trying to set myself up as a maverick unlicensed freelance psychiatrist here. If you think you might have ADHD, or any other ailment, whether mental or physical, call your primary care physician. Don't email me.

At the same time, for me, this diagnosis is not really ambiguous or in a gray area. This is me looking down and noticing I've only got one arm, and diagnosing myself as a one-armed person. I've taken numerous ADHD screening questionnaires and reliably scored well into the range of "there is no ambiguity whatsoever, you absolutely have ADHD", so I feel confident to describe myself as having it.

Terminology aside, this post is about a set of cognitive and metacognitive issues that I have, and some tools that I found useful to remedy them. I think others might find those same tools useful in similar situations. So if you're also uncomfortable with the inherently unreliable nature of self-diagnosis, or the clinical specificity of the term "ADHD" - and I absolutely don't blame you if you are - I invite you to read "ADHD" as a shorthand for some character traits that I informally believe fit that label, and not a robust clinical analysis of myself or anyone else.

With that extended disclaimer out of the way, I'll get started on the post itself; and where better to do that than at the start of my own challenges.

The 'Laziness' model

photo of a cat relaxing on a couch Photo by Zosia Korcz on Unsplash

Throughout my childhood, I was labeled an "underachiever". I performed well on tests and didn't do homework. I was frequently told by adults - especially my teachers - that I was "brilliant" but "lazy".

Was I lazy? Is there even such a thing as "laziness"? Here's a spoiler for you - "no"1 - but I didn't know that at the time. All I knew was that I couldn't seem to do certain things - boring things: homework, long division, and cleaning up my room, for a few examples. I couldn't seem to do the things that my peers found routine and trivial.

This is a common enough experience that it shows up clearly even in systematic reviews and meta-analyses of adult sufferers of ADHD. Everybody tells you you're lazy, and so you believe it. It sure looks like laziness from the outside!

In retrospect, that's the interesting problem with this false diagnosis: "from the outside". Assuming for the moment that laziness does in fact exist and is a salient character flaw, what would the experience of the interiority of such laziness actually feel like?

It seems unlikely that it would feel like I what I actually felt at the time:

  1. Frequently, suddenly remembering, in contexts where it wouldn't help - walking to school, in an unrelated class, while walking to work - that I had to Do The Thing.

  2. Anxiously, yearningly, often desperately wishing I could Do The Thing.

  3. Trying to Do The Thing at the responsible time, finding that my mind would wander and I would lose several hours of time... sitting for hours, literally bored to tears, while I attempted and failed to Do The Thing.

  4. At long last, finally managing to start. Once I was truly exhausted and starting to panic, I'd drink a gallon of heavily-caffeinated and very sugary soda at 2 in the morning and finally finally find that I suddenly had the ability to Do The Thing, and white-knuckle my way through an all-nighter to finish The Thing. (This step was more common after I got to my late teens; before that, The Thing just wouldn't get Done.)

Sitting up night after night destroying my mental and physical health, depriving myself of sleep, focusing with every ounce of my will on tasks that I absolutely hated doing but was forcing myself to complete at all costs: it doesn't seem to line up with the popular conception of what "laziness" might be like! Yet, I absolutely believed that I was lazy. If I were not lazy, surely Doing The Thing wouldn't be so difficult!

I took pains at the start of this post to point out that mental health diagnosis is usually best left to professionals. I think that at this point in the story I should emphasize that "I'm lazy" is also itself a self-diagnosis, and - at least in every case where I've ever heard it used - a much worse one than "I have ADHD".

If you are not a licensed psychologist or psychiatrist, any time you decide with certainty that someone (even yourself!) has an intrinsic, persistent character flaw, you're effectively diagnosing them. If you decide that they're inherently lazy, or selfish, or arrogant, you're effectively diagnosing them with a sort of personality disorder of your own invention.

So, although I didn't see it at the time, laziness didn't seem to describe me terribly well. What description fits better?

The 'Attention Deficit' model

photo of a squirrel in a grass field Photo by Tom Bradley on Unsplash

In my late 20s, my Uncle Joel gave me a gift that changed my life: the book "Driven to Distraction: Recognizing and Coping with Attention Deficit Disorder"2 by Edward M. Hallowell. The life-changing aspect of this book was not so much that it showed that there were other people "like me", or that my problem had a name, but that it gave me a different, and more accurately predictive, model to understand my own behavior.

In other words, it allowed me to see - for the first time - that the scarcest resource limiting my efficacy wasn't the will to do the work, but rather the ability to focus. With this enhanced understanding, I could select a more effective strategy for dealing with the problem.

I did select such a strategy! It worked very well - albeit with some caveats. I'll get to those in a moment.

Although my limiting factor was the ability to pay attention, the problem that prevented me from recognizing this was one of metacognition - the way I was thinking about how I think.

My early model of my own mind was that I was a lazy person who just needed to do what I had assumed everyone else must be doing: forcing myself to do the tasks that I was having trouble completing. If I really wanted to get them done, then what possible other reason could there be for me to not do them?

The 'laziness' model didn't generate particularly good predictions. For any given project at school, it would predict that I would not try very hard to do it, since the very dictionary definition of 'lazy' is "unwilling to work or use energy". The observed behavior, by contrast, was constant, panicked, intense (albeit failed, or at least highly inefficient) uses of significant amounts of energy.

The main reason to have a model of a thing is to make predictions about that thing. If the predictions that a model gives you are consistently wrong, then the model isn't directly useful. At that point, it's time to discard it and find a better one. At the very least, it's time to revise the model in question until it starts giving you more accurate, actionable information.

The 'laziness' model is wrong, but worse than that, it's harmful. What it routinely predicts, regardless of context, is that I need more negative self-talk, more 'motivation' in the form of vicious self-criticism, more forcing myself to "just do it". All of these things, particularly when performed habitually, cause real, significant harm.

If I gave myself the most negative self-talk I could muster, the most vicious criticism, and really put Maximum Effort into forcing myself to do the thing I wanted done... if it didn't work, of course that just meant that I needed to engage in even more self-abuse! I could always try harder!

This is the worst way that a model can be inaccurate: an unfalsifiable, self-reinforcing prediction. I could never demonstrate to myself that I'd really been as unkind to myself as was possible; there was always room for escalation. Psychologically, it's also the worst kind of behavioral advice, which is the kind that generates a self-reinforcing negative feedback loop.

Once I started putting my newfound knowledge into practice, the difference between interventions predicated on an understanding of the problem as "lack of usable attention span" and those based on "lack of willpower" was night and day. I stopped trying to white-knuckle my way through all of my challenges and developed non-judgmental ways to remind myself to do things.

I knew that I, personally, was never going to spontaneously remember to do things at the right time, so I developed ways of letting computers remind me. I knew that I'd never be able to stick with routine, repetitive tasks, so I made a unified list of all the tedious administrative tasks I need to perform. I can't keep important dates and times in mind, so I rely completely upon my calendar.

Even given these successes, "it worked!" is a colossal oversimplification. Today, it's about 15 years later, and I'm still sifting through the psychological rubble wrought by the destructive, maladaptive coping mechanisms that I just described, and still trying to find better ways to remain effective when I'm feeling distracted... which is most of the time.

Simply having a better model at the coarsest level is just the first step. Instantiating that model in a working, fleshed out technological system is a ton of work in its own right.3 But it's work that starts having little successes, which is a lot easier to build on and maintain momentum with than the same failure repeated day after day.

Given that I was starting - nearly from scratch - at 25, and had a lifetime worth of bad habits to unlearn, constructing a workable system that addressed my personal organizational needs still took the better part of a decade.

So as I move into the next, slightly more prescriptive section here, I don't want to give anybody the idea that I think this is easy.

Don't give up!

Listen up, Simon. Don't believe in yourself. Believe in me! Believe in the Kamina who believes in you!

Kamina, Episode 1,
Tengen Toppa Gurren Lagann

At the start of this post, I specifically mentioned that I hadn't wanted to write at length about ADHD due to my discomfort with self-diagnosis. So, you might be wondering: what was it that overcame this resistance and prompted me to finally write about my own experiences with ADHD?

The original inspiration was a pattern of complaints about suffering from ADHD I see periodically - mainly on Twitter - that look roughly like this:

These are paraphrased and anonymized on purpose; I really don't want to direct any negative attention towards someone specific, particularly someone just venting about struggles.

Of course, no blog post in mid-2020 would be complete without some reference to the ... situation. The original inspiration for this post predates the dawn of the new hell-world we all now inhabit, but, to say the least, COVID-194 has presented some new challenges to the coping mechanisms I'm writing about here. (Still, I know that I'm considerably better off than the average American in this mess.)

The message I'm trying to get across here is hopeful - others suffering with executive-function deficits similar to mine might be able to do what I did and fix a lot of their problems with this one weird trick! - and the constant drumbeat of despair all around us right now makes that sort of message feel more urgent.

Posts like the ones I described above seem to represent a recurring pattern of despair, and they make me sad. Not because I can't identify with them; I have absolutely had these feelings. Not even because they're wrong, exactly: it really is harder for folks with ADHD to handle some of these situations, and the struggle really is lifelong.

They make me sad because they're expressing a fatalistic perspective; a fixed mindset5 that precludes any hope of future improvement. The through line that I have seen from all of these posts is a familiar, specific kind of despair; a thought I've had myself multiple times:

When somebody that I care about asks me, 'Can you do the dishes later?', I want to say 'yes' and have them believe me. I want to be able to believe myself, and I don't think I will ever be able to.

Unlike myself when I was younger, the authors of these posts already have a name for their problem: ADHD. Sometimes they've even tried some amount of therapy or even medication.

Even so, they're still buying in to the maladaptive strategy of "just try harder". Since they already know that ADHD is, at least in part, a structural brain difference, they despair of ever being able to actually do that though, which leaves "giving up" as the only viable strategy.

Don't give up! I believe in you!

Different problems, different tools

I have had another lifelong problem since when I was young: I am severely nearsighted. Yet, I never developed any psychological hangups around that; nobody ever told me that I needed to buckle down and just squint harder. This problem was socially quite well understood, so… I got glasses. Then I could see, as long as I consistently used those glasses.

Nobody ever expected me to be able to see without glasses.

photo of a pair of eyeglasses resting on a book Photo by NordWood Themes on Unsplash

Calendars, to-do lists, and systems like Getting Things Done are the corrective lenses for the ADHD brain.6.

If a to-do list is a corrective lens for ADHD, one of the major issues around understanding how to use it is that the mass-market literature around to-do lists assumes a certain level of neurotypicality. Assistive devices may frequently be useful to non-disabled people, but their relationship to and use of such affordances is very different.

Through the Looking-Glass ...

Let's stretch this lens metaphor into absurdity.

In our metaphorical world, ADHD is myopia, and so most - or at least many - folks are "sight-typical". Productivity systems are our "lenses".

If nearsightedness were as poorly understood as ADHD, and you were nearsighted, you wouldn't be able to pop on down to Lenscrafters and pick up a pair of spectacles. You might realize that the problem was with your eyes, and think, "lenses might help me see farther". Many kinds of lenses might be commercially available in such a world! Lenses for telescopes, cameras, microscopes...

The way that someone with 20/20 vision might use a lens to see farther is to use a telescope to see something really far away. But you, my hypothetically-nearsighted friend, don't need a powerful zoom lens to take surveillance photographs from a helicopter. Even if you could make such lenses work to correct your vision, you wouldn't want to carry a pair of 2-kilogram DSLR zoom lenses everywhere you go. You want eyeglasses, which are something different.

photo of a picture of a giraffe with DSLR lenses over its eyes Photo by James Bold on Unsplash

The lenses in eyeglasses are - while operating on fundamentally the same principles of optics as the lenses in a telescope or a microscope - constructed and packaged in a completely different way. But most importantly, the way you use them is to wear them every day, not to deploy them on special occasions in the rare event where you need to do something extreme, but all the time, every day, in the same way.

... and What I Found There

photo of a to-do list written in a notebook Photo by Glenn Carstens-Peters on Unsplash

A person with nominal executive function might use the occasional free-floating to-do list to track a big, complex project with a lot of small interrelated tasks. Most folks in the modern information-driven economy routinely need to do projects that are too complex to easily memorize all the required steps. Even doing your own personal taxes has enough steps to require at least a little bit of tracking.

Such a person could make a to-do list for that one project - their telescope, if you will - put it in a place where they'd remember to look at it when they're working on that project, and then remember to check things off when they're done.

They could have one to-do list on the fridge for groceries, a note on their phone for stuff to get for their spouse, and a wiki page outlining some tasks at work. They would probably have enough free-floating executive function to remember which list maps to which project and when each project is relevant, and remember to check each one at the appropriate time.

I spent a lot of time trying to make disconnected to-do lists like this work for me. They never have. Even when I'm feeling particularly productive there is a cycle of list-generation, that goes like this:

  1. When I want to work on the project in question, I can't remember where the to-do list is, but I need to figure out what I need to do again.

  2. So I go and write a new to-do list, spend a bunch of time rewriting the one I'd already written but can't quickly find. Then I do some work on the project, check off a few things, and put the list away.

  3. Later, I'll find both lists, both half checked off, and now I waste a bunch of time trying to figure out which one is the right one.

  4. Repeat this process a few times, and now I have a dozen lists. The lists themselves start generating more work than the actual project, because now I am constantly re-making and finding lists, trying to figure out which one is the most up to date.

This is the simplest case, but the real problem happens at a higher level: one of the biggest problems caused by any executive function deficit like ADHD is the difficulty of task initiation.

The more irrelevant distractions I can see while I'm trying to work out what to do next, the harder that decision becomes. And there's nothing quite so distracting as the detritus of a thousand half-finished to-do lists.

One List To Rule Them All

What I've found works for me is a single, primary to-do list that I can obsessively check in with every minute of every day, which subsumes every other list related to every other project in my life.

I'm hardly the only person to have this insight - if you start engaging with the "productivity" noosphere, reading all the books, listening to the podcasts, this is a recurring theme. You don't just have an 'app' or a 'list', you have to have a System. It has to be reliable; you have to know you're going to keep checking it, or it's worthless for storing your commitments. But unfortunately this is frequently buried under a lot of other technical complexity about the fiddly details of how to set up one system or the other. It's very easy to miss the forest for the trees.

Having ADHD means that I routinely forget what I've decided to do over the course of only a minute or two after I've decided to do it. Just this week, I had to remind myself no fewer than three times to write down "buy more olive oil" because I kept remembering that we were running low when I was in the kitchen and by the time I finished washing my hands to put it into my phone I'd already forgotten why I did that and went back to making dinner.

I need to write everything down. I'm not going to remember five or six, or even two or three places to check for what to do next. I need to have one place to check what comes next, and then build the habit of constantly going back to it, both to add new things and to see what needs to be done.

Technology can help. Technology might even be necessary - it is for me.

But if you're considering trying this out for the first time, be mindful that piles of to-do apps can be just as distracting as piles of paper. The important thing is to clearly, singularly decide on the one place which is the 'root' of your task tracking system.

You can even do this with a pen and paper. Carry the same, single notebook with you everywhere, and make it absolutely clear that it is your primary list, which is where you have to put any references to other lists. Some people have a lot more success with something tactile, to engage all the senses.

For me personally, the high-tech portion of this strategy is indispensable. I use a combination of OmniFocus for things that have to be done and Apple's built-in calendar application for places I have to be at a particular time.7

OmniFocus8 defines the core gameplay loop of my life. Rather than having to cultivate and retain an elaborate series of interlocking habits and rituals to remain functional, I have a single root habit which triggers every other habit.

That habit? Consulting the unified "what should I do next" perspective in OmniFocus. Every time I am even marginally distracted, I check that view again.

Any time I have trouble initiating a task, I start breaking down the top task in that list into smaller and smaller "next physical action". I don't even rely on myself to do this; since I know I'll forget to break things down, I frequently make tasks that look like this:

To reduce distraction, I routinely close down any windows that are not necessary for whatever I'm currently working on. Particularly, I routinely sweep to get rid of browser tabs, asking (as I would with an email) "does this window represent a task I should do?". If yes, it goes in the task system, if no, I close it so it won't distract me further.

To facilitate this clean-up, on every computer that I use, I have a global hot-key set up to turn the thing that I'm looking at - some selected text, an image, an email message, a browser tab, a chat message at work - into a task that I can look at later.

Everything I have to do on a regular basis is in this system as a recurring task; for example:

Yes, even basic personal hygiene is in here. Not because I'll necessarily forget, or that it takes a lot of energy, but I don't want to waste one iota of brainpower I could be devoting to my current task to worrying about whether I might need to do something else later. If I don't see 'brush teeth' in my "what should I do next" view, then I know, with certainty, that I don't need to be thinking about tooth-brushing right now.

The "what should I do next" view is available on all of my computers, on my tablet, on my phone, and it even dominates my watch-face; I check it more often than I check the time:

screenshot of an apple watch face displaying a to-do item saying “write ADHD blog post”

No single feature is a hard requirement of my system; I could get along without any one of them in a pinch. However, the way that they combine to constantly reinforce what the next thing I need to do is in any given context, at any given time, means that I need to expend less energy trying to consciously hang on to all the context.

Limitations and Risks

I don't want to give an overly rosy view of this strategy. Getting a single unified to-do system that works for you is not the same as getting a brain that can remember to do stuff. So here are some caveats:

  1. Implementing and maintaining such a system is never easy. It just takes tasks like 'making sure I renew my passport before I need to travel', 'show up on time for the meeting' and 'buy a gift at least a week before the wedding' from totally impossible to possible to do at least somewhat reliably with a sustainable level of effort. The main thing that I believe is possible for everyone is being able to commit to simple future tasks.
  2. Building enough data about one's own habits and procrastination triggers also takes time, and to make such a system effective, one needs to do that work as well. (A passive time-tracking tool like Screen Time on your phone or RescueTime on your workstation can be quite illuminating - and surprising.)
  3. The initial wave of relief I felt when I started tracking tasks masked a gradual increase in my general anxiety over time. Checking and re-checking the 'what to do next' list can become a bit of an anxious compulsion, a safety behavior that doesn't always help me plan my day. As one builds the habit of routinely checking the list, it's important to avoid developing constant anxiety about the list as the only motivation to do so.
  4. Similarly, it is important to learn to under-commit. Not only does one need to avoid putting an unrealistic amount of stuff into the system, everybody (but especially everybody with ADHD!) needs non-trivial chunks of unstructured, unplanned time, where the system will clearly say 'nothing to do now, just relax'. The "poor self-observation" and "time blindness" symptoms of ADHD ensure that properly estimating things before committing is a constant challenge that never really goes away either.
  5. This strategy definitely won't be sufficient for some folks. ADHD is a spectrum and there's no precise mechanism to calibrate where you are on it. Some folks will respond really well to this strategy, some folks will need medication before it helps to a useful degree.

Finishing up (about finishing up)

If you're suffering from ADHD and despairing that you will never finish a task or be on time to an appointment: you can. It's possible to do it at least pretty reliably. I believe if you commit to one and only one task tracking system, and consistently use it every single day, all the time, you can commit to tasks and get them done.

If you do it consistently enough, it will eventually become muscle memory, and not something you need to consciously remember to do every day.

It's still never going to be easy to Do The Thing, even if your digital brain can perfectly remember what The Thing is right now.

At the very least, it was possible for me to learn to trust myself when I say that I will do something in the future, by designing a system around my own limited attention, and if I can do it, I think you can too.


This was a big one! I'd like to particularly thank my Uncle Joel, without whom this post (and many of my other achievements) would not be possible for the reasons described above, as well as Moshe Zadka, Amber Brown, Tom Most, and Eevee for extensive feedback on previous drafts of this post.

Additionally, I'd like to thank David Reid for introducing me to many of the tools and techniques that I still use every day, and Cory Benfield, Jonathan Lange, and Hynek Schlawack for many illuminating conversations over the years about the specifics and detailed mechanics of the tools whose use I describe in this post.

Any errors, of course, remain my own.

  1. The broader topic of the nature of "character", fundamental attribution error and the extent to which the entire concept of a "character flaw" is a cognitive illusion that arises from the expedient but cruel habit of ignoring the context in which someone is making decisions is more than enough fodder for another post, but here are some good articles covering a newly-emerging psychological consensus that laziness as we understand it doesn't really exist, and that there are always mitigating factors.

  2. Paid link. See disclosures.

  3. It was 54 years from Einstein figuring out the photoelectric effect in 1905 to the first MOSFET in 1959; and another 45 before we got MicroSD cards out of the theory of quantum mechanics.

  4. Hello, future archaeologists! If you're reading this in the far-flung future, as of this writing, shit is just incredibly fucked up right now. Just incredibly, horrifically fucked up.

  5. Growth Mindset is a useful concept, but it definitely has a lot of problems, and has been a particularly pointed casualty of the replication crisis. This is a pretty good post outlining its remaining utility, even in the face of its relatively small remaining effect size.

  6. This is to say nothing of medication, which is also quite useful. More or less necessary, in fact, for some of those suffering from ADHD. One thing I want to be very careful to point out is that in this post I'm talking about my own experiences with ADHD here; without a proper diagnosis, I haven't had the opportunity to try a pharmacological solution, so I can't comment on its efficacy for me. However, there's a school of thought that since some people can resolve some of their ADHD problems with non-medicative interventions, therefore all people should refrain from medication. I want to be as clear as possible that I do not endorse this point of view.

  7. I'm not going to get into what I use for email here, since I've written about that before, and you can just go read that.

  8. Since I know many of my readers are not in the Apple ecosystem, and might be motivated by this post to put some of these ideas into action, there are plenty of cross-platform apps with similar capabilities. You might check out Taskwarrior, Todoist, or Remember The Milk. There's definitely something out there that can work for you!

02 Aug 2020 8:00am GMT

24 Jul 2020

feedPlanet Twisted

Moshe Zadka: The Hardest Logic Puzzle Ever (In Python)

The Labyrinth is a children's movie. The main character is 16 years old, and solving a logic puzzle that will literally decide if she lives or dies. In fiction, characters are faced with realistic challenges: ones they can solve, even if they have to make an effort.

So, it makes sense that the designer of the eponymous labyrinth did not consult logicians Richard Smullyan, George Boolos (no relation to the inventor of boolean algebra), and John McCarthy (yes, the same person who invented Lisp and suggested that a "2-month, 10-(person) study" would make significant headway in the study of Artificial Intelligence). Those three would suggest that the designer use The Hardest Logic Puzzle Ever.

There are persistent rumors of the movie getting a reboot, or perhaps a sequel. Like any good sequel, the protagonists should face newer and bigger challenges. In the interests of helping the screen writers for the sequel/reboot, here is my explanation of the "Hardest Logic Puzzle Ever", together with clear code.

from __future__ import annotations

Do you remember movies from your childhood that just did not age that well? You cringe at some tasteless joke, you say "I can't believe it was acceptable to show this back then"? I think we can agree we want to future-proof the script for a bit.

Using modern-style annotations will make our code much easier to maintain.

import attr

This movie will come out in the 2020s, and we should use 2020-era code to model it. The attrs library is almost always the right solution to implement classes.

import random

The protagonist will face unknown challenges. Randomness is a state of knowledge. From her perspective, the true state of the world is random.

from zope import interface
from typing import Callable, Mapping, Tuple

This is already a hard logic puzzle, no reason to make it harder on ourselves. Clear interface and type hints will make the logic easier to understand.

This is why zope.interface is appropriate for The Hardest Logic Puzzle Ever. We also need the Callable interface, since our protagonist will be asking the Gods questions in the form of functions, and Mapping, since she will eventually need to answer the question "which God is which".

The Tuple type will most be used by the careful protagonist in her internal type hints. This is high stakes code, and she wants to make sure she gets it right.

In the HLPE (Hardest Logic Puzzle Ever), the ones who answer the questions are Gods. Just like in the Marvel Cinematic Universe, they might not be literal "Gods", but clearly powerful aliens. As aliens, they have their own language. The words for "yes" and "no" are "da" and "ja" - but we do not know which is which.

I suggest that this will not be revealed in the script. This is good fodder for endless fan discussions later on Reddit. As such, the best way is to make sure we do not know the answer ourselves: make it a random language!

import enum

class GodWords(enum.Enum):
    ja = "ja"
    da = "da"

def make_god_language() -> Mapping[bool, GodWords]:
    words = list(GodWords)
    ret = {}
    return {True: words.pop(), False: words.pop()}

Shuffling the words for "yes" and "no" means that the .pop() call will get a random one. Now we have the language: it maps an abstract concept (a Python Boolean) to a string.

In the HLPE, there are three Gods, called "A", "B", and "C". They can be asked any question that refers to the Gods.

class GodNames(enum.Enum):
    A = "A"
    B = "B"
    C = "C"

class IGod(interface.Interface):
    def ask(question: Question) -> GodWords:

But what questions is the protagonist allowed to ask? Questions are something the audience-identification protagonist will ask. For this, a Protocol is appropriate. (Also, those are more convenient for describing functions, which we do not want to annotate with explicit implementation declarations.)

from typing_extensions import Protocol

class Question(Protocol):
    def __call__(self, gods: Dict[GodName, IGod]) -> bool:

Because of how annotations work, at this point we need not know what GodName or IGod are.

The simplest of the Gods is the one who speaks always truly (in the God language).

@attr.s(auto_attribs=True, frozen=True)
class TrueGod:
    _gods: Mapping[GodNames, IGod]
    _language: Mapping[bool, GodWords]

    def ask(self, question: Question) -> GodWords:
        return self._language[bool(question(self._gods))]

The next God always lies.

@attr.s(auto_attribs=True, frozen=True)
class FalseGod:
    _gods: Mapping[GodNames, IGod]
    _language: Mapping[bool, GodWords]

    def ask(self, question: Question) -> GodWords:
        return self._language[not bool(question(self._gods))]

But how to implement Random? This is a harder question than it seems.

The original statement just said "whether Random speaks truly or falsely is a completely random matter". What does that mean? If you ask it two questions, can it answer truthfully to one and lie to the other?

Boolos wrote a "clarification": "Whether Random speaks truly or not should be thought of as depending on the flip of a coin hidden in (their) brain: if the coin comes down heads, (they) speaks truly; if tails, falsely." This clarification fails to elucidate much: it does not answer, for example, the question above.

Finally, based on the suggested solution, and assuming that the obvious simpler solutions do not work, Raben and Raben suggested suggested the clear guideline: "Whether Random says ja or da should be thought of as depending on the flip of a coin hidden in his brain: if the coin comes down heads, he says ja; if tails, he says da."

This is the guideline I have chosen to implement here.

@attr.s(auto_attribs=True, frozen=True)
class RandomGod:
    _gods: Mapping[GodNames, IGod]
    _language: Mapping[bool, GodWords]

    def ask(self, question: Question) -> GodWords:
        return self._language[random.choice([True, False])]

So much back and forth discussion, over two millenia, for such simple code.

I'm sure the God-like aliens would have used code to describe the puzzle from the beginning, avoiding the messiness of natural language.

Accessing the God classes themselves would be the height of hubris, but the goal of the protagonist is to answer "which God is which". We will build a special enumeration of the Gods' identities, to be used in the solution.

GodIdentities = enum.Enum('God Identities',
                          {klass.__name__: klass.__name__
                           for klass in [TrueGod, FalseGod, RandomGod]})

With the Gods' personalities implemented, we can write the code that creates a random world that complies with the terms of the puzzle. Three Gods, known as "A", "B", and "C", assigned to the names randomly, and speaking in a randomly generated language.

def make_gods() -> Mapping[GodNames, IGod]:
    language = make_god_language()
    gods = {}
    god_list = [klass(gods=gods, language=language)
                for klass in [TrueGod, FalseGod, RandomGod]]
    for name in GodNames:
        gods[name] = god_list.pop()
    return gods

The code so far corresponds to the first part of the scene: where the protagonist comes to the place of the Gods, learns the local rules, and realizes that she must either solve the puzzle correctly, or fail.

This time she is granted the chance to ask three questions. However, there are many more unknowns: there are 6 possible assignments for the Gods, and two possible meanings for the language. Frankly, I doubt that I would be able to solve the puzzle on my feet, when I am afraid for my life.

But luckily, I have Wikipedia and time, and so I have written up the code to find a solution here.

Part of the solution is to ask a God a question about themselves: "if I asked you SOME QUESTION, would you say ja". While no question asked of Random is useful (the answer is random) for either True or False, this question would result in "ja" the right answer is "yes", and "da* if the right answer is"no". This means that wrapping questions like this means we have to care neither the identity of the God, nor about the details of the God language.

This makes it a useful abstraction!

def if_asked_a_question_would_you_say_ja_is_ja(
        god_name: GodNames,
        gods: Mapping[GodNames, IGod],
        question: Callable[[IGod, Mapping[GodNames, IGod]], bool],
    ) -> bool:
    you = gods[god_name]
    def add_you(gods):
        return question(you, gods)
    return you.ask(lambda gods: you.ask(add_you) == GodWords.ja) == GodWords.ja

This would be a wonderful chance for a flash-"forward" into a hypothetical scene: the movie goes into black-and-white, and the protagonist voice-overs: if "A" is "True", what would happen if I ask them "is 1 equal 1"? What would happen if I ask them "if I asked you, 'is 1 equal 1?', would you answer 'ja? What if"A" is "False"?

def hypothetical():
    language = make_god_language()
    gods = {}
    hypothetical_true_god = TrueGod(gods=gods, language=language)
    hypothetical_false_god = FalseGod(gods=gods, language=language)
    gods[GodNames.A] = hypothetical_true_god
    gods[GodNames.B] = hypothetical_false_god
    for (name, identity) in [(GodNames.A, GodIdentities.TrueGod), (GodNames.B, GodIdentities.FalseGod)]:
        for question in [lambda x,y: 1==1, lambda x, y: 1==0]:
            objective_value = question(None, None)
                f"{identity}, asked {objective_value} question:",
                if_asked_a_question_would_you_say_ja_is_ja(name, gods, question)
del hypothetical
God Identities.TrueGod, asked True question: True
God Identities.TrueGod, asked False question: False
God Identities.FalseGod, asked True question: True
God Identities.FalseGod, asked False question: False

Movie goes back to color. A smile spreads on the protagonist's face. She knows how to solve this.

The next challenge is to find a God that is not Random. If you ask God B about whether A is Random, then if the answer is "ja", then it means either the correct answer is that A is Random or it means B is Random. Either way, C is not Random.

For similar reasons, if B answers "da", then "A" is not Random.

Either way, we have found a non-Random God. Now we know that we can find the truth from them by using the wrapper!

So we ask them whether they're True. Now we ask them about whether "B" is Random.

So we know:

def ask_questions(gods: Mapping[GodNames, IGod]) -> Tuple[GodNames, bool, bool]:
    is_a_random_according_to_b = if_asked_a_question_would_you_say_ja_is_ja(
        lambda you, gods: isinstance(gods[GodNames.A], RandomGod)
    interlocutor = GodNames.C if is_a_random_according_to_b else GodNames.A
    is_interlocutor_true = if_asked_a_question_would_you_say_ja_is_ja(
        lambda you, gods: isinstance(you, TrueGod)
    is_b_random = if_asked_a_question_would_you_say_ja_is_ja(
        lambda you, gods: isinstance(gods[GodNames.B], RandomGod)
    return interlocutor, is_interlocutor_true, is_b_random

Once again, the movie goes into a black and white flash-forward as the protagonist plans her move.

def hypothetical():
    for experiment in range(1, 5):
        print("Experiment", experiment)
        gods = make_gods()
        interlocutor, is_interlocutor_true, is_b_random = ask_questions(gods)
        print(f"I think {interlocutor} is {is_interlocutor_true}God. They're {type(gods[interlocutor]).__name__}.")
        print(f"B is {'' if is_b_random else 'not '}RandomGod. They're {type(gods[GodNames.B]).__name__}.")
del hypothetical
Experiment 1
I think GodNames.C is FalseGod. They're FalseGod.
B is not RandomGod. They're TrueGod.
Experiment 2
I think GodNames.A is FalseGod. They're FalseGod.
B is not RandomGod. They're TrueGod.
Experiment 3
I think GodNames.A is TrueGod. They're TrueGod.
B is RandomGod. They're RandomGod.
Experiment 4
I think GodNames.A is FalseGod. They're FalseGod.
B is not RandomGod. They're TrueGod.

Now that we know the answers, it is time to put them all together. We first record whether the interlocutor is True or False. If B is Random, we mark them as such. If not, we know that neither the interlocutor or B is Random, so the other God must be Random.

Now that we know two Gods' identities, the last name that remains belongs to the last possible identity.

def analyze_answers(interlocutor: GodNames, is_interlocutor_true: bool, is_b_random: bool):
    solution = {}
    solution[interlocutor] = (GodIdentities.TrueGod if is_interlocutor_true
                              else GodIdentities.FalseGod)
    [other_god] = set(GodNames) - set([interlocutor, GodNames.B])
    random_god = GodNames.B if is_b_random else other_god
    solution[random_god] = GodIdentities.RandomGod
    [last_god] = set(GodNames) - set(solution.keys())
    [last_god_value] = set(GodIdentities) - set(solution.values())
    solution[last_god] = last_god_value
    return solution

Putting the questioning and the analysis together is straightforward.

def find_solution(gods: Mapping[GodNames, IGod]) -> Mapping[GodNames, GodIdentities]:
    interlocutor, is_interlocutor_true, is_b_random = ask_questions(gods)
    return analyze_answers(interlocutor, is_interlocutor_true, is_b_random)

Our little checker returns both a description of the situation, as well as whether the solution was correct.

def check_solution() -> Tuple[Mapping[str, str], Mapping[str, str], bool]:
    gods = make_gods()
    solution = find_solution(gods)
    reality = sorted([(name.value, type(god).__name__) for name, god in gods.items()])
    deduced = sorted([(name.value, identity.value) for name, identity in solution.items()])
    return reality, deduced, reality == deduced

The last step is to test our solution multiple times. Again, remember that there are 6 * 2 = 12 possible situations. However, if "B" is Random, we can get two different answers. This means the total number of options for a path is more than 12, but less than 24.

If we run the solution for a 1000 times, the probability that a given path will not be taken is less than (23/24)**1000 * 24. How much is it?

(23/24)**1000 * 24

Good enough!

Now we can see if the script works. We lack Hollywood's professional script doctors, but we do have a powerful Python interpreter.

for i in range(1000):
    reality, deduced, correct = check_solution()
    if not correct:
        raise ValueError("Solution is incorrect", reality, deduced)
    if i % 200 == 0:
        print("Solved correctly for", reality)
Solved correctly for [('A', 'RandomGod'), ('B', 'TrueGod'), ('C', 'FalseGod')]
Solved correctly for [('A', 'RandomGod'), ('B', 'FalseGod'), ('C', 'TrueGod')]
Solved correctly for [('A', 'RandomGod'), ('B', 'TrueGod'), ('C', 'FalseGod')]
Solved correctly for [('A', 'TrueGod'), ('B', 'FalseGod'), ('C', 'RandomGod')]
Solved correctly for [('A', 'TrueGod'), ('B', 'RandomGod'), ('C', 'FalseGod')]

We printed out every 200th situation, to have some nice output!

Python confirms it. Hollywood should buy our script.

Thanks to Glyph Lefkowitz for his feedback on the Labyrinth post, some of which inspired changes in this post. Thanks to Mark Williams for his feedback on an early draft. Any mistakes or issues that remain are my responsibility.

24 Jul 2020 4:00pm GMT

22 Jul 2020

feedPlanet Twisted

Glyph Lefkowitz: I Want A New Duck

Get it?
Quack quack quack quack
Quack quack quack quack

Weird Al Yancovic,
"I Want A New Duck"

Mypy makes most things better

Mypy is a static type checker for Python. If you're not already familiar, you should check it out; it's rapidly becoming a standard for Python projects. All the cool kids are doing it. With Mypy, you get all the benefits of high-level dynamic typing for rapid experimentation, and all the benefits of rigorous type checking to complement your tests and improve reliability.1 The best of both worlds!

Mypy can change how you write Python code. In most cases, this is for the better. For example, I have opined on numerous occasions about how bad None is. But this can significantly change with Mypy. Now, when you return None, you can say -> Optional[str] and rest assured that all your callers will be quickly, statically checked for places where they might encounter an AttributeError on that None, which makes this a more appealing option than risking raising a runtime exception (which Mypy can't check).

But sometimes, things can get worse

But in some cases, as you add type annotations, they can make your code more brittle, especially if you annotate with the most initially obvious types. Which is to say, you define some custom classes, and then say that the parameters to and return values from your functions and methods are simply instances of those classes you just defined.

Most Mypy tutorials give you a bunch of examples with str, int, List[int], maybe an Optional[float] or two, and then leave you to your own devices when it comes to defining your own classes; yet, huge amounts of real-world applications are custom classes.

So if you're new to Mypy, particularly if you're applying it to a large existing codebase, it's quite natural to write a little code like this:

from dataclasses import dataclass
class Duck:
    quiet: bool = False
    def quack(self) -> None:
        print("Quack." if self.quiet else "QUACK!")

and then, later, write some code like this:

def duck_war(aggressor: Duck, defender: Duck) -> None:
    print("The only winning move is not to play.")

In untyped, pre-Mypy python, in addition to being a poignant message about the futility of escalating violence, duck_war is a very flexible function, regardless of where it's defined. It can take anything with a quack() method.

But, while the strictness of the Mypy type-check here brings a level of safety - no None accidentally masquerading as a Duck here - it also adds a level of brittleness. Tests which use carefully-constructed fakes will now fail to type check, because duck_war technically insists upon only precisely instances of Duck and nothing else.

A few sub-optimal answers to this question

So when you want something else that has slightly different behavior - when you want a new Duck2, so to speak - what do you do?

There are a couple of anti-patterns you might arrive at to work around this as you begin your Mypy journey:

  1. add # type: ignore comments to all your tests, or remove their type signatures so they don't get type checked. This solution throws the baby out with the bath water, as it eliminates any safety that any of these callers experience.
  2. add calls to cast(Duck, ...) around any things which you know are "enough like" a Duck for your purposes. This is much more fine-grained and targeted (and can be a great hack for working with libraries who provide type stubs which are too specific) but this also trades off a bit too much safety, since nothing at the point of the cast verifies anything unless you build your own ad-hoc system to do so.
  3. subclassing Duck. This can also be expedient, and not too bad if you have to; Mypy removes some of the sharpest edges from Python inheritance, providing some guard rails around overriding methods, but it remains a bad idea for all the usual reasons.

The good answer: typing.Protocol

Mypy has a feature, typing.Protocol , that provides a straightforward way to describe any object that has a quack() method.

You can do this like so:

from typing import Protocol

class Ducky(Protocol):
    def quack(self) -> None:

Now, with only a small modification to its signature - while leaving the implementation the same - duck_war can now support anything sufficiently duck-like:

def duck_war(aggressor: Ducky, defender: Ducky) -> None:

In addition to making it possible for other code - for example, a unit test - to pass its own implementation of Ducky into duck_war without subclassing or tricking the type checker, this change also improves the safety of duck_war's implementation itself. Previously, when it took a Duck, it would have been equally valid for duck_war to access the .quiet attribute of Duck as it would have been to access .quack, even though .quiet is ostensibly an internal implementation detail.

Now, we could add an underscore prefix to quiet to make it "private", but the type checker will still happily let you access it. So a Protocol allows you to clearly reveal your intention about what types you expect your arguments to be.

Why isn't everything like this?

Unfortunately, typing.Protocol began its life as typing_extensions.Protocol: a custom extended feature of the type system that wasn't present in Mypy initially, and isn't in the standard library until Python 3.8. Built-in types like Iterable and Sequence are type-checked as if they're Protocols by being slightly special within Mypy, but it's not clear to the casual user how this is happening.

However, other types, like io.TextIO, don't quite behave this way, and some early-adopter projects for Mypy have types that are either too strict or too permissive because they predated this.

So I really wanted to write this post to highlight the Protocol style of describing types and encourage folks to use it.

In conclusion

The concept I've described above is not new in the world of type theory.

The way that typing works in Mypy with most types - builtins, custom classes, and abstract base classes - is known as nominal typing. Nominal as in "based on names"; if the object you have directly references the name of the type it's being compared to, by being an instance of it, then it matches.

In other words: if it's named "Duck", it's a duck. There are some advantages to nominal typing3, but this brittleness is not very Pythonic!

In contrast, the type of type-checking accomplished by Protocol is known as structural typing.4 Whether the caller matches a Protocol depends on the structure of your object - in other words, what methods and attributes it has.

In even other-er words - if it .quack()s like a duck, it is a duck.

If you're just starting to use Mypy - particularly if you're building a library that exports types that users are expected to implement - consider using Protocol to describe those types. With Protocol, while you get much-improved safety from type-checking, you don't lose the wonderful flexibility and easy testability that duck typing has always given you in Python.

  1. And the early promise of using those type hints to making your code really fast with mypyc, although it's still a bit too limited and poorly documented to start encouraging it too broadly...

  2. I said the title of the post, in the post! I love it when that happens.

  3. I have another post coming up about using zope.interface with Mypy, which combines the abstract typing of Protocol and the avoidance of traditional inheritance with the heightened safety that prevents accidentally matching similar signatures that are named the same but mean something else.

  4. The official documentation for Protocol in Mypy itself is even titled "Protocols and structural subtyping".

22 Jul 2020 6:43am GMT

20 Jul 2020

feedPlanet Twisted

Hynek Schlawack: Python in GitHub Actions

GitHub's own CI called GitHub Actions has been out of closed beta for a while and offers generous free quotas and a seamless integration with the rest of the site. Let's have a look at how to use it for an open source Python package.

20 Jul 2020 12:00am GMT

13 Jul 2020

feedPlanet Twisted

Moshe Zadka: Hey, Back Off!

The choice in parameters for back-off configuration is important. It can be the difference between a barely noticable blip in service quality and an hours-long site outage. In order to explore the consequences of the choice, I wrote a little fictional ditty about a fictional website.

I hope you enjoy escaping into this fictional reality as much as I enjoyed writing about it.

Your recipe site is different. After all, recipe sites are a dime-a-dozen. With today's modern technology, any kid can put a quick mock-up together with Django, React, and MongoDB to store recipes and retrieve them by various attributes.

In order to make your recipe site stand above the rest, you made sure it uses really cutting edge techniques. From details of the web requests coming in, using sophisiticated language parsing and machine learning algorithm, with just a few words about the user's likes and dislikes, you find the perfect recipe just for them.

HackerNews called it "just a bunch of buzzwords", of course. But once the graphs went up into the right, with 50% month-over-month growth rates, everyone explained that they knew that this one was different. Popularity sky-rocketed, the engineers worked on scaling up the site, and though it was not the world's most sophisticated microservice architecture, it was medium-service architecture, at least.

The web front end would call the machine learning cluster, running on special GPU machines, to get the appropriate keywords by which to look up the recipe. Maybe not a the kind of 50-microservices-architecture that takes three whiteboards to explain, but at least it was easy enough to scale up horizontally. You hired a great Site Reliability Engineer, who built a sophisticated continuous delivery machine. As your machine learning team fine-tuned the model, it would slowly roll out into the cluster, running continous A/B tests that would immediately roll back the change if the model performed worse than before.

The SRE also made sure the web front-end would back off of a malfunctioning machine learning node, as those do sometimes. Instead of immediately reconnecting, it would try reconnecting at intervals starting at 5 milliseconds and increasing by powers of 2: 10ms, 20ms, and so on.


You will never forget what happened next. A new model was rolled out. It looked great. Performed wonderfully. The only problem was that it had a hidden time-bomb. The model had a small overfit that happend to match the sum of the user's ID and the time. This, in itself, is the kind of overfit that happens every day. Unfortunately, if that value exceeded a threshold, it triggered a bug in the machine learning library. When that happened, the node would become flakey, and start dropping random connections. Even worse, for the specific input used in the health checks, it would work: all nodes appeared healthy in the monitoring dashboard, and to the service discovery framework.

A nightmare scenario.

One by one, nodes started dropping off, as users with higher IDs connected and the seconds ticked on mercilessly. The front end started backing off: by 5ms, then 10ms, then 20ms.

The exponential function explodes fast, so of course the backoff (with jitter, as is common practice) had an upper limit. When the Site Reliability Engineer set the upper limit, there was a lot of things on their mind. Decisions are hard to make. Sometimes, one neuron firing makes all the difference. But neurons are small, and electrons are smaller.

When we look at the firing of a neuron, we can no longer imagine the world is as Maxwell and Newton imagined it to be. Quantum effects must be taken into account. As per the obviously correct Many-Worlds interpretation of Quantum Mechanics, the one world had split into two that would never interact again.

In one world, the SRE had set the maximum to 1 second. In the other, to 10 minutes. For a while, these worlds seemed to parallel each other closely: sure, a few bits on in a YAML file were different, but what storm could come from such a small butterfly?

It was not until the disasterous model roll-out that the worlds would diverge wildly. In the world where the limit was set to one second, the front ends were hammering the nodes mercilessly. Rolling back the model would mean that a node would start getting too many connections, and before a few seconds had passed, it would fall back down.

Eventually, in this world, the whole front-end had to be brought down, the model fully rolled back, and only then the front-end brought back up. This was too bad, because the front-end had a bad-but-working model built-in, and some recipes would still be found while the "outage" was happening. Sure, they were not the "wow you read my mind" quality, but they were still decent results.

Bringing down the whole front-end cluster, and bringing it up again, turned the outage from a blip in recipe click-through rates into a three-hour, news-coverage-worthy outage.

In the other world, where the back-off had a maximum of ten minutes, things progressed much more smoothly. As a machine learning node's model was rolled back, it came back up, and machines started connecting to it. The first one to be brought up did go down from connection overload -- but took ten minutes to do so, enough time to ascertain that this solution was correct. A few more nodes were rolled back, and as the connections grew, the roll back flowed through the fleet.

The outage has been managed, and other than a few irate customers posting on Twitter about looking for vegan recipes and getting a "meat lover's delight", the outage mostly went unnoticed.

Back-off is important. Exponential back-off with jitter and a maximum is almost always the right solution. Yes, the exponent matters a little. The initial back off matters a little. But the maximum matters a lot. Set the maximum to "human time frames": a few minutes (1-30) is a good balance.

Even in a big cluster, an extra action every 10 minutes will probably not cause serious downstream repercussions. But even the most entitled customer can be mollified by a support technician for five minutes doing "everything possible to find a solution" while waiting the clock out on the 10 minute back-off clock.

Choose maximums for back-off carefully, or the site you bring down may be your own.

Thanks to Avy Faingezicht for his feedback on an earlier draft. Any mistakes or issues that remain are my reponsibility.

13 Jul 2020 4:00am GMT