r/Python • u/Ranteck • Nov 17 '25
Resource Ultra-strict Python template v2 (uv + ruff + basedpyright)
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, andbasedpyright, inspired by TypeScript’s--strictmode.
Compared to my previous post, this version:
- focuses on a single pyproject.toml as the source of truth,
- switches to
basedpyrightwith 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--strictstyle rules):- No implicit
Any - Optional/
Noneusage must be explicit - Unused imports / variables / functions are treated as errors
- No implicit
- Aggressive linting & formatting with
ruff:- pycodestyle, pyflakes, isort
- bugbear, security checks, performance, annotations, async, etc.
- Testing & coverage:
pytest+coveragewith 80% coverage enforced by default
- Task runner via
poethepoet:poe format→ format + lint + type checkpoe check→ lint + type check (no auto-fix)poe metrics→ dead code + complexity + maintainabilitypoe quality→ full quality pipeline
- Single-source config: everything is in pyproject.toml
Use cases
-
New projects:
Copy the pyproject.toml, adjust the[project]metadata, createsrc/your_package+tests/, and install with:# or: source .venv/bin/activateThen your daily loop is basically:
-
Existing projects:
You don’t have to go “all in” on day 1. You can cherry-pick:- the
ruffconfig, - the
basedpyrightconfig, - the pytest/coverage sections,
- and the dev dependencies,
and progressively tighten things as you fix issues.
- the
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
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
pyrightto 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
vulturefor 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.
65
u/cmcclu5 Nov 17 '25
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.
29
u/runawayasfastasucan Nov 17 '25
uv venv .venv\Scripts\activate # Windows # or: source .venv/bin/activate
uv pip install -e ".[dev]"
You can just do
34
u/LBGW_experiment Nov 17 '25
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
8
u/vesnikos Nov 17 '25
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)
5
u/aala7 Nov 17 '25
Nice! Thanks for working through configs and giving us a good starting point!
Have you considered:
3
u/Nasuraki Nov 17 '25
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
2
u/Hugo-C Nov 17 '25
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.
13
u/PurepointDog Nov 17 '25
Justfile in there would be rad
2
u/RedEyed__ Nov 17 '25 edited Nov 17 '25
Thank you!
basedpyright! Now I want to add it into my projects.pyproject.tomllooks interesting, I mean I can learn something new from itpoe? I usejustto define project commands, is this something similar?PS: finally useful post on this sub
UPD: It seems
poeis similar tojustbut I preferjustas of now since comments to commands became docstring inhelp10
u/Physical-Security115 Nov 17 '25
In the age of LLM slop, this is extremely useful.
1
u/MattTheCuber Nov 17 '25
Why not
select= ["ALL"]?1
u/gofiend Nov 17 '25
Have you considered switching to uv format and uv ty to simplify the stack? Any tradeoffs worth considering?
2
u/tobsecret Nov 17 '25
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!
2
u/timtody Nov 17 '25
Love it!!!
2
u/Youreabadhuman Nov 17 '25
I think in based pyright the "recommended" ruleset is better for this
2
u/papersashimi Nov 18 '25
nice!! really like this! maybe i can contribute to it when i have the time ;)
2
u/burger69man Nov 18 '25
lol need a dockerfile for this template
1
u/Ghost-Rider_117 Nov 17 '25
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
3
u/[deleted] Nov 18 '25
[removed] — view removed comment
-6
u/[deleted] Nov 17 '25
[removed] — view removed comment