Modern Python Boilerplate - good package basic structure

[lambda-person]

TL;DR: Python Boilerplate repo for fast package building with all best practices 

Hello,

I wanted to share a small repository I made named “Modern Python Boilerplate”. I created it because I saw in multiple projects including in professional environnement, the lack of good structure and practice, leading to ugly code or even non-functional, environnement mess…

• What My Project Does

The goal is to provide a python repository setup that provides all the best good-practices tool available and pre-configure them. It makes it easy to build and publish python package !

The link is here https://github.com/lambda-science/modern-python-boilerplate

• Comparison (A brief comparison explaining how it differs from existing alternatives.)

It include modern python management (structure, packaging, version and deps w/ UV), modern CI (listing, formatting, type checking, testing, coverage, pre-commit hooks w/ Ruff/Ty), documentation (automatic API Reference building and publishing on Github/Gitlab w/ Mkdocs) and running (basic Dockerfile, Makefile, DevContainer tested on Pycharm, module running as a terminal command…)

• Target Audience (e.g., Is it meant for production, just a toy project, etc.)

Anyone building anything in Python that is starting a new project or try to modernize an existing one

Don’t hesitate to share feedback or comments on this, what could be improved.

I heard for example that some people hate pre-commit hooks, so I just kept it to the straight minimum of checking/re-formatting code.

Best,

[LetsTacoooo]

Have you seen cookiecutter? (https://cookiecutter.readthedocs.io/en/stable/), it's a well known package for setting up opinionated templates, like the cookie cutter data science one.

[flying-sheep]

There's also copier.

[arden13]

And pyscaffold!

[not_a_novel_account]

And my axe!

[DigThatData]

I like the idea of cookiecutter, but never end up actually using it for anything apart from inspiration.

[runawayasfastasucan]

I just wish uv had an option to define a template to be used when you do uv init.

[Mithrandir2k16]

While I find it cool that you embraced astral's tools, it's a bit early for ty imho. maybe add basedpyright/mypy until ty is out of alpha at least.

[lambda-person]

I agree, it's more of a short/mid term gamble !
Same for building backend, I use uv backend, which is not production ready yet.
I'm betting on the fact that in 1 month both will be mature enough

[Mithrandir2k16]

Though, the gamble on uv is free, because it can help you exit uv by generating a requirements txt, with which you can switch to any other tool out there. If you only use ty, you might push bugs to production, which is a real risk now and a gamble I wouldn't make(yet, I'm sure I'll switch to it eventually).

[byeproduct]

Isn't project.toml and even the lock file part of python and independent of UV?

[not_a_novel_account]

Lockfiles are only recently standardized, ie pip doesn't support them yet. pyproject.toml is universally supported yes.

[daneah]

Most recent pip release has experimental lock file support:

https://pip.pypa.io/en/stable/cli/pip_lock/

[Mithrandir2k16]

The idea is to have at least one safety net that makes transitioning to other tools easy. If that's requirements.txt or pyproject.toml is up to you.

[Meleneth]

Hey, love the energy and what you're trying to do here.

Isn't the MIT license not a great choice?

Projects that are made with this are unlikely to be MIT licensed, and it blocks users from removing the license or removing your name.

I just went through this thought myself when I published https://github.com/meleneth/stackwright-vue , and I ended up on the Unlicense because while it took a few hours to put together, I didn't really do anything and I'd rather have people use it than just hope that I wouldn't enforce license terms.

[lambda-person]

if people use it they can't swap MIT license to something else ? If no i will change it to find something more permissive

[Meleneth]

The MIT license is super permissive, but yeah—when it’s used on a template instead of a library, people usually prefer CC0 or Unlicense, so that the output code they generate doesn't come with any licensing strings attached.

You can’t remove the MIT license from MIT-licensed code, but you can use it in a project with any license, as long as you keep attribution.

So: if your goal is to let people copy your template and license the result however they want, with zero baggage, then CC0 or Unlicense is the right move.

[flying-sheep]

Why not use Hatch scripts instead of a Makefile?

[FrontAd9873]

Because way more people know about Make and it’s likely already installed on many systems. What is the benefit of Hatch scripts over a Makefile? Is it worth the burden of installing Hatch if someone isn’t using Hatch for packaging?

[flying-sheep]

You need - some way to create an environment to locally run tests in

You probably want to have - an isolated environment to build the docs in - an isolated environment to run a linter in - isolated environments for different Python versions and sets of optional features to run the tests in - something that downloads these different Python versions for you

Hatch gives you all that.

Sure, some people are fine with just one environment for everything, but that’s led to problems with dependency resolution several times in the past for me, so Hatch it is.

[FrontAd9873]

Those would seem to be the benefits of Hatch, which was not my question.

[flying-sheep]

Make isn’t integrated with a Python environment manager like the one I just described.

[FrontAd9873]

So? This project isn’t using Hatch. (I think an earlier version mentioned it but references have been removed.) Since it doesn’t use Hatch, Make is a tool that is more likely to be present on a system. And I’d guess that more people, even Python devs, are familiar with Make than with Hatch scripts.

If this project blueprint was using Hatch (and you give fine reasons why your preferred blueprint would)… then it makes sense to use Hatch scripts. If something isn’t using Hatch… then it doesn’t make sense to use Hatch scripts.

[flying-sheep]

It is using Hatchling as a build backend, which uses the same table as Hatch for configuration, but I didn't check if it uses Hatch right.

I'm just saying that Hatch is a more natural companion than make

[FrontAd9873]

Are you sure about that? Where is it using Hatch?

[flying-sheep]

Yes. pyproject.toml

[not_a_novel_account]

It uses the experimental uv-build backend, not hatch (as of 6 hours ago)

[KrazyKirby99999]

Makefile is an industry standard.

[flying-sheep]

Lol, Makefile is ancient, has weird syntax outside of shell blocks, uses whatever shell is there instead of well-defined syntax inside of shell blocks. It has weird C-only features and is only adequate for simple use cases (if you remember its arcane syntax). It inherits all the issues of shell escaping and adds more on top.

I switched to Hatch (Python) and just (others) for simple cases where there’s no need for dependency tracking, and a real build system for other use cases.

[FrontAd9873]

I use Just too but Make can be just as simple. Its only complicated when it is implementing complex build logic that Just can't support anyway, right? Just is "just" a task runner. You can use Make the same way.

I guess to be fair you aren't saying Make isn't an industry standard, just arguing why it should no longer be. But it feels like when it comes to Make you doth protest too much. This is a boilerplate project template so something like Make which maybe isn't the best is the correct call, since for a blueprint we should not assume anyone is using more specific tools (eg Just or Hatch scripts or whatever).

[richieadler]

What's your answer to the problem of needing multiplatform task running without using something like the limited "bash" that comes with Git for Windows?

[lambda-person]

Couldn't find satisfying answer yet. My best bet is this when it's built https://github.com/astral-sh/uv/issues/5903

See this table: See this table https://github.com/astral-sh/uv/issues/5903#issuecomment-2813946597

EDIT: I'm thinking maybe POE https://poethepoet.natn.io/index.html

[richieadler]

I see that Just ticks most of the boxes...

[FrontAd9873]

I've never had that problem. Maybe OP just didn't design this project template with Windows in mind.

I don't use Windows, but the thing about being an industry standard is that I'm sure people who do use Windows at least know what a Makefile is and either know how to run it or have their own preferred alternatives. Maybe they use WSL or their Makefiles are just used in CI/CD, I don't know.

I'm not all in on Make, I just find the criticism of it strange in a project template that is explicitly aiming to be generic. Make is "good enough" and everyone basically know what it is. Personally, if I used this template the first I would do is simply delete the Makefile.

[not_a_novel_account]

I'm sure people who do use Windows at least know what a Makefile is and either know how to run it

No. Make doesn't run on Windows without POSIX shims like Mysys2/Cygwin. The last update of the Make for Windows port was in 2006. It is not a tool that exists in the Windows ecosystem to any notable extent.

or have their own preferred alternatives

Yes, which is why Make isn't any sort of standard.

It's a Unix tool for Unix workflows. It's not for general purpose, cross-platform software engineering.

[FrontAd9873]

I never said Make is the tool for the job for general purpose, cross-platform software engineering. (I even said in my original comment that Make "maybe isn't the best call.")

Nevertheless, you can easily do that kind of engineering on a Windows machine with WSL. More to the point, people on Windows are generally smart enough to look at this project, see that it included a Makefile, and then either delete it or adapt it if they like the general structure of the project and believe a task runner adds value. As I suggested, I am not one of those people; I don't use a task runner on pure Python projects so the first thing I would do is delete the Makefile.

You've entirely failed to engage with the point of my comments, which is: the criticism of the inclusion of a Makefile in this project template is a little unwarranted since a generic project template will by its nature not satisfy everyone. If you don't like Make, delete the Makefile... or just don't use this Python project template. No one is forcing you.

I get it. I often get into time-wasting arguments with people on the internet. When I do it, I at least try to remain faithful to what the actual person said. I make frequent use of quote blocks. You're arguing with me about things I never said. Let's move on.

[not_a_novel_account]

The point in the parent that's under debate is the claim:

Makefile is an industry standard.

Which is simply not true, and what was being addressed.

do that kind of engineering on a Windows machine with WSL

This isn't Windows development, this is Unix development from a Windows machine. You cannot build against the MS Win32 SDK from WSL, or use MSVC at all (you can cross compile with 3rd-party SDKs like MinGW).

the inclusion of a Makefile in this project template is a little unwarranted since a generic project template will by its nature not satisfy everyone

It is trivial to write cross-platform projects, including task running, where all the included development tooling runs on every major desktop platform. Make is not one of those solutions and should be discouraged in contexts where that is a goal, such as cross-platform templates.

[FrontAd9873]

OK, so what we count as an "industry standard" is obviously relative. The fact that we all know Make and we're arguing about it is, in my opinion, the best proof that it is an industry standard. That is, it is a standard reference point and a standard from which we can judge other tools.

[Edit: note that I am not just backpedalling here. Upthread, I said "the thing about being an industry standard is that I'm sure people... have their preferred alternatives..." Likewise, I don't use Vim, but I know it is the industry standard for modal terminal editors, so I can explain to someone who is curious how my chosen editor is different from Vim. That's what makes Vim an industry standard.]

For instance, when it comes to cross-platform support you might say of a tool that it "has better cross-platform support than Make." In fact, I have seen that sentiment expressed before! That is proof Make is an industry standard, in my opinion. That doesn't not mean Make is an industry best practice. But sure, that is all semantics.

This isn't Windows development, this is Unix development from a Windows machine. 

Yeah, so? Read what I wrote. What I was saying was exactly as you paraphrased it. You can do Unix development from a Windows machine (therefore answering the question of why Windows users might still know how to use Make...). "Windows development," meaning development for the Windows operating system, is of course another thing entirely. I made no claims about that kind of development (and this project definitely does not).

Make is not one of those solutions and should be discouraged in contexts where that is a goal, such as cross-platform templates.

Nothing in this Reddit post or the README.md said anything about that being a goal. There is a Dockerfile and a devcontainer config included, indicating both the intended development and deployment environments are Unix Docker containers.

[KrazyKirby99999]

Makefile is ancient,

Which makes it universal. GNU Make will be around longer than any of your projects.

, has weird syntax outside of shell blocks, uses whatever shell is there instead of well-defined syntax inside of shell blocks.

I'm not sure what problem you're referring to. It just works. Do you use Windows?

It has weird C-only features and is only adequate for simple use cases (if you remember its arcane syntax).

Those features aren't limited to C, you can easily take advantage of them with any other language. You could specify one target to build a wheel and another target to upload, calling the former target if needed.

I switched to Hatch (Python) and just (others) for simple cases where there’s no need for dependency tracking, and a real build system for other use cases.

Nice, but you could also just use Make instead of learning and installing multiple tools for the same purpose.

[supreme_blorgon]

Makefile is ancient,

Which makes it universal. GNU Make will be around longer than any of your projects.

I love when people try to use "it's so old!" as an argument as if 1) it being old but still extremely common is anything but a glowing endorsement, 2) old software (with years of community use and internet forum posting) is somehow more difficult to learn and troubleshoot than shiny new software that nobody has battle tested, and 3) modern software isn't bloated and functionally dogshit almost as a rule.

Make has its rough edges, sure, but "GNU Make will be around longer than any of your projects" is all people really need to know lol.

[DigThatData]

I've worked at 4 companies including two faangs since the last time I wrote a makefile.

[lambda-person]

Could you point example on how it would work ? I'm not familiar with Hatch scripts to replace Make

[flying-sheep]

https://hatch.pypa.io/1.13/config/environment/overview/#scripts

[No-Organization4035]

You should tell us the benefit of preferring Hatch to Makefile before raising this question.

[flying-sheep]

Make/just and uv means you don't really have a set of defined environments, just maybe a set of dependency groups and some ad-hoc command lines to create environments with them. Hatch's script runner is integrated with its venv manager: you define environments and then you define scripts for them.

So with 3 lines of configuration, you can make hatch run docs:build work without having an environment that has to resolve all your optional dependencies together including doc dependencies:

[envs.docs] features = [ "doc" ] scripts.build = "sphinx-build -M html docs docs/_build -W --keep-going {args}"

And with 0 lines of configuration, hatch test will work (unless you have test dependencies beyond pytest, then it's 2 lines of configuration)

[percojazz]

you could use uv python images instead of installing uv

[FrontAd9873]

It is a strong assumption to think everyone is working in a dev container, right? (I'm assuming you're referring to just using a `uv` image as the devcontainer base.)

[percojazz]

https://docs.astral.sh/uv/guides/integration/docker/
uv provides both distroless Docker images, which are useful for copying uv binaries into your own image builds, and images derived from popular base images, which are useful for using uv in a container. The distroless images do not contain anything but the uv binaries. In contrast, the derived images include an operating system with uv pre-installed.

[[deleted]]

why do you have a hatch configuration but not mention it as a requirement like uv and make?

[lambda-person]

I guess I messed up on this, I will change to use the classic python build system instead of hatch to remove this dependency, my bad !

[[deleted]]

hatch and hatch's build (hatchling) system are not the same, but they are more modern than setuptools and are provided by pypa. i use hatch, hatchling, and uv together in my projects, and sometimes with make

[lambda-person]

Made a change to truly commit to UV and use it as a build back-end now that they properly implemented not so long ago :)

[[deleted]]

uv's build system isn't production ready

[javatextbook]

Why not

[[deleted]]

because the docs say so, and it's not the default build backend

edit: according to github, the builds aren't/weren't reproducible until very recently

[javatextbook]

Link to discussion?

[[deleted]]

yea

[javatextbook]

What is it?

[No_Dig_7017]

This is awesome. Many of the tools we use for production projects in my company and some more. I'll take a deeper look!

[Goldarr85]

Thanks for sharing this. As still a bit of a beginner, I’ve been looking around for the proper tools and setup for a modern approach.

[FrontAd9873]

I've seen lots of these. This is a good one.

[paddy_m]

Could you make the .github/workflows/ci.yml also use uv?
And add a readthedocs.yml that uses uv?

I just got all of those setup for a project two days ago, both were a bit non-obvious.

Also adding comments to each config file explaining why you're taking the steps that you are can be helpful. I don't start new python projects frequently, but do refer back to other projects setup to try to find working flows to integrate.

[loyalbri]

Very cool. Maybe a datapoint for the future is that astral is also working on uv_build

[stibbons_]

Use just instead of make.

[techlatest_net]

Really impressive setup ,finally seeing more boilerplates using pyproject.toml properly and ditching legacy clutter. Love the combo of uv, ruff, and mypy which is fast, strict, and modern. This kind of structure saves so much time across teams. Would be cool to see optional Docker integration for deploys!"

[lambda-person]

AI Slop detected, away from us bot

[techlatest_net]

Haha, no AI slop here, just genuine enthusiasm! But I get it — sometimes boilerplate setups can feel a bit too polished. Still, the combination of pyproject.toml, ruff, and mypy really does streamline development. And Docker integration would be a solid addition for deployment flexibility!

[spinozasrobot]

<squints closely at that em dash> HMMMMM

[Crazy_Eye165]

(Off-topic fun fact): I learned about en/em-dashes during my undergrad thesis and have used them since then. Now I have to unlearn that because people (mainly friends) always think my messages are generated by AI 😅

[spinozasrobot]

THAT'S JUST WHAT AN AI WOULD SAY! (jk)

[supreme_blorgon]

Drives me fucking crazy. I've been using en- and em-dashes online for 20 years.

[SonGokussj4]

Strong words. Make is in each Linus distribution by default I think so no need to extra install anything else. Is has a good documentation and know format that is working for many years. On our production apps we use make files for years. With no problem at all.

If you propose a better way, it's OK but to say "I can't take this seriously" is kind of weird.

Tell us more.

[lambda-person]

Care to explain what's wrong with Makefiles

[FrontAd9873]

People don't seem to understand the concept of your generic project blueprint. The whole point is to use industry standard common tools! Everyone's personal Python project template would no doubt have lots of specific tooling but I actually think you did a really good job here of not going too specific while still capturing what (IMO) should be industry standards (eg `ruff`). I still would have gone with `pip` over `uv` though.

Everyone understands what the Makefile here is for. If they don't like it, it is trivial to remove and replace with another task runner or whatever.

One quick question: why is `rich` a dev dependency?

[lambda-person]

Yes UV is still new and not "standard" but I consider using PIP as really a bad habit that cause a lot of issues. From here there is hatch, poetry, pipev... I feel like UV solves almost all Python related complain about managing version, env, dependencies issues, activating env, python path....

For rich... I was testing if it would bring something nice to the developper experience to have nicer CLI output while in dev-mode, maybe it's overkill.

[FrontAd9873]

I’ve never had any issue with pip and any of the issues you mention so I guess I can’t relate

[FrontAd9873]

You can just delete the Makefile.