isort y Organización de Importaciones
Un orden de importación consistente hace que los diffs sean legibles y previene sorpresas de importaciones circulares. Las reglas I de isort de Ruff manejan esto automáticamente; no se necesita una instalación separada de isort.
Receta
[tool.ruff.lint.isort]
known-first-party = ["myapp"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]uv run ruff check --fix . # auto-ordena las importacionesCuándo recurrir a esto:
- Los bloques de importación están ordenados inconsistentemente entre archivos
- La revisión de código dedica tiempo a detalles de importación
- Las importaciones circulares necesitan una separación más clara entre stdlib y locales
Ejemplo Funcional
# Orden correcto (después de ruff fix)
from __future__ import annotations
import os
from pathlib import Path
import httpx
from pydantic import BaseModel
from myapp.config import settings
from myapp.models import User[tool.ruff.lint.isort]
known-first-party = ["myapp", "myapp_utils"]
force-single-line = false
lines-after-imports = 2Lo que esto demuestra:
- Importaciones
futureprimero, luego stdlib, third-party, first-party, local - Líneas en blanco separan los grupos
known-first-partyle dice a ruff qué paquetes son tuyos--fixreordena sin edición manual
Análisis Profundo
Grupos de Importación
| Grupo | Ejemplos |
|---|---|
future | from __future__ import annotations |
| standard-library | os, pathlib, typing |
| third-party | httpx, fastapi, pandas |
| first-party | tus paquetes instalados |
| local-folder | importaciones relativas en scripts |
Notas de Python
# Prefiere importaciones absolutas en bibliotecas
from myapp.services import billing
# Las importaciones relativas están bien dentro de un paquete
from .models import UserTrampas Comunes
- Falta
known-first-party: tus paquetes se ordenan como third-party. Solución: lista todos los nombres de paquetes first-party. - isort + ruff configurados ambos: reglas conflictivas. Solución: usa solo ruff; elimina isort independiente.
- Importaciones de estrella (
from x import *): el lint las marca y oscurece el origen. Solución: importaciones explícitas excepto re-exportaciones de__init__.py. - Importaciones circulares por orden: reordenar no soluciona problemas de diseño. Solución: reestructura módulos; usa importaciones perezosas o
TYPE_CHECKING. - Orden diferente en
__init__.py: las re-exportaciones confunden a isort. Solución: anulación por archivo o__all__explícito.
Alternativas
| Alternativa | Úsala Cuando | No la Uses Cuando |
|---|---|---|
| Orden manual | Proyecto de 1-2 archivos | Cualquier proyecto en equipo |
| isort independiente | No usas ruff | Ya usas ruff |
| Sin ordenación | - | Nunca para producción |
Preguntas Frecuentes
¿Necesito isort si tengo ruff?
No. Ruff implementa las reglas de isort de forma nativa.
¿Cómo fuerzo importaciones de una sola línea?
force-single-line = true en [tool.ruff.lint.isort].
¿Qué pasa con los alias de importación?
import pandas as pd permanece en el grupo third-party. isort preserva los alias.
¿Cómo manejo las importaciones de TYPE_CHECKING?
El isort de Ruff las coloca correctamente. Usa bloques if TYPE_CHECKING: como de costumbre.
¿Puedo excluir un archivo de la ordenación de importaciones?
Ignorar por archivo: "__init__.py" = ["I001"] si las re-exportaciones necesitan orden manual.
¿Por qué dos líneas en blanco después de las importaciones?
PEP 8 recomienda dos líneas en blanco antes de las funciones de nivel superior. lines-after-imports = 2 lo impone.
¿Cómo manejan los monorepos los first-party?
Lista todos los nombres de paquetes del espacio de trabajo en known-first-party.
¿El orden de importación afecta el rendimiento?
No. Esto es solo para legibilidad y convención.
¿Cómo ordeno al guardar?
Extensión ruff de VS Code con "source.organizeImports.ruff": "explicit" o formato al guardar.
¿Qué es I001?
El código de violación de ordenación de importaciones de Ruff. Se corrige con ruff check --fix.
Relacionado
- Configuración de Ruff - configuración de ruff
- Reglas Esenciales de Linting - reglas
Ien contexto - Black / Ruff Format - formateo (separado de las importaciones)
- Mejores Prácticas de Linting y Formateo - convenciones
Versiones de la Pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.