execubot-py

Package providing the Execubot project Python code (https://execubot.fr).

Yes, you can even play Execubot in your terminal! 🤖

CLI

execubot-cli play       <FILE>...   # play level in terminal (curses)
execubot-cli print      <FILE>...   # print level source with syntax highlighting
execubot-cli extractor  <FILE>...   # parse level file and show metadata
execubot-cli solver     <FILE>...   # solve level and show solution
execubot-cli generator  <FILE>...   # generate JSON metadata for web frontend
execubot-cli grid       <FILE>...   # show standardized grid
execubot-cli lang       <FILE>...   # show language dict
execubot-cli tags       <FILE>...   # show tags
execubot-cli difficulty <FILE>...   # show difficulty score

<FILE> accepts file paths or bare level numbers (e.g. 1 → level1.pye).

The standalone script scripts/execubot-cli (PEP 723) is provided and can be run directly without installing the package:

scripts/execubot-cli play 106

Level file format (.pye)

grid = [['purple', 'green']]   # header: Python assignments (grid is mandatory; row=0, col=0, lang='en', message, author are optional)
                               # mandatory blank line
right()                        # body: level code executed by the solver

Python API

from execubot_py import solve, extractor, stdgrid, dictlang, generate, tags, difficulty

solve("path/to/level.pye")                        # → [('Right', 0), ('Down', 2), ...]
extractor("path/to/level.pye")                    # → {'grid': ..., 'code': ..., 'row': 0, ...}
stdgrid(["w o", "y w"])                           # → [['white', 'orange'], ['yellow', 'white']]
dictlang("fr")                                    # → {'purple': 'violet', 'right': 'droite', ...}
generate("path/to/level.pye")                     # → '{"id": 1, "answer": [...], "grid": [...], ...}'
tags("if orange():\n    right()")                 # → ['if']
difficulty("while orange():\n    right()")        # → 10

# solve, extractor and generate also accept raw file content instead of a path
content = "grid = [['white', 'orange']]\n\nright()"
solve(content)                                    # → [('Right', 0)]

Architecture

The package is split into two layers:

solver.py — core engine

• Execubot class: takes (code, grid, row, col, lang) and runs the player's Python code via exec() in a restricted namespace (only color-test functions and direction functions are exposed).
• extractor(): parses a .pye level file, splitting it at the first blank line — the header (above) is exec'd to extract grid, row, col, lang, etc.; the body (below) becomes code.
• Translations live in Execubot.translations (a class-level dict built from translation.py, or from json/solver.json under Brython). Color/direction functions are injected under their translated names at solve time. Supported languages: 🇬🇧 en, 🇫🇷 fr, 🇪🇸 es, 🇮🇹 it, 🇳🇱 nl, 🇻🇳 vi.

generator.py — level metadata

• Level(Execubot): extends the solver to produce JSON output (generator()) consumed by the web frontend. Computes difficulty (keyword-weighted score) and tags from the level's code.

Tests compare CLI/function output against golden files in tests/out/*.out. When adding or modifying a level, regenerate the fixtures with scripts/updater_tests.sh.

Brython variant: src/execubot_py/solver/solver.py is compiled to solver.brython.js for the browser frontend — not shipped in the package but available via CDN at https://www.jsdelivr.com/package/gh/fgallaire/execubot.

Credits

Copyright (C) 2025-2026, Florent Gallaire <fgallaire@gmail.com> & Célia Piquet <cepiquet@proton.me>.

Licensed under the GNU GPLv3 or later.