From futons to functions: further reading

Presented at: PyCon AU 2021 (online), Kiwi PyCon 2022 (Ōtautahi Christchurch, Aotearoa New Zealand)

This talk was written on the land of the Wurundjeri people of the Kulin Nation, and the land of the Kaurna people. Aboriginal sovereignty over these lands was never ceded.

This talk is structured around industrial designer Dieter Rams’ Ten principles for good design, which you can read on Vitsœ’s website. It is an improved, but also abridged, version of my talk Dieter RAMs: the ten principles of good API design, which I presented at Linux.conf.au in January 2021.

If you’d like to say hi, you can reach me on Twitter, the Fediverse or via email.

Protocols and evolution

• Graydon Hoare describes Rust’s relationship to its research language predecessors in the slide deck in which he first introduced Rust to the world at the Mozilla Annual Summit, July 2010.
• Rust documentarian Steve Klabnik talks about Rust’s origin and goals in Rust is more than safety. Graydon Hoare’s response Rust is mostly safety, Dave Herman’s response Safety is Rust’s fire flower, and Steve’s follow-up Fire Mario, not fire flowers are also worth a read.
• For more reading about Rust, Yehuda Katz explores one particular Rust feature and compares it to its contemporaries in Rust means never having to close a socket.
• The “deeply disturbing jokes” I mention are a reference to a “joke” told by Richard M. Stallman in his public speaking work for years. Of particular note is the unsettling experience one fifteen-year-old audience member had at one such talk, as well as the fact that this forms a pattern of behaviour coming from this figurehead of the free software movement. Note that the linked content contains references to sexual harassment, institutional sexual abuse, sexual coercion, rape, pedophilia.

Learnability

• Daniele Procida’s 2017 PyCon AU talk, What nobody tells you about documentation, is an excellent resource on the topic of writing API documentation. He expands on the concepts in that talk in Diátaxis, a systematic framework for documentation.
• Sydney’s Powerhouse Museum has an exhibition called Interface: people, machines, design, which features all of the objects I discuss in this section.
• Christopher Neugebauer’s 2019 PyCon AU talk, Fantastic blocks and where to hide them, discusses Pythonic language design, and the language features that have been introduced instead of Ruby-style anonymous code blocks. (He also does some awful things with decorators.)

Containing complexity

• The API of the Wagtail CMS is an excellent example of using a “Lego block” style API to contain complexity.
• Wagtail’s StreamField was a truly exciting feature when it was first released. Part of that was the data model and the editing experience that enabled, but if you have a read of the documentation for StreamField’s API, the way it provides multiple, pluggable components that you can mix and match, and building blocks for your own custom components helped as well.
• In my own work, the Lorikeet e-commerce framework is heavily inspired by Wagtail’s API design, and attempts to implement a similar “Lego block” style API. (I regret that neither I, nor the workplace at which I created Lorikeet, are actively maintaining it at present.)
• Andrew Godwin discusses some of the challenges that the Django ORM presented in an asyncio world in his 2020 PyConline AU talk Taking Django’s ORM async. Interestingly, he also discusses some of the API design principles that make Django what it is, including something very similar to the “Lego bricks” model.
• SQLAlchemy sort of provides a solution for the N+1 problem: relationships can be defined with lazy='raise' or queried with raiseload(), which raises an error in situations where SQLAlchemy would otherwise issue an extra query. There doesn’t appear to be a setting to make this the default for all relationships, though.
• André Roberge’s PyCon AU 2021 talk on Python runtime errors, It doesn’t work!, hasn’t been uploaded yet but will hopefully be soon.
• If you’re building a CLI tool and you want to produce error messages that have cross-references to documentation on the Web, the formatting library Rich can produce clickable links, by outputting control codes that some newer terminal emulators support.

In conclusion

• If you’d like to know more about the impact software development has on the environment, Merrin Macleod’s 2019 PyCon AU talk Environment Variables is a must watch.
• Contempt culture is a term coined in Aurynn Shaw’s 2015 article of the same name, and expanded upon in her multiple talks on the topic at PyCon AU and other conferences.
• Thank you to Lilly Ryan and Benno Rice, whose assistance in putting together this talk (or earlier versions thereof) was invaluable.