HoodScript

A Python 3 dialect whose grammar keywords come from documented features of African American Vernacular English, with strict 1:1 mapping to Python and crash reports written in plain English.

bet greet(who, greeting="wassup"):
    dip greeting + ", " + who

fam Dog:
    bet __init__(self, name):
        self.name = name
    bet speak(self):
        dip self.name + " says woof"

be i in 1..3:
    holla greet("fam"), Dog("Rex").speak(), i

Every keyword is one Python keyword under a different name. bet is def. dip is return. be is for. Nothing is added, nothing is reinterpreted. That means:

• .hs files can import any Python package (numpy, fastapi, json, …)
• Python files can import .hs modules after one line: hoodscript.install()
• Type checkers, linters, profilers, and debuggers all work on the output
• hood2py gives you back plain Python whenever you want to leave

Every keyword is cited. Tier A grammar words (be, finna, done, tryna) each have a Yale Grammatical Diversity Project page. Tier B lexical words (bet, fam, holla, dip, chill, cap) each have dictionary attestation of AAVE origin. The rest is Python's own word or plain English, labeled as such. Sources: hoodscript/docs/linguistics.md. Spec: GRAMMAR.md. Full table: docs/keywords.md.

Try it in the browser

khaoticdev62.github.io/hoodscript — HoodScript on the left, the exact Python on the right, live. Runs entirely in your browser (Pyodide); nothing is sent anywhere. Programs run inside the sandbox, so import os is refused and a runaway loop is stopped.

Install

git clone https://github.com/khaoticdev62/hoodscript && cd hoodscript
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Requires Python ≥ 3.10. To try it with no install at all, prefix commands with PYTHONPATH=src and use python3 -m hoodscript instead of hoodscript.

Run

hoodscript hello.hs           # transpile + execute
hoodscript -c hello.hs        # print the Python it becomes
hoodscript repl --mirror      # interactive REPL (hood> prompt; chill to exit; --mirror shows the Python)
hoodscript playground         # launch in-browser Pyodide WebAssembly playground
hoodscript kernel install     # Jupyter kernel (pip install "hoodscript[jupyter]"); or %load_ext hoodscript
hoodscript fmt|lint <file.hs> # formatter / linter (pip install "hoodscript[tools]")
hoodscript learn [topic]      # interactive tutor driving docs/curriculum.md
hoodscript                    # a short tour of all commands
hoodscript zen                # the Zen of HoodScript (HPEP 20); or `import vibe`
hoodscript lsp                # language server over stdio, for editors
hoodscript make-stubs f.py    # emit a .pyi-style stub with empty bodies

Convert

hood2py program.hs > program.py     # HoodScript → Python
py2hood program.py > program.hs     # Python → HoodScript

Both are token-level rewrites: comments, spacing, and line numbers survive round-trips untouched.

Crash reports

Unhandled exceptions never show a raw Python traceback. Every error is translated into plain English — what happened, why, and what to do — with a "did you mean?" computed from what was actually in scope:

🚨 HOODSCRIPT CRASH REPORT — HS0001 UnknownNameTrip

  File "boom.hs", line 4, in <module>()
    main()
  File "boom.hs", line 3, in main()
    holla totl
          ^^^^

What happened: I can't find anything called 'totl'.
Why: Nothing gave 'totl' a value before line 3, or it was spelled differently when it was created.
Fix: Did you mean 'total'? If not, set it first: `totl = ...` above this line.

(run with --python-traceback to see the raw Python error)

Thirty-five catalogued diagnostics (HS0001–HS0299), each with a worked example that the test suite executes. pip install "hoodscript[pretty]" adds colour and a box on terminals. --python-traceback shows the raw Python when you're debugging the compiler rather than a program.

The language in one screen

Everything else — if, else, while, import, with, match, None, self, every builtin — is Python's own word, and every Python keyword still works in a .hs file.

Play

pip install "hoodscript[farm]"
hoodfarm levels            # the 8 challenges
hoodfarm play 1            # edit solution.hs in your editor; the farm re-runs on every save
hoodfarm run my.hs -b      # headless benchmark, exit 0 on pass

The Drone Was Replaced: program a farming drone in HoodScript, one level at a time. Same language, same crash reports — the game just adds a bot.

pip install "hoodscript[arcade]"
hoodarcade                      # Big Mama's Cookout · BeatLab 808 · Drop Day
hoodarcade play cookout 1       # edit the solution file; the stage re-runs on save

Learn

• docs/onboarding.md — from zero to a running program in ten minutes
• docs/curriculum.md — ten lessons, each with a runnable file
• MANUAL.md — the full manual
• agents.md — architecture and subsystem walkthrough
• CLAUDE.md — the standing brief for anyone (human or agent) changing the code
• SPRINT_PLAN.md — what's next · CHANGELOG.md · CONTRIBUTING.md

Repo layout

src/hoodscript/   the package (transpiler, importer, cache, CLI, REPL, LSP, migrator)
tests/            pytest suite — includes one conformance test per keyword and one run per doc example
docs/             onboarding, curriculum, generated keyword table, archived plans
scripts/          gen_keywords.py
editors/vscode/   extension manifest
hoodscript/       Sprint 0–1 prototype: linguistic research, sourcing policy, v1.0 grammar — reference only

License

MIT — see LICENSE.