python-debugpy

Python Debugpy

Use quando código Python precisar de depuração interativa: variáveis ocultas, mutação de estado confusa, testes com falha, subprocessos, serviços de longa duração ou attach remoto/headless.

Escolha o depurador mais leve que alcance o frame defeituoso.

Escolha

• breakpoint(): código local, edições no fonte são permitidas, caminho mais rápido.
• python3 -m pdb: sem editar o fonte, execute desde o início.
• python3 -m pdb -c continue: pare em uma exceção não tratada.
• debugpy: processo remoto/headless, cliente DAP, PID já em execução ou race de inicialização de serviço.

Comandos

python3 -m pdb caminho/para/script.py arg1
python3 -m pdb -c continue caminho/para/script.py
python3 -c "import debugpy" || python3 -m pip install debugpy
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client caminho/para/script.py
python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m pacote.modulo
python3 -m debugpy --listen 127.0.0.1:5678 --pid <pid>

Para attach com edição no fonte:

import debugpy

debugpy.listen(("127.0.0.1", 5678))
debugpy.wait_for_client()
debugpy.breakpoint()

Para inspeção post-mortem:

import pdb, sys

try:
    run()
except Exception:
    pdb.post_mortem(sys.exc_info()[2])
    raise

pdb

• Fluxo: n, s, r, c, q.
• Pilha/fonte: w, u, d, a, l, ll.
• Valores: p expr, pp expr, display expr.
• Breakpoints: b arquivo.py:42, b func, b arquivo.py:42, condição, cl <num>.
• Mutar/avaliar: !declaração; REPL completo: interact.

Regras

• Reproduza com o menor comando/teste primeiro.
• Desabilite workers de teste paralelos para pdb; stdin interativo geralmente quebra dentro de pools de workers.
• Mantenha debugpy no ambiente ativo; não o adicione como dependência do projeto a menos que o projeto já o queira.
• Vincule servidores de depuração a 127.0.0.1; não exponha 0.0.0.0 a menos que isolado ou via túnel.
• Use portas únicas para sessões paralelas.
• debugpy --pid injeta em um processo em execução; confirme o pid alvo antes de anexar.
• Se o attach por PID falhar no Linux, verifique privilégios ptrace/container antes de alterar o alvo.
• Limpe antes do commit: rg -n 'breakpoint\(|pdb\.set_trace|debugpy\.' --type py.
• Reexecute o teste/gate normal do projeto sem o depurador.
• PYTHONBREAKPOINT=0 desabilita breakpoint().
• Se um processo ficar travado após a desconexão do depurador, confirme que ele não está pausado em um breakpoint.