Criando scripts Python autônomos com uv

• Como usar uv em scripts Python para criar scripts autônomos que podem ser executados imediatamente sem instalar dependências
• Uma abordagem prática que surgiu ao usar scripts Python para testes de API em um projeto Go

Limitações da abordagem anterior

• Para executar scripts Python que usam pacotes como httpx, IPython e loguru, era preciso escolher uma das opções abaixo
  • Instalar os pacotes diretamente no Python do sistema
  • Criar um ambiente virtual, instalar os pacotes e então executar
• Ambos os métodos são trabalhosos, podem afetar o ambiente do sistema e, ao compartilhar com outras pessoas, acabam exigindo explicações longas

Execução simplificada de scripts com uv

• uv é um gerenciador de pacotes Python e substituto do pip que permite executar scripts Python em um ambiente de execução isolado
• Com o comentário # /// script, é possível declarar as dependências dentro do próprio script

  # /// script  
  # dependencies = ["ipython", "httpx", "loguru"]  
  # ///  
  

• Um script com essa configuração pode ser executado com o seguinte comando:

  uv run jam_users.py  
  

• O uv cuida automaticamente de criar um ambiente virtual temporário, instalar os pacotes necessários e executar o script de uma só vez

Transformando em um script executável

• É possível torná-lo executável como um script Python comum usando #!/usr/bin/env python, mas essa abordagem não reconhece o comentário script do uv
• Em vez disso, isso pode ser resolvido colocando diretamente o comando do uv no shebang, como abaixo

  #!/usr/bin/env -S uv run --script  
  # /// script  
  # dependencies = ["ipython", "httpx", "loguru"]  
  # ///  
  

• Depois de usar chmod +x, ele pode ser executado diretamente e continua funcionando em outros sistemas Unix desde que o uv esteja instalado:

  ./jam_users.py  
  

Vantagens e utilidade

• A abordagem com uv é muito útil ao repassar scripts para outras pessoas
• Os pacotes e o ambiente necessários são configurados automaticamente sem preparação complexa
• Não polui o Python do sistema nem o ambiente global
• Um único script resolve tanto a execução quanto o gerenciamento de dependências

O autor explica que, no passado, teve dificuldade ao repassar scripts Python para outras pessoas por causa das instruções de instalação complicadas, mas que agora consegue resolver esse problema de forma simples com uv

• É eficaz não apenas para pequenos scripts de teste, mas também para scripts de automação usados no trabalho