Skip to content

dev-tools

Betwixt: a data transformation layer design spec

TLDR

Your DB type and your API type are not the same shape. Stop trying to squish them together with awkward hooks, aliases, and non-local mapping functions. Betwixt your models lives a new, delcarative mapping layer.

Pick any non-trivial Python backend. There is a database type (an ORM row, a @dataclass, an attrs class) and there is an API type (a Pydantic model, an msgspec struct, whatever the framework demands). They are not the same shape. They cannot be the same shape: one is constrained by the storage schema, the other by the wire contract. Mapping between them is real work.

Introducing chill-out: ice out supply-chain attacks

chill-hero

TLDR

Every new dependency release is an attack window. chill-out audits your lockfile, blocks anything too fresh to trust, and fixes violations automatically. It works for Python and npm, and takes thirty seconds to wire into CI.

Your lockfile has a freshness problem you might not be thinking about. A new release of any package you depend on, direct or transitive, is a window of time when a supply chain attack could reach your production environment before anyone notices. chill-out closes that window by refusing any locked version that hasn't cleared a configurable cooldown period.

Charm your Pydantic models with Wizdantic

TLDR

Conjure populated Pydantic models from thin air with an interactive terminal wizard.

CLI tools that need structured configuration often end up with a maze of input() calls, hand-rolled validation, and forgotten edge cases. If you already have a Pydantic model describing that configuration, wizdantic turns it into an interactive wizard with a single function call. You define the shape of the data once, and the wizard handles the rest.

Introducing mkdocs-editor-notes: Keep Your Documentation Clean While Tracking TODOs

TLDR

Track TODOs right in your docs without cluttering them. Use footnote syntax, get an auto-generated tracker page.

Writing documentation is hard. Keeping it up-to-date is even harder. When I'm writing, I inevitably encounter sections that need more work:

  • I should add an example here
  • Need to verify this with the team
  • TODO: Update this after the API changes
  • Does this make sense to beginners?

These thoughts are valuable—they represent improvements, questions, and reminders that will make documentation better. But where do you put them?

Makefile magic

TLDR

I have a cool structure, nice convenience functions, and flashy magic that "makes" my projects pretty awesome!

For a fairly long time, now, I've been including a Makefile in all of my projects. It's a nice way to provide access to actions that need to be done over-and-over in a software project. It's familiar (to most folks), works on almost any reasonable dev environment out-of-the box, and makes getting started on the project really straightforward.

Over the years, I've developed a lot of cool stuff that I like to include in my Makefiles. This ranges from some basic patterns and structures that I've found helpful to some fancy "magic" that makes it nice to work with.

make help example

Example of make help with my custom Makefile

Today, I decided to create a GitHub repo to showcase these patterns in a few example Makefile entries. I thought it might be nice to talk through what's offered there and explain some of the deeper magic.