# Hedy trades real Python syntax for gradual programming levels

> A gradual programming language for teaching children, where each level adds one construct until learners reach a subset of syntactically valid Python, with the compiler and web application in the same repository. Suited to classrooms starting from scratch, and a poor fit for a curriculum that wants genuine Python from the first lesson.

**hedyorg/hedy** — Hedy is a gradual programming language to teach children programming. Gradual languages use different language levels, where each level adds new concepts and syntactic complexity. At the end of the Hedy level sequence, kids master a subset of syntactically valid Python.

- Repository: https://github.com/hedyorg/hedy
- Website: https://www.hedy.org
- Stars: 1,694 · Forks: 340
- Language: CSS
- License: EUPL-1.2
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/hedyorg-hedy

## The levels exist so that syntax can arrive one construct at a time

Hedy is described as a gradual programming language aimed at teaching programming and teaching Python. The first level offers printing text and asking for input, and that level is meant to introduce learners to the idea of a programming language and to the environment. From there, Hedy builds up to include more complex syntax and additional concepts.

The repository description is blunter about the trade: gradual languages use different language levels where each level adds new concepts and syntactic complexity, and at the end of the Hedy level sequence kids master a subset of syntactically valid Python.

That phrase, a subset of syntactically valid Python, is the whole design. Hedy is not Python with a friendly editor: learners reach a subset of valid Python syntax through earlier, less complex levels.

The consequence for a teacher is that migrating a class off Hedy is not free. Whatever subset of Python Hedy lands on is the subset learners actually know, and it is narrower than the language.

## This repository is the language, the web app and the test harness at once

The top level listing is long, and it explains what Hedy is operationally: a web application, a language implementation, and a content and translation pipeline.

The entry points are app.py, hedyweb.py, config.py, envs.py, utils.py, docs.py and logging_config.py, with gunicorn.conf.py and Procfile for serving. There is a Dockerfile, compose.yaml and a .devcontainer/, plus offline instructions as three separate files for macOS, Ubuntu and Windows, and app.spec and app_macos.spec for PyInstaller desktop builds.

The language side has its own directories. grammars-Total/ holds the grammar definitions, semantics/ holds the meaning of each construct, highlighting/ is for syntax highlighting in the browser, and content/ holds the lesson material. That separation is the interesting structural fact: the grammar, the semantics and the teaching content are three separate trees, so a language change and a lesson change are edits in different places.

Then there is translations/ and messages.pot, a gettext catalogue, with babel.cfg, static_babel_content.json and a static_babel_content.py that extracts translatable strings from the templates. Combined with static/, templates/, tailwind/ and the package.json toolchain, this is a full application rather than a compiler library.

## Offline Hedy exists because classrooms have bad wifi

The README states the latest version is at hedy.org, and then points at an Offline Hedy wiki page for people who want to download Hedy and run it on their own machine.

The offline path is not incidental. The repository carries three platform-specific readme files at the root, OFFLINE_README_MACOS.txt, OFFLINE_README_UBUNTU.txt and OFFLINE_README_WINDOWS.txt, which tells you that running the whole application on an unmanaged machine is a supported scenario rather than a hack.

For a classroom, that changes the deployment decision. The hosted site is the easy option, but a school with unreliable connectivity, or one that cannot send student work to a third party, needs the local path. That is presumably why the offline instructions are per operating system rather than one Docker command.

The Docker path also exists. compose.yaml is minimal, building from the Dockerfile, mapping port 8080 to container port 8000, and passing --access-logfile - --log-file - so logs go to standard output rather than to files inside the container.

## Translation is a first-class contribution path, not an afterthought

The README has a section inviting people to help translate Hedy through Weblate, and it states plainly that you do not need programming experience or knowledge to translate it.

The repository supports that at the code level. There is a translations/ directory, a messages.pot template, babel.cfg, and a static_babel_content.py script that walks the static content to produce the strings to translate. The greeting line in the README itself, Živjo Hedy! Привет Хеди! !سلام هيدي, is a small illustration of the range of languages the project maintains.

For anyone evaluating it, this cuts both ways. Broad translation coverage is a real strength for a teaching tool used across countries, and it also means the application has a substantial content pipeline that has to work before a new language is usable. A fork that adds one language inherits the extraction and build steps as well as the strings.

## Cypress runs the browser tests, doit drives the build

package.json describes itself as existing to bring in npm dependencies and orchestrate deploy-time build commands, which tells you the JavaScript side is a build orchestrator rather than the application itself. Its build script runs doit run deploy.

The Python side carries the task runner configuration in pyproject.toml, where doit is set to a json backend with a .doit.db.json dependency file and the doit_watch plugin loaded for file watching. dodo.py at the root is where the tasks live.

Testing is layered. There is tests/ for the unit level and tests_e2e.py at the root, and the Cypress scripts open or run the end to end specs under cypress/e2e. The Cypress dependencies include cypress-real-events for real browser events, puppeteer, chai-colors, code coverage plugins from both @cypress/code-coverage and istanbul, and nyc with its TypeScript config.

Requirements are split the same way. requirements.txt includes requirements-prod.txt and then adds the development tooling: pytest, pytest-cov, pytest-xdist, hypothesis for property based testing, doit, pyinstaller for the desktop builds, pylint and pre-commit. hypothesis in the list is the interesting one for a language implementation, since property based testing on a transpiler catches the cases you would not think to write.

## Maintenance cadence, licence, and the contribution expectations

The releases are frequent and dated. The recent versions are 26.10.8 on 2026-10-08, 26.10.10 on 2026-10-10 and 26.10.14 on 2026-10-14, and the last push was on 2026-10-16. The numbering is calendar based, so a release identifies the day it went out, which suits a project that ships to classrooms on a schedule.

The licence is EUPL-1.2, the European Union Public Licence. That is a copyleft licence and a different choice from the permissive licences most open source teaching tools use, so anyone planning to incorporate Hedy code into a closed platform should look at the obligations before assuming it is a drop-in.

The contributing guidance is unusually prescriptive and worth reading before opening a pull request. The README says the project does not have the bandwidth to inspect pull requests that are not aligned with its goals, and directs contributors to the wiki section on a first contribution, then to Discord in the #programmers-general channel.

There are separate issue templates for bugs, content issues, ideas for the interface and ideas for the language, which is a signal about where the project expects input. And it asks for neutral phrasing in bug reports, suggesting did not do what I expected rather than calling something broken.

## Conclusion

Adopt Hedy if you are teaching complete beginners, particularly younger children, and you want one artefact that takes them from printing text to Python without rewriting everything when real syntax arrives. Do not adopt it if the goal is that learners write real Python from the start, because Hedy's early levels use syntax that is deliberately not Python. Verify first which parts you are adopting, since the repository contains the language implementation, the web application, the translations and the end-to-end tests.

## FAQ

### What is Hedy and how does it teach programming?

Hedy is a gradual programming language for teaching children. The first level offers printing text and asking for input to introduce the idea of a programming language, and each level then adds new concepts and syntactic complexity.

### Does Hedy teach real Python?

The repository description states that at the end of the Hedy level sequence kids master a subset of syntactically valid Python, so the later levels use valid Python syntax while earlier levels deliberately do not.

### Can Hedy run without an internet connection?

Yes. The README points to an Offline Hedy page, and the repository ships separate offline instructions for macOS, Ubuntu and Windows as OFFLINE_README_MACOS.txt, OFFLINE_README_UBUNTU.txt and OFFLINE_README_WINDOWS.txt, plus PyInstaller spec files for desktop builds.

### How is Hedy tested?

There is a tests/ directory for unit tests plus an end to end suite run with Cypress, whose package.json scripts open or run specs under cypress/e2e. The Python requirements include pytest, pytest-cov, pytest-xdist and hypothesis.

### What licence is Hedy released under?

The repository declares the EUPL-1.2, the European Union Public Licence, with the licence text in the LICENSE file at the root.

## Sources

- [hedyorg/hedy on GitHub](https://github.com/hedyorg/hedy)
- [License: EUPL-1.2](https://github.com/hedyorg/hedy/blob/main/LICENSE)
- [Project website](https://www.hedy.org)
- [README](https://github.com/hedyorg/hedy/blob/main/README.md)
- [Releases](https://github.com/hedyorg/hedy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hedyorg-hedy