README.pt-BR.md

Client Side Python

🇺🇸 English | 🇯🇵 日本語 | 🇨🇳 简体中文 | 🇪🇸 Español | 🇧🇷 Português (Brasil) | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français

PlayGround

Um playground de Python baseado em navegador e executado no lado do cliente.

---

Visão geral

Client Side Python é um playground de Python baseado em navegador, alimentado por Pyodide.
Todo o código Python é executado inteiramente dentro da aba do navegador (WebAssembly, sem backend), então seu código nunca sai da sua máquina.

Isso o torna útil para:

• Testar rapidamente pequenos trechos de código Python
• Demonstrar conceitos básicos de Python em sala de aula ou workshops
• Experimentar tarefas simples de cálculo numérico ou scripting em um sandbox seguro
• Mostrar como WebAssembly + Pyodide podem levar Python “de verdade” para o navegador

---

Recursos

• Execução totalmente no lado do cliente

  • Usa Pyodide para executar CPython em WebAssembly.
  • Nenhum servidor, banco de dados ou autenticação é necessário por padrão.

• Editor de código simples + console

  • Área de texto para código Python.
  • Área de console que mostra stdout e stderr.
  • Botões: Run, Stop, Clear, Load Sample, Copy Output.

• Mecanismo de “Stop” suave

  • A execução é encapsulada com um token de cancelamento suave.
  • Quando você pressiona Stop, a execução atual é logicamente cancelada para que resultados tardios sejam ignorados em vez de quebrar a UI.

• Interface web responsiva

  • Construída com Expo / React Native Web e componentes do Material UI.
  • O layout se adapta a diferentes tamanhos de viewport (desktop / tablet).

• CI determinístico via Docker

  • Os testes com Jest são executados em um contêiner Docker usando docker-compose.test.yml.
  • Workflows do GitHub Actions são fornecidos para CI e testes baseados em Docker.

• Deploy automático no GitHub Pages

  • Um workflow do GitHub Actions compila o bundle web do Expo e o publica no GitHub Pages para a branch main.

---

Como funciona

Na primeira carga, o aplicativo:

1. Busca o Pyodide a partir de uma CDN.
2. Inicializa o runtime do Pyodide e expõe runPythonAsync.
3. Anexa handlers personalizados para stdout e stderr, para que a saída do Python seja transmitida para o console na página.
4. Usa um token de execução simples para implementar um soft Stop:
   • Cada execução incrementa um execId interno.
   • Se uma execução terminar com um execId desatualizado, sua saída será descartada.
   • Isso evita que resultados antigos contaminem o console.

Tudo isso acontece no navegador, sem nenhuma chamada a APIs de backend.

---

🚀 Primeiros passos

1. Pré-requisitos

• Docker e Docker Compose

2. Compile e inicie todos os serviços:

# set environment variables:
export REACT_NATIVE_PACKAGER_HOSTNAME=${YOUR_HOST}

# Build the image
docker compose build

# Run the container
docker compose up

3. Teste:

docker compose -f docker-compose.test.yml up --build --exit-code-from frontend_test 

---

License

• Apache License 2.0