Compreender as mudanças significativas nos pacotes

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

Esta página contém informações detalhadas sobre o pacote pre-1.0 Qiskit e o motivo pelo qual fizemos as alterações no pacote.

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

Prefácio: glossário de terminologia de embalagens da Python

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

• Clique para expandir e ler o glossário desta página.

  • módulo : Um único arquivo Python.

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

    Esse não é o mesmo objeto que você pip install (que é uma distribuição ), mas normalmente o que você pip install e o que você import têm o mesmo nome.

  • submódulo, subpacote : Esses são termos imprecisos, mas são comumente usados. A subparte significa "contido em uma embalagem". 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. É importante ressaltar que nenhuma distribuição que contribui para um pacote de namespace é necessariamente proprietária de todos os arquivos instalados, portanto, pode ser complicado desinstalar completamente o ou atualizar uma delas.

  • distribuição : Os arquivos compactados Python, arquivos de dados e metadados que são baixados quando você executa pip install something. Em geral, 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ê estiver familiarizado com "gerenciadores de pacotes" fora do contexto de Python, como apt de Debian / Ubuntu ou Homebrew em macOS,, então o que eles chamam de "pacote", Python chama de distribuição, e não há correspondência exata para o que Python chama de pacote.

    A maioria das fontes que falam sobre o empacotamento do Python usa o termo pacote para se referir tanto a distribuições quanto a pacotes, e você deve consultar o contexto para entender o que significa. Em geral, se você import , o código-fonte significa "pacote" e, se você pip install , o código-fonte significa "distribuição".

  • caminho de pesquisa : Ao tentar acessar import something, Python pesquisa uma lista predefinida de locais para um módulo ou pacote chamado something. A lista de locais é o caminho de pesquisa. Você pode ver e modificar o caminho de pesquisa 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 necessária é um requisito, e o gerenciador de pacotes (geralmente pip ou conda) deve garantir que todos os requisitos sejam instalados com versões compatíveis.

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 pesquisa não é apenas uma pesquisa em diretórios, mas, para esta discussão, apenas os arquivos no disco são relevantes. Não são necessárias complicações adicionais para entender os problemas descritos nesta seção, portanto, você pode usar o modelo descrito acima.

A antiga estrutura Qiskit

Historicamente, o Qiskit era composto de 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, agora obsoletos, que fornecem recursos específicos de algoritmos exploratórios ou de execução de experimentos. Para facilitar para o usuário, também fornecemos uma distribuição Python chamada qiskit, que não continha 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 estava em qiskit-terra, que possuía a 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 causou alguns problemas para nós e nossos usuários.

Por exemplo, as bibliotecas downstream que dependiam do Qiskit geralmente só precisavam do núcleo do compilador e não precisavam do restante do grande ecossistema que acompanhava o pip install qiskit. Portanto, eles especificariam corretamente seu requisito como qiskit-terra. No entanto, quando as pessoas tentavam desinstalar o Qiskit executando pip uninstall qiskit, pip encontrava problemas:

• pip não remove as distribuições que agora não estão sendo usadas. Portanto, o site pip uninstall qiskit não fez quase nada; não havia código na distribuição, portanto, nenhum código foi removido.
• Mesmo que o código fosse removido, muitas distribuições downstream permaneceriam instaladas porque dependiam do qiskit-terra.
• Mesmo que o qiskit-terra tenha sido desinstalado, ele ainda poderá deixar um diretório qiskit importável sem nenhum código utilizável, porque 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 as resoluções de requisitos anteriores. Como havia dois pacotes, a atualização de um pacote que exigia a atualização do qiskit-terra causou um ambiente inválido; o pip atualizou o qiskit-terra , mas deixou o qiskit intocado. Ele emitiu um aviso sobre esse e todos os comandos subsequentes do pip install , mas como nada parecia estar quebrado, os usuários normalmente ignoravam o aviso e o pip não gerava um status de erro nem proibia as operações.

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

Da mesma forma, cada vez mais desencorajamos outras bibliotecas a usar os ganchos de namespace. Removemos o último uso dos hooks pelo Qiskit em pacotes não obsoletos com o lançamento do Qiskit Aer v0.11 e seu novo pacote qiskit_aer Python, embora até o Qiskit v1.0 também tenhamos forçado o caminho do namespace qiskit.providers.aer a funcionar. A partir do Qiskit v1.0, removemos a capacidade dos pacotes de estender qualquer espaço de nome qiskit . Portanto, o site pip uninstall na distribuição correta em um ambiente válido agora funciona conforme o 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 possui todo o código contido em seu diretório. Essa é a estrutura normal do código Python e é a estrutura mais simples e menos propensa a erros.

A distribuição qiskit-terra em PyPI nunca será atualizada para a versão 1.0 ou posterior; ela é totalmente 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 de PyPI, e deixaremos sua versão mais recente em um estado funcional, para que o código científico antigo e os pacotes legados possam continuar a usá-lo com mais facilidade.

Infelizmente, devido ao legado do metapacote e às deficiências do pip como gerenciador de pacotes, não é possível criar um caminho de atualização completamente tranquilo para os usuários do Qiskit v1.0, especialmente porque alguns pacotes dependem de versões anteriores do Qiskit e alguns exigem 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 do aplicativo?

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 metapacotes, 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 várias 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, agora obsoletos, que fornecem recursos específicos de algoritmos exploratórios ou de execução de experimentos.

Se você deseja instalar os pacotes que antes faziam parte do metapacote Qiskit, acesse o ecossistema Qiskit para encontrar uma variedade de pacotes que atendam às suas necessidades. Você também pode ler o guia de migração do v1.0 para obter mais informações sobre como instalar a nova distribuição.