Metadata-Version: 2.4
Name: execubot-py
Version: 2.5
Summary: Package providing the Execubot project Python code (https://execubot.fr).
Author: Florent Gallaire, Célia Piquet
Author-email: Florent Gallaire <fgallaire@gmail.com>, Célia Piquet <cepiquet@proton.me>
License-Expression: GPL-3.0-or-later
License-File: COPYING
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Topic :: Games/Entertainment
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: docopt>=0.6.2
Requires-Dist: natsort>=8.4.0
Requires-Dist: rich>=14.2.0
Requires-Python: >=3.10
Project-URL: Documentation, https://execubot.forge.apps.education.fr
Project-URL: Homepage, https://execubot.fr
Project-URL: Issues, https://forge.apps.education.fr/cpiquet/execubot/issues
Project-URL: Repository, https://forge.apps.education.fr/cpiquet/execubot
Description-Content-Type: text/markdown

# execubot-py

<div align="center"><img src="https://execubot.fr/img/robot.png" width="200"></div>

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

<div align="center"><img src="https://forge.apps.education.fr/cpiquet/execubot/raw/main/img/screenshotCurses.png" width="500"></div>

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

## CLI
```bash
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:

```bash
scripts/execubot-cli play 106
```

## Level file format (`.pye`)

```python
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

```python
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](https://www.gnu.org/licenses/gpl-3.0.html) or later.
