Чтобы протестировать wheel-пакет, фактически собранный вашим проектом, создайте чистое виртуальное окружение macOS, установите файл wheel из dist/ и проверьте правильность его метаданных и поведения импорта. Выполните приведенные ниже команды из каталога проекта в Терминале. Это проверит установку для используемой версии Python и архитектуры Mac; тест не гарантирует совместимость со всеми поддерживаемыми версиями Python или моделями Mac.

1. Сборка wheel-пакета из вашего проекта

Используйте тот интерпретатор Python, который вы хотите протестировать. В macOS python3 является стандартной командой для Python 3; если вы используете менеджер версий, сначала выберите нужный интерпретатор. Из каталога, содержащего pyproject.toml, соберите wheel с помощью инструмента build от Python Packaging Authority: руководство Packaging Python Projects описывает этот этап сборки и итоговый каталог dist/.

python3 -m pip install --upgrade build
python3 -m build --wheel

Команда сборки создает файл .whl в dist/. Сборка из корня проекта делает артефакт доступным для последующего теста установки. Wheel — это скомпилированный/собранный дистрибутив (built distribution), который вы хотите протестировать; установка каталога проекта напрямую или использование редактируемого режима (editable mode) тестировали бы другой сценарий установки. См. The Packaging Flow, где описывается разница между деревом исходного кода, артефактами сборки и установкой.

2. Создание чистого виртуального окружения

Создайте окружение в каталоге проекта, но держите результат сборки отдельно от него. Если папка .venv-wheel-test уже существует и вам нужен чистый запуск, сначала удалите её; эта команда безвозвратно удаляет данный каталог и его содержимое, поэтому проверьте путь перед запуском.

rm -rf .venv-wheel-test
python3 -m venv .venv-wheel-test
source .venv-wheel-test/bin/activate
python -m pip --version

В выведенном пути к pip должен присутствовать .venv-wheel-test. Модуль Python venv создает изолированное окружение на основе интерпретатора, использованного для его создания, с собственным набором установленных пакетов; оболочка zsh, используемая по умолчанию в Терминале macOS, поддерживает показанную команду активации source. Документация по venv в Python объясняет как изоляцию, так и активацию. Чтобы не зависеть от активации окружения или от того, какой именно python находится в вашем системном пути shell, используйте .venv-wheel-test/bin/python вместо python в последующих командах.

3. Установка файла wheel, а не каталога с исходным кодом

Выведите список файлов wheel, чтобы определить точный артефакт для тестирования:

ls dist/*.whl

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

python -m pip install "dist/my_package-1.2.3-py3-none-any.whl"

Это установит локальный wheel-пакет и при необходимости разрешит его объявленные зависимости из настроенного индекса пакетов. При этом ваш каталог с исходными кодами не устанавливается. pip поддерживает установку напрямую из локальных архивов дистрибутивов, как описано в Install packages in a virtual environment using pip and venv. Если тест должен работать без доступа к сети, сделайте зависимости wheel-пакета доступными локально; в противном случае разрешение зависимостей может завершиться ошибкой. Если вы используете --no-deps, pip пропустит установку зависимостей, поэтому операции импорта, требующие эти пакеты, могут завершиться сбоем, даже если сам wheel установился корректно.

4. Проверка установки и поведения импорта

Проверьте метаданные установленного дистрибутива и согласованность объявленных зависимостей:

python -m pip show my-package
python -m pip check

Для команды pip show используйте название дистрибутива, указанное в имени файла wheel или метаданных проекта; оно может отличаться от имени импорта в Python. Затем протестируйте импорт, используя имя модуля, указанное в документации вашего пакета. Например, если модуль называется my_package, выполните:

python -c 'import my_package; print(my_package.__file__)'

Успешный импорт, при котором путь к файлу указывает внутрь .venv-wheel-test, свидетельствует о том, что установленный пакет импортируется именно из тестового окружения. Один только импорт не тестирует каждую функцию или точку входа: запустите соответствующие тесты вашего проекта в этом окружении, если вам необходимо поведенческое покрытие.

Если wheel не удается установить

Ошибка о несовместимости wheel обычно означает, что его теги совместимости не соответствуют активной версии Python, macOS или архитектуре процессора. Пакеты Wheel, содержащие скомпилированные расширения, могут зависеть от платформы; чисто питоновский (pure-Python) wheel обычно имеет более широкую совместимость. Спецификация platform compatibility tags объясняет, как установщики используют эти теги. Соберите или получите совместимый wheel для интерпретатора и архитектуры Mac, которые вы намерены поддерживать, а затем повторите тест в заново созданном окружении.

Если установка прошла успешно, но импорт завершился ошибкой, убедитесь, что имя импорта указано верно и что необходимые зависимости среды выполнения объявлены проектом. Если wheel устанавливается, но в нем отсутствует модуль или файл данных, проверьте содержимое wheel и исправьте конфигурацию упаковки проекта перед повторной сборкой. Чистое окружение помогает выявить необъявленные зависимости и отсутствующие в пакете файлы, которые могут маскироваться пакетами или исходными файлами в среде разработки.

Успешная установка, проверка зависимостей и целевой импорт подтверждают корректную работу основных частей wheel-пакета на данном Mac и данной версии Python. Они не подтверждают работоспособность на других платформах или версиях Python; тестируйте их отдельно с соответствующими интерпретаторами и совместимыми сборками wheel.

Источники