Mantener la coherencia en el código Python es uno de esos hábitos que marcan la diferencia entre un equipo eficiente y uno caótico. Con Ruff, puedes formatear tu código Python automáticamente, reemplazar herramientas como Black e Isort y cumplir con la PEP 8 sin preocuparte. Si escribes en Python y te importan las diferencias limpias, este flujo de trabajo es para ti.
¿Por qué usar Ruff como formateador de Python?
Ruff es un formateador y linter moderno que reemplaza directamente a Black, la herramienta que solía gestionar el formato PEP 8 en la mayoría de los proyectos Python. La ventaja es la velocidad y una única fuente de configuración: todo reside en tu archivo pyproject.toml.
¿Qué es Ruff en Python? Ruff es un formateador y linter automático para Python que sigue la PEP 8 por defecto y reemplaza a Black e Isort con una única herramienta más rápida.
El objetivo es simple: dejar de discutir sobre comillas, líneas en blanco o el orden de importación, y permitir que la herramienta imponga un estilo común a todo el equipo.
¿Cómo instalo Ruff con uv en un proyecto Python? La instalación se ejecuta desde la terminal, dentro de la carpeta de tu proyecto. El comando utiliza `uv add`, que agrega paquetes a un proyecto, con la opción `--dev` para que la dependencia solo exista en tu entorno de desarrollo [00:32].
`bash`
`uv add --dev ruff`
Tras pulsar Intro, Ruff aparece como una nueva dependencia con su versión. Si abres `pyproject.toml`, la verás listada dentro del grupo `dev`, lo que significa que se instala solo cuando descargas las dependencias de desarrollo.
Una vez instalado, ejecuta el formateador desde la raíz del proyecto:
`bash`
`ruff format .`
El punto apunta a la ruta actual. En el ejemplo de la lección, la salida mostró 20 archivos reformateados y 3 sin cambios [01:30]. Las diferencias mostraron líneas en blanco adicionales añadidas en algunos lugares y comillas simples convertidas a comillas dobles, todo alineado con PEP 8.
¿Qué cambia realmente `ruff format` en tu código?
Por defecto, Ruff aplica las reglas de PEP 8 a todos los archivos Python que procesa. Los cambios típicos incluyen:
Convertir comillas simples a dobles.
Agregar o eliminar líneas en blanco para ajustarse a las reglas de estilo.
Normalizar el espaciado dentro de expresiones y definiciones de funciones.
Estandarizar el formato en todos los archivos del proyecto.
Después de esta lista, la idea clave es que Ruff tiene un estilo definido a propósito. Obtienes un estilo predecible sin necesidad de escribir una guía de estilo desde cero.
¿Cómo configuro Ruff con pyproject.toml?
Algunos proyectos no siguen estrictamente la PEP 8, y eso no representa ningún problema. Ruff cuenta con un sistema de configuración integrado en pyproject.toml, el archivo que los proyectos de Python utilizan ahora por defecto para su configuración [02:15].
Por ejemplo, si tu equipo prefiere las comillas simples, puedes agregar un bloque como este:
toml
[tool.ruff.format]
quote-style = "single"
Al ejecutar `ruff format` nuevamente, las comillas dobles anteriores volverán a ser simples, ya que la opción `quote-style` ahora está configurada como "single" [02:55]. Si eliminas esa configuración, Ruff vuelve a sus valores predeterminados de PEP 8 y utiliza comillas dobles de nuevo.
¿Debo seguir PEP 8 o el estilo propio de mi proyecto? Sigue siempre un estándar único y coherente. Si tu proyecto ya se desvía de PEP 8, atén a las reglas del proyecto y aplícalas mediante pyproject.toml.
El principio es la coherencia. Tanto si usas PEP 8 como un estilo personalizado, todos los archivos deben parecer escritos por la misma persona.
¿Cómo excluyo archivos del formato de Ruff?
A veces trabajas con código generado automáticamente por un framework y no quieres que tu editor o formateador lo modifique. Ruff gestiona esto con la opción `extend-exclude` dentro de la sección `[tool.ruff]` de pyproject.toml [03:45].
toml
[tool.ruff]
extend-exclude = ["do_not_format"]
En la lección, se creó una carpeta llamada do_not_format dentro del proyecto Platzi News, con un archivo .py entre comillas simples. Tras añadir la ruta relativa a extend-exclude y ejecutar ruff format, ese archivo permaneció intacto [04:20]. Todo lo que se encuentre dentro de la ruta excluida es ignorado por el formateador.
Esto resulta útil para migraciones, código de terceros o archivos generados automáticamente que deben conservar su estructura original.
¿Cuáles son las mejores prácticas para el formateo automático en Python?
Tres hábitos hacen que el formateo automático sea realmente rentable en proyectos reales:
Configurar Ruff desde el inicio del proyecto para evitar conflictos de formato posteriores.
Integrar ruff format en tus hooks de precommit para que ningún código sin formato llegue al repositorio.
Definir reglas consistentes para todo el equipo utilizando pyproject.toml como fuente única de información.
Tras poner esto en marcha, tus solicitudes de extracción dejarán de mostrar diferencias de formato innecesarias y empezarán a mostrar los cambios lógicos reales, que es de lo que se trata la revisión de código.
Ahora te toca a ti. Configura Ruff en uno de tus proyectos personales y comparte cuántos archivos se modificaron la primera vez que ejecutaste `ruff format`. Deja tu resultado en los comentarios y compáralo con el resto de la comunidad.
