Skip to content
| Marketplace
Sign in
Visual Studio Code>Debuggers>Python Slow RunnerNew to Visual Studio Code? Get it now.
Python Slow Runner

Python Slow Runner

LEONARDO EZEQUIEL BLANCO PAGLIARI

|
7 installs
| (0) | Free
Execute Python scripts slowly while highlighting each line for classroom demonstrations.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

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

  1. 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).
  2. O código é executado normalmente no terminal integrado do VS Code, exibindo print() e aceitando input().
  3. 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.
  4. 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:
    1. 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.
    2. A extensão abre ou reutiliza um terminal integrado do VS Code (vscode.window.createTerminal).
    3. 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.
    4. 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:
    1. Envia o número da linha (frame.f_lineno) para a extensão via socket TCP/HTTP na porta SLOW_RUNNER_PORT.
    2. 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:
    1. Localizar o TextEditor correspondente ao arquivo em execução.
    2. 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).
    3. 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

  1. Instale o Node.js LTS e o Python 3.

  2. Na raiz do projeto, instale as dependências:

    npm install
    
  3. Compile a extensão:

    npm run compile
    
  4. 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.

  5. 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.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft