Saltar a contenido

Cómo migrar a Ruff

El stack migró de isort + black + flake8 a Ruff como herramienta unificada de linting, formato y ordenamiento de imports. Esta guía te muestra la configuración y cómo correr los checks.

Por qué Ruff

Aspecto Antes (isort + black + flake8) Ruff
Velocidad ~10-30 s 10-100× más rápido (Rust)
Herramientas 3 + plugins 1 binario único
Configuración 3 secciones 1 sola [tool.ruff]
Reglas activas Limitadas 700+ portadas y unificadas
Auto-fix Parcial Mayoritario

El detonante fue un bug bloqueante en la extensión ms-python.isort con Python 3.12 en Windows (PackageNotFoundError, LSP crash -32097).

Configuración aplicada

En pyproject.toml:

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = ["E", "W", "F", "I", "UP", "B"]
ignore = []

[tool.ruff.lint.isort]
known-first-party = ["domains", "tools", "core", "src"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
Regla Origen Qué detecta
E/W pycodestyle Errores/warnings de estilo
F pyflakes Imports/nombres/variables sin usar
I isort Ordenamiento de imports
UP pyupgrade Modernización PEP 585/604
B flake8-bugbear Bugs sutiles (mutable defaults, zip sin strict=)

Workflow local

ruff check .                      # lint (uso diario)
ruff check . --fix                # auto-fixes seguros
ruff check . --select I001 --fix  # solo ordenar imports
ruff format .                     # formatear (drop-in de black)
ruff format --check .             # modo CI (falla si necesita formato)
ruff check . --statistics         # estadísticas por regla

CI (GitHub Actions)

ruff:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: "3.12"
    - run: pip install -r requirements-dev.txt
    - run: ruff check . --output-format=github
    - run: ruff format --check .

--output-format=github produce anotaciones nativas en el PR.

Migrar VSCode de isort a Ruff

code --uninstall-extension ms-python.isort
code --install-extension charliermarsh.ruff

.vscode/settings.json:

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

Proveedor único por categoría

Política del stack: un solo proveedor de lint/format/imports (charliermarsh.ruff). Extensions prohibidas (redundantes): ms-python.black-formatter, ms-python.flake8, ms-python.pylint, ms-python.autopep8.

Aplicar fixes en fases

Aplicar todos los auto-fixes en un commit mezcla mucho ruido. Plan recomendado:

  1. Imports (riesgo bajo): ruff check . --select I001 --fix
  2. Tipos (riesgo bajo-medio): ruff check . --select UP --fix
  3. F + B (revisión manual): ruff check . --select F,B → revisar → --fix --unsafe-fixes
  4. Formato (último): ruff format .

Ver también

Fuente canónica

Deriva de docs/shared/RUFF_MIGRATION.md.