My Python starter kit

When I start a Python experiment, I want the same baseline I get in TypeScript:

  • predictable environments
  • fast feedback loops
  • formatting and linting that I never think about
  • type checking that catches the obvious mistakes early
  • a repo shape that makes editors behave

Python can do all of that. It just doesn’t show up by default.

So I made a starter kit I can clone and get straight to the interesting part.

Github repo

What this repo optimises for

This is for “I’m exploring something” work:

  • quick spikes that might die
  • notebooks that turn into scripts
  • scripts that turn into little packages
  • experiments where you want to keep standards without adding friction

If the project survives, it should already be structured enough to ship.

The core choices

uv gives me a TS-like mental model:

  • create the environment
  • add deps with uv add
  • lock it
  • run stuff consistently

It’s fast enough that you stop negotiating with yourself.

Ruff as the single source of truth

One tool that:

  • lints
  • formats
  • keeps the codebase from drifting into “every file has a different vibe”

The aim is not perfection. The aim is consistency without effort.

Type checking that actually runs

I want type checking as part of the normal workflow, not a thing that lives in CI and nobody trusts.

When you’re iterating quickly, “fail fast” is a feature.

A minimal but real test setup

Even if you only write a few tests, having the harness ready matters.

Most experiments fail because they get messy, not because the idea was wrong.

What’s deliberately not included

This is not trying to be clever:

  • no huge framework scaffolding
  • no forced architecture
  • no “best practices” sermon
  • no pretending every repo is a production service

The mental model

This repo is meant to behave like a good TypeScript project:

  • you get guardrails by default
  • you don’t waste time choosing tools
  • the editor understands the project immediately
  • the code stays readable as it grows

Think of it as: “start messy, but don’t start sloppy”.

How I use it

  • clone with degit
  • setup a venv and sync uv venv .venv && uv sync
  • uv add whatever I need
  • write code immediately

That’s it.