# Roteiro de Instalação do Ambiente da Disciplina Este roteiro leva, do zero, a um ambiente de trabalho padronizado: Python, Visual Studio Code (VSCode) e um ambiente isolado por projeto (venv). Siga **na ordem**, sem pular etapas, e pare em cada "Verificação" para confirmar que aquele passo deu certo antes de seguir. Se uma verificação falhar, resolva-a antes de continuar (a seção "Problemas comuns", ao final, cobre as falhas mais frequentes). > **Importante (leia antes de começar):** > - **Não instale o Anaconda nem o Miniconda** para esta disciplina. Se você já instalou o Anaconda Navigator antes (quando o plano era usar o Spyder), **não precisa desinstalá-lo agora**: a seção "Se você já tem Anaconda/conda nesta máquina" explica como evitar conflito sem remover nada. > - Onde o roteiro pedir "feche e reabra o terminal", faça isso de verdade: muitos erros somem só com a reabertura. --- ## Sumário das etapas 1. Verificar e (se preciso) instalar o Python (python.org) 2. Verificar/instalar o VSCode e a extensão Python 3. Abrir a pasta do projeto e criar o ambiente isolado (venv) 4. Instalar os pacotes da disciplina (requirements.txt) 5. Instalar o Google Chrome e o driver (necessário para o dsd-br) 6. Verificação final integrada (A extensão de chat de IA do VSCode será indicada separadamente pelo instrutor.) --- ## Etapa 1: Verificar e (se preciso) instalar o Python Antes de instalar qualquer coisa, verifique se o seu computador já tem um Python adequado. **Versão mínima exigida pela disciplina: Python 3.10.** (Os pacotes que usaremos não funcionam em versões anteriores.) ### Passo 1.1: verificar se o Python já está instalado Abra um terminal novo (no Windows, o "Prompt de Comando" ou o "PowerShell"; no macOS, o "Terminal") e digite: ``` python --version ``` No macOS, se o comando acima não funcionar, tente também: ``` python3 --version ``` Interprete o resultado: - **Apareceu `Python 3.10.x` ou mais novo** (3.11, 3.12, 3.13...): ótimo, você **já tem** um Python adequado. **Pule o Passo 1.2** e vá direto para a Etapa 2. - **Apareceu uma versão anterior à 3.10** (por exemplo, `Python 3.9.x` ou `Python 2.7.x`): você precisa instalar uma versão mais nova. Faça o Passo 1.2. - **Apareceu "não é reconhecido" (Windows) ou "command not found" (macOS):** não há Python disponível. Faça o Passo 1.2. ### Passo 1.2: instalar o Python (apenas se o Passo 1.1 indicou que é necessário) Use **apenas** o instalador do site oficial. Não use a Microsoft Store nem o conda. **Windows** 1. Acesse https://www.python.org/downloads/ e baixe a versão mais recente para Windows. 2. Ao abrir o instalador, **marque a caixa "Add python.exe to PATH"** na primeira tela (isso é o passo mais importante; sem ele, nada do resto funciona). 3. Clique em "Install Now" e conclua. **macOS** 1. Acesse https://www.python.org/downloads/ e baixe a versão para macOS. 2. Abra o pacote `.pkg` e siga a instalação padrão. ### Verificação 1 Repita o comando do Passo 1.1 em um terminal **novo**: ``` python --version ``` Deve aparecer `Python 3.10.x` ou mais novo (no macOS, se `python` não funcionar, use `python3 --version`). > Se, após instalar, ainda aparecer "não é reconhecido" ou uma versão antiga, o PATH não foi configurado. No Windows, reinstale marcando "Add to PATH". Feche e reabra o terminal antes de testar de novo. --- ## Etapa 2: Verificar/instalar o VSCode e a extensão Python Se você **já tem o VSCode instalado**, não precisa reinstalá-lo: pule a instalação e vá direto para o Passo 2.2 (extensões). ### Passo 2.1: verificar se o VSCode já está instalado Procure pelo programa "Visual Studio Code" na sua máquina: - **Windows:** abra o menu Iniciar e digite "Visual Studio Code". - **macOS:** abra o Launchpad (ou a pasta Aplicativos) e procure "Visual Studio Code". Se ele aparecer e abrir normalmente, **está instalado**: pule a instalação e siga para o Passo 2.2. Se **não** encontrar, instale: 1. Baixe o VSCode em https://code.visualstudio.com e instale com as opções padrão. - **No Windows**, durante a instalação, marque a opção "Adicionar ao PATH" (geralmente já vem marcada). ### Passo 2.2: instalar a extensão Python 1. Abra o VSCode. 2. No ícone de **Extensões / Extensions** (na barra lateral esquerda, parece quatro quadradinhos), pesquise e instale **apenas** esta: - **Python** (publicada pela Microsoft). Se ela já estiver instalada (comum em quem já usava o VSCode), apenas confirme que está ativada; não precisa reinstalar. 3. Se o instrutor indicar uma extensão de chat de IA, instale também essa (e somente essa). Não instale outras extensões por conta própria: cada extensão a mais é uma fonte de diferença entre as máquinas da turma. ### Verificação 2 No VSCode, abra a paleta de comandos (Command Palette: `Ctrl+Shift+P` no Windows, `Cmd+Shift+P` no macOS), digite `Python: Select Interpreter` (os comandos da paleta são sempre em inglês, mesmo com a interface em português) e confirme que o comando aparece na lista. (Ainda não selecione nada; faremos isso na Etapa 3.) --- ## Etapa 3: Abrir a pasta do projeto e criar o ambiente isolado (venv) Cada projeto da disciplina terá a sua própria pasta com um ambiente isolado dentro. É isso que evita os conflitos entre projetos e entre máquinas (inclusive com um conda eventualmente instalado). > **Regra obrigatória sobre a localização da pasta:** a pasta do projeto deve ficar em um **caminho local do computador** (por exemplo, `C:\Projetos\` no Windows, ou a pasta "Documentos"). **Não** use uma pasta dentro do Google Drive, OneDrive ou Dropbox. Essas pastas sincronizadas com a nuvem fazem o ambiente Python (`.venv`) falhar ao ser executado, com erros difíceis de diagnosticar. O seu **código** pode ser guardado na nuvem ou no GitHub depois, mas a pasta de trabalho com o `.venv` precisa ser local. (Se o seu objetivo é acessar o trabalho de outros computadores, a forma correta é versionar o código com Git/GitHub e recriar o `.venv` em cada máquina, e não sincronizar o `.venv` em si, que não funciona entre máquinas diferentes.) 1. No VSCode, clique em **Arquivo > Abrir Pasta** (Open Folder). Na janela que abrir, você pode **escolher uma pasta já existente** ou **criar uma nova ali mesmo**, usando o botão **Nova Pasta** (New Folder) e dando um nome sem espaços nem acentos (sugestão: `disciplina`). Selecione essa pasta para abri-la no VSCode. > **Onde a pasta NÃO pode estar:** confirme que o caminho da pasta escolhida **não** contém "Google Drive", "Meu Drive", "OneDrive" nem "Dropbox". Essas pastas sincronizadas com a nuvem fazem o ambiente Python (`.venv`) falhar ao ser executado, com erros difíceis de diagnosticar. Use um caminho local, como `C:\Projetos\` (Windows) ou "Documentos" (macOS). > **Se aparecer uma pergunta sobre onde gravar as configurações do workspace** (alguma janela oferecendo salvar a configuração "na pasta"/"como pasta" ou então "como um arquivo de workspace"), escolha a opção de salvar **na/como pasta**. Isso cria, dentro do projeto, uma subpasta `.vscode` que guarda as configurações junto com a pasta da disciplina, que é o que queremos. **Não** escolha salvar como um arquivo de workspace separado (`.code-workspace`). Se também aparecer uma pergunta perguntando se você "confia nos autores" da pasta (Workspace Trust: "Do you trust the authors of the files in this folder?"), responda que **sim** (a pasta é sua): clique na opção de confiar (Yes, I trust the authors). 2. Abra o **terminal integrado** do VSCode em **Terminal > Novo Terminal** (Terminal > New Terminal), ou pressione `Ctrl+'`. Ele abre já dentro da pasta que você acabou de abrir. > **Confirme o caminho antes de seguir.** Olhe o início da linha do terminal: ele mostra a pasta atual. Deve ser a pasta local que você escolheu (por exemplo, `PS C:\Projetos\disciplina>`). **Se aparecer `G:\Meu Drive`, `OneDrive` ou similar, pare:** a pasta está na nuvem e o próximo passo vai falhar. Volte ao item 1 e escolha (ou crie) uma pasta em um local correto antes de continuar. 3. Crie o ambiente isolado digitando: **Windows:** ``` python -m venv .venv ``` **macOS:** ``` python3 -m venv .venv ``` 4. O VSCode deve detectar a nova pasta `.venv` e perguntar se você quer usá-la como interpretador. Clique em **Sim / Yes**. Se não perguntar, abra a paleta (Command Palette: `Ctrl+Shift+P`), digite `Python: Select Interpreter` e escolha o que aponta para `.venv`. 5. **Feche o terminal integrado e abra um novo** (`Ctrl+'`). Agora ele deve ativar o ambiente automaticamente: você verá `(.venv)` no início da linha do terminal. ### Verificação 3 (a mais importante do roteiro) Com `(.venv)` aparecendo no terminal, digite: ``` python -c "import sys; print(sys.executable)" ``` O caminho mostrado deve terminar dentro da pasta `.venv` do seu projeto. > **Se o caminho terminar em `anaconda3`, `miniconda3` ou numa pasta do sistema (e não em `.venv`), procure o instrutor antes de continuar.** Isso significa que o conda da sua máquina está interferindo, e há um ajuste simples para corrigir (veja a última seção). --- ## Etapa 4: Instalar os pacotes da disciplina O arquivo `requirements.txt` (fornecido pelo instrutor) lista os pacotes que toda a turma usará, nas mesmas versões. Isso garante que o código funcione igual em todas as máquinas. 1. Coloque o arquivo `requirements.txt` dentro da pasta do projeto (a mesma que você abriu no VSCode). 2. Com o terminal integrado mostrando `(.venv)`, digite: ``` pip install -r requirements.txt ``` 3. Aguarde a instalação concluir. ### Verificação 4 No terminal (ainda com `(.venv)`): ``` pip list ``` Os pacotes do `requirements.txt` devem aparecer na lista. --- ## Etapa 5: Instalar o Google Chrome e o driver (necessário para o dsd-br) O pacote `dsd-br` controla um navegador **Google Chrome** de verdade para extrair os dados do STF. Sem o Chrome, ele não funciona. Esta etapa só é necessária porque a disciplina usa o `dsd-br`. ### Parte A (recomendada e padrão da turma): deixar o driver automático 1. Confirme que o **Google Chrome** está instalado (na nossa turma, todos já têm). Em caso de dúvida, abra o Chrome normalmente uma vez. Se por acaso não tiver, instale em https://www.google.com/chrome/. 2. **Pronto, não há mais nada a fazer.** Você **não** precisa baixar o "chromedriver": o Selenium (que vem com o `dsd-br`) detecta o Chrome e baixa sozinho o driver compatível na primeira vez que o programa rodar, desde que haja conexão com a internet. Siga para a Etapa 6. > Esta é a forma padrão da disciplina. Só recorra à Parte B se o teste do Selenium na Etapa 6 falhar com erro relacionado a "driver", ou se o instrutor pedir. ### Parte B (segunda opção, fora do uso normal da turma): baixar o chromedriver manualmente Não use isto por padrão. Recorra a ele apenas quando o download automático não funciona (rede que bloqueia o Selenium, máquina sem internet no momento de rodar, ou exigência do instrutor de fixar uma versão). > **Atenção à regra de ouro:** a versão do chromedriver tem que ter o **mesmo número principal** da versão do seu Chrome. Se o Chrome se atualizar depois, o driver para de funcionar (erro `SessionNotCreatedException`) e você precisará baixar o driver de novo. É por isso que o caminho automático da Parte A é preferível. 1. **Descubra a versão do seu Chrome:** abra o Chrome, vá no menu de três pontos > Ajuda > Sobre o Google Chrome. Anote o número principal (os três primeiros dígitos, por exemplo `148`). 2. **Descubra a sua plataforma:** - Windows: `win64`. - Mac com chip Apple (M1/M2/M3/M4): `mac-arm64`. - Mac com processador Intel: `mac-x64`. (No Mac, em caso de dúvida: menu da maçã > Sobre Este Mac.) 3. **Baixe o driver na fonte oficial:** acesse https://googlechromelabs.github.io/chrome-for-testing/, vá até a seção do canal **Stable** e, na linha **chromedriver**, baixe o arquivo da sua plataforma cuja versão tenha o mesmo número principal do seu Chrome. Use **apenas** essa página oficial; evite sites de terceiros que oferecem "downloads diretos". 4. **Extraia** o arquivo `.zip`. Dentro há o `chromedriver.exe` (Windows) ou `chromedriver` (Mac). 5. **Coloque o driver onde o programa o encontre.** O mais simples para a disciplina é copiar o `chromedriver` (ou `chromedriver.exe`) para **dentro da pasta do projeto** (a mesma do `.venv`). 6. **Somente no Mac:** o sistema bloqueia o driver por segurança na primeira vez. Se aparecer um aviso impedindo a execução, vá em Ajustes do Sistema > Privacidade e Segurança e autorize o `chromedriver`, ou rode no terminal, dentro da pasta do projeto: `xattr -d com.apple.quarantine chromedriver`. --- ## Etapa 6: Verificação final integrada No VSCode, com a pasta do projeto aberta e o terminal mostrando `(.venv)`: 1. Confirme o Python isolado: ``` python -c "import sys; print(sys.executable)" ``` (o caminho deve terminar em `.venv`) 2. Confirme que o Chrome e o Selenium conversam (teste de fumaça). Cole esta linha única no terminal: ``` python -c "from selenium import webdriver; o=webdriver.ChromeOptions(); o.add_argument('--headless=new'); d=webdriver.Chrome(options=o); d.get('https://example.com'); print('Selenium OK:', d.title); d.quit()" ``` Deve aparecer `Selenium OK: Example Domain`. Se aparecer, o Chrome, o driver e o Selenium estão funcionando. > Se o passo 2 falhar com erro mencionando "driver" (por exemplo, `NoSuchDriverException`), volte à Etapa 5: na maioria dos casos falta o Chrome instalado (Parte A) ou há bloqueio de rede ao download automático (use a Parte B). Se falhar mencionando "version" ou `SessionNotCreatedException`, o driver da Parte B não corresponde à versão do seu Chrome. Se as duas confirmações vierem corretas, o ambiente está pronto. --- ## Problemas comuns **"python não é reconhecido" / "command not found"** O PATH não foi configurado. No Windows, reinstale o Python marcando "Add to PATH". Em qualquer sistema, feche e reabra o terminal após instalar. **O terminal não mostra `(.venv)`** Feche o terminal integrado e abra um novo. Se ainda não mostrar, refaça a seleção do interpretador (Command Palette com `Ctrl+Shift+P` > `Python: Select Interpreter` > escolha o `.venv`) e abra outro terminal. **`pip install` falha por permissão** Confirme que o terminal mostra `(.venv)` antes de rodar o comando. Nunca use o `pip` fora do ambiente e nunca rode como administrador. **O terminal abre em uma pasta diferente da que você abriu (por exemplo, vai para o Google Drive mesmo com a pasta correta aberta no Explorer)** Primeiro, descarte as causas simples: feche **todos** os terminais abertos (use o ícone de lixeira / "Kill Terminal" no painel do terminal) e abra um novo, pois um terminal antigo pode ter ficado preso na pasta anterior; e confirme que não há **duas janelas** do VSCode abertas (feche todas e reabra apenas a pasta certa). Se, mesmo com um terminal **novo** e a pasta certa no topo do Explorer, ele ainda abrir no lugar errado, é sinal de que há uma configuração fixando o diretório inicial do terminal. Para corrigir, edite o arquivo de configurações (JSON): 1. Abra a paleta (Command Palette: `Ctrl+Shift+P`) e digite `Preferences: Open User Settings (JSON)`. Selecione. 2. No arquivo que abrir, procure (`Ctrl+F`) por `cwd`. 3. Se existir uma linha como `"terminal.integrated.cwd": "G:\\Meu Drive\\..."` (ou qualquer caminho que não seja o do seu projeto), **apague essa linha inteira** (cuide para não deixar uma vírgula solta quebrando o arquivo) e salve (`Ctrl+S`). 4. Verifique também, dentro da pasta do projeto, se há uma subpasta `.vscode` com um `settings.json` contendo a mesma linha `cwd`; se houver, remova-a ali também. 5. Rode `Developer: Reload Window` (pela paleta) e abra um terminal novo. O caminho no prompt deve passar a ser o da pasta do projeto. > Por que isso acontece: a configuração `terminal.integrated.cwd` força todo terminal a abrir em um caminho fixo, ignorando a pasta do projeto. Ela costuma ser um resíduo de um projeto anterior. Removê-la nas **configurações do usuário** (e não só nas da pasta) garante que o problema não se repita em projetos futuros. **O caminho da Verificação 3 termina em `anaconda3` ou `miniconda3`** O conda está ativando um Python que não é o do projeto. Veja a próxima seção. --- ## Se você já tem Anaconda/conda nesta máquina Muitos instalaram o Anaconda Navigator anteriormente, quando a ideia era usar o Spyder. Esta disciplina **não** usa nem o Spyder nem o conda, e você **não precisa desinstalar nada**. Na maioria das máquinas, o `.venv` do projeto funciona normalmente mesmo com o conda instalado (foi o que a Verificação 3 confirmou). Só faça o ajuste abaixo **se** a Verificação 3 mostrou um caminho terminando em `anaconda3`/`miniconda3` em vez de `.venv`: 1. Abra o terminal e desligue a ativação automática do ambiente `base` do conda: ``` conda config --set auto_activate_base false ``` 2. Feche o VSCode por completo e reabra. 3. Refaça a Etapa 3 (criar/selecionar o `.venv`) e a Verificação 3. Esse ajuste é reversível e não remove nada. Se, mesmo assim, a Verificação 3 continuar apontando para o conda, procure o instrutor: é um caso individual da sua máquina, não um problema da turma.