Comprender los cambios de paquetes incompatibles de Qiskit v1.0

Qiskit v1.0 utiliza una estructura de empaquetado diferente a la de las versiones anteriores de Qiskit y probablemente causará problemas en entornos que usen paquetes que no estén preparados para Qiskit v1.0.

precaución

No intentes actualizar un entorno virtual de Python existente a Qiskit v1.0 directamente.

No realizaremos cambios de empaquetado incompatibles similares en el futuro. Este es un evento único, al momento del lanzamiento de Qiskit v1.0, específicamente para que nuestra gestión de paquetes sea lo más sencilla posible en el futuro.

Esta página contiene información detallada sobre el paquete Qiskit anterior a la versión 1.0 y por qué realizamos los cambios de empaquetado incompatibles.

Sabemos que el cambio es inconveniente, pero esto restaura Qiskit a la estructura de paquete simple que utiliza la mayoría de los paquetes de Python, lo que será más fácil para usuarios, desarrolladores y autores de bibliotecas una vez que se complete la transición a Qiskit v1.0.

Prefacio: glosario de terminología de empaquetado de Python

Para explicar mejor cómo estaba estructurado el antiguo metapaquete de Qiskit y cómo cambió con el lanzamiento de Qiskit v1.0, a continuación se presenta un glosario de la jerga comúnmente usada en el empaquetado de Python. Las siguientes palabras tienen significados específicos que usaremos en este documento.

Haz clic aquí para leer el glosario de esta página

• módulo: Un único archivo de Python.

• paquete: Un directorio que contiene un __init__.py y otros archivos o paquetes que Python puede leer. Este es el código real tal como está instalado en tu computadora, y es lo que se ejecuta cuando corres import something. Python considera que cualquier directorio que esté en la ruta de búsqueda es algo que puedes importar (e importará muchos elementos adicionales).

  No es el mismo objeto que instalas con pip install (que es una distribución), pero típicamente lo que instalas con pip install y lo que importas tienen el mismo nombre.

• submódulo, subpaquete: Estos son términos imprecisos, pero de uso común. La parte sub significa "contenido dentro de un paquete". Un submódulo es un módulo y un subpaquete es un paquete, pero forman parte de un paquete más grande.

• paquete de espacio de nombres: Un paquete en el que otras distribuciones pueden instalar submódulos o subpaquetes. Es importante destacar que ninguna distribución que contribuya a un paquete de espacio de nombres necesariamente posee todos los archivos instalados, por lo que puede ser complicado desinstalarlo o actualizarlo por completo.

• distribución: Los archivos de Python comprimidos, archivos de datos y metadatos que se descargan cuando ejecutas pip install something. Por lo general, una distribución contiene exactamente un paquete y los metadatos sobre cómo instalarlo (sus requisitos, etc.), pero esto no es obligatorio. Una distribución puede contener cero o más módulos o paquetes.

  Si estás familiarizado con los "gestores de paquetes" fuera del contexto de Python, como apt de Debian/Ubuntu o Homebrew en macOS, lo que ellos llaman "paquete", Python lo llama distribución, y no hay equivalente exacto para lo que Python llama paquete.

  La mayoría de las fuentes que hablan sobre el empaquetado de Python usan el término paquete para referirse tanto a distribuciones como a paquetes, y debes referirte al contexto para entender qué se quiere decir. En general, si lo importas con import, la fuente se refiere a "paquete", y si lo instalas con pip install, la fuente se refiere a "distribución".

• ruta de búsqueda: Al intentar import something, Python busca en una lista predefinida de lugares un módulo o paquete llamado something. La lista de lugares es la ruta de búsqueda. Puedes ver y modificar la ruta de búsqueda en sys.path.

• requisito: Una distribución contiene información sobre otras distribuciones de las que depende al instalarse. Cualquier otra distribución que sea necesaria es un requisito, y el gestor de paquetes (generalmente pip o conda) debe asegurarse de que todos los requisitos estén instalados con versiones compatibles.

Python es altamente dinámico y pueden surgir muchas complejidades; por ejemplo, es posible que un módulo o paquete no corresponda a archivos en disco, o que sean extensiones compiladas.

La ruta de búsqueda no es solo una búsqueda en directorios, pero para esta discusión, solo son relevantes los archivos en disco. Las complicaciones adicionales no son necesarias para entender los problemas descritos en esta sección, por lo que puedes usar el modelo descrito anteriormente.

La antigua estructura de Qiskit

Históricamente, Qiskit estaba compuesto por muchas distribuciones de Python: qiskit-terra, el núcleo del compilador; qiskit-aer, el simulador de alto rendimiento; el proveedor original de IBM Quantum®; y varios paquetes ahora obsoletos que ofrecían características algorítmicas exploratorias o de ejecución de experimentos. Para facilitar el uso, también proporcionamos una distribución de Python llamada qiskit, que no contenía código propio, pero hacía que todos los demás componentes se instalaran. A esto lo llamamos el metapaquete, por analogía con conceptos similares en otros gestores de paquetes. El código del núcleo de Qiskit vivía en qiskit-terra, que era propietario de la raíz del paquete de Python qiskit. En otras palabras, qiskit-terra controlaba lo que ocurría al ejecutar import qiskit. Hasta Qiskit v1.0, el paquete qiskit era un paquete de espacio de nombres y contenía un segundo paquete de espacio de nombres en qiskit.providers.

Esta organización nos causó a nosotros y a nuestros usuarios bastantes problemas.

Por ejemplo, las bibliotecas externas que dependían de Qiskit a menudo solo necesitaban el núcleo del compilador y no requerían el resto del gran ecosistema que venía con pip install qiskit. Por ello, correctamente especificaban su requisito como qiskit-terra. Sin embargo, cuando la gente intentaba desinstalar Qiskit ejecutando pip uninstall qiskit, pip encontraba problemas:

• pip no elimina las distribuciones que ya no se usan. Por lo tanto, pip uninstall qiskit no hacía casi nada; no había código en la distribución, por lo que no se eliminaba ningún código.
• Incluso si se eliminara el código, muchas distribuciones externas permanecerían instaladas porque dependían de qiskit-terra.
• Incluso si se desinstalara qiskit-terra, podría seguir quedando un directorio qiskit importable sin código utilizable, porque era un paquete de espacio de nombres.

Al instalar o actualizar distribuciones con un comando pip install, pip tampoco tiene en cuenta las resoluciones de requisitos anteriores. Debido a que había dos paquetes, actualizar un paquete que requería que qiskit-terra fuera actualizado causaba un entorno inválido; pip actualizaba qiskit-terra pero dejaba qiskit sin cambios. Emitía una advertencia en ese y en todos los comandos pip install posteriores, pero como nada parecía estar roto, los usuarios normalmente ignoraban la advertencia, y pip no generaba un estado de error ni impedía las operaciones.

Con el tiempo, fuimos eliminando elementos del metapaquete qiskit hasta que, a partir de Qiskit v0.44, solo queda qiskit-terra. De estos componentes, qiskit-aer sigue existiendo y se actualiza activamente, pero ahora se instala como una distribución separada.

De manera similar, desaconsejamos cada vez más que otras bibliotecas usaran los ganchos del espacio de nombres. Eliminamos el último uso de Qiskit de los ganchos en paquetes no obsoletos con el lanzamiento de Qiskit Aer v0.11 y su nuevo paquete de Python qiskit_aer, aunque hasta Qiskit v1.0 también forzamos que funcionara la ruta de espacio de nombres qiskit.providers.aer. A partir de Qiskit v1.0, hemos eliminado la capacidad de que los paquetes extiendan cualquier espacio de nombres de qiskit. Por lo tanto, pip uninstall sobre la distribución correcta en un entorno válido ahora funciona como se espera.

La nueva estructura de Qiskit

A partir de la versión 1.0, Qiskit comprende una única distribución, llamada qiskit, que instala un único paquete, también llamado qiskit, que es propietario de todo el código contenido en su directorio. Esta es la estructura normal del código Python y es la estructura más simple y menos propensa a errores.

La distribución qiskit-terra en PyPI nunca se actualizará a la versión 1.0 o posterior; está completamente reemplazada por qiskit. El nombre qiskit-terra ya no interviene en la instalación. Sin embargo, el paquete qiskit-terra no se está eliminando de PyPI, y dejaremos su versión más reciente en un estado funcional, para que el código científico antiguo y los paquetes heredados puedan seguir usándolo más fácilmente.

Desafortunadamente, debido al legado del metapaquete y las deficiencias de pip como gestor de paquetes, no nos es posible proporcionar una ruta de actualización completamente fluida a Qiskit v1.0, especialmente mientras algunos paquetes dependen de versiones anteriores de Qiskit y otros requieren solo Qiskit v1.0+. Estos problemas disminuirán a medida que más del ecosistema migre a Qiskit v1.0.

¿A dónde fueron los módulos de aplicación?

Es posible que notes que el comando pip install qiskit ya no incluye paquetes como qiskit-aer o qiskit-nature. Con la eliminación de la estructura del metapaquete, muchos de estos paquetes se dividieron en distribuciones que deben instalarse por separado.

Antes del lanzamiento del SDK de Qiskit v1.0, Qiskit estaba compuesto por muchas distribuciones de Python diferentes, como qiskit-terra, el núcleo del compilador; qiskit-aer, el simulador de alto rendimiento; el proveedor original de IBM Quantum®; y varios paquetes ahora obsoletos que ofrecían características algorítmicas exploratorias o de ejecución de experimentos.

Si deseas instalar los paquetes que anteriormente estaban incluidos en el metapaquete de Qiskit, visita el ecosistema de Qiskit para encontrar una variedad de paquetes que se adapten a tus necesidades. También puedes leer la guía de migración a v1.0 para obtener más información sobre cómo instalar la nueva distribución.