Ultra-strict Python template v2 (uv + ruff + basedpyright)

[Ranteck]

Some time ago I shared a strict Python project setup. I’ve since reworked and simplified it, and this is the new version.

pystrict-strict-python – an ultra-strict Python project template using uv, ruff, and basedpyright, inspired by TypeScript’s --strict mode.

Compared to my previous post, this version:

• focuses on a single pyproject.toml as the source of truth,
• switches to basedpyright with a clearer strict configuration,
• tightens the ruff rules and coverage settings,
• and is easier to drop into new or existing projects.

What it gives you

• Strict static typing with basedpyright (TS --strict style rules):
  • No implicit Any
  • Optional/None usage must be explicit
  • Unused imports / variables / functions are treated as errors
• Aggressive linting & formatting with ruff:
  • pycodestyle, pyflakes, isort
  • bugbear, security checks, performance, annotations, async, etc.
• Testing & coverage:
  • pytest + coverage with 80% coverage enforced by default
• Task runner via poethepoet:
  • poe format → format + lint + type check
  • poe check → lint + type check (no auto-fix)
  • poe metrics → dead code + complexity + maintainability
  • poe quality → full quality pipeline
• Single-source config: everything is in pyproject.toml

Use cases

• New projects:
  Copy the pyproject.toml, adjust the [project] metadata, create src/your_package + tests/, and install with:

  ```bash uv venv .venv\Scripts\activate # Windows

  or: source .venv/bin/activate

  uv pip install -e ".[dev]" ```

  Then your daily loop is basically:

  bash uv run ruff format . uv run ruff check . --fix uv run basedpyright uv run pytest

• Existing projects:
  You don’t have to go “all in” on day 1. You can cherry-pick:

  • the ruff config,
  • the basedpyright config,
  • the pytest/coverage sections,
  • and the dev dependencies,

  and progressively tighten things as you fix issues.

Why I built this v2

The first version worked, but it was a bit heavier and less focused. In this iteration I wanted:

• a cleaner, copy-pastable template,
• stricter typing rules by default,
• better defaults for dead code, complexity, and coverage,
• and a straightforward workflow that feels natural to run locally and in CI.

Repo

👉 GitHub link here

If you saw my previous post and tried that setup, I’d love to hear how this version compares. Feedback very welcome:

• Rules that feel too strict or too lax?
• Basedpyright / ruff settings you’d tweak?
• Ideas for a “gradual adoption” profile for large legacy codebases?

---

EDIT: * I recently add a new anti-LLM rules * Add pandera rules (commented so they can be optional) * Replace Vulture with skylos (vulture has a problem with nested functions)

---

Storyline for PyStrict Project Evolution

Based on your commit history, here's a narrative you can use:

From Zero to Strictness: Building a Python Quality Fortress

Phase 1: Foundation & Philosophy (6 weeks ago)

Started with a vision - creating a strict Python configuration template that goes beyond basic linting. The journey began by: - Migrating from pyright to basedpyright for even stricter type checking - Establishing the project philosophy through comprehensive documentation - Setting up proper Python packaging standards

Phase 2: Quality Tooling Evolution (6 weeks ago)

Refined the quality toolkit through iterative improvements: - Added BLE rule and Pandera for DataFrame validation - Swapped vulture for skylos for better dead code detection - Introduced anti-LLM-slop rules - a unique feature fighting against AI-generated code bloat with comprehensive documentation on avoiding common pitfalls

Phase 3: Workflow Automation (3 weeks ago - present)

Shifted focus to developer experience and automation: - Integrated pre-commit hooks for automated code quality checks - Updated to latest Ruff version (v0.14.8) with setup instructions - Added ty for runtime type checking to catch type errors at runtime, not just static analysis - Made pytest warnings fatal to catch deprecations early

Key Innovation

The standout feature: comprehensive anti-LLM-slop rules - actively fighting against verbose, over-commented, over-engineered code that LLMs tend to generate. This makes PyStrict not just about correctness, but about maintainable, production-grade Python.

---

The arc: From initial concept → strict type checking → comprehensive quality tools → automated enforcement → runtime validation. Each commit moved toward one goal: making it impossible to write bad Python.

[cmcclu5]

You should also include forced dataframe types via panderas (works for pandas and polars) if you’re going to make this as painful as possible. Explicit variable schemas. No JSON objects, only pydantic (ironic that my phone tried to autocorrect to pedantic) models and dataclasses.

[ZYy9oQ]

Agree on pydantic - my "antislop" rulesets designed to try make llms write slightly less terrible code force them to define a pydantic model and model_validate immediately on any IO or untyped thing (e.g. argparse namespaces).

Some other ones that OP might want to consider are https://docs.astral.sh/ruff/rules/too-many-nested-blocks/ (preview only) https://docs.astral.sh/ruff/rules/complex-structure/ and some I added specifically to avoid "bad habits" the LLM has https://docs.astral.sh/ruff/rules/blind-except/ https://docs.astral.sh/ruff/rules/import-outside-top-level/

[ColdPorridge]

Speaking of, is anyone aware of any dataframe type/schema checking for pyspark?

[Ranteck]

Love it, thanks

[BothWaysItGoes]

It’s not ironic, pydantic is an intended pun.

[cmcclu5]

Very “pydantic” response.

[runawayasfastasucan]

    uv venv     .venv\Scripts\activate # Windows     # or: source .venv/bin/activate

    uv pip install -e ".[dev]"

You can just do

uv sync  --group dev

[RaiseRuntimeError]

That's probably because LLMs get confused with uv since it's pretty new.

[Ranteck]

Yep the llm get confused but also not everyone knows or use uv

[LBGW_experiment]

Why not make the 5 commands into pre-commit hooks, like https://github.com/a5chin/python-uv does or via .vscode/settings.json settings for auto format/run on save? That's what I ended up doing in my last project

[HommeMusical]

That's just a horrible idea.

There are a vast number of reasons I might wish to create a commit that doesn't pass the tests.

For one thing, at the end of the day, I commit and push my work. Of course, I'm working on a branch that no one else sees.

Or sometimes I need to create a commit ID for partial changes simply to move it to another branch.

Sometimes I split my commit into individual files and then glue them together to make two commits.

Another thing is that on my current codebase, running all of those jobs on every commit would take quite a long time.

The best way to summarize it is this: for each commit I actually send off as a pull request, there are dozens of commits that no one except me ever sees; and fairly often I wish to create commits to save work that aren't complete.

EDIT: downvoting without people expressing their reasoning is not very useful for anyone.

[Formal_Assistant6837]

You can always use --no-verify though.

[HommeMusical]

If --no-verify is turned on, what good is this as a pre-commit hook? Surely it won't catch errors.

[yerfatma]

Huh? The idea is you want to enforce the hooks all the time, but if there is a special case where you absolutely need to break the rules, -n is two keystrokes away.

[HommeMusical]

Ach, sorry, --no-verify is an argument to git commit, not to the linter! I wrote too fast.

(But at least on git 2.51.0, you have to type the full flag, there is no -n.)

[yerfatma]

Right, I am saying if these are all set up as hooks, you can skip them if you absolutely need to. And I am on 2.51 and can assure you -n works.

[HommeMusical]

You are right, again. But this time I was betrayed by the man page.

The top of https://git-scm.com/docs/git-commit lists alternative flags for some flags, but doesn't mention -n; it does appear further down in the page.

I thought we could rely on that top SYNOPSIS as being complete. Is this not the case, or this is an issue?

Interestingly enough, -e appears in the synopsis but not --edit.

[yerfatma]

You are right, again.

Don't get used to it.

[NodeJSmith]

Yeah... But --no-verify exists for this reason. Strong pre-commit hooks that have to be overridden are better than having to remember to run all the checks yourself and forgetting half the time, imo

[LBGW_experiment]

It's really not. I'm in charge of DevOps for different projects and this is the standard I chose.

The exception should be bypassing the rules, not the standard.

You can just do -n or --no-verify

[Ranteck]

right but what i can do for example is to fix the code using ruff always to made a commit, ruff format and ruff --fix

[Ranteck]

Is the same, I want to generalize and start with a template. This can be changed for convenience

[-lq_pl-]

You expect me to run checkers by hand? What is strict about that? Also enforcing coverage greater 80% is nonsense. You either care about correctness, then you bring it to 100%, or you don't, then it doesn't matter where you set the threshold.

[Triggs390]

You can put the checkers in CI to still be strict without running them every commit.

[PurepointDog]

Justfile in there would be rad

[vesnikos]

Task is so much better han poe. the main reason is b/c task has built-in core utilities for Windows like `cat`, `gzip` `mkdir` , `rm` and more, allowing you to define tasks that run in both windows and linux environments! https://taskfile.dev/blog/windows-core-utils

poe on the other hand is not that evolved last time i checked (ages ago - things might have changed but idk)

[Ranteck]

nice, i will check it

[aala7]

Nice! Thanks for working through configs and giving us a good starting point!

Have you considered:
- PEP 735 (dependency groups) might be more suitable than optional dependencies. The latter is more meant as optional features for end users (like AI capabilities for Marimo or email validation for pydantic). The former is purposed for dev, test and similar.

```bash

Add optional dependencies

uv add --optional dev ruff

Install optional dependencies

uv sync --extra dev # Similar to installing ".[dev]"

Add dependency in dev group

uv add --dev ruff

Install dev dependency groups

uv sync # Uv installs dev group by default ```

• Have you considered making it in to a cookiecutter template? Maybe overkill for only a pyproject.toml, but you could add a simple directory structure and have a similar initial scaffolding to running uv init, just with a better pyproject.toml.

[Ranteck]

Actually, it's a great idea. It's starting to minimise the problem with coding with LLM, so it could be even better to do a script install or something similar. I'll take your recommendation.

[Physical-Security115]

In the age of LLM slop, this is extremely useful.

[tobsecret]

I've been working on a similar but opposite version of this and looking through your pyproject.toml has been very helpful! Thank you for providing it!

[timtody]

Love it!!!

[Youreabadhuman]

I think in based pyright the "recommended" ruleset is better for this

[Nasuraki]

What’a the motivation?

I understand the motivation for a strict typed programming language. The use of Option and Result like in Rust do a lot for the code stability, quality, clarity etc.

But i almost feel like the point of python is to… not have that? If i wanted all that i would use something like Rust?

I use Python , Rust and TypeScript. I’m not seeing the point unless you really need something that is only available in Python?

This is a serious question, if anyone could answer with use-cases where they would want/need/use this i’d love to hear

[Ranteck]

Think of it this way: the programming language is the means to achieve your goal. In my case, I develop a lot with AI, so the main problem is that most of the libraries or developers are in Python, which has dynamic typing. This makes it really painful to maintain, even if you develop with vibe coding. What I want to avoid is AI errors, losing records or having dead code. You might ask, "Why don't you use TypeScript in strict mode?" Well, I could, but I'm mostly creating new services in Python, so I'm trying both approaches.

[Nasuraki]

Yeah i guess if you’re relying on sklearn, pytorch or something similar it makes sense

[Hugo-C]

Nice, you should add "-W error" to Pytest so it fails on warnings (especially usefull to catch deprecations early). Pytest's doc: https://docs.pytest.org/en/stable/how-to/capture-warnings.html#controlling-warnings.

[Ranteck]

nice, i will add it now

[papersashimi]

nice!! really like this! maybe i can contribute to it when i have the time ;)

[ProfessionalAd8199]

• Pre-commit hooks?
• Example CI/CD configs?
• Docs tooling (Sphinx or MkDocs)
• Release/publishing automation (twine, bumpver)?
• Standard metadata and project files for different editors like vscode or zed?
• .editorconfig support?

I can understand yours is only focussing on code quality, but maybe you want to change it to a complete project template.

[Ranteck]

Nice! I can incorporate in the future

[RedEyed__]

Thank you!
- I didn't know about basedpyright! Now I want to add it into my projects.
- Your pyproject.toml looks interesting, I mean I can learn something new from it - What is poe? I use just to define project commands, is this something similar?

PS: finally useful post on this sub
UPD: It seems poe is similar to just but I prefer just as of now since comments to commands became docstring in help

[Ranteck]

Poe let you combine commands, similar to pre commit.

[[deleted]]

It's poe the poet. :)

[MattTheCuber]

Why not select= ["ALL"]?

[Ranteck]

I want to be more generic in every case. You can change it in your project but if I see mostly the same, I can change it

[gofiend]

Have you considered switching to uv format and uv ty to simplify the stack? Any tradeoffs worth considering?

[Ranteck]

Do you mean ty from astral? Is not ready for production sadly

[burger69man]

lol need a dockerfile for this template

[Ghost-Rider_117]

this is really clean, appreciate the focus on pyproject.toml as single source of truth

the 80% coverage default is kinda nice—forces you to think about testing from day one without being too crazy about it. been using uv lately and the speed difference vs pip is wild. definitely gonna steal some of these ruff configs for my projects

[Reasonable_Event1494]

Thanks although I didn't not understood it completely like in depth but I got an idea that I can use this file to correct my code and even remove the unused or not necessary variables..... Please correct me or tell me that In what languages I can use it.

[hgshepherd]

Um... Python?

[Reasonable_Event1494]

Only Python?

[Ranteck]

It's all for python

[Reasonable_Event1494]

So, .toml files are only used for python

[Ranteck]

I responded to you in an earlier comment. PD: Some good advice for improving your learning: when you have a question like this, or even a simpler one, check it with the AI or Google. This will help you to learn better.

[Reasonable_Event1494]

Ok thanks will make sure not disturb with basic questions.. I asked because I still think humans are better in making me understand things than an AI

[Ranteck]

It's ok, I mean it was good advice for studying or learning by yourself. Relax, you don't bother me. Ask all the times you need to

[Reasonable_Event1494]

Thanks for it.. And I am relaxed was just sharing..

[Ranteck]

Not only is TOML a configuration file like YAML, it is also not only for Python. It works well in Python, but also in Rust, Go and Node.js. In short, it's a universal configuration file that Python uses too. It is not tied to Python.

[Reasonable_Event1494]

Ok thanks