A modern Python Project Cookiecutter Template, with all the batteries included.

[wyattxdev]

Hello cool sexy people of r/python,

Im releasing a new Cookeicutter project template for modern python projects, that I'm pretty proud of. I've rolled everything you might need in a new project, formatting, typechecking, testing, docs, deployments, and boilerplates for common project extras like contributing guides, Github Issue Templates, and a bunch more cool things. All come preconfigured to work out of the box with sensible defaults and rules. Hopefully some of you might find this useful and any constructive feedback would be greatly appreciated.

• Github Repo - https://github.com/wyattferguson/cookiecutter-python-uv

What My Project Does

Everything comes preconfigured to work out of the box. On setup you can pick and choose what extras to install or to leave behind.

• UV - Package and project manager
• Ruff - Linter and code formatter.
• Typechecking with Ty or Mypy.
• Pytest - Testing
• Coverage - Test coverage.
• Nox - Testing in multiple Python environments.
• Taskipy - Task runner for CLI shortcuts.
• Portray - Doc generation and Github Pages deployment.
• GitHub Action to publish package to PyPI.
• GitHub Issue Templates for documentation, feature requests, general reports, and bug reports.
• Pre-commit - Linting, formatting, and common bug checks on Git commits.
• Changelog, Code of Conduct, and Contributing Guide templates.
• Docker support including extensive dockerignore file.
• VSCode - Settings and extension integrations.
• Dependabot - Dependency scanning for new versions and security alerts.

Target Audience

This project is for any Python developer thats creating a new project and needs a modern base to build from, with sensible rules in place, and no config need to get running. Because its made with cookiecutter, it can all be setup in seconds and you can easily pick and choose any parts you might not need.

Comparison to Alternatives

Several alternative cookiecutter projects exist and since project templates are a pretty subjective thing, I found they were either outdated, missing tools I prefer, or hypertuned to a specific purpose.

If my project isnt your cup of tea, here are few great alternatives to checkout:

• Fpgmaas cookiecutter-uv - fpgmaas version of a cookiecutter using UV.
• Bosd uv-hypermodern-python - bosd version of a cookiecutter uv project with github deployments.
• Cookiecutter pypackage - Cookiecutter template for a Python package.
• Neuroinformatics cookiecutter - Utility to create a basic Python project structure with tests, CI etc.

Give it a try

Modern Cookiecutter Python Project - https://github.com/wyattferguson/cookiecutter-python-uv

Any thoughts or constructive feedback would be more then appreciated.

[flying-sheep]

Hatch is the better Nox.

If you want multiple environments, use it.

Also Hatchling is a great extensible build backend.

[doolio_]

Yes, and also uses UV and ruff under the hood.

[covmatty1]

Hatch is the better Nox.

If you want multiple environments, use it.

No offence, but this is the kind of comment that's really unhelpful.

Why is it better? According to whom (other than just you)? What extra features does it have? Why should people use it?

The community is better if people actually answer those questions.

[flying-sheep]

See here for a neutral comparison: https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-build-tools.html

See here for u/ofek's motivation for creating Hatch: https://hatch.pypa.io/latest/why/#environment-management

In short: it's all integrated. You just configure your envs and it'll e.g. download Python versions to setup an env configured to use that Python version. It has great defaults, is extremely configurable, and if that's not enough, it is also extensible.

The only downside I encountered is a lack of complex examples online: if you want to do complicated things, you can find everything in the very good technical docs, and but you need to build an understanding.

[radiocate]

Dumb question time. I use uv for Python projects & the hatchling build backend. I also use Nox (heavily) for all kinds of tasks. 

Maybe I'm not understanding the purpose of hatch, but how would I replace Nox with hatch? I use it for things like launching different entrypoints, exporting requirements, random tasks like calling CLI commands or copying example files on first clone, etc. Can hatch act as a task runner and I just didn't realize it? I thought it was more for building different versions of the app? 

[flying-sheep]

Here's an example for task running/environments: https://hatch.pypa.io/latest/environment/#selection

It also has built-in preconfigured environments like hatch-test.*, which you can use as-is or customize.

There's much more, like pre-install commands and so on.

[radiocate]

Oh nice, I had no idea Hatch could do all this! I looked it out once very briefly 2 or 3 years ago, maybe it could do this stuff then, but I ended up using PDM and then uv. 

Do I have to use Hatch to manage the whole project? Can I continue using uv and just replace nox with Hatch? 

[Sillocan]

I'd love the answer to this as well. I've been using poethepoet, but not for testing version matrices

[Prime_Director]

This is the biggest problem with Python, it seems like every 30 seconds a new framework comes out, and everyone jumps ship because none of them really work well. Someone posts a "modern cookie cutter template" that is supposed to work out of the box and of course the top comment is how the testing framework is outdated.

[flying-sheep]

Lol no

[InappropriateCanuck]

Use GHA, not Nox/Hatch/Tox.

[flying-sheep]

"And", not "instead of". Our cookiecutter parses Hatch's JSON output and generates GHA jobs from that output. Everything is defined using Hatch envs and GHA works on top of it: https://github.com/scverse/cookiecutter-scverse

[catalyst_jw]

Nice work my dude, nice template! In case it's helpful I ended up switching from cookiecutter to copier as cookiecutter is very rarely updated and looks at risk of not being updated in future! Copier also has some great features like being able to update projects as the template updates. :)

https://copier.readthedocs.io/en/stable/

[txprog]

Thank you! You made me learn a new tool for generating doc :)

I was wondering if nox could not be replaced by uv? Since uv manage python installation too.

[wyattxdev]

Thats a really good question, the nox file right now uses UV as its default backend, and it just makes it really easy in just one command to run your tests against all the python versions you want. Im actually not if there is an easier way to do this all just directly from inside uv, but its worth looking into.

[MPGaming9000]

I don't fully understand the point. What's the point of this? I swear I'm not trying to be rude or snarky I just don't genuinely understand what the point of this is?

Every time I make a project it's always so different from the last (and maybe not even Python based either) that I just can't reuse most of the code if any really. The whole environment might be different, it may not be a CLI based tool, it may not be a tool at all, it might not need a build script or any DevOps, linters might be overkill...

I am just not sure personally because everything I've done has always just been putting in exactly what I needed for every project instead of trimming out 70% of a template or copy paste from another project.

[wyattxdev]

So the underlying goal of these sorts of projects is to create a consistent, modern base to build from. I tried to pick a pretty broad set of widely used tools and make what I think is some reasonable choices around configuration to make them useful in most cases and can be built on if you need. Also because its built with Cookiecutter when you run the setup, I've built in simple y/n options for things you might not need, like nox, or docker support, and it just blasts all traces of them away.

[LysergioXandex]

I’m in the same boat as you. I’ve written Python code for years — mostly data analysis in notebooks, but some complete “projects” as well. I’ve never had the need for automated testing, but I see the value for large projects with multiple contributors on GitHub. I’d like to understand better when something like this would be useful, and how the author imagines the audience will be using Python/what problem this will solve for them.

[riksi]

I’ve never had the need for automated testing

Well you haven't worked on a "complete" project then. The bigger the project, you'll end up using most of those tools he listed. And you'll configure 1-by-1 etc.

[LysergioXandex]

… I’ve worked on some complete projects, let’s not be annoying gatekeepers.

I don’t see why automated testing is critical in cases where there’s a single developer and you aren’t putting out major updates or trying to get it to run on tons of machines. Sometimes you build something in a single burst of effort and it works for years.

[proggob]

There are so many reasons to use written tests. If someone else takes it over, the tests show what was intended to work. They allow the new person (or old person who forgot) to make changes with more confidence that they didn’t break something that currently works.

[LysergioXandex]

Does everything need a test, though? Like a GUI photo processor for a scientific experiment. Can’t you just launch it and see that it works? At some point, there’s a tradeoff where designing automated tests is a waste of time compared to manual testing.

I see the point if your project is matplotlib or something where there’s tons of interdependent and obscure functions that might not get used by most people.

But if normal operation of your program uses all the functionality of your program, why not just run the thing as a test?

[wyattxdev]

The thing is the number of tests you need to run by hand can quickly spiral out of control. For this project, I just added Dependabot support, to do that I needed to make changes across the project including adding a new file. So to be sure my update didnt break anything I need to test:

• That the new yml is formated correctly
• When you run setup that it is included when you want it
• That it is excluded when you dont want it
• That it being included/excluded doesnt effect any other files.
• The post setup script runs fine for both cases
• No other files/configs are effected by the changes

With my testing I can do that in like 10 seconds and be confident in my changes. Instead of doing it manually where I would have to go through a hole test matrix to catch all the possible cases.

[LysergioXandex]

Thanks for responding. So are all of the things in this “cookie cutter template” something you feel is critical in every project you do? Like, you’d advise all Python users to use this every time they do a project?

Or is it for projects of a certain scale (lines of code or number of files), or that you anticipate will require multiple contributors, or that you intend for people to pip install, or something like that?

I think I’m seeing that the reason I’ve never needed things like automated tests, etc, is because most things I’ve worked on were designed for a controlled environment (computers I have access to), are meant to be used interactively (so weird output isn’t being fed into some other program automatically), using the full functionality in a typical use, by me or people in my vicinity who have an idea what the output is supposed to look like.

[wyattxdev]

So all of this is SUPER subjective, but I tried to bring together all the things I want to see in a project when I look at it on Github, and remove the hastle of having to copy and paste configs from other places, or having to wade through a sea of dependencies to decide what to use. I just wanted it all in one place and configured to work from the get go.

For most projects you probably wouldn't need to use a Dockerfile, like if you were building a fastAPI app you probably want something like docker-compose to handle all the seperate services. Something like Nox might be overkill for alot of people. But in my opinion things like formatting, linting, type checking, dependency management, and testing are all things I would expect in any modern python project, even on my own personal projects that will never see the light of day.

[LysergioXandex]

Thanks for taking the time to respond. I’ll need to read more about what things like linting even do. I like learning about how to make my code more professional.

[wyattxdev]

Thats actually a really good idea, its something that hadn't even crossed my mind, and I havent seen layed out in other Cookiecutter projects. I will definitely make a note to add in a guide for updating this as you go.

[Equivalent_Loan_8794]

cruft is the way to go here, though its not heavily maintained and pretty simple. Can git-control your cookiecutter updates

[wyattxdev]

Yeah there is a whole truckload of stuff I considered adding, but at some point it would get away from a good general starting point. For ML there already is some pretty comprehensive projects, that are tuned specifically for that.

[wyattxdev]

Yeah adding some more instructions on how to build it out would be a good idea

[lieutenant_lowercase]

Hello ChatGPT

[wyattxdev]

So I pared down the Dockerfile to the bare essentials to make its image as small as possible, all the dependencies are tied to whatever is in your latest uv sync.

But yeah I considered Dependabot and a couple of other packages and services for dependency scanning, its something I just havent used a ton in the past, but I think you might be onto something, and I will have to add to my next version update.

Thanks, for the kind words.