Linting with Ruff¶

Ruff is an extremely fast Python linter and code formatter written in Rust. It can replace multiple tools including Flake8, isort, and more. For MicroPython stubs, ruff provides stub-specific linting through its built-in flake8-pyi plugin.

Why use Ruff with MicroPython stubs?¶

Fast: Ruff is 10-100x faster than other Python linters
Comprehensive: Includes 800+ rules from popular linters
Stub-aware: Built-in support for .pyi stub file linting via flake8-pyi rules
Easy to configure: Single configuration file in pyproject.toml

Installation¶

Install ruff using pip:

pip install ruff

Or add it to your pyproject.toml:

[project.optional-dependencies]
test = [
    "ruff",
    # ... other test dependencies
]

Configuration¶

Ruff can be configured in your pyproject.toml file. For MicroPython stubs, we enable the PYI (flake8-pyi) rules for stub-specific checking:

[tool.ruff]
line-length = 140
target-version = "py39"

[tool.ruff.lint]
extend-select = [
    "PYI", # flake8-pyi - stub file specific checks
]
ignore = [
    "F401",   # unused import
    "F403",   # import *
    "F821",   # undefined name (can occur in stubs)
    "E402",   # module level import not at top of file - common in test snippets
    "PYI021", # Docstrings should not be included in stubs (but we want them for MicroPython)
    "PYI044", # `from __future__ import annotations` - used in generated stubs
    "PYI048", # Function body must contain exactly one statement - docstrings count
    "PYI011", # Only simple default values allowed for typed arguments - we want actual defaults
    "PYI014", # Only simple default values allowed for arguments - we want actual defaults
    "PYI029", # __str__ and __repr__ are useful in MicroPython stubs
]

Running Ruff¶

Check your code¶

# Check a single file
ruff check my_file.py

# Check a directory
ruff check src/

# Check with automatic fixes
ruff check --fix src/

Format your code¶

Ruff can also format your code (similar to Black):

# Format a file
ruff format my_file.py

# Format a directory
ruff format src/

Check stub files¶

To check MicroPython stub files:

# Check a specific stub directory
ruff check stubs/micropython-v1_24_1-esp32-stubs/

# Check all stubs
ruff check stubs/

Integration with the test suite¶

The MicroPython stubs project includes ruff as one of the linters in the quality test suite. When running tests, ruff will automatically check code snippets and stub files for quality issues.

IDE Integration¶

Most modern Python IDEs support Ruff:

VS Code¶

Install the Ruff extension from the VS Code marketplace:

Extension ID: charliermarsh.ruff

Configure in .vscode/settings.json:

{
    "[python]": {
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll": true,
            "source.organizeImports": true
        },
        "editor.defaultFormatter": "charliermarsh.ruff"
    }
}

PyCharm¶

PyCharm supports Ruff through the external tools configuration or via plugins from the JetBrains marketplace.

Comparison with other linters¶

For MicroPython stubs, we use multiple complementary linters:

Pyright: Type checking and type inference
MyPy: Alternative type checker with different semantics
Ruff: Fast linting including stub-specific rules

Each serves a different purpose:

Pyright/MyPy focus on type correctness
Ruff focuses on code quality, style, and stub-specific best practices