Entenda as mudanças de pacote do Qiskit v1.0 que causam quebra de compatibilidade

O Qiskit v1.0 usa uma estrutura de empacotamento diferente das versões anteriores do Qiskit e provavelmente causará problemas em ambientes que utilizam pacotes que ainda não estão prontos para o Qiskit v1.0.

cuidado

Não tente atualizar um ambiente virtual Python existente para o Qiskit v1.0 no próprio local.

Não faremos mudanças de empacotamento semelhantes que quebrem compatibilidade no futuro. Este é um evento único, no lançamento do Qiskit v1.0, especificamente para que nossa história de empacotamento seja a mais simples possível no futuro.

Esta página contém informações detalhadas sobre o pacote Qiskit anterior à versão 1.0 e por que fizemos as mudanças de empacotamento que causam quebra de compatibilidade.

Sabemos que a mudança é inconveniente, mas ela restaura o Qiskit à estrutura de pacote simples que a maioria dos pacotes Python utiliza, o que será mais fácil para usuários, desenvolvedores e autores de bibliotecas após a conclusão da transição para o Qiskit v1.0.

Prefácio: glossário de terminologia de empacotamento Python

Para explicar melhor como o antigo metapacote do Qiskit era estruturado e como isso mudou com o lançamento do Qiskit v1.0, abaixo está um glossário de jargões comumente usados no empacotamento Python. As palavras a seguir têm significados específicos que usaremos neste documento.

Clique aqui para ler o glossário desta página

• módulo: Um único arquivo Python.

• pacote: Um diretório contendo um __init__.py e outros arquivos ou pacotes que o Python pode ler. Este é o código real instalado no seu computador, e é o que é executado quando você roda import something. O Python considera qualquer diretório que esteja no caminho de busca como algo que você pode importar (e importará muitos itens adicionais).

  Este não é o mesmo objeto que você instala com pip install (que é uma distribuição), mas tipicamente o que você instala com pip install e o que você importa com import têm o mesmo nome.

• submódulo, subpacote: Estes são termos imprecisos, mas são comumente usados. A parte sub significa "contido dentro de um pacote". Um submódulo é um módulo e um subpacote é um pacote, mas eles fazem parte de um pacote maior.

• pacote de namespace: Um pacote que pode ter submódulos ou subpacotes instalados nele por outras distribuições. De forma importante, nenhuma distribuição que contribui para um pacote de namespace necessariamente possui todos os arquivos instalados, por isso pode ser complicado desinstalar completamente ou atualizar um deles.

• distribuição: Os arquivos Python comprimidos, arquivos de dados e metadados que são baixados quando você executa pip install something. Geralmente, uma distribuição contém exatamente um pacote e os metadados sobre como instalá-lo (seus requisitos e assim por diante), mas isso não é obrigatório. Uma distribuição pode conter zero ou mais módulos ou pacotes.

  Se você está familiarizado com "gerenciadores de pacotes" fora do contexto do Python, como apt do Debian/Ubuntu ou Homebrew no macOS, então o que eles chamam de "pacote", o Python chama de distribuição, e não há equivalente exato para o que o Python chama de pacote.

  A maioria das fontes que falam sobre empacotamento Python usa o termo pacote para se referir tanto a distribuições quanto a pacotes, e você precisa recorrer ao contexto para entender o que se quer dizer. Em geral, se você usa import, a fonte quer dizer "pacote", e se você usa pip install, a fonte quer dizer "distribuição".

• caminho de busca: Ao tentar executar import something, o Python pesquisa numa lista predefinida de lugares por um módulo ou pacote chamado something. A lista de lugares é o caminho de busca. Você pode ver e modificar o caminho de busca em sys.path.

• requisito: Uma distribuição contém informações sobre outras distribuições das quais ela depende quando instalada. Qualquer outra distribuição que for necessária é um requisito, e o gerenciador de pacotes (geralmente pip ou conda) deve garantir que todos os requisitos estejam instalados com versões compatíveis.

O Python é altamente dinâmico, e muitas complexidades podem surgir; por exemplo, é possível que um módulo ou pacote não corresponda a arquivos no disco, ou que sejam extensões compiladas.

O caminho de busca não é apenas uma busca em diretórios, mas para esta discussão, apenas os arquivos em disco são relevantes. Complicações adicionais não são necessárias para entender os problemas descritos nesta seção, então você pode usar o modelo descrito acima.

A antiga estrutura do Qiskit

Historicamente, o Qiskit era composto por muitas distribuições Python: qiskit-terra, o núcleo do compilador; qiskit-aer, o simulador de alto desempenho; o provedor IBM Quantum® original; e vários pacotes hoje obsoletos que forneciam funcionalidades algorítmicas exploratórias específicas ou recursos para execução de experimentos. Para facilitar o uso, também fornecemos uma distribuição Python chamada qiskit, que não continha nenhum código próprio, mas fazia com que todos os outros componentes fossem instalados. Chamamos isso de metapacote, por analogia a conceitos semelhantes em outros gerenciadores de pacotes. O código do núcleo do Qiskit vivia em qiskit-terra, que era dono da raiz do pacote Python qiskit. Em outras palavras, qiskit-terra controlava o que acontecia quando você executava import qiskit. Até o Qiskit v1.0, o pacote qiskit era um pacote de namespace e continha um segundo pacote de namespace em qiskit.providers.

Essa organização nos causou, a nós e aos nossos usuários, vários problemas.

Por exemplo, bibliotecas downstream que dependiam do Qiskit muitas vezes precisavam apenas do núcleo do compilador, e não requeriam o restante do grande ecossistema que vinha com pip install qiskit. Portanto, elas especificavam corretamente seu requisito como qiskit-terra. No entanto, quando as pessoas tentavam desinstalar o Qiskit executando pip uninstall qiskit, o pip encontrava problemas:

• pip não remove distribuições que não estão mais em uso. Então pip uninstall qiskit não fazia quase nada; não havia código na distribuição, então nenhum código era removido.
• Mesmo que fosse remover o código, muitas distribuições downstream permaneceriam instaladas porque dependiam de qiskit-terra.
• Mesmo que qiskit-terra fosse desinstalado, ainda poderia deixar um diretório qiskit importável sem código utilizável, pois era um pacote de namespace.

Ao instalar ou atualizar distribuições com um comando pip install, o pip também não leva em conta resoluções de requisitos anteriores. Como havia dois pacotes, atualizar um pacote que exigia que qiskit-terra fosse atualizado causava um ambiente inválido; o pip atualizava qiskit-terra mas deixava qiskit intocado. Ele emitia um aviso neste e em todos os comandos pip install subsequentes, mas como nada parecia quebrado, os usuários geralmente ignoravam o aviso, e o pip não emitia um status de erro nem proibia operações.

Com o tempo, removemos elementos do metapacote qiskit até que, a partir do Qiskit v0.44, apenas qiskit-terra permanece. Desses componentes, qiskit-aer ainda existe e é atualizado ativamente, mas agora é instalado como uma distribuição separada.

Da mesma forma, cada vez mais desencorajamos outras bibliotecas de usar os ganchos de namespace. Removemos o último uso do Qiskit dos ganchos em pacotes não obsoletos com o lançamento do Qiskit Aer v0.11 e seu novo pacote Python qiskit_aer, embora até o Qiskit v1.0 também tenhamos forçado o caminho de namespace qiskit.providers.aer a funcionar. A partir do Qiskit v1.0, removemos a capacidade de pacotes estenderem qualquer namespace qiskit. Assim, pip uninstall na distribuição correta em um ambiente válido agora funciona como esperado.

A nova estrutura do Qiskit

A partir da versão 1.0, o Qiskit compreende uma única distribuição, chamada qiskit, que instala um único pacote, também chamado qiskit, que é dono de todo o código contido em seu diretório. Esta é a estrutura normal do código Python, e é a estrutura mais simples e menos propensa a erros.

A distribuição qiskit-terra no PyPI nunca será atualizada para a versão 1.0 ou posterior; ela foi completamente substituída por qiskit. O nome qiskit-terra não está mais envolvido na instalação. No entanto, o pacote qiskit-terra não está sendo removido do PyPI, e deixaremos sua versão mais recente em um estado funcional, para que código científico antigo e pacotes legados possam continuar a utilizá-lo com mais facilidade.

Infelizmente, por causa do legado do metapacote e das deficiências do pip como gerenciador de pacotes, não é possível para nós criar um caminho de atualização completamente suave para os usuários para o Qiskit v1.0, especialmente enquanto alguns pacotes dependem de versões anteriores do Qiskit e outros requerem apenas o Qiskit v1.0+. Esses problemas diminuirão à medida que mais do ecossistema migrar para o Qiskit v1.0.

Para onde foram os módulos de aplicação?

Você pode notar que o comando pip install qiskit não incluirá mais pacotes como qiskit-aer ou qiskit-nature. Com a remoção da estrutura de metapacote, muitos desses pacotes foram divididos em distribuições que precisam ser instaladas separadamente.

Antes do lançamento do Qiskit SDK v1.0, o Qiskit era composto por muitas distribuições Python diferentes, como qiskit-terra, o núcleo do compilador; qiskit-aer, o simulador de alto desempenho; o provedor IBM Quantum® original; e vários pacotes hoje obsoletos que forneciam funcionalidades algorítmicas exploratórias específicas ou recursos para execução de experimentos.

Se você quiser instalar os pacotes que anteriormente estavam incluídos no metapacote do Qiskit, visite o ecossistema Qiskit para encontrar uma variedade de pacotes que atendam às suas necessidades. Você também pode ler o guia de migração v1.0 para mais informações sobre como instalar a nova distribuição.