In this lesson, you will learn how to fine-tune your ruff.toml configuration to enforce project-specific architectural standards and silence valid, yet noisy, code patterns.
Why Customize Linting?
While standard linting rules keep code clean, they often clash with specific architectural patterns. For example, you might want to enforce strict naming conventions in your domain layer, or you might be using a dynamic library that triggers "undefined name" false positives. Rather than ignoring errors globally, you can surgically modify Ruff’s behavior to match your project’s reality.
Configuring pyproject.toml
Ruff is configured via your pyproject.toml file. You can toggle specific rules (using their unique identifiers) or define custom behavior for entire file patterns.
Suppose your architecture requires that all Repository classes end with the suffix Repo, but you have a legacy module that doesn't follow this. Instead of disabling the naming rule entirely, you can use the extend-select and ignore settings to fine-tune it:
[tool.ruff]
# Enable additional rules beyond the default 'select' set
extend-select = ["N801"] # Check for class naming conventions
[tool.ruff.lint]
# Globally ignore specific rules that don't fit your patterns
ignore = ["ANN101"]
# Use per-file-ignores for complex logic or legacy modules
[tool.ruff.lint.per-file-ignores]
"src/legacy_db/*.py" = ["N801"] # Silence naming rule for legacy files only
"tests/**/*.py" = ["S101"] # Allow 'assert' in test files but not production
Addressing False Positives
Sometimes, a project uses complex metaprogramming or specific design patterns that look like errors to a static analyzer. If you encounter a consistent false positive—where Ruff flags code that is architecturally sound—you can disable that specific rule for the entire project or specific sub-directories.
By strategically using per-file-ignores, you keep the "strictness" of your linter intact for 95% of your codebase while providing the flexibility required for the 5% that demands a custom approach. This ensures your linting remains a helpful guide rather than an obstacle to complex implementation.
Key Takeaway: Use per-file-ignores in your pyproject.toml to suppress specific linter errors for unique architectural patterns or legacy modules without compromising the global code quality standards of your project.