Configuración y uso de Ruf como formateador automático en Python

Mantener un código consistente y legible acelera el trabajo en equipo. Aquí aprenderás a configurar Ruf como formateador automático en Python, reemplazando herramientas como Black y Sort, aplicando PEP 8 por defecto y ajustando reglas desde pyproject.toml. Verás cómo formatear todo el proyecto, personalizar comillas y excluir rutas generadas por un framework.

¿Cómo instalar y configurar Ruf con pyproject.toml?

Configurar Ruf desde el principio evita fricciones de estilo y facilita la colaboración. La instalación se hace en el entorno de desarrollo y queda registrada en el archivo de configuración del proyecto.

• Abre la terminal en la carpeta del proyecto.
• Agrega la dependencia al entorno de desarrollo con el gestor de paquetes.

V add --def Ruf

• Verifica que en pyproject aparezca la dependencia en el grupo de desarrollo.
• Ejecuta el formateo en el path actual.

root format .

• Revisa los cambios: se reportan archivos reformateados y archivos sin cambios.
  • Ejemplo real: 20 archivos reformateados y 3 sin cambios.
• Cambios típicos que verás:
  • Inserción de líneas en blanco para legibilidad.
  • Cambio de comillas simples a dobles o viceversa.
  • Alineación y espacios según PEP 8.

Idea clave: por defecto, Ruf aplica PEP 8 automáticamente. Si tu equipo usa otro estándar, configura las reglas en pyproject.toml para mantener consistencia.

¿Qué reglas PEP 8 aplica y cómo personalizarlas?

Ruf es un reemplazo de Black que formatea según PEP 8. Sin embargo, puedes ajustar el estilo para seguir reglas ya establecidas en tu proyecto, todo desde pyproject.toml dentro de la sección de configuración de la herramienta.

¿Cómo cambiar el estilo de comillas?

Si necesitas que las comillas sean simples, define el quote style en la configuración. Al volver a ejecutar el formateo, Ruf actualizará los archivos según la regla.

[tool.ruf]
quote style = "single"

• Efecto: cuando había comillas dobles, pasarán a comillas simples.
• Úsalo solo si tu proyecto no seguirá PEP 8 por defecto en este aspecto.

¿Cómo excluir archivos con extend exclude?

Evita que se formatee código generado automáticamente por un framework agregando rutas a una lista de exclusiones. Crea una carpeta, por ejemplo: do not format, y añádela a la configuración.

[tool.ruf]
extend exclude = ["Platinus/do not format/"]

• Crea un archivo .py dentro de esa ruta con comillas simples.
• Ejecuta:

root format .

• Resultado: ese archivo no se modifica.

Buenas prácticas de configuración:

• Mantén un estándar único: si no es PEP 8, que sea el estándar del proyecto.
• Controla cambios de estilo desde pyproject.toml para todo el equipo.

¿Qué buenas prácticas y flujo de trabajo recomiendan?

Adoptar Ruf de forma ordenada reduce conflictos en pull requests y acelera las revisiones.

• Configura Ruf desde el inicio del proyecto para evitar divergencias de formato.
• Integra Ruf format en hooks de pre-commit para validar antes de cada commit.
• Define reglas consistentes en pyproject.toml y compártelas con todo el equipo.
• Si necesitas volver a PEP 8 por defecto, revierte cambios de configuración y vuelve a formatear.

¿Ya configuraste Ruf en un proyecto personal? Comparte cuántos archivos se modificaron y qué reglas ajustaste para tu equipo.