Linting and formatting

---

What is linting and formatting

Linting

---

Formatting

---

Ruff

Black and Flake8 are formatter and linter that are traditionally used for Python development.

Ruff docs

Ruff - fast linter and formatter written in Rust and aims to used as a replacement to the above two as well as dozens of other plugins, and thereby improve code quality in one tool.

Installation

You can either install it globally with uv tool install ruff

or with uv add --dev ruff to add to your uv project.

Performing checks

• Run check on a a file: ruff check main.py

• Run check on a directory: ruff check .

  • "." is current directory. Or you can specify directory name as an argument.

• If you want to run the checks and fix errors simultaneously: ruff check --fix .

  • You might not want to just let Ruff fix the errors without telling you what exactly it changed. For that case, there is another option you can use called --diff that will show you which lines will be changed in each file before changes are applied. After that you may apply the corrections without the --diff option.

• There is another option called --watch that you can use with ruff checkwhich will monitor errors in real-time via terminal.

If you're running Ruff commands inside your uv project, you can run it in an isolated environment like so: uv run ruff check .... UV manages caching and ensures consistency across your team for reproducibility.

# UV ensures tools match your uv.lock
uv sync # Installs everything from pyproject.toml
uv run ruff check # Uses locked version
# Everyone gets identical versions from uv.lock

Performing formatting

• ruff format .

• or ruff format <filename>

You generally want to run checks first before running formatting. That way, Ruff fixes don't mess up any of the formatting.

---

Ruff rulesets

Docs

When you run your Ruff checks, it will output error codes which you can then search in the Ruff documentation and find out their meaning and why the error was thrown. There are over 800 lint rules that Ruff supports.

You can also see all available rules by running ruff rule --all

Or you can explore a specific rule like this: ruff rule F821

In order to specify either rule type or a specific rule within that type when running ruff check:

ruff check --select E
one_ring.py:4:89: E501 Line too long (122 > 88)
Found 1 error.

ruff check --select E501
one_ring.py:4:89: E501 Line too long (122 > 88)
Found 1 error.

You can configure Ruff rules in your pyproject.toml file.

Here's how:

Add a [tool.ruff.lint] section to your pyproject.toml:

[tool.ruff.lint]
# Enable specific rules or rule categories
select = [
    "E",   # pycodestyle errors
    "F",   # Pyflakes
    "W",   # pycodestyle warnings
    "I",   # isort
    "N",   # pep8-naming
    "UP",  # pyupgrade
    "B",   # flake8-bugbear
]

# Optionally ignore specific rules
ignore = [
    "E501",  # Line too long
    "B008",  # Do not perform function call in argument defaults
]

# Set line length
line-length = 88

The .lint is a namespace/section that groups lint-specific configuration options. You can add it to each element within a section or for an entire section.

You can enable all rules and then ignore specific ones:

[tool.ruff.lint]
select = ["ALL"]
ignore = ["D", "ANN"]  # Ignore docstring and annotation rules

Note, however, that it's not recommended to check all the rules (over 800) because some rules may be conflicting.

lint.extend-select

This adds rules to the default set without replacing it. The default set is ["E4", "E7", "E9", "F"] (a subset of pycodestyle errors and Pyflakes).

[tool.ruff.lint]
extend-select = ["I", "N", "UP"]  # Adds these to the defaults
# Now you have: E4, E7, E9, F, I, N, UP

Per-File Ignores

[tool.ruff.per-file-ignores]
"__init__.py" = ["F401"]  # Ignore unused imports in __init__.py
"tests/*" = ["S101"]      # Allow assert statements in tests

---

Ruff global configuration file

Location on Mac OS/Linux: ~/.config/ruff/ruff.toml

You can also enable formatting on save and default formatter in settings.json file which you can find via VSCode by typing "Preferences: Open User Settings (JSON)" and find //Python settings section.

---