Para probar el wheel que realmente construyó su proyecto, cree un entorno virtual limpio en macOS, instale el archivo wheel desde dist/ y compruebe que sus metadatos y su comportamiento de importación sean correctos. Ejecute los comandos siguientes desde el directorio de su proyecto en Terminal. Esto prueba la instalación para la versión de Python y la arquitectura de Mac que utilizó; no determina la compatibilidad con todas las versiones de Python o Mac admitidas.

1. Construir el wheel a partir de su proyecto

Utilice el intérprete de Python que desea probar. En macOS, python3 es un comando habitual para Python 3; si utiliza un gestor de versiones, seleccione primero el intérprete deseado. Desde el directorio que contiene pyproject.toml, construya un wheel con la herramienta build de la Python Packaging Authority: Packaging Python Projects documenta este paso de compilación y el directorio dist/ resultante.

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

El comando build crea un archivo .whl en dist/. Construirlo desde la raíz del proyecto hace que el artefacto esté disponible para la prueba de instalación posterior. Un wheel es la distribución compilada que desea probar; instalar el directorio del proyecto o utilizar el modo editable probaría una vía de instalación diferente. Consulte The Packaging Flow para conocer la diferencia entre un árbol de código fuente, los artefactos de compilación y la instalación.

2. Crear un entorno virtual limpio

Cree el entorno en el directorio del proyecto, pero mantenga la salida de compilación separada de él. Si .venv-wheel-test ya existe y desea una ejecución limpia, elimínelo primero; este comando borra permanentemente ese directorio específico y su contenido, así que confirme la ruta antes de ejecutarlo.

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

La ruta de pip reportada debe contener .venv-wheel-test. El módulo venv de Python crea un entorno aislado basado en el intérprete utilizado para crearlo, con sus propios paquetes instalados; el zsh predeterminado de macOS Terminal admite el comando de activación source que se muestra aquí. La documentación de venv de Python explica tanto el aislamiento como la activación. Para evitar depender de la activación o de qué python se encuentra en la ruta de su shell, utilice .venv-wheel-test/bin/python en lugar de python en los comandos restantes.

3. Instalar el archivo wheel, no el directorio de origen

Liste los archivos wheel para que pueda identificar el artefacto exacto que va a probar:

ls dist/*.whl

Copie el nombre de archivo deseado de la salida en el comando siguiente. Conserve las comillas y reemplace el nombre de archivo de ejemplo por el real. El nombre de archivo con guiones mostrado es ilustrativo; los nombres de los wheels incluyen el nombre de la distribución, la versión y las etiquetas de compatibilidad, por lo que el suyo será diferente.

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

Esto instala el wheel local y resuelve sus dependencias declaradas desde el índice de paquetes configurado si es necesario. No instala su directorio de origen. pip admite la instalación directa de archivos de distribución locales, como se describe en Install packages in a virtual environment using pip and venv. Si la prueba debe funcionar sin acceso a la red, haga que las dependencias del wheel también estén disponibles localmente; de lo contrario, la resolución de dependencias podría fallar. Si utiliza --no-deps, pip omite la instalación de dependencias, por lo que las importaciones que requieran esos paquetes pueden fallar incluso cuando el wheel en sí se instale correctamente.

4. Comprobar la instalación y el comportamiento de importación

Verifique los metadatos de la distribución instalada y si sus dependencias declaradas son consistentes:

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

Utilice el nombre de la distribución que se muestra en el nombre de archivo del wheel o en los metadatos del proyecto para pip show; este puede diferir del nombre de importación en Python. Luego pruebe una importación utilizando el nombre de módulo que documenta su paquete. Por ejemplo, si el módulo es my_package, ejecute:

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

Una importación exitosa cuya ruta de archivo apunte al interior de .venv-wheel-test es evidencia de que el paquete instalado se está importando desde el entorno de prueba. Una importación por sí sola no prueba cada función o punto de entrada: ejecute las pruebas relevantes de su proyecto contra este entorno si necesita cobertura de comportamiento.

Cuando falla la instalación de un wheel

Un error sobre un wheel incompatible suele significar que sus etiquetas de compatibilidad no coinciden con la versión activa de Python, de macOS o con la arquitectura de la CPU. Los wheels que contienen extensiones compiladas pueden ser específicos de una plataforma; un wheel de Python puro puede tener un uso más amplio. La especificación de etiquetas de compatibilidad de plataformas explica cómo utilizan esas etiquetas los instaladores. Construya u obtenga un wheel compatible para el intérprete y la arquitectura de Mac que pretende admitir, y luego repita la prueba en un entorno recién creado.

Si la instalación se completa correctamente pero falla una importación, compruebe que el nombre de importación sea correcto y que las dependencias de tiempo de ejecución requeridas estén declaradas por el proyecto. Si el wheel se instala pero omite un módulo o un archivo de datos, inspeccione el contenido del wheel y corrija la configuración de empaquetado del proyecto antes de volver a compilar. Un entorno limpio ayuda a exponer dependencias no declaradas y archivos empaquetados faltantes que podrían quedar enmascarados por paquetes o archivos de origen en un entorno de desarrollo.

Una instalación exitosa, la comprobación de dependencias y una importación específica confirman aspectos útiles del comportamiento del wheel en esta versión de Mac y Python. No verifican otras plataformas o versiones de Python; pruébelas por separado con intérpretes correspondientes y compilaciones de wheels compatibles.

Fuentes