pylint

pylint Best Practices

Pylint is our go-to for deep semantic analysis and identifying complex code smells in Python. While Ruff handles fast style checks and MyPy ensures type correctness, Pylint focuses on broader architectural and logical issues. This guide ensures Pylint is a powerful, not noisy, part of our workflow.

1. Configuration is King: pyproject.toml

Always use pyproject.toml for Pylint configuration. This ensures consistency across all environments and developers.

Action: Generate a baseline config and commit it.

pylint --generate-toml-config > pyproject.toml

1.1. Silence the Noise, Enable What Matters

Pylint is notoriously noisy by default. Start by disabling everything and selectively enabling relevant categories. Focus on convention, refactor, warning, and error for semantic checks.

❌ BAD: Default Pylint output (overwhelming)

pylint your_module.py # Flooded with style and minor issues

✅ GOOD: Targeted Pylint checks in pyproject.toml

# pyproject.toml
[tool.pylint.main]
disable = "all"
enable = [
    "convention",
    "refactor",
    "warning",
    "error",
    # Add specific messages if needed, e.g., "W0611", "R0913"
]

1.2. Filter by Confidence

Reduce false positives by only showing warnings with high confidence.

✅ GOOD: Filter low-confidence warnings in pyproject.toml

# pyproject.toml
[tool.pylint.main]
confidence = ["HIGH", "CONTROL_FLOW"] # Focus on reliable detections

2. Code Organization & Readability

Pylint helps enforce structural best practices beyond basic style.

2.1. Docstrings for Everything

Every module, class, and function must have a docstring. Pylint enforces this.

❌ BAD: Missing docstrings

def calculate_sum(a, b):
    return a + b

✅ GOOD: Clear and concise docstrings

"""This module provides basic arithmetic operations."""

def calculate_sum(a: int, b: int) -> int:
    """
    Calculates the sum of two integers.

    :param a: The first integer.
    :param b: The second integer.
    :return: The sum of a and b.
    """
    return a + b

Pylint messages: C0114 (module), C0115 (class), C0116 (function/method)