# 11.1. Ferramentas Úteis Bem-vindo à aula sobre Ferramentas Úteis! Este é um guia essencial para entender como preparar corretamente seu ambiente de desenvolvimento Python. ## Sumário - [Por que preparar o ambiente?](#por-que-preparar-o-ambiente) - [venv – Ambiente Virtual](#venv--ambiente-virtual) - [pip – Gerenciador de Pacotes](#pip--gerenciador-de-pacotes) - [uv – Alternativa Moderna](#uv--alternativa-moderna) - [Resumo dos Comandos](#resumo-dos-comandos) ## Por que preparar o ambiente? Imagine que você está trabalhando em dois projetos diferentes: um usa a versão 1.0 de uma biblioteca e outro usa a versão 2.0 da mesma biblioteca. Se você instalar tudo no mesmo lugar, os projetos vão entrar em conflito! Por isso, precisamos de ferramentas que: - **Isolam** os projetos uns dos outros (cada um com suas próprias dependências) - **Gerenciam** a instalação de bibliotecas externas - **Documentam** quais bibliotecas são necessárias para rodar o projeto As três ferramentas que vamos estudar resolvem exatamente esses problemas: `venv`, `pip` e `uv`. --- ## venv – Ambiente Virtual O `venv` é uma ferramenta que vem **junto com o Python**. Ele cria um ambiente isolado para cada projeto, onde você pode instalar bibliotecas sem afetar outros projetos ou o sistema. ### Por que usar ambientes virtuais? - **Isolamento**: Cada projeto tem suas próprias versões de bibliotecas - **Reprodutibilidade**: Facilita compartilhar o projeto com outras pessoas - **Organização**: Evita "poluir" o Python global com pacotes de projetos específicos - **Segurança**: Protege o sistema operacional de conflitos de dependências ### Criando um ambiente virtual Para criar um ambiente virtual, navegue até a pasta do seu projeto e execute: ```bash python -m venv ``` O parâmetro `` é o nome da pasta que será criada. A convenção mais comum é usar `.venv` ou `venv`: ```bash python -m venv .venv ``` Ao rodar o comando, você verá algo parecido com isso: ![Pasta .venv](/api/materiais-assets/1-introducao-ao-python/11-appendix/assets/venv.png) ### Ativando o ambiente virtual Após criar, você precisa **ativar** o ambiente para usá-lo. O comando muda dependendo do sistema operacional: **Windows (PowerShell ou CMD):** ```bash .venv\Scripts\activate ``` **macOS / Linux:** ```bash source .venv/bin/activate ``` Quando o ambiente está ativo, você verá o nome dele no início da linha do terminal: ```bash (.venv) C:\Users\usuario\meu_projeto> ``` ### Desativando o ambiente Quando terminar de trabalhar no projeto, você pode desativar o ambiente com: ```bash deactivate ``` O terminal voltará ao normal, sem o prefixo `(.venv)`. ## pip – Gerenciador de Pacotes O `pip` é o **gerenciador de pacotes padrão do Python**. Ele permite instalar, atualizar e remover bibliotecas externas do [PyPI](https://pypi.org/) (Python Package Index), o repositório oficial de pacotes Python. ### Por que usar o pip? - **Instalação fácil**: Um único comando para baixar e instalar qualquer biblioteca - **Gestão de dependências**: Controla as versões das bibliotecas instaladas - **Compatibilidade**: Funciona em qualquer sistema operacional - **Integração**: Funciona perfeitamente com ambientes virtuais ### Instalando pacotes Para instalar uma biblioteca, use: ```bash pip install ``` Por exemplo, para instalar a biblioteca `requests` (muito usada para fazer requisições HTTP): ```bash pip install requests ``` Você também pode instalar uma versão específica: ```bash pip install requests==2.28.0 ``` ### Listando pacotes instalados Para ver todos os pacotes instalados no ambiente atual: ```bash pip list ``` ### Exportando dependências para requirements.txt Quando você quer compartilhar seu projeto ou fazer deploy, é importante documentar quais bibliotecas são necessárias. O arquivo `requirements.txt` é o padrão para isso: ```bash pip freeze > requirements.txt ``` Esse comando vai listar todos os pacotes instalados com suas versões exatas para o arquivo "requirements.txt". O arquivo gerado terá um formato assim: ``` certifi==2023.7.22 charset-normalizer==3.2.0 requests==2.31.0 urllib3==2.0.4 ``` ### Instalando dependências do requirements.txt Quando outra pessoa (ou você em outro computador) for trabalhar no projeto, basta executar: ```bash pip install -r requirements.txt ``` Isso instalará automaticamente todas as bibliotecas listadas nas versões especificadas. ### Removendo pacotes Para desinstalar um pacote: ```bash pip uninstall ``` ## uv – Alternativa Moderna O `uv` é uma ferramenta **moderna e extremamente rápida** para gerenciamento de projetos Python. Ela combina as funcionalidades do `venv`, `pip`, e muito mais em uma única ferramenta otimizada. ### Por que usar o uv? - **Velocidade**: 10 a 100x mais rápido que o pip (escrito em Rust) - **Tudo em um**: Gerencia ambientes virtuais, pacotes e versões do Python - **Moderno**: Usa o padrão `pyproject.toml` para configuração - **Compatível**: Funciona com `requirements.txt` existentes - **Lock files**: Gera arquivos de lock para reprodutibilidade perfeita ### Instalando o uv O uv precisa ser instalado separadamente. A forma mais fácil é: **Windows (PowerShell):** ```bash powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` **macOS / Linux:** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### Inicializando um novo projeto Para criar um novo projeto Python com toda a estrutura necessária: ```bash uv init ``` **O que este comando faz:** O comando `uv init` cria automaticamente toda a estrutura inicial do projeto. Veja como fica: ![estrutura gerada pelo uv init](/api/materiais-assets/1-introducao-ao-python/11-appendix/assets/uv_init.png) Vamos entender cada arquivo criado: #### `.gitignore` Arquivo que diz ao Git quais arquivos e pastas **não devem ser versionados**. Por padrão, o uv já configura para ignorar a pasta `.venv` e outros arquivos temporários do Python: ``` # Python-generated files __pycache__/ *.py[oc] build/ dist/ wheels/ *.egg-info # Virtual environments .venv ``` Isso evita que você suba arquivos desnecessários para o repositório. #### `.python-version` Arquivo simples que especifica **qual versão do Python** o projeto usa. Contém apenas uma linha, por exemplo: ``` 3.14 ``` O uv (e outras ferramentas como pyenv) leem esse arquivo para saber qual versão do Python usar automaticamente quando você entra na pasta do projeto. #### `main.py` O **arquivo principal** do seu projeto, criado com um código de exemplo básico: ```python def main(): print("Hello from meu-projeto!") if __name__ == "__main__": main() ``` É o ponto de entrada padrão da aplicação. Você pode renomeá-lo ou criar outros arquivos conforme a necessidade do projeto. #### `pyproject.toml` O **arquivo mais importante** do projeto. Ele centraliza todas as configurações em um só lugar, substituindo arquivos como `setup.py` e `requirements.txt`. É o padrão moderno para projetos Python. Exemplo de conteúdo inicial: ```toml [project] name = "meu-projeto" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.14" dependencies = [] ``` Aqui você define: - **name**: nome do projeto - **version**: versão atual - **description**: descrição do projeto - **requires-python**: versão mínima do Python necessária - **dependencies**: lista de bibliotecas que o projeto precisa (preenchida automaticamente ao usar `uv add`) #### `README.md` Arquivo de **documentação** do projeto em formato Markdown. É o que aparece na página inicial quando você sobe o projeto para o GitHub. Use esse arquivo para explicar o que o projeto faz, como instalar e como usar. ### Criando ambiente virtual com uv O uv também pode criar ambientes virtuais: ```bash uv venv ``` Isso cria uma pasta `.venv` automaticamente. Para ativar, use os mesmos comandos do venv tradicional: **Windows:** ```bash .venv\Scripts\activate ``` **macOS / Linux:** ```bash source .venv/bin/activate ``` ### Adicionando dependências Para adicionar uma biblioteca ao projeto: ```bash uv add ``` **O que este comando faz:** - Instala o pacote no ambiente virtual - Adiciona a dependência no `pyproject.toml` - Atualiza o arquivo `uv.lock` com as versões exatas ### Instalando todas as dependências Para instalar todas as dependências definidas no projeto (equivalente ao `pip install -r requirements.txt`): ```bash uv sync ``` **Explicação:** - `uv sync`: sincroniza o ambiente com as dependências definidas no `pyproject.toml` - Usa o `uv.lock` para garantir versões exatas e reprodutíveis ### Trabalhando com requirements.txt existente Se você tem um projeto antigo com `requirements.txt`, o uv é compatível: ```bash uv pip install -r requirements.txt ``` ## Resumo dos comandos ### venv | Ação | Comando | |------|---------| | Criar ambiente | `python -m venv .venv` | | Ativar | `.venv\Scripts\activate` (Windows) ou `source .venv/bin/activate` (macOS/Linux) | | Desativar | `deactivate` | --- ### pip | Ação | Comando | |------|---------| | Instalar pacote | `pip install ` | | Instalar versão específica | `pip install ==` | | Listar pacotes | `pip list` | | Exportar dependências | `pip freeze > requirements.txt` | | Instalar do arquivo | `pip install -r requirements.txt` | | Desinstalar pacote | `pip uninstall ` | --- ### uv | Ação | Comando | |------|---------| | Inicializar projeto | `uv init` | | Criar ambiente virtual | `uv venv` | | Adicionar dependência | `uv add ` | | Instalar dependências | `uv sync` | | Instalar do requirements.txt | `uv pip install -r requirements.txt` | --- ## Complemente o Aprendizado Para aprofundar seus conhecimentos sobre gerenciamento de ambientes Python, confira os seguintes recursos: - [venv — Creation of virtual environments (Documentação Oficial)](https://docs.python.org/3/library/venv.html) - [pip — The Python Package Installer (Documentação Oficial)](https://pip.pypa.io/en/stable/) - [uv — An extremely fast Python package manager (Documentação Oficial)](https://docs.astral.sh/uv/) > Lembre-se: preparar corretamente o ambiente de desenvolvimento é o primeiro passo para um projeto bem organizado. Independente da ferramenta escolhida, o importante é manter seus projetos isolados e suas dependências documentadas!