Execução de código

O IDE do QuantCraft oferece três maneiras de executar o arquivo que você está editando (espaço de trabalho), cada uma com um propósito específico:

Os três botões ficam no canto superior direito da área do editor quando há um arquivo aberto. Run e Test estão sempre disponíveis para qualquer arquivo; Compile aparece para arquivos .py que seguem o modelo de estratégia do QuantCraft.

---

Execução rápida (o botão Run)

O botão Run é a forma mais simples de executar código: ele executa o arquivo que você está vendo, de cima para baixo, como um simples python myfile.py.

Como executar

1. Abra no editor o arquivo que você quer executar (não precisa ser uma estratégia — qualquer arquivo .py funciona).
2. Clique em Run na barra de ferramentas acima do editor.
3. Na primeira vez em cada sessão, você verá a caixa de diálogo Disclaimer (veja abaixo). Clique em I understand para continuar.
4. A saída é transmitida para o painel de saída, na parte inferior do espaço de trabalho, conforme é produzida.

Enquanto o código está em execução, os botões Run e Test ficam desativados para evitar execuções sobrepostas.

O que é executado

• O arquivo ativo é o ponto de entrada.
• Todos os outros arquivos e pastas do seu espaço de trabalho ficam disponíveis para que você possa fazer import a partir do arquivo em execução (as pastas do espaço de trabalho funcionam como pacotes Python — from my_folder import my_module).
• O código roda no ambiente Python do IDE do QuantCraft (Dependências); portanto, qualquer pacote listado em Packages (inclusive os que você adicionou) pode ser importado.

O que funciona dentro do Run

• print(...) e tudo o que for escrito em stdout / stderr aparece ao vivo no painel de saída (os erros são exibidos em vermelho).
• As figuras do Matplotlib (gráficos no estilo plt.show()) são renderizadas como imagens no painel de saída.
• As figuras do Plotly são renderizadas como gráficos interativos.
• O script pode usar a biblioteca padrão, pacotes de terceiros do seu ambiente e seus próprios módulos do espaço de trabalho.

Quando não usar o Run

O Run executa Python puro — ele não aciona o mecanismo de backtest do QuantCraft. Se o seu arquivo depende dos callbacks de estratégia on_init, on_bar e on_finish, o Run não os chamará; use o Test (Ciclo de vida da estratégia).

---

Saída

Onde quer que o seu código imprima, desenhe ou gere erros, é no painel de saída, na parte inferior do espaço de trabalho, que você verá.

O que você verá

• Linhas de log com carimbo de data e hora para tudo o que for escrito em stdout.
• Erros em vermelho para tudo o que for escrito em stderr, além de um pequeno selo com a contagem de erros no cabeçalho do painel.
• Gráficos em linha — imagens do Matplotlib e gráficos interativos do Plotly.
• (no output) se o script foi executado com sucesso, mas não imprimiu nada.
• (exit code N) se o script terminou com um código de saída diferente de zero sem escrever um erro.

Trabalhando com o painel

• Clique no título Output (ou na seta ao lado) para recolher / expandir o painel.
• O painel rola automaticamente até a saída mais recente à medida que novas linhas chegam.
• O painel é compartilhado entre arquivos — na próxima vez que você usar Run ou Test, a saída anterior é limpa para que você comece do zero.
• Use o divisor acima do painel para redimensionar quanto da tela ele ocupa.

Run e Test escrevem no mesmo painel de saída; o Test também mostra resultados estruturados na visualização Test Results da área do editor.

---

Avisos

O QuantCraft executa Python na sua máquina, usando a sua conta de usuário. Antes da sua primeira execução em uma sessão, você verá uma caixa Disclaimer que explica isso em linguagem simples.

O que o aviso cobre

• O código roda sem isolamento (sandbox) — os scripts podem ler e gravar arquivos aos quais você tem acesso, usar a rede e iniciar outros programas (por exemplo, via subprocess).
• Isso é adequado para desenvolvimento local com código em que você confia.
• Você é responsável pelo código que executa, pelos pacotes que instala e pelos dados que envia a serviços externos.

As duas formas como ele aparece

• Aviso do fluxo Run — aparece ao clicar em Run (ou Test). Inclui uma caixa “Don't show this again”. Se você a marcar antes de clicar em I understand, os próximos Run e Test ignorarão a caixa de diálogo e serão executados imediatamente.
• Aviso de referência — também acessível a qualquer momento pelo botão Disclaimer no cabeçalho do painel de saída. Esta versão é somente leitura — fechá-la não altera suas configurações.

Se você mudar de ideia depois e quiser que a caixa de diálogo volte, limpe os dados do site do QuantCraft no navegador/aplicativo (ou use o seu fluxo habitual de redefinição do aplicativo) e o aviso aparecerá de novo no próximo Run.

---

Run, Test ou Compile — quando usar cada um

Use este guia rápido para escolher a ação certa.

Use o Run quando…

• Você quiser executar rapidamente um script e ver o que ele imprime ou desenha.
• Você estiver prototipando funções auxiliares, explorando dados ou verificando se um cálculo faz o que você espera.
• Você estiver escrevendo um pequeno script utilitário que não é uma estratégia.
• Você quiser imprimir valores intermediários durante o desenvolvimento.

O Run é o ciclo de feedback mais rápido. Ele não simula operações, não calcula métricas de desempenho e não precisa do modelo de estratégia.

Use o Test quando…

• Você quiser fazer o backtest de uma estratégia em dados históricos.
• Seu arquivo seguir o modelo de estratégia do QuantCraft (com on_init, on_bar, on_finish).
• Você precisar de resultados estruturados: curva de patrimônio, métricas de desempenho, histórico de operações e gráficos.
• Você quiser varrer parâmetros (otimização por força bruta) ou executar uma otimização genética para buscar boas combinações de parâmetros.

Ao clicar em Test, a caixa de diálogo Backtest é aberta para que você escolha o símbolo, o intervalo de datas, os parâmetros e (opcionalmente) as configurações de otimização. O Test executa a sua estratégia por meio de um subprocesso de backtest (não é o mesmo caminho do Run simples) — o IDE envia a configuração por WebSocket e transmite o progresso para o painel de saída. Os resultados aparecem então na visualização Test Results do editor. Você pode usar Stop em um teste demorado a qualquer momento.

Use o Compile quando…

• Você tiver uma estratégia concluída que quer anexar a um gráfico (para que ela rode em dados ao vivo ou gravados fora do IDE).
• O arquivo for uma estratégia .py que inclua os callbacks obrigatórios (on_init, on_bar, on_finish).

O Compile empacota a estratégia junto com os módulos do espaço de trabalho que ela importa e os pacotes do IDE de que precisa em um único arquivo de pacote executável (*.qcraft.json) que você salva no disco pela caixa de diálogo de arquivos do sistema. O pacote não roda sozinho — ele é feito para ser anexado a um gráfico e conduzir uma estratégia a partir dali.

Se o botão Compile estiver desativado, falta ao arquivo um dos callbacks de estratégia obrigatórios. Adicione def on_init():, def on_bar(...): e def on_finish(): (ou use o modelo de estratégia padrão) para ativá-lo.

---

Dicas

• Interromper uma execução longa — Quando um backtest está em andamento, um botão Stop aparece ao lado dos controles Run/Test. Scripts do Run simples podem ser encerrados fechando o arquivo ou interrompendo o backend.
• Para onde foi a minha saída? — O painel de saída é compartilhado entre Run e Test. Se você alternou entre eles, role para cima no painel; a saída da última execução fica no final.
• Importar outros arquivos do espaço de trabalho também funciona no Run — tanto o Run quanto o Test enxergam o seu espaço de trabalho como uma árvore de pacotes, então as mesmas instruções import se comportam de forma consistente em ambos.
• Compile antes de compartilhar — Se você quiser usar a estratégia em um gráfico, sempre use o Compile após a sua última edição para que o pacote reflita o seu código mais recente.