system/scripts/AUDIT_IMPORTS_README.md

Аудит импортов Python (audit_imports.py)

Скрипт для комплексной проверки импортов в Python файлах проекта.

Возможности

  1. Несуществующие модули - Выявляет импорты модулей, которые не существуют в проекте или не установлены
  2. Неиспользуемые импорты - Находит импорты, которые не используются в коде
  3. Циклические зависимости - Обнаруживает циклические импорты между модулями
  4. Устаревшие пути импортов - Предупреждает об импортах из старых путей (например, system/connectors → library/connectors)
  5. Синтаксические ошибки - Выявляет ошибки синтаксиса в Python файлах

Использование

Запуск аудита

python3 system/scripts/audit_imports.py

Проверяемые области

По умолчанию проверяются следующие директории:
- library/ - Переиспользуемые компоненты платформы
- system/ - Ядро платформы
- infra/ - Инфраструктурные сервисы
- projects/ - Бизнес-проекты

Выходные данные

Консольный вывод

================================================================================
АУДИТ ИМПОРТОВ PYTHON
================================================================================

📂 Найдено файлов: 719
📍 Области: library, system, infra, projects

СВОДКА:
--------------------------------------------------------------------------------
Проверено файлов:        719
Файлов с ошибками:       539

❌ Ошибки импортов:       1704
⚠️  Неиспользуемые:       1154
🔄 Устаревшие пути:      0
⛓️  Циклические зависим:  0
🔴 Синтаксические ошибки: 0

❌ МОДУЛИ НЕ НАЙДЕНЫ:
--------------------------------------------------------------------------------
  infra/@messenger.service/run.py:28 - src.bot_service
  infra/@messenger.service/run.py:29 - src.webhook_server
  ...

⚠️  НЕИСПОЛЬЗУЕМЫЕ ИМПОРТЫ (первые 30):
--------------------------------------------------------------------------------
  infra/@mail.service/check_mail.py:12 - datetime.datetime
  infra/@md-viewer.service/app.py:11 - pathlib.Path
  ...

CSV отчёт

Скрипт создаёт детальный CSV отчёт: system/scripts/audit_imports_report.csv

Формат:

TYPE,FILE,LINE,MODULE,DETAILS
ERROR_MODULE_NOT_FOUND,infra/@messenger.service/run.py,28,src.bot_service,Module 'src.bot_service' not found
WARNING_UNUSED,infra/@mail.service/check_mail.py,12,datetime.datetime,Unused import 'datetime.datetime'
WARNING_DEPRECATED,projects/pirotehnika/file.py,5,system.connectors.ozon,Update to: library.connectors.api.ozon

Встроенные модули

Скрипт знает о Python 3 встроенных модулях и популярных пакетах:
- Весь Python standard library
- numpy, pandas, sqlalchemy, fastapi, flask, django
- pytorch, tensorflow, transformers, scikit-learn
- И более 200 других популярных пакетов

Интерпретация ошибок

ERROR_MODULE_NOT_FOUND

Модуль не найден в проекте и не в списке встроенных модулей.

Возможные причины:
- Пакет не установлен
- Опечатка в имени модуля
- Относительный импорт в неправильном контексте
- Внешний пакет не в requirements.txt

Решение:

pip install package_name
# или
pip freeze > requirements.txt

WARNING_UNUSED

Импорт не используется в коде.

Возможные причины:
- Забыли удалить импорт при рефакторинге
- Импорт нужен для re-export (добавить в __all__)
- Импорт используется через косвенные пути

Решение:

# Если импорт нужен для re-export
from module import something
__all__ = ['something']

# Если не нужен - удалить

WARNING_DEPRECATED

Используется старый путь импорта.

Пример:

# Старо:
from system.connectors.api.ozon import OzonClient

# Ново:
from library.connectors.api.ozon import OzonClient

Примеры использования

Найти все неиспользуемые импорты в library/

python3 system/scripts/audit_imports.py | grep "WARNING_UNUSED"

Анализ CSV отчёта

# Ошибки импортов
grep "ERROR_MODULE_NOT_FOUND" system/scripts/audit_imports_report.csv | wc -l

# Группировка по файлам
cut -d, -f2 system/scripts/audit_imports_report.csv | sort | uniq -c | sort -rn

# Самые проблемные модули
grep "ERROR_MODULE_NOT_FOUND" system/scripts/audit_imports_report.csv | \
  cut -d, -f4 | sort | uniq -c | sort -rn | head -20

Экспорт в Excel

# Скопировать CSV в Excel
cp system/scripts/audit_imports_report.csv /tmp/audit_imports.csv
# Открыть в LibreOffice Calc или Excel

Технические детали

Архитектура

  1. ImportAnalyzer - AST-парсер для анализа импортов и их использования
  2. ImportAuditor - Основной класс для проверки модулей и сбора ошибок
  3. export_to_csv - Экспортирование результатов в CSV

Проверка существования модулей

Скрипт проверяет наличие модуля в следующем порядке:
1. Встроенные модули Python
2. Популярные пакеты (numpy, pandas, etc.)
3. Директории library/, system/, infra/
4. Директории в projects/

Анализ использования импортов

Используется AST (Abstract Syntax Tree) для анализа:
- Прямых ссылок на импортированные имена
- Использования через точку (module.function)
- Игнорируются подчёркивания (_) и all

Ограничения

  1. Не проверяет динамические импорты: __import__(), importlib.import_module()
  2. Не разрешает относительные импорты в полную форму (может быть false positive)
  3. TYPE_CHECKING импорты могут быть ошибочно помечены как неиспользуемые
  4. Циклические зависимости обнаруживаются только на уровне файлов, не модулей

Развитие

Планируемые улучшения:
- [ ] Поддержка динамических импортов
- [ ] Анализ requirements.txt и pyproject.toml
- [ ] Генерация графов зависимостей
- [ ] Автоматическое исправление устаревших путей
- [ ] Интеграция с pre-commit hooks
- [ ] Анализ производительности импортов

Контакт

Скрипт является частью системы аудита платформы.
Вопросы и предложения в system/CLAUDE.md.