A lightweight Python project starter

If you spin up a lot of small Python projects, code tends to drift. A few quick fixes, a rushed dependency, and before you know it the repo is a tangle. I wanted some guardrails that make the right thing the easy thing without getting in the way.

→ So I assembled a minimal project starter.

It's a tiny, opinionated template built around modern tooling:

pixi for fast, reproducible environments; pre-commit for formatting and linting hygiene; beartype for runtime type checking; pytest for tests; and GitHub Actions to run it all on every PR. The idea is simple: keep iteration fast while preventing the most common messes.

Inside the package_name/ folder you'll find a placeholder structure that makes subtle suggestions as to how you should structure your code:

Define custom types in types.py (it's 2024, let's write typesafe Python!). Put your utility functions in utils.py (don't have random little utility functions all over the place). Put your model code in model.py. Make main functions accessible like package_name.my_module by importing them in __init__.py.

To get started using this, click the green Use this template button in the top right corner of the Github repository, then clone the new repo and run bash scripts/setup.sh. If you accept the (awesome) defaults, handy bash script will do all the boring work, and let you get straight into coding.

There are a few things I really like about this template:

• There is no framework at use. No Cookiecutter, just text files that get altered by bash script (which deletes itself after running).
• It's minimal. If I want to remove or add something, that's easy.
• Logic is a Python package by default. Before I started using this, I would start new projects in a notebook, and at some point I would port logic out of the notebook into a proper Python package. That refactoring step was always a hassle. With this, it's simpler to just have the model logic inside the package folder and then import it into your notebook, from the beginning.
• Reusing this, most of my projects look boringly similar. Which is fantastic because it makes understanding code easier. Better yet, this is now the default structure we use at PyMC Labs, so projects that other folks spin up become easier for everyone to understand too!
• Setup time is near zero. I even made a bash function that uses this to spin up a more minimal project folder which I use for little adhoc experiments.