Models exist through time

OK, OK, we all know this, right? This is why we have database migrations, because our models (for me, this roughly means “database-persisted instances of some kind of in-memory object”, but you can interpret it more widely if that’s useful for you) change through time. We didn’t know we needed to track whether a Frobble …

REST-push

Or, what to do about HTTP 202 Sometimes, we write code that takes a while to run. Whether that’s because of a big linear optimization problem (it could take minutes!) or because of external HTTP calls (it could take seconds!), it would increase the latency of our HTTP responses unacceptably, and so we have to …

Writing custom Sphinx themes

I’ve been struggling to write this next piece because I feel like I don’t actually know how to do this. But I’ll write what I do know, and I hope that it helps you! There are two kinds of themes I’ve written for Sphinx: themes for HTML output and themes for PDF output. I understand …

Social media and hospitality

I’m thinking about *hospitality*, and social media. Every social media site I’ve used (and services more broadly, really) encodes certain notions of hospitality. When you post something, you are inviting certain people into your space, based on the site you’re using and who can see it and the ways they can interact with it or …

Building docs for different targets with Sphinx (with bonus Unicode support)

Let’s say you want to build your docs in different formats. I already alluded to html versus dirhtml, but the distinction between those is relatively small; it’s just a matter of directory structure. What if I want to build my docs as PDFs or ePubs or something else? Well, Sphinx can do it. By default, …

Fun times with unittest.mock

In foo.py: In test_foo.py (running under pytest, with pytest-mock): It took me a tick to realize that the function definition was being evaluated at import time, including the values for the kwargs. Even though the body, of course, wasn’t being evaluated. I solved it with this change to foo.py: This is related to the thing …

Getting your docs on Read the Docs

You’ve seen it before: software projects with lucid and lovely documentation, all available on subdomain.readthedocs.org. So, how do? Well, the good folks at Read the Docs have made your life very easy. Assuming your documentation’s reStructuredText source is kept in git, and you are OK with pushing it to GitHub, you can get Read the …

Let’s talk about Sphinx

I’ve fielded a few questions lately from folks about Sphinx, reStructuredText, and documentation in the Python world and more broadly. So I thought I’d write up a bit of an intro to how I use and understand these tools, and how better documentation makes me a better developer. Restructured understanding of reStructuredText There’s a lot …

Craft and writing prose

Prose is important; even if you’re writing for no one else, you’re writing for yourself in the future. The best developers I know write a lot of prose, both documentation and commit messages and comments. The value is not immediately visible, it won’t make your tests pass, but it actually is part of keeping technical …