Advanced Ruff Configuration

Why Configure Ruff? (Tier 1: Motivation)

In Lesson 8, you used Ruff's defaults: format with double quotes, 88-character lines, standard PEP 8 rules.

But what if your team prefers:

• Single quotes instead of double quotes?
• 100-character lines instead of 88?
• Stricter rules (docstring checking, strict naming)?
• Ignoring certain rules (e.g., E501 line length)?

Solution: Configure Ruff in pyproject.toml so your team all follows the same rules.

Key benefit: Configuration is version-controlled (part of your git repo). Everyone on the team gets identical settings automatically when they clone the project.

---

The TOML Format (Tier 1: Brief Introduction)

Before configuring Ruff, you need to understand TOML files (the format pyproject.toml uses).

TOML is simple:

• key = value for settings
• [section.subsection] for grouping
• Comments with #

Example pyproject.toml structure:

[project]
name = "my-project"
version = "0.1.0"

[tool.ruff]
line-length = 88

Key insight: You don't memorize TOML syntax. In Tier 2, you'll ask AI to generate configurations, and you'll just paste them in. The goal is understanding what to configure, not memorizing how.

---

Basic Ruff Configuration (Tier 2: AI-Assisted)

Open your project's pyproject.toml file in Zed.

Current structure (after uv init):

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.13"

[dependency-groups]
dev = ["ruff>=0.14.0"]

Now you'll add a [tool.ruff] section to customize behavior.

Tell your AI companion:

I have a Python project using uv and Ruff. My team prefers:
- 88-character line length (Ruff default)
- Python 3.13
- Import sorting enabled
- Unused import detection

Update my pyproject.toml with a [tool.ruff] section that configures this.

AI will generate something like:

[tool.ruff]
line-length = 88
target-version = "py313"

[tool.ruff.lint]
select = ["E", "F", "I"]

[tool.ruff.format]
quote-style = "double"

Copy-paste this into your pyproject.toml.

Verify it works:

uv run ruff check .

Ruff now uses your custom configuration.

Source: Verified in intelligence/001-verified-tool-documentation.md

---

Rule Categories Explained (Tier 1: Understand Options)

Ruff organizes rules into categories (single letters). You enable/disable whole categories:

Category	Purpose	Examples
E	pycodestyle — PEP 8 style	Spacing, indentation, blank lines
F	Pyflakes — Logic errors	Unused imports, undefined variables
B	flake8-bugbear — Likely bugs	Mutable defaults, unreachable code
I	isort — Import sorting	Alphabetize imports, group them
N	pep8-naming — Naming rules	Function names in lowercase
D	pydocstyle — Docstrings	Docstring formatting (advanced)

Example: Select import sorting + bug detection:

[tool.ruff.lint]
select = ["F", "I", "B"]  # Pyflakes, isort, bugbear

Example: Select all but ignore long lines:

[tool.ruff.lint]
select = ["E", "F"]       # pycodestyle + Pyflakes
ignore = ["E501"]         # But ignore line-too-long

Key insight: Start simple (select F for safety), add more rules as your team agrees.

---

Configure Line Length & Target Version (Tier 1: Common Settings)

Every project needs these two settings:

line-length

How many characters wide should a line be before Ruff complains?

[tool.ruff]
line-length = 88  # Industry standard (Black-compatible)

Common values:

• 88: Industry default (Black's choice)
• 100: Slightly more lenient
• 120: Very permissive
• 79: Strict (PEP 8 original, rarely used anymore)

target-version

Which Python version should Ruff assume?

[tool.ruff]
target-version = "py313"  # Python 3.13

Why it matters: Ruff adjusts rules based on Python version. Python 3.13 has features older versions don't.

Common values:

• "py313": Python 3.13 (latest, what we use)
• "py312": Python 3.12
• "py311": Python 3.11

---

Complete Configuration Example (Tier 2: Reference)

Here's a professional pyproject.toml with complete Ruff setup:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-project"
version = "0.1.0"
description = "Brief description"
authors = [{name = "Your Name", email = "you@example.com"}]
requires-python = ">=3.13"

[dependency-groups]
dev = ["ruff>=0.14.0", "pyright>=1.1.400"]

[tool.ruff]
line-length = 88
target-version = "py313"

[tool.ruff.lint]
select = ["E", "F", "B", "I"]  # Enable: style, safety, bugs, imports
ignore = ["E501"]              # But don't complain about line length

[tool.ruff.format]
quote-style = "double"         # Use "hello" not 'hello'
indent-style = "space"         # Use spaces, not tabs

Save this to pyproject.toml and run:

uv run ruff check .

Ruff now follows your configuration.

Source: Verified in intelligence/001-verified-tool-documentation.md

---

Integrate with Zed: Format-on-Save (Tier 2: Editor Integration)

Wouldn't it be nice if Zed automatically formatted your code when you save?

Open Zed's settings:

• Mac: Cmd+, (comma)
• Windows/Linux: Ctrl+,

In the settings file, add this Python-specific section:

{
  "languages": {
    "Python": {
      "formatter": "language_server",
      "format_on_save": true
    }
  }
}

Now when you save a Python file (Cmd+S or Ctrl+S), Ruff automatically formats it.

Benefit: You write code freely; Ruff keeps it clean. No manual uv run ruff format . needed.

Source: Verified in intelligence/001-verified-tool-documentation.md

---

Ignoring Rules Selectively (Tier 2: Fine-Tuning)

Sometimes a specific rule doesn't fit your project. You can ignore it for a single line or the whole file.

Ignore one rule on a specific line:

Loading Python environment...

Ignore all rules for a line:

Loading Python environment...

Ignore a rule project-wide:

[tool.ruff.lint]
ignore = ["E501", "D100"]  # Ignore: line-too-long, missing module docstring

When to use:

• One-off exceptions: # noqa on the line
• Team decision: Add to ignore list in pyproject.toml

---

Tier 3 Preview: Scaling Configuration (Tier 2: Awareness)

As projects grow, you might want:

• Shared configuration: One pyproject.toml template for all team projects
• CI/CD integration: Ruff checks run automatically on every git push
• Pre-commit hooks: Ruff runs before allowing commits

These are Lesson 12 topics. For now, just know: your pyproject.toml is the single source of truth for your team's code standards.

---

Try With AI

How do you configure Ruff for team standards and integrate multiple quality tools without conflicts?

🔍 Explore Configuration Hierarchy:

"My Python codebase has mixed styles: some files use 88-char lines, others 120; imports aren't sorted consistently; mix of single and double quotes; varying blank lines before functions. Which should I enforce via Ruff config vs leave flexible? Explain the difference between [tool.ruff], [tool.ruff.lint], and [tool.ruff.format] sections. How do I choose which rule categories (E, F, B, I, N, D) to enable? Can I have different rules for tests vs production?"

🧪 Test Tool Conflicts:

"I'm using Ruff, Pyright, and Black together and hitting conflicts: Ruff and Black disagree on line breaking, Pyright catches type errors Ruff doesn't, and Zed's format-on-save sometimes formats twice or not at all. For each conflict, show me the pyproject.toml config to prevent it, explain which tool takes precedence, how to verify they work together, and the proper execution order (format → lint → type-check)."

🎯 Build Production Configuration:

"Generate a production-ready pyproject.toml integrating Ruff (line length 88, Python 3.13 target, enable E/F/B/I categories, ignore E501, double quotes, space indentation) and Pyright (basic mode, exclude .venv and pycache). Ensure no conflicts, configure for Zed LSP integration, and add comments explaining each setting. For each, explain why this value (industry standard, team preference, safety) and how to test it works."

🚀 Configure IDE Integration:

"Create matching Zed settings.json that uses Ruff for formatting with format-on-save enabled, shows Ruff diagnostics and Pyright type errors inline, excludes .venv from file watching, and sets Python tab width to 4 spaces. Include both user-level settings (all projects) and workspace settings (project-specific)."

🔧 Troubleshoot Common Issues:

"I'm seeing these problems with my Ruff setup: (1) Ruff says my pyproject.toml has a syntax error, (2) Format-on-save isn't working in Zed, (3) My rules look right but Ruff still complains. For each issue, explain what's happening and give me the fix or workaround. What are the most common configuration mistakes and how can I prevent them?"

---