isort & Organização de Imports
Uma ordem de importação consistente torna os diffs legíveis e previne surpresas com imports circulares. As regras isort do Ruff (I) cuidam disso automaticamente - nenhuma instalação separada do isort é necessária.
Receita
[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 importsQuando usar isso:
- Blocos de importação estão ordenados de forma inconsistente entre os arquivos
- A revisão de código gasta tempo em detalhes de importação
- Imports circulares precisam de uma separação mais clara entre stdlib e local
Exemplo de Trabalho
# Ordem correta (após 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 = 2O que isso demonstra:
- Imports
futureprimeiro, depois stdlib, third-party, first-party, local - Linhas em branco separam os grupos
known-first-partyinforma ao ruff quais pacotes são seus--fixreordena sem edição manual
Mergulho Profundo
Grupos de Importação
| Grupo | Exemplos |
|---|---|
future | from __future__ import annotations |
| standard-library | os, pathlib, typing |
| third-party | httpx, fastapi, pandas |
| first-party | seus pacotes instalados |
| local-folder | imports relativos em scripts |
Notas Python
# Prefira imports absolutos em bibliotecas
from myapp.services import billing
# Imports relativos ok dentro de um pacote
from .models import UserArmadilhas
known-first-partyausente - seus pacotes são ordenados como third-party. Correção: liste todos os nomes de pacotes first-party.- isort + ruff configurados - regras conflitantes. Correção: use apenas ruff; remova o isort independente.
- Imports em estrela (
from x import *) - o lint sinaliza e obscurece a origem. Correção: imports explícitos, exceto re-exports de__init__.py. - Imports circulares devido à ordem - a reordenação não corrige problemas de design. Correção: reestruture os módulos; use imports preguiçosos ou
TYPE_CHECKING. - Ordem diferente em
__init__.py- re-exports confundem o isort. Correção: override por arquivo ou__all__explícito.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Ordenação manual | Projeto de 1-2 arquivos | Qualquer projeto em equipe |
| isort independente | Não usando ruff | Já usando ruff |
| Sem ordenação | - | Nunca para produção |
FAQs
Preciso de isort se tenho ruff?
Não. O Ruff implementa as regras do isort nativamente.
Como forçar imports de linha única?
force-single-line = true em [tool.ruff.lint.isort].
E sobre aliases de importação?
import pandas as pd permanece no grupo third-party. O isort preserva aliases.
Como lidar com imports TYPE_CHECKING?
Os blocos if TYPE_CHECKING: do Ruff os colocam corretamente. Use blocos if TYPE_CHECKING: como normal.
Posso excluir um arquivo da ordenação de imports?
Ignorar por arquivo: "__init__.py" = ["I001"] se re-exports precisarem de ordem manual.
Por que duas linhas em branco após os imports?
PEP 8 recomenda duas linhas em branco antes de funções de nível superior. lines-after-imports = 2 impõe isso.
Como monorepos lidam com first-party?
Liste todos os nomes de pacotes do workspace em known-first-party.
A ordem de importação afeta o desempenho?
Não. Isso é apenas para legibilidade e convenção.
Como ordenar ao salvar?
Extensão ruff do VS Code com "source.organizeImports.ruff": "explicit" ou formatar ao salvar.
O que é I001?
O código de violação de ordenação de imports do Ruff. Corrigido com ruff check --fix.
Relacionados
- Configuração do Ruff - configuração do ruff
- Regras Essenciais de Lint - regras I em contexto
- Black / Formatação Ruff - formatação (separado de imports)
- Melhores Práticas de Linting e Formatação - convenções
Versões do Stack: Esta página foi 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+, e uv 0.6+.