Quando um pequeno escritório assume a manutenção de uma aplicação Python ou configura um novo computador, o conjunto de pacotes dessa aplicação deve ser rastreável. Com venv e pip, é possível preparar uma reconstrução controlada. São essenciais um ambiente inicial limpo, dependências verificadas e testes da aplicação. Uma exportação de pacotes, por si só, não garante uma reprodutibilidade universal.
1. Definir os pré-requisitos e o diretório de trabalho
Todos os exemplos Unix que se seguem destinam-se exclusivamente a um projeto de teste separado, não ao diretório da aplicação em produção. É necessário um interpretador Python já instalado, mantido atualizado e compatível com o projeto. Documente previamente:
- a versão prevista do interpretador, incluindo a versão secundária,
- o sistema operativo e a arquitetura do processador,
- o estado do projeto, a configuração necessária e os testes da aplicação disponíveis.
python3 representa aqui esse interpretador escolhido deliberadamente. Antes de começar, verifique a que interpretador corresponde; se necessário, utilize o seu caminho explícito. Não substitua o Python do sistema operativo nem altere o PATH global. Todos os caminhos relativos referem-se ao diretório raiz do projeto de teste. Nomes de ficheiros como requirements-snapshot.txt são exemplos escolhidos livremente e, se forem alterados, devem ser ajustados de forma consistente em todas as referências.
2. Preparar um ambiente de origem limpo
Crie um ambiente próprio, inicialmente limpo, para o estado previsto do projeto:
python3 -m venv .venv-srcInstale aí apenas as dependências previstas para o projeto de teste, de acordo com as respetivas instruções de instalação. Para tal, utilize explicitamente .venv-src/bin/python -m pip, para não atuar inadvertidamente sobre outro ambiente. Não importe um conjunto de pacotes não verificado de um ambiente de trabalho partilhado nem efetue atualizações indiscriminadas de pacotes.
Segundo a documentação do venv, os pacotes do projeto estão isolados por predefinição. No entanto, o ambiente continua associado ao seu interpretador de base e não constitui um ambiente isolado de segurança. Não é necessário ativá-lo quando se utilizam caminhos explícitos para o interpretador. Teste agora a aplicação com dados de teste adequados; só depois deverá efetuar a exportação.
3. Registar e verificar o conjunto de pacotes testado
.venv-src/bin/python -m pip freeze > requirements-snapshot.txtpip freeze apresenta os pacotes instalados. Não é um resolvedor de dependências que produza um ficheiro de bloqueio e, por predefinição, omite determinados pacotes de inicialização. Por isso, o ficheiro é um registo inicial do estado dos pacotes, não uma descrição completa do interpretador, das ferramentas e da plataforma.
Abra a exportação antes de a partilhar. Verifique, em particular, as instalações editáveis, os caminhos locais e os URL de pacotes privados. Remova as credenciais dos ficheiros partilhados. Esclareça também de que forma os pacotes privados necessários continuarão acessíveis com a devida autorização; a simples eliminação dessas entradas não permite uma reconstrução completa. Registe as dependências diretas e transitivas, em vez de listar apenas as bibliotecas utilizadas diretamente.
4. Reconstruir de forma independente e verificar
Mantenha .venv-src inalterado. Crie, em paralelo, o segundo ambiente com um interpretador adequado e compatível e instale a lista verificada:
python3 -m venv .venv-rebuild
.venv-rebuild/bin/python -m pip install -r requirements-snapshot.txt
.venv-rebuild/bin/python -m pip checkpip check verifica exclusivamente a compatibilidade das dependências declaradas. Um resultado sem problemas não substitui os testes da aplicação nem uma auditoria de segurança. Por isso, execute as mesmas verificações funcionais que no ambiente de origem: por exemplo, uma importação prevista, uma execução de processamento típica e a verificação dos resultados. Inicie também estas verificações explicitamente com .venv-rebuild/bin/python. Documente os erros e os resultados dos testes antes de aceitar a reconstrução.
5. Documentar a plataforma e os ficheiros dos pacotes com maior detalhe
Para uma maior rastreabilidade, registe também as versões de Python e pip utilizadas, bem como o sistema operativo e a arquitetura. Segundo o guia do pip para instalações repetíveis, a fixação completa das versões das dependências diretas e transitivas, bem como a verificação dos hashes dos pacotes, pode reforçar a fiabilidade do processo. Os hashes confirmam que os ficheiros dos pacotes são os esperados, não que estejam isentos de software malicioso. Os arquivos Wheel podem ser específicos de uma plataforma; por isso, um conjunto de pacotes disponível noutra arquitetura não é automaticamente equivalente.
6. Garantir o regresso ao estado anterior e registar o resultado
Conserve o ambiente anterior, bem como uma cópia de segurança da aplicação e dos dados, até a nova configuração estar verificada. Em caso de erro, descarte apenas o novo ambiente de teste e investigue a causa; a base de trabalho anterior permanece intacta. Os ambientes virtuais são recriados, não movidos nem copiados.
Conclusão: Uma reconstrução útil consiste numa exportação de pacotes verificada, numa plataforma documentada e em testes da aplicação bem-sucedidos. Esta combinação torna as alterações rastreáveis, sem confundir uma lista de pacotes com uma garantia abrangente de reprodutibilidade.