U-Script

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:

• .us files can import any Python package (numpy, fastapi, json, …)
• Python files can import .us modules after one line: uscript.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: uscript/docs/linguistics.md. Spec: GRAMMAR.md. Full table: docs/keywords.md.

Try it in the browser

khaoticdev62.github.io/uscript — U-Script 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/uscript && cd uscript
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 uscript instead of uscript.

Run

uscript hello.us           # transpile + execute
uscript -c hello.us        # print the Python it becomes
uscript repl --mirror      # interactive REPL (hood> prompt; chill to exit; --mirror shows the Python)
uscript playground         # launch in-browser Pyodide WebAssembly playground
uscript kernel install     # Jupyter kernel (pip install "uscript[jupyter]"); or %load_ext uscript
uscript fmt|lint <file.us> # formatter / linter (pip install "uscript[tools]"); lint has HL001–HL006
uscript test [project]      # run the project's pytest suite from its root
uscript replay <file.us>   # run it, then step through it backwards (b/f/j/l/v/w); --dump prints all
uscript migrate <file.us>  # rewrite v1.0.0 code (cook/serve/holler/Facts…) to the v1.1 lexicon; -w writes, --diff shows
uscript sourcing <word>    # Rule Zero check: standing, Green's Dictionary of Slang, UD liability screen, --coraal PATH
uscript learn [topic]      # interactive tutor driving docs/curriculum.md
uscript                    # a short tour of all commands
uscript zen                # the Zen of U-Script (HPEP 20); or `import vibe`
uscript lsp                # language server over stdio, for editors
uscript make-stubs f.py    # emit a .pyi-style stub with empty bodies
uscript version --json      # machine-readable package/language compatibility info
uscript compat app.us       # validate a source file without running it

Convert

hood2py program.us > program.py     # U-Script → Python
py2hood program.py > program.us     # Python → U-Script

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:

🚨 USCRIPT CRASH REPORT — HS0001 UnknownNameTrip

  File "boom.us", line 4, in <module>()
    main()
  File "boom.us", 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 "uscript[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 .us file.

Play

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

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

pip install "uscript[arcade]"
uarcade                      # Big Mama's Cookout · BeatLab 808 · Drop Day
uarcade 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
• docs/hoodlib.md — the small standard library: chart (sparklines, bars, histograms), disk (atomic files)
• 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/uscript/   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
uscript/       Sprint 0–1 prototype: linguistic research, sourcing policy, v1.0 grammar — reference only

License

MIT — see LICENSE.