Metadata-Version: 2.5
Name: uscript
Version: 1.6.4
Summary: A production-grade Python 3 conlang based on AAVE with 1:1 AST parity.
Project-URL: Homepage, https://github.com/khaoticdev62/uscript
Project-URL: Documentation, https://khaoticdev62.github.io/uscript/
Project-URL: Repository, https://github.com/khaoticdev62/uscript
Project-URL: Issues, https://github.com/khaoticdev62/uscript/issues
Author: Khaotic Labs
License: MIT
License-File: LICENSE
Keywords: aave,developer-tools,education,programming-language,python
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Software Development :: Compilers
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: ipykernel>=6.0.0; extra == 'all'
Requires-Dist: ipython>=8.0.0; extra == 'all'
Requires-Dist: jedi>=0.19.1; extra == 'all'
Requires-Dist: mypy>=1.9.0; extra == 'all'
Requires-Dist: pdoc>=14.0.0; extra == 'all'
Requires-Dist: prompt-toolkit>=3.0.40; extra == 'all'
Requires-Dist: pygls<2,>=1.3.1; extra == 'all'
Requires-Dist: rich>=13.7; extra == 'all'
Requires-Dist: ruff>=0.3.0; extra == 'all'
Provides-Extra: arcade
Requires-Dist: rich>=13.7; extra == 'arcade'
Provides-Extra: dev
Requires-Dist: build>=1.1.0; extra == 'dev'
Requires-Dist: debugpy>=1.8.0; extra == 'dev'
Requires-Dist: hatch-vcs>=0.4.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: ipykernel>=6.0.0; extra == 'dev'
Requires-Dist: ipython>=8.0.0; extra == 'dev'
Requires-Dist: jedi>=0.19.1; extra == 'dev'
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: prompt-toolkit>=3.0.40; extra == 'dev'
Requires-Dist: pygls<2,>=1.3.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: rich>=13.7; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: doc
Requires-Dist: pdoc>=14.0.0; extra == 'doc'
Provides-Extra: farm
Requires-Dist: rich>=13.7; extra == 'farm'
Provides-Extra: jupyter
Requires-Dist: ipykernel>=6.0.0; extra == 'jupyter'
Requires-Dist: ipython>=8.0.0; extra == 'jupyter'
Provides-Extra: lsp
Requires-Dist: jedi>=0.19.1; extra == 'lsp'
Requires-Dist: pygls<2,>=1.3.1; extra == 'lsp'
Provides-Extra: pretty
Requires-Dist: rich>=13.7; extra == 'pretty'
Provides-Extra: repl
Requires-Dist: prompt-toolkit>=3.0.40; extra == 'repl'
Provides-Extra: tools
Requires-Dist: mypy>=1.9.0; extra == 'tools'
Requires-Dist: ruff>=0.3.0; extra == 'tools'
Description-Content-Type: text/markdown

# 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**.

```hood
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`](uscript/docs/linguistics.md).
Spec: [`GRAMMAR.md`](GRAMMAR.md). Full table: [`docs/keywords.md`](docs/keywords.md).

## Try it in the browser

**[khaoticdev62.github.io/uscript](https://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

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

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

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

| Python | U-Script | | Python | U-Script |
|---|---|---|---|---|
| `def` / `return` | `bet` / `dip` | | `try` / `except` / `finally` | `tryna` / `catch` / `regardless` |
| `class` | `fam` | | `raise` | `throw` |
| `for` | `be` | | `continue` / `pass` | `skip` / `chill` |
| `async` / `await` | `finna` / `done` | | `False` | `cap` |
| `print` / `input` | `holla` / `ask` | | `ValueError`, `KeyError`, … | `BadValueTrip`, `MissingKeyTrip`, … |
| `True` | `no cap` | | `not` | `ain't` / `ain't nobody` |
| `while True:` | `steady:` | | `x is not None` | `it's x` |
| `X: Final = v` | `BIN X = v` | | `range(a, b + 1)` | `a..b` |
| `elif` | `else if` | | | |

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

```bash
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`.

```bash
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`](docs/onboarding.md) — from zero to a running program in ten minutes
- [`docs/curriculum.md`](docs/curriculum.md) — ten lessons, each with a runnable file
- [`MANUAL.md`](MANUAL.md) — the full manual
- [`docs/hoodlib.md`](docs/hoodlib.md) — the small standard library: `chart` (sparklines, bars, histograms), `disk` (atomic files)
- [`agents.md`](agents.md) — architecture and subsystem walkthrough
- [`CLAUDE.md`](CLAUDE.md) — the standing brief for anyone (human or agent) changing the code
- [`SPRINT_PLAN.md`](SPRINT_PLAN.md) — what's next · [`CHANGELOG.md`](CHANGELOG.md) · [`CONTRIBUTING.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](LICENSE).
