debug

🐞 Debug (DAP via debugpy)

O Codis tem um painel de depuração real para Python: breakpoints, step into/over/out, inspeção de variáveis e um console com avaliação de expressões no frame parado - tudo isso conversando de fato com o protocolo DAP (Debug Adapter Protocol) através do debugpy.

Diferente de ferramentas que só abrem uma porta e esperam algum cliente externo conectar, o próprio Codis é o cliente DAP. Você não precisa instalar nem configurar nenhum IDE adicional - basta ter debugpy disponível no Python que você usa.

---

Como usar (passo a passo)

1. Instale o debugpy, se ainda não tiver:

   pip install debugpy

2. Abra um arquivo .py salvo em disco no editor (arquivos não salvos não podem ser depurados).
3. Clique na margem esquerda do editor (o gutter, ao lado do número da linha) na linha onde você quer parar. Um marcador de breakpoint aparece ali.
4. Abra o Painel de Debug (painel inferior → aba Debug).
5. Clique em ▶ Run.

O Codis vai:

• Iniciar o debugpy no arquivo ativo, numa porta local (padrão 5678);
• Conectar a ele como cliente DAP automaticamente;
• Enviar os breakpoints marcados no gutter;
• Liberar a execução.

Quando a execução chegar numa linha marcada, ela para (⏸ Stopped: breakpoint), a linha correspondente é destacada no editor, e o painel mostra a pilha de chamadas e as variáveis locais/globais daquele ponto.

Sem nenhum breakpoint marcado, o script roda do início ao fim sem parar - você só verá a saída normal no console do painel. Isso é esperado, não é um bug: marque pelo menos um breakpoint antes de clicar em Run se quiser inspecionar o estado do programa.

Controles da toolbar

Botão	Ação	Atalho sugerido
▶ Run	Inicia uma nova sessão de depuração no arquivo ativo	F5
⏹ Stop	Encerra a sessão e o processo depurado	-
↻ Restart	Para e inicia novamente (com os mesmos breakpoints)	-
⤵ Step Into	Entra na próxima função chamada na linha atual	F11
⤴ Step Over	Executa a linha atual sem entrar em chamadas de função	F10
⤴⤴ Step Out	Sai da função atual, voltando ao chamador	Shift+F11
⏩ Continue	Segue a execução até o próximo breakpoint	F5

Os botões de step/continue só têm efeito quando a execução está de fato parada num breakpoint (⏸ Stopped). Fora disso, o painel avisa que não há sessão parada para avançar.

Breakpoints

• Adicionar/remover: clique na margem esquerda do editor, ao lado do número da linha.
• A lista de breakpoints no painel reflete sempre o arquivo/aba ativa - trocar de aba atualiza a lista automaticamente.
• Se você adicionar ou remover um breakpoint enquanto uma sessão de debug já está rodando, a mudança é enviada ao vivo ao debugpy (não é preciso parar e reiniciar a sessão).
• Breakpoints não persistem entre reinicializações do Codis nem entre fechar/reabrir o arquivo.

Console e avaliação de expressões

O campo de entrada do painel funciona como um REPL:

• Sem sessão de debug parada: avalia num namespace Python local isolado, sem relação com o programa em execução - útil só para cálculos rápidos.
• Com a execução parada num breakpoint: a expressão é avaliada de fato no contexto do frame parado, com acesso real às variáveis locais e globais daquele ponto do programa - o mesmo que um evaluate do DAP faria num IDE completo. Você pode inclusive atribuir valores (x = 10) para alterar o estado em tempo real.

Variáveis e Call Stack

Quando a execução para num breakpoint, o painel busca automaticamente:

• A pilha de chamadas (stackTrace) - o topo da pilha é usado para posicionar o cursor no editor;
• Os escopos Locals e Globals do frame selecionado, com seus respectivos valores.

---

Detecção automática

Por padrão, o Codis detecta e usa o debugpy automaticamente sempre que ele estiver disponível no Python/ambiente em uso - não é necessário habilitar nada manualmente. Se debugpy não estiver instalado, o Codis avisa no console e cai para uma execução simples (sem breakpoints reais, só captura de saída).

Se quiser desativar o debug real e forçar sempre a execução simples (por exemplo, para evitar a sobrecarga do debugpy em scripts muito curtos), use a configuração abaixo.

Configurações

Acesse em Configurações → Avançado (ou Ctrl+, → categoria correspondente):

Chave	Tipo	Padrão	Descrição
debug_dap_enabled	bool	true	Usa debugpy/DAP real quando disponível. Desative para forçar execução simples sem breakpoints.
debug_dap_port	int	5678	Porta local usada pelo debugpy para a conexão DAP.

Dica: se você também usa o VS Code (ou outro editor com depurador Python) aberto ao mesmo tempo no mesmo projeto, veja a seção de conflito de porta abaixo - é só mudar debug_dap_port no Codis e o problema desaparece.

---

Limitações atuais

• Suporte real (DAP completo) apenas para Python. Outras linguagens executam no painel de forma simples (saída capturada do processo), sem breakpoints/stepping reais.
• Cada sessão de debug depura um arquivo por vez - multi-threading/multi-processo do programa depurado funciona, mas múltiplas sessões simultâneas do Codis não são suportadas.
• Breakpoints condicionais, breakpoints de função e exception breakpoints ainda não têm UI dedicada no painel.
• Depuração remota (em outra máquina) é um recurso separado - veja SSH Remoto → Debug Remoto, que usa um mecanismo de túnel independente deste painel local.

---

Resolução de problemas

"Nenhuma sessão de depuração ativa" ao clicar em Step/Continue

A sessão anterior já terminou (processo encerrado ou rodou até o fim sem breakpoints). Clique em ▶ Run para iniciar uma nova sessão.

O programa roda até o fim e nada para

Você não marcou nenhum breakpoint antes de clicar em Run. Clique na margem esquerda do editor, na linha desejada, antes de iniciar a depuração.

Erro ao iniciar / a porta já está em uso

Normalmente significa que outro processo já está escutando na porta configurada (debug_dap_port, padrão 5678) - o caso mais comum é ter o VS Code aberto ao mesmo tempo depurando Python no mesmo projeto (veja a seção dedicada abaixo). Mude debug_dap_port para outro valor (ex: 5690) em Configurações → Avançado e tente novamente.

Uso simultâneo com VS Code (ou outro IDE) causa conflito

O Codis e a extensão Python Debugger do VS Code usam, por padrão, exatamente a mesma porta (5678) para o debugpy, porque ambos seguem a mesma convenção da ferramenta. Se os dois estiverem abertos e tentando depurar Python ao mesmo tempo, um deles vai falhar ao abrir a porta, ou o cliente errado pode acabar conectando à sessão do outro.

Isso não é um bug de incompatibilidade entre os editores - é só os dois competindo pelo mesmo número de porta nos bastidores. A solução é simples:

1. Abra Configurações → Avançado no Codis (ou Ctrl+,);
2. Mude debug_dap_port para um valor diferente do que o VS Code usa (ex: 5690, 15678, qualquer porta livre);
3. Pronto - as duas ferramentas podem depurar ao mesmo tempo, sem conflito.

Isso só é necessário se você realmente for depurar Python nos dois editores ao mesmo tempo, no mesmo projeto. Usar só um dos dois por vez nunca tem esse problema.

debugpy não encontrado

Instale com pip install debugpy no mesmo ambiente/interpretador Python usado pelo Codis para executar seus scripts (verifique se é o mesmo python/venv que aparece na barra de status).

A saída do programa (print) não aparece no console

Se isso acontecer, confirme que está usando uma versão atualizada do Codis - versões antigas tinham um bug em que a saída do processo depurado não era redirecionada de volta corretamente. Atualizar resolve.

---

Ver também: Recursos Avançados · Configurações · SSH Remoto