Python Slow Runner (Visual Line Tracer)
Extensão educacional para Visual Studio Code projetada para facilitar o ensino de lógica e automação (QA) com Python. Inspirada no jogo The Farmer Was Replaced, a extensão permite executar scripts Python em câmera lenta no terminal enquanto destaca visualmente no editor a linha exata que está sendo executada em tempo real, sem utilizar o depurador nativo do VS Code.
Contexto e Motivação
Esta extensão foi criada com o apoio de inteligência artificial, por meio da colaboração entre desenvolvimento assistido por IA e orientação prática para o uso em sala de aula.
Seu principal objetivo é resolver uma dificuldade observada entre os alunos: a dificuldade de visualizar e compreender a lógica de execução dos códigos diretamente pelo terminal. Ao acompanhar cada linha sendo executada, junto com o resultado exibido no terminal, os alunos podem relacionar o código escrito às decisões, repetições, entradas e saídas ocorridas durante a execução.
Objetivo e Experiência do Usuário
- O aluno abre um arquivo
.py e clica no botão com ícone de play + relógio na barra superior do editor (ou aciona via Command Palette).
- O código é executado normalmente no terminal integrado do VS Code, exibindo
print() e aceitando input().
- A cada linha executada, o script pausa brevemente (delay configurável) e o editor destaca automaticamente a linha atual com uma cor de fundo, acompanhando a rolagem da tela.
- O aluno não precisa alterar seu código-fonte, importar bibliotecas extras ou digitar comandos customizados no terminal.
Requisitos Funcionais
1. Interface e Comandos (package.json)
- Comando Principal:
python-slow-runner.runSlow (Título: Python: Run File in Slow Motion).
- Botão no Editor: Adicionar um ícone de ação (
editor/title) visível apenas quando resourceLangId == python.
- Configurações do Usuário (
contributes.configuration):
pythonSlowRunner.stepDelaySeconds: Número em segundos para o atraso entre cada linha (Padrão: 1.5).
pythonSlowRunner.highlightColor: String RGBA para a cor de fundo da linha ativa. O alpha máximo é 0.30 (Padrão: "rgba(255, 215, 0, 0.25)").
2. Mecanismo de Injeção Transparente (Python)
- A extensão deve conter um script auxiliar embutido (ex:
resources/tracer/sitecustomize.py).
- Quando o comando
runSlow for acionado:
- A extensão inicia um servidor IPC/HTTP ou TCP local efêmero (porta aleatória disponível) em Node.js para receber eventos de linha.
- A extensão abre ou reutiliza um terminal integrado do VS Code (
vscode.window.createTerminal).
- O terminal deve ser iniciado com variáveis de ambiente injetadas (
env):
PYTHONPATH: Apontando para a pasta resources/tracer da extensão (concatenado ao PYTHONPATH existente, se houver).
SLOW_RUNNER_PORT: Porta do servidor local da extensão.
SLOW_RUNNER_DELAY: Valor da configuração stepDelaySeconds.
SLOW_RUNNER_TARGET_FILE: Caminho absoluto do arquivo .py aberto no editor ativo.
- O terminal executa o comando padrão:
python "<caminho_do_arquivo>".
3. Comportamento do Rastreador (sitecustomize.py)
- O Python carrega automaticamente o
sitecustomize.py antes de executar o script do aluno devido ao PYTHONPATH.
- O script verifica se a variável
SLOW_RUNNER_TARGET_FILE está definida. Se não estiver, não faz nada (garantindo que execuções normais no terminal não sejam afetadas).
- Utiliza
sys.settrace para interceptar apenas eventos do tipo 'line' cujo frame.f_code.co_filename corresponda exatamente ao arquivo alvo (SLOW_RUNNER_TARGET_FILE), ignorando bibliotecas internas do Python.
- A cada linha interceptada:
- Envia o número da linha (
frame.f_lineno) para a extensão via socket TCP/HTTP na porta SLOW_RUNNER_PORT.
- Aguarda o tempo definido em
SLOW_RUNNER_DELAY usando time.sleep().
4. Destaque Visual no Editor (extension.ts)
- Criar uma instância de
vscode.window.createTextEditorDecorationType usando a cor configurada em highlightColor e isWholeLine: true.
- Ao receber o número da linha do processo Python:
- Localizar o
TextEditor correspondente ao arquivo em execução.
- Aplicar a decoração (
editor.setDecorations) na linha recebida (lembrando que a API do VS Code usa índice base 0, enquanto o Python usa base 1).
- Usar
editor.revealRange para garantir que a linha fique visível na tela caso o código seja longo.
- Ao finalizar a execução do processo ou fechar o terminal, limpar todas as decorações ativas (
editor.setDecorations(decorationType, [])) e encerrar o servidor local.
Estrutura de Pastas Esperada
├── package.json
├── tsconfig.json
├── src/
│ └── extension.ts # Lógica do comando, servidor local e decorações do editor
└── resources/
└── tracer/
└── sitecustomize.py # Script de rastreamento injetado via PYTHONPATH
Desenvolvimento
Instale o Node.js LTS e o Python 3.
Na raiz do projeto, instale as dependências:
npm install
Compile a extensão:
npm run compile
Abra a pasta no VS Code e pressione F5 para iniciar uma janela de extensão
para desenvolvimento. A configuração Run Extension em .vscode/launch.json
compila o projeto automaticamente antes de abrir essa janela.
Abra um arquivo Python e use o botão com play + relógio. A seta ao lado abre
o painel visual Python Slow Runner Settings, com:
- controle deslizante e campo numérico para o atraso em segundos;
- sliders de vermelho, verde, azul e opacidade;
- campos sincronizados para RGB, HEX e HSL;
- limite de opacidade de 30% para preservar a leitura do terminal.
A API pública do VS Code não permite criar um split button idêntico ao botão
interno de Run; por isso, a seta abre esse painel gráfico próprio da extensão.
Se o programa terminar com um erro não tratado, a extensão identifica a última
linha do arquivo do aluno presente no traceback, seleciona essa linha no editor
e rola a tela até ela. Erros tratados pelo próprio programa não interrompem a
execução nem alteram a seleção.
O comando usa o interpretador python disponível no PATH. O arquivo do aluno
não é alterado: o rastreador é carregado por PYTHONPATH e só é ativado quando
as variáveis SLOW_RUNNER_* são injetadas pela extensão.
Empacotamento local
Para gerar um arquivo instalável .vsix, instale o empacotador e execute:
npm install --global @vscode/vsce
npm run package
O arquivo .vsix gerado pode ser instalado pelo menu ... da área de
Extensões, em Install from VSIX.... Para publicar no Marketplace, adicione
um publisher próprio ao package.json e siga o fluxo de autenticação do
vsce; nunca coloque o Personal Access Token no projeto.