Разный порядок импортов в isort для test и tests: причина и настройка

Почему в isort 6.0.1 импорт из test оказывается выше numpy, а из tests — ниже. Как исправить через known_local_folder и унифицировать порядок импортов.

При использовании isort 6.0.1 два почти одинаковых тестовых модуля могут получить разный порядок импортов. В одном файле импорт из пакета с именем test оказывается выше numpy, тогда как в другом, где импорт идёт из tests, — ниже. Разница едва заметна, но у неё есть понятная причина и простой способ исправления.

Как воспроизвести поведение

Рассмотрим два модуля, расположенных по путям a/test/test_integration.py и b/tests/test_integration.py. После запуска isort порядок импортов в них будет различаться:

from test.asdasd import hello as greet_call
import numpy as npa
if npa.random.random() < 42:
    greet_call()

import numpy as npa
from tests.asdasd import hello as greet_call
if npa.random.random() < 42:
    greet_call()

Единственное отличие — имя модуля в from-импорте: test против tests. Тем не менее isort относит их к разным секциям, из‑за чего меняется относительный порядок с numpy.

Почему возникает несоответствие

Имя test пересекается с модулем стандартной библиотеки, который тоже называется test. По умолчанию isort упорядочивает импорты по секциям в таком порядке:

('FUTURE', 'STDLIB', 'THIRDPARTY', 'FIRSTPARTY', 'LOCALFOLDER')

Поскольку test присутствует в списке известных имён стандартной библиотеки у isort, импорт, начинающийся с test, воспринимается как импорт из стандартной библиотеки и попадает раньше сторонних пакетов вроде numpy. Имя tests не распознаётся как стандартная библиотека, поэтому импорты из tests рассматриваются как локальные или first‑party, что естественным образом ставит их после numpy.

Как настроить порядок единообразно

Если test — это часть вашего проекта, а не стандартная библиотека, укажите isort, что его нужно считать локальным импортом. Тогда поведение станет согласованным с импортами из tests. Настроить это можно через параметр known_local_folder.

Через файл .isort.cfg:

[settings]
known_local_folder=test

Или в pyproject.toml:

[tool.isort]
known_local_folder = ["test"]

С такой конфигурацией импорты из test больше не будут попадать в секцию стандартной библиотеки, и расхождение с tests исчезнет.

Почему это важно знать

Порядок импортов влияет на диффы, код‑ревью и стабильность CI. Кажущееся безобидным решение назвать пакет test может незаметно изменить то, как isort классифицирует импорты, — в итоге появляются лишние перестановки и путаница между модулями. Осознание того, что isort сортирует по секциям и что некоторые имена зарезервированы за стандартной библиотекой, помогает избежать подобных сюрпризов.

Практические выводы

Либо не называйте собственные пакеты так же, как модули стандартной библиотеки, либо явно сообщайте isort, как их классифицировать. Если пакет с именем test у вас уже есть и вам важен стабильный порядок по всем файлам, задайте known_local_folder со значением test — тогда isort будет относиться к нему так же, как к tests. Это сохранит единообразное расположение сторонних импортов вроде numpy относительно модулей проекта и сократит лишние перестановки в блоках импортов.