Buttondown's engineers write about the new features and functionality they're building.

Engineering

, a headless wrapper around ProseMirror that removes much of the busywork and trickiness in building a lovely, feature-rich writing experience.

Tiptap comes with a lot of great extensions out of the box for common bits of functionality like headings, but for the more esoteric stuff they expose a pretty solid Extensions API so you can build out your own blocks. We built out our own extension for 

 a few weeks ago, and have now open-sourced it so any developer trying to add footnotes doesn't have to re-invent the wheel.

 (admittedly, not the most creative name in the world) and you can install it right now:

Or, if you're so interested, play around with it on 

A huge thank you to the Tiptap team for building such a solid, extendible framework! (And if you're interested, check out the rest of our open source packages 

We open-sourced our foot notes editor. Say hello to "tiptap-footnotes"!

Open-sourcing our footnotes editor

Buttondown's contribution to open source software is long overdue; we, like every other piece of software out there, stand on the shoulders of giants.

Many parts of Buttondown do not make sense to open source: they are overfitted, finnicky, or otherwise engineered in a manner that makes them a poor choice of software for community usage and/or stewardship.

But there are many parts which I suspect 

 be useful as open source projects, and I'm excited to announce the first of many such initiatives: the dryly (but descriptively!) named 

 is a way to connect the URLs of your Django application to a Typescript app. That's all it does: you provide a 

 useful to get some of the benefits of strong typing even when you're using Python to power your SPA. It's a small utility, but one that has prevented countless bugs in production — I hope you find it useful.

Open-sourcing our Python-to-Typescript route generator

Announcing django-typescript-routes

 ("og:images") to your emails, which show up on social media sites when you share the link to your archived email.

We recently added a couple pre-filled templates that you can choose, as an alternative to designing your own image and uploading it:

It generates the images directly, instead of the previously ubiquitous method of creating a screenshot using 

. That method was effective, but it takes a lot of infrastructure to run an entire Chrome browser just to take screenshots. Vercel's solution is lightweight and works beautifully with 

 (as expected, given that they made both).

The problem with a constrained environment like images is that a lot of possible edge cases can arise — most of them involving text that's longer than expected or not in the format you expected.

To mitigate this, I built a big page of test case so I could visually confirm that nothing's falling apart. I had a bit of fun with the test cases as well:

I also built a randomized tester, which takes the most common English words and generates a nonsensical newsletter name and subject line. By clicking "randomize" over and over, I could get some additional confidence that the designs were resilient.

(Of course, I'm sure there are edge cases that I didn't catch. If you find a combination of text that looks off, please let me know — 

Now, the templates are piped into Buttondown's share image picker (which comes up when you click "Web archive" in the toolbar at the bottom). We use query string parameters to pass the newsletter's name and subject to render these dynamically.

Since Buttondown simply stores the URL of the share image, this required minimal changes to Buttondown's app. The custom-generated images are now available as an option, if you choose to use them.

We recently added pre-filled templates for your archived emails' share images, using Vercel's @vercel/og and Satori libraries.

How we built made-for-you og:images

Buttondown is a Django app for sending emails, mostly beloved by technical users who like its REST API and Markdown support. Like most other email platforms, it also hosts 

 of sent emails, and these archives process a millions of pageviews every month in traffic.

These archive pages are classical Django detail views: 

 is an example of one. You can see from the URL that the contract is pretty simple: given a username and a slug, return the email. Simple enough!

I noticed that Google Search Console was dinging Buttondown for a slow TTFB: Buttondown's archive pages were averaging around 1.2s, and the guidance is to be below one second. These views are pretty uncomplicated, so I dove in with Django Debug Toolbar (ol' faithful) to see what was happening:

Nine queries! Yikes! DDT is kind enough to provide all of the information you really need: what queries are being run, which ones are repeated, and in what order. Let's dive in, shall we?

This is obvious when you say it out loud: the easiest queries to optimize are the ones that you can straight up remove because they're entirely unnecessary. In this case, I had 

Both of these pull data from Buttondown's mirrored store of Stripe data, and are entirely unnecessary on this page: we don't surface the payment link directly to users on this route, nor do we need information about the author's Stripe account. So we remove them from the serializer that was pulling them in:

class PublicNewsletterSerializer(serializers.ModelSerializer):
-     stripe_account = serializers.SerializerMethodField()
-     stripe_payment_link = serializers.SerializerMethodField()

...

-    def get_stripe_payment_link(self, obj: Newsletter) -> str:
-        if not obj.stripe_payment_link:
-            return ""
-        return obj.stripe_payment_link.data["url"]

-    def get_stripe_account(self, obj: Newsletter) -> str:
-        if not obj.stripe_account:
-            return ""
-        return obj.stripe_account.account_id

...

    class Meta:
        fields = (
            ...
-            "stripe_account",
-            "stripe_payment_link",
            ...
        )

DDT helpfully informs us that some of these queries are 

: we grab the email, newsletter, and account twice. This is because of some janky logic I have in the permissions-checking for a given email: we show a slightly different version of the email depending on who's logged in (a premium subscriber may see different data compared to an unpaid one, for instance, or the author may be able to see posts that aren't published yet.)

Rather than fetching the email twice, then, let's just cache the email the first time it's fetched:

@method_decorator(xframe_options_exempt, name="dispatch")
class EmailView(TemplateView):
    def get_template_names(self) -> List[str]:
-        return determine_template_path(self.request, self.get_object())
+        return determine_template_path(self.request, self.email)

    def get_username(self) -> str:
        if hasattr(self.request, "newsletter_for_subdomain"):
@@ -89,7 +89,8 @@ def get_object(self) -> Optional[Email]:
        email_slug = self.kwargs.get("slug")
        username = self.get_username()

-        return find_email(email_id or email_slug or "", username)
+        self.email = find_email(email_id or email_slug or "", username)
+        return self.email

    def get_context_data(self, **kwargs: Any) -> Dict:
        context = super().get_context_data(**kwargs)

If you look at those top three queries, it sounds fairly obvious what they're doing:

These are all part of the same object, so we can use Django's 

 method to pull in those foreign keys as part of the initial query.

-            return emails.get(**kwargs)
+            return emails.select_related("newsletter__owning_account").get(**kwargs)

And with that one-liner, we're down to 385ms across only 

We're down to just two queries, but one of them is fairly large — 300ms for a simple join on an index seems awfully large, right?

Well, here's a fun bit of esoterica about Buttondown's implementation: 

. They contain a bunch of different cached versions of themselves, like:

and so on, to make sending emails as quick as possible. But — especially for larger emails — these add up in size, and the simple act of serializing them from Postgres to Python is non-trivially slow.

This is compounded by the fact that Django's ORM defaults to the equivalent of a 

 — if you fetch a row, you're getting all of the columns included in that row.

 command which allows us to selectively exclude certain fields that we know we don't need (in this case, it's various versions of the email that are rendered for other views):

- return emails.select_related("newsletter__owning_account").get(**kwargs)
+ return emails.select_related("newsletter__owning_account").defer(
+    "rendered_html_for_email",
+    "rendered_html_for_web",
+    "body",
+ ).get(**kwargs)

We started with a view that took 1050ms across nine queries and we ended up with one that took 300ms across two queries. Pretty excellent for an hour's work and ~thirty lines of code, considering this view gets hit a few million times a month.

It bears repeating that none of the techniques described above are particularly novel. None required extensive tooling beyond 

; exactly zero rocket surgery was performed in the course of this optimization.

And yet! This code stuck around, unoptimized, for quite some time. There is so much performance work out there in so many applications that looks like the above: twenty-dollar bills, sitting there crumpled on the ground, waiting to be picked up.

To wit, there are other things I could probably do to get this endpoint even faster:

And all of those are good ideas for different days — but I'm a sucker for performance work that ends up with 

Here's how we cut the email view's TTFB by 70%

Speeding up a Django view

This is a pretty technical post! If you're not interested in Typescript, feel free to skip this one.

 this fairly common pattern, but there are a bunch of strings in Buttondown that I want to be able to pretty-print in a fallback-friendly way.

UTM campaigns are a great example: 95% of the time this value is 

 can be anything. So you round up the most common keys and throw them in a map that you can reference down the line:

const UTM_CAMPAIGN_TO_LABEL = {
    'facebook': "Facebook",
    'reddit': "Reddit",
    'linkedin': "LinkedIn"
    // ... and so on
};

[
    "facebook",
    "reddit",
    "linkedin",
    "yandex"
].map(campaign => UTM_CAMPAIGN_TO_LABEL[campaign] || campaign)

 what's in your map, and unless the strings you pass in are a strict subset of those keys it's sad.

 the type inference by expanding the key type to string, 

const UTM_CAMPAIGN_TO_LABEL: {[key in string]: string} = {
    'facebook': "Facebook",
    'reddit': "Reddit",
    'linkedin': "LinkedIn"
    // ... and so on
};

[
	"facebook",
	"reddit",
	"linkedin",
	"yandex"
].map(campaign => UTM_CAMPAIGN_TO_LABEL[campaign] || campaign)

This is trivial, and despite its triviality I forget how to do this around 40% of time. My hope is that you, too, may discover this if you google "typescript-friendly label fallbacks" (because what else are you going to call this pattern? I honestly have no idea.)

Here's a quick workaround that keeps Typescript happy.

Typescript-friendly label fallbacks

 about having migrated Buttondown from a number of separate microrepositories to a single monorepo. I've since 

 the migration, and the slight irritation I felt from having to unwind a bunch of technical choices with deployment + continuous integration has faded.

I am here to tell you: if you are running a software business and you aren't at, like, Google-tier scale, just throw it all in a monorepo. I am 

 myself for not having done this to begin with.

 drawbacks of having a monorepo if you are not a Google-tier company:

Conversely, here are a list of things that became an order of magnitude 

 now that my entire codebase is in a single repository:

You may be reading this short essay and thinking: "Yeah, no shit! Of course you do not need a monorepo when you're talking about, like, 150K lines of code." Congratulations — you are sensible, and well adjusted, and certainly wiser than I was six months ago.

But I know there's a few of you out there who are clinging to 

 — some irrational reason why you have your welterweight project split across four separate repositories.

Maybe it's some abstract sense of purity; maybe it's because you didn't realize most IaaS let you deploy from a subfolder. Whatever the reason is: trust me. Move it into a monorepo. If you do and you end up regretting it, 

 and I'll donate to the charity of your choice.

To wrap up, I will deputize two people who are smarter than I am who have 

In which I tell you that you're overcomplicating things and you should throw everything behind a single git repository.

Just use a monorepo

 to write about annual planning, and how this year is going to differ from previous ones, but I have (in true fashion) procrastinated finalizing my annual plan a little bit. So that'll be next week, and this week I would like to write about... monorepos.

Buttondown is now in a monorepo. There's two big advantages of this approach (and these advantages are not particularly new to Buttondown):

As you can probably tell from the benefits and drawbacks, this is...marginal. It took around five hours to finish everything (less than I expected) and I've probably recouped all of fifteen minutes' worth of effort in doing so. (Which, frankly, isn't a bad calculus if you extrapolate from a week to a year or so.)

But this is the time of year for hastily undertaking such projects! I'm trying to keep the backlog down low, but all of the "this seems nice but when am I going to have the time" type of work happens right now, in that lovely December twilight, where the roadmap doesn't matter and the sales pipeline slows down a bit.

I opine, perhaps for too long, on the idea of monorepos.

On monorepos

This post is a small technical snippet for Python and Django programmers. If you don't know what those proper nouns mean, don't worry — feel free to skip this post.

 since its inception to route backend API urls from the Django backend to the Vue frontend.

This has been (not to damn with faint praise!) better than nothing: some kind of syncing mechanism certainly beats having to manually correlate backend routes with frontend definitions. But there are two nits I've had with the package:

Naturally, I thought to myself: why not try my hand at building a better version? I'm happy to share that it was fairly painless: while I'm still a little bit away from 

 open-sourcing this as a package (there are a number of administrative tasks like registering with PEP and settling on a name that I need to take care of), here is the 

 — 34 lines of Python and 4 lines of templated TypeScript.

I am confident this implementation is missing many, many, many edge cases. It does not handle URL namespacing nor non-string parameters, nor I'm sure many other things. But it is a step change improvement to Buttondown's codebase, and I'm excited to have it. Please let me know if you find it useful, or if you have any feature requests/suggestions — I promise to update this blog post with a link to the repository once it's published to PEP.

Pre-announcing an alternative to django-js-reverse

Generating a Typescript router in Django

I have been a fan of the asynchronous programming library 

 for a long time. It's been a classic "sweet spot" library: more powerful and futureproof than rolling my own solution from scratch, but more aggressively minimalist and ergonomic than something like 

 which has felt the accumulated weight of a decade of bloat and featureq requests.

. Every API request, Stripe event, email sent, or webhook event created (plus around seventeen dozen other things) goes through RQ in order to keep the interface nice and snappy and the concomitant backend requests short and stout.

One of the things that is not so great about RQ is the out-of-the-box observability; it comes with an admin dashboard that does little else than tell you the number of items in each queue, and you're left to build out your own solution from scratch.

 subclass is easy to plop in and replace with the default one that RQ provides. I'm using 

 as the logger mechanism, but that's more of an implementation detail than anything (you can use whatever you want).

class JobWithBetterLogging(Job):
    def perform(self) -> Any:
        start = time.time()
        result = super().perform()
        end = time.time()
        logger.info(
            "job.finished",
            key=self.key,
            seconds=(end - start),
            method=self.func_name,
            data_size=len(self._data),
            queue=self.origin,
            enqueued_at=self.enqueued_at.timestamp() if self.enqueued_at else None,
            started_at=self.started_at.timestamp() if self.started_at else None,
        )
        return result

 of information here: your logs now tell you exactly what keys are being logged, how long each function took, how long they've been sitting in the queue, the 

 of the payload you placed within Redis, and what queue was being used. This, combined with offline log analysis (or a structured query engine like 

) will let you construct dashboards that can trivially answer questions like:

A quick hit nerd post for all you Pythonistas out there.

Better logging in RQ

This is a pretty technical post with absolutely no new information about Buttondown's features! If you're not interested in Django (or don't know what Django is), feel free to skip this one.

, a newsletter tool. It's a pretty nice tool, in my opinion! Please check it out if you get a chance.

This application is around 45,000 lines of Django code [^2], with commits dating back to 2016. It's grown and mutated a lot over the past six years.

I've been meaning to write more about how my approach to structuring and developing Buttondown has changed over the years, and I think a good jumping off point would be the biggest conceptual tool Django offers to organize your code: 

A Django application is a Python package that is specifically intended for use in a Django project. An application may use common Django conventions, such as having models, tests, urls, and views submodules.

Django apps are small libraries designed to represent a single aspect of a project. A Django project is made up of many Django apps. Some of those apps are internal to the project and will never be reused; others are third-party Django packages.

The art of creating and maintaining a good Django app is that it should follow the truncated Unix philosophy according to Douglas McIlroy: ‘Write programs that do one thing and do it well.”’

Apps are essentially a DSL around modules: they provide a level of namespacing and structure around logically disjoint pieces of functionality & business logic.

As far as I can tell, there are two main competing visions for how to use apps in Django:

I think I land somewhere in the middle, but leaning towards the former camp. My heuristic is roughly: 

is this code something that I would want to break out into its own codebase or deploy target at some point?

Here's a top level overview of the apps Buttondown has with some high-level metadata; keep scrolling for more in-depth information.

 with the long-term goal of exposing all important parts of the app's functionality for programmatic access. (The somewhat silly Platonic ideal I strive towards: someone should be able to build out their own Buttondown client just with the API surfaces I provide.)

As such, I carve out that API as its own app. This app doesn't own many models in of itself — except a fairly generic 

 model which tracks incoming requests and outgoing responses — but acts as a superstructure for various primitives owned by 

If I had a magic wand and/or infinite time, this app would probably be shaped a little differently: more like a series of middlewares and decorators that, when applied to 

, could expose those apps to the external API.

This is a nice theoretical exercise, but the ROI on such work feels very low. I know apps are mostly about model separation, but I think "separation of concerns" (mushy of a phrase as that might be ) is particularly valid, and has served me well here.

One of the internal frameworks I really loved at 

 was "checker", which was a very pleasant DSL for declaring programmatic scheduled invariant checks in your code. This is my shamelessly reappropriated version of that framework, and its proven so invaluable I'm surprised that it's not more ubiquitous.

 objects and does a bunch of metaprogramming to email (or page) me whenever a list returns something.

Sometimes I use this for administrative tasks, like manually auditing new accounts who connect Stripe accounts with pre-existing customers & charges:

@register_checker
def no_stripe_accounts_need_auditing() -> Iterable[CheckerFailure]:
    for newsletter in Newsletter.objects.filter(
        paid_subscriptions_status=Newsletter.PaidSubscriptionsStatus.NEEDS_AUDITING
    ):
        if newsletter.stripe_account:
            yield CheckerFailure(
                text=f"Stripe account {newsletter.stripe_account.account_id} needs auditing",
                subtext=f"""
                    Newsletter: {newsletter}
                    Link to Stripe: https://dashboard.stripe.com/connect/accounts/{newsletter.stripe_account.account_id}
                    Admin URL: https://admin.buttondown.com/admin/emails/newsletter/{newsletter.id}/change/
                """,
                data={"newsletter_id": str(newsletter.id)},
            )

Other times, I use it for checking to ensure that no emails are in a problematic state space that necessitate re-driving or SMTP shenanigans:

@register_checker(
    severity=Checker.Severity.HIGH, cadence=Checker.Cadence.EVERY_TEN_MINUTES
)
def no_emails_stuck_in_flight() -> Iterable[CheckerFailure]:
    for email in fetch_relevant_emails():
        text = f"Email {email.id} (from {email.newsletter.username}) is stuck in flight"

        expected_receipts = calculate_expected_receipts(email)
        if not expected_receipts:
            continue

        actual_receipts = EmailDeliveryReceipt.objects.filter(email=email)
        # 'high' is the queue used for asynchronously_send_email_to_recipients.
        queue = django_rq.get_queue("high")
        current_backlog_size = queue.count

        subtext = (
            f"Expected {expected_receipts.count()} receipts "
            f"but only received {actual_receipts.count()}.  "
            f"Current backlog: {current_backlog_size}"
        )
        yield CheckerFailure(
            text=text, subtext=subtext, data={"email_id": str(email.id)}
        )

(I really, really want to open-source this, and probably will at some point this year.)

 app acts as a simple interface that takes strings and returns a 

 object associated with them. That result is compiled from a number of heuristics, from regular expressions to internal data to external services like CleanTalk and Mailgun.

I'm pretty happy with this interface! I originally came to the approach with the concept of one-day deploying this as a stand-alone SaaS, and while my appetite in doing so has largely abated (feels like a lot of boilerplate for a fairly small incremental bump in revenue) it's made the rats' nest of logic well-encapsulated.

 is, as one might guess from the name, the oldest and largest app in the codebase. It contains the three most important models in Buttondown — 

 — plus another 34 to boot. By default, most logic ends up here; it is the sun of Buttondown's little heliocentric universe, as you might have surmised from that summary table above.

 would look like, and haven't come up with any satisfactory answers. The logic here is tightly coupled, and decoupling feels very low-ROI.

Buttondown generates a lot of events from third-party applications. I store data points for every attempted (and successful) email 

 in order to both surface analytics to newsletter authors and to track internal heuristics like particularly spammy authors or slow-to-respond domains. That's not even getting into opt-in functionality like click or open tracking which leads to even more events.

Plus, Buttondown connects to a swath of ESPs (Mailgun, AWS, and Postmark to name a few) which means the interface for events between providers has to be relatively consistent. Enter this app, which stands up a bunch of webhook routes and munges responses into a generic 

 object that contains pointers to other models.

A not so fun fact: I've titled this section 

 — Mailgun was Buttondown's first ESP, so it made sense at the time. Mailgun's now only processing around 5% of Buttondown's email traffic. Let this be a lesson to you all!

For a decently long amount of time, I used 

 to manage flags and switches for Buttondown. I try to avoid phased rollouts in the "1% of traffic, then 10% of traffic, then 25% of traffic" vein except for very fraught situations, but I find these primitives useful in two scenarios:

 and focus on a lighter-weight flags system to reduce my third-party dependency surface area a bit and, more importantly, to reduce the number of database queries I'd need for some particularly chokepoint-y areas like email rendering or address validation.

I'd like to open source this app at some point: it's 

 wave a magic wand, I'd have this app not exist at all: 

 these days is to have your marketing site be in a different codebase entirely, and to have your core application be on 

Unfortunately, I was not conventionally wise in 2016, and at this point it's not so trivial for me, since 

 is where most folks' archives live and I'd need to do some tricky routing shenanigans.

So what do I do instead? I serve the marketing pages in boring ol' Django, and store the code for them in a standalone app so the views and routes are at least in their own little world. There are a couple models here — namely 

 (which powers a little widget in the login page letting folks know about new features) — but data and business logic is thin-to-non-existent here.

, and has quite a bit of dedicated logic to make it play nice: I've got custom extensions for tables, footnotes, highlighting, smart embeds (for things like Instagram and YouTube, whose oembeds are not email-friendly due to their use of iframes), and much more.

This all culminates in a single method meant to be the external 'interface': 

This has been a really nice encapsulation of business logic & function. While I don't see myself open-sourcing or spinning off a dedicated rendering instance or anything like that, it makes it very easy to dive into rendering esoterica and it leads to very maintainable code.

This app is a bit of a misnomer, since it sounds like it might pertain to either managing paid newsletters or managing paying users. It's actually even more simple than that: it's a series of webhooks and models meant explicitly to replicate Stripe's state space in my own database.

This app explicitly doesn't have any business logic; any operations like "mark a subscriber as churned once a 

 is updated" or "create a new subscriber when a new 

, which seemed...a little cumbersome and confusing the two times I tried to onboard to it. Building out my own equivalent probably took more time than it was worth, but I appreciate the gradually revealed complexity and it felt like a particularly important part of the database to treat with care.)

, let alone with a bespoke app. A couple reasons, in descending order of magnitude:

In terms of how I actually model this within Postgres: I try to respect foreign key relationships, and plop the rest of the data in 

class StripeSubscription(BaseStripeModel):
    # Core information.
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    data = models.JSONField(default=dict)

    # Relevant dates.
    creation_date = models.DateTimeField(auto_now_add=True)
    modification_date = models.DateTimeField(auto_now=True)

    # Stripe-side primary key.
    subscription_id = models.CharField(max_length=100, unique=True)

    # Foreign keys.
    customer = models.ForeignKey(
        "StripeCustomer",
        on_delete=models.CASCADE,
        related_name="subscriptions",
    )
    account = models.ForeignKey(
        "StripeAccount",
        on_delete=models.CASCADE,
        related_name="subscriptions",
    )
    plan = models.ForeignKey(
        "StripePlan",
        on_delete=models.CASCADE,
        related_name="subscriptions",
    )

That's the full list! I subscribe to a pattern that I suspect is fairly common amongst codebases of Buttondown's size: one overstuffed, gross "primary" application and a bunch of orbiting, comparatively better-designed ones.

 using apps: they make my brain happy in the same way cleaning up test code makes me happy (which is to say, sometimes the happiness is worth the lack of obvious business value.) That being said, I'd be warier of being over-aggressive with app usage as opposed to being over-conservative; I've lost afternoons to chasing down cross-app migration issues whereas besides some very long 

 lists I can't point to any specific footguns I've stumbled upon from having a Very Big Django App.

Please let me know if you have any questions — I'm 

[^1]: As someone who's lost five hours of their life to shenanigans with cross-app migration squashing, I can certainly sympathize with some of the histrionics of this world-view. [^2]: Well, and a bunch of front-end code, but that's out of scope for this post. Also, my front-end code is much more poorly organized than my back-end code.

I nerd out about structuring a medium-sized Django project

How I organize Buttondown's Django applications

 is an application for writing, sending, and growing newsletters — though that part isn't quite applicable to this essay! The more important part: Buttondown has a Python & Django backend of around 38,000 lines and it's been around for around four years, so it has a good-but-not-excessive amount of cruft and abstractions that I wish I could take back.

. [^1] The longer answer, as provided by the 

Mypy is an optional static type checker for Python that aims to combine the benefits of dynamic (or "duck") typing and static typing. Mypy combines the expressive power and convenience of Python with a powerful type system and compile-time type checking. Mypy type checks standard Python programs; run them using any Python VM with basically no runtime overhead.

I've actually been using something that's, like, 

 was for a long time my Python IDE of choice [^2] and it had really strong support for type hints, meaning that a declaration like:

def count_words(input: str) -> int: return len(input.split())

would be enough to provide PyCharm with information for 

, such that I would get a very angry red squiggle if I tried to write something like:

arbitrary_string = "hello world" if "hello" in count_words(arbitrary_string): print("Greetings found!")

even if you have no plans to integrate with mypy

 I would recommend getting in the habit of using type hints! (Much electronic ink has been spilled about the niceties of writing type signatures as an exercise in thinking more deeply about your interfaces & contracts. I won't rehash those arguments, but rest assured I agree with them.) However, that was the depth of my investment. Back when I did this in ~2019 or so, I looked into actually providing a typecheck 

 for the Python codebase and was stymied by lack of third-party "stub" support. [^3] That was around eighteen months or so ago, and things have improved significantly since then! On a lark, I decided to pick back up the branch (aptly named 

 have progressed significantly, to the point where the majority of issues flagged by mypy were not "hey, I have no idea what 

After some configuration futzing, I was greeted with a veritable 

$ poetry run invoke typecheck utils/functional.py:58: error: Incompatible return value type (got "Dict[Any, Any]", expected "Stream") markdown_rendering/extensions/newtab.py:28: error: "handleMatch" undefined in superclass emails/views/utils.py:99: error: "BulkActionView" has no attribute "model" # ...truncated for concision... api/tests/test_emails.py:31: error: "Client" has no attribute "credentials" api/tests/test_emails.py:34: error: "HttpResponse" has no attribute "data" Found 822 errors in 281 files (checked 887 source files)

 telling me something was amiss. It was time to get to work!

The first stumbling block is perhaps the most stereotypical: dealing with optionals. My code now has a lot of the following pattern:

The journey of 37,000 lines of static types begins with a single annotation.