From 0c293de91213b1cd596a95ef44899989e3bfae20 Mon Sep 17 00:00:00 2001
From: jbranchaud <jbranchaud@gmail.com>
Date: Mon, 6 Jul 2026 16:41:35 -0500
Subject: [PATCH] Add Lint And Format Project With Ruff as a Python TIL

---
 README.md                                   |  3 +-
 python/lint-and-format-project-with-ruff.md | 81 +++++++++++++++++++++
 2 files changed, 83 insertions(+), 1 deletion(-)
 create mode 100644 python/lint-and-format-project-with-ruff.md

diff --git a/README.md b/README.md
index c36b7da..cab6368 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ working across different projects via [VisualMode](https://www.visualmode.dev/).
 
 For a steady stream of TILs, [sign up for my newsletter](https://visualmode.kit.com/newsletter).
 
-_1810 TILs and counting..._
+_1811 TILs and counting..._
 
 See some of the other learning resources I work on:
 
@@ -1084,6 +1084,7 @@ If you've learned something here, support my efforts writing daily TILs by
 - [Iterate First N Items From Enumerable](python/iterate-first-n-items-from-enumerable.md)
 - [Iterate Over A Dictionary](python/iterate-over-a-dictionary.md)
 - [Keep A Tally With collections.Counter](python/keep-a-tally-with-collections-counter.md)
+- [Lint And Format Project With Ruff](python/lint-and-format-project-with-ruff.md)
 - [Load A File Into The Python REPL](python/load-a-file-into-the-python-repl.md)
 - [Look Inside Pytest tmp_path](python/look-inside-pytest-tmp-path.md)
 - [Make Dataclass Sortable By Specific Field](python/make-dataclass-sortable-by-specific-field.md)
diff --git a/python/lint-and-format-project-with-ruff.md b/python/lint-and-format-project-with-ruff.md
new file mode 100644
index 0000000..d2bc9ce
--- /dev/null
+++ b/python/lint-and-format-project-with-ruff.md
@@ -0,0 +1,81 @@
+# Lint And Format Project With Ruff
+
+[Ruff](https://docs.astral.sh/ruff/) is "an extremely fast Python linter and
+code formatter, written in Rust." I recently added it to my [`py-vmt` CLI project](https://github.com/jbranchaud/py-vmt) and here are some of the commands
+I used right out of the box.
+
+First, I use `uv` and so I installed it like so:
+
+```bash
+❯ uv add --dev ruff
+```
+
+First, I checked for linting errors. There were a bunch. The output looked like
+this:
+
+```bash
+❯ uv run ruff check
+F841 Local variable `frozen_datetime` is assigned to but never used
+  --> tests/src/py_vmt/test_cli.py:88:43
+   |
+86 |         2026, 3, 14, 15, 5, 11, 0, datetime.timezone.utc
+87 |     )
+88 |     with freeze_time(initial_datetime) as frozen_datetime:
+   |                                           ^^^^^^^^^^^^^^^
+89 |         # cancel session without one started
+90 |         cancel_result = runner.invoke(cli, ["cancel"])
+   |
+help: Remove assignment to unused variable `frozen_datetime`
+
+...
+
+Found 11 errors.
+[*] 2 fixable with the `--fix` option (7 hidden fixes can be enabled with the `--unsafe-fixes` option).
+```
+
+Some of them could be automatically fixed, so I dealt with those first using the
+`--fix` flag.
+
+```bash
+❯ uv run ruff check --fix
+```
+
+The remaining lint issues I had to deal with manually. Once I had addressed all
+of them I got this message:
+
+```bash
+❯ uv run ruff check
+All checks passed!
+```
+
+With the lint issues out of the way, the next stuff was to use `ruff` to apply
+consistent auto-formatting across the entire project. Because I hadn't been
+using any auto-formatter up to this point on this project, I can expect the diff
+to be significant.
+
+I can start with a dry run using the `--check` flag. This gives a summary of how
+much formatting churn there is going to be.
+
+```bash
+❯ uv run ruff format --check
+Would reformat: src/py_vmt/cli.py
+Would reformat: src/py_vmt/session.py
+Would reformat: src/py_vmt/time_helpers.py
+Would reformat: tests/src/py_vmt/test_cli.py
+Would reformat: tests/src/py_vmt/test_session.py
+Would reformat: tests/src/py_vmt/test_time_helpers.py
+6 files would be reformatted, 3 files already formatted
+```
+
+I'm using git and I have a clean working copy, so there is no real harm in just
+going for it either.
+
+```bash
+❯ uv run ruff format
+6 files reformatted, 3 files left unchanged
+```
+
+That makes all the formatting changes and I can use `git diff` to browse through
+them before eventually committing them.
+
+See `uv run ruff check --help` and `uv run ruff format --help` for more details.