hoodscript 1.1.0__tar.gz → 1.2.0__tar.gz

{hoodscript-1.1.0 → hoodscript-1.2.0}/CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to HoodScript. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning: the keyword set is the public API; changing it is at least a minor bump.
 
+## [1.2.0] — 2026-09-11
+
+### Added
+
+- **Interactive Jupyter Notebook Kernel & IPython Magics** (`src/hoodscript/kernel/`, `examples/quickstart.ipynb`):
+  - Dedicated standalone Jupyter kernel (`hoodscript-kernel` / `HoodScriptKernel`) subclassing `ipykernel.kernelbase.Kernel`.
+  - Automatic 1:1 transpilation of notebook cells to Python prior to execution in the kernel's persistent namespace.
+  - Rich HTML plain-English JPE error cards rendered in-cell with collapsible raw Python tracebacks.
+  - Dynamic tab autocompletion over HoodScript keywords, patterns, exception names, and namespace variables.
+  - Cell and line inspection magics: `%hood_transpile` (preview generated Python without executing) and `%hood_tb` (toggle raw traceback view).
+  - IPython extension (`%load_ext hoodscript`) providing `%%hood` and `%%hood_transpile` for hybrid Python/HoodScript notebooks and Google Colab.
+  - CLI installer subcommand: `hoodscript kernel install [--user] [--prefix PREFIX]`.
+  - Interactive starter notebook: `examples/quickstart.ipynb`.
+  - Optional dependency extra: `pip install hoodscript[jupyter]`.
+  - QA (audited end to end over ZMQ with `jupyter_client` before acceptance; four
+    defects fixed): `holla` output never reached the cell (the base `Kernel`
+    never tells ipykernel's stdout stream which cell is running — `set_parent`
+    now does); a trailing bare expression displayed nothing (now shown as the
+    result, like IPython); crash cards showed the *Python* line (`def f()`) and,
+    for syntax errors, a stdlib `ast.py` frame (cells are registered in
+    `linecache` as `<notebook>`, a program pseudo-file; syntax errors carry no
+    frames); `%load_ext hoodscript` as documented did not work (only
+    `hoodscript.kernel` did) and `examples/quickstart.ipynb` had no kernelspec
+    metadata. `tests/test_kernel_zmq.py` drives the real kernel process.
+
+
 ## [1.1.0] — 2026-09-11
 
 The reconciled language. Every keyword is now either cited in
@@ -179,5 +205,6 @@ PEP 552 bytecode cache, CLI, REPL, crash reports with `*Trip` names,
 `py2hood` / `hood2py`, stub generator, pygls language server (diagnostics,
 hover, completion). Keyword set later found to be uncited — see v1.1.0.
 
+[1.2.0]: https://github.com/khaoticdev62/hoodscript/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/khaoticdev62/hoodscript/compare/bf801ab...v1.1.0
 [1.0.0]: https://github.com/khaoticdev62/hoodscript/commits/bf801ab

{hoodscript-1.1.0 → hoodscript-1.2.0}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.5
 Name: hoodscript
-Version: 1.1.0
+Version: 1.2.0
 Summary: A production-grade Python 3 conlang based on AAVE with 1:1 AST parity.
 License: MIT
 License-File: LICENSE
 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: prompt-toolkit>=3.0.40; extra == 'all'
@@ -16,6 +18,8 @@ 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: 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'
@@ -24,6 +28,9 @@ 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: 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'
@@ -96,6 +103,8 @@ with `PYTHONPATH=src` and use `python3 -m hoodscript` instead of `hoodscript`.
 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-1.1.0 → hoodscript-1.2.0}/README.md

@@ -58,6 +58,8 @@ with `PYTHONPATH=src` and use `python3 -m hoodscript` instead of `hoodscript`.
 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-1.1.0 → hoodscript-1.2.0}/SECURITY.md

@@ -50,14 +50,16 @@ To protect host environments against runaway workloads, the sandbox enforces thr
 
 ## 4. Code Execution Audit
 
-`exec`/`eval` appear in exactly four places, all on code objects produced by
+`exec`/`eval` appear in exactly six places, all on code objects produced by
 `compile()` from the transpiler's output of the user's own source — never on
 text from anywhere else:
 1. `src/hoodscript/cli.py` — running a file
 2. `src/hoodscript/repl.py` — the interactive session (`eval` first, `exec` fallback)
 3. `src/hoodscript/debugger.py` — running a file under debugpy
 4. `src/hoodscript/tutor.py` — running a curriculum lesson
-`tests/security/test_exec_sites.py` fails if a fifth appears.
+5. `src/hoodscript/kernel/kernel.py` — executing notebook cells in the HoodScript kernel
+6. `src/hoodscript/kernel/magics.py` — executing `%%hood` cells in IPython / Google Colab
+`tests/security/test_exec_sites.py` fails if a seventh appears.
 
 ### Why this is safe and equivalent to `compile()`:
 - `transpile()` performs strictly lexical substitution over Python's `tokenize.tokenize` stream and deterministic character-preserving pattern transforms (Rules R1–R12).

{hoodscript-1.1.0 → hoodscript-1.2.0}/docs/onboarding.md

@@ -219,14 +219,42 @@ Speaks the Language Server Protocol over stdio. Provides:
 Point any LSP-capable editor at that command for the `hoodscript` language ID.
 A VS Code extension manifest lives in `editors/vscode/`.
 
-## 11. Run the tests
+## 11. Jupyter Notebooks & Google Colab
+
+Use HoodScript interactively inside JupyterLab, classic Notebooks, or Google Colab:
+
+### Option A: Dedicated Jupyter Kernel
+```bash
+pip install hoodscript[jupyter]
+hoodscript kernel install
+jupyter lab
+```
+Select the **HoodScript** kernel from the launcher. Every cell executes native HoodScript with tab completion and rich plain-English JPE error cards.
+
+### Option B: Google Colab & Existing Python Notebooks
+In the first cell:
+```python
+!pip install hoodscript[jupyter]
+%load_ext hoodscript
+```
+Now write HoodScript in any cell using `%%hood`:
+```ipython
+%%hood
+bet calculate(x):
+    dip x * 10
+
+holla "Result:", calculate(4.2)
+```
+Preview the generated Python anytime with `%%hood_transpile`.
+
+## 12. Run the tests
 
 ```bash
 pytest                          # with the venv
 PYTHONPATH=src pytest tests/    # without an editable install
 ```
 
-## 12. Where to go next
+## 13. Where to go next
 
 - [`curriculum.md`](curriculum.md) — ten lessons covering the whole language
 - [`../agents.md`](../agents.md) — how the transpiler, importer, cache, and

hoodscript-1.2.0/examples/quickstart.ipynb

@@ -0,0 +1,142 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# HoodScript Interactive Quickstart Notebook\n",
+    "\n",
+    "Welcome to **HoodScript** in Jupyter! HoodScript maps authentic AAVE keywords **1:1 to Python 3** and explains every error in **plain conversational English**.\n",
+    "\n",
+    "### Two Ways to Use HoodScript in Notebooks:\n",
+    "1. **Native HoodScript Kernel**: Select `HoodScript` from the kernel dropdown.\n",
+    "2. **IPython Magic**: In a standard Python notebook or Google Colab, run `%load_ext hoodscript` and use `%%hood` at the top of cells."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Lesson 1: Values, Booleans, and holla\n",
+    "name = \"Khris\"\n",
+    "age = 28\n",
+    "verified = no cap    # True\n",
+    "fake = cap           # False\n",
+    "\n",
+    "holla \"User:\", name, \"Age:\", age, \"Verified:\", verified"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Live Transpilation Inspection\n",
+    "HoodScript adheres strictly to the **1:1 Law**: every line of HoodScript corresponds to valid Python with preserved line numbers.\n",
+    "Use `%hood_transpile` to inspect the generated Python code:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%hood_transpile\n",
+    "be i in 1..5:\n",
+    "    if i == 3:\n",
+    "        skip\n",
+    "    holla \"Lap:\", i"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Loops and Inclusive Ranges: `be` and `1..n`\n",
+    "`be x in xs` represents habitual action (Python's `for x in xs`). `1..5` is an inclusive range (1, 2, 3, 4, 5)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "total = 0\n",
+    "be i in 1..10:\n",
+    "    total = total + i\n",
+    "\n",
+    "holla \"Sum of 1..10 is:\", total"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Functions and Classes: `bet`, `dip`, and `fam`\n",
+    "`bet` defines a function; `dip` returns with a value; `fam` defines a class."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bet apply_discount(price, pct=0.15):\n",
+    "    dip price * (1.0 - pct)\n",
+    "\n",
+    "fam Shopper:\n",
+    "    bet __init__(self, name, wallet):\n",
+    "        self.name = name\n",
+    "        self.wallet = wallet\n",
+    "\n",
+    "    bet purchase(self, item_name, original_price):\n",
+    "        final_price = apply_discount(original_price)\n",
+    "        self.wallet = self.wallet - final_price\n",
+    "        holla self.name, \"bought\", item_name, \"for\", final_price, \"| Balance remaining:\", self.wallet\n",
+    "\n",
+    "buyer = Shopper(\"Sam\", 150.0)\n",
+    "buyer.purchase(\"Sneakers\", 80.0)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Plain-English Error Handling: `tryna`, `catch`, and `ZeroSplitTrip`\n",
+    "Exceptions are never dumped as raw Python tracebacks; they are rendered with plain-English explanations, causes, and suggestions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tryna:\n",
+    "    result = 100 / 0\n",
+    "catch ZeroSplitTrip as err:\n",
+    "    holla \"Caught expected error:\", err\n",
+    "regardless:\n",
+    "    holla \"Execution completed clean.\""
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "hoodscript",
+   "file_extension": ".hs",
+   "mimetype": "text/x-hoodscript"
+  },
+  "kernelspec": {
+   "name": "hoodscript",
+   "display_name": "HoodScript",
+   "language": "hoodscript"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

{hoodscript-1.1.0 → hoodscript-1.2.0}/pyproject.toml

@@ -16,7 +16,8 @@ repl = ["prompt-toolkit>=3.0.40"]
 lsp = ["pygls>=1.3.1,<2", "jedi>=0.19.1"]
 tools = ["ruff>=0.3.0", "mypy>=1.9.0"]
 pretty = ["rich>=13.7"]
-all = ["prompt-toolkit>=3.0.40", "pygls>=1.3.1,<2", "jedi>=0.19.1", "rich>=13.7", "ruff>=0.3.0", "mypy>=1.9.0"]
+jupyter = ["ipykernel>=6.0.0", "ipython>=8.0.0"]
+all = ["prompt-toolkit>=3.0.40", "pygls>=1.3.1,<2", "jedi>=0.19.1", "rich>=13.7", "ruff>=0.3.0", "mypy>=1.9.0", "ipykernel>=6.0.0", "ipython>=8.0.0"]
 dev = [
     "rich>=13.7",
     "pytest>=8.0.0",
@@ -29,11 +30,14 @@ dev = [
     "pygls>=1.3.1,<2",
     "jedi>=0.19.1",
     "hatch-vcs>=0.4.0",
+    "ipykernel>=6.0.0",
+    "ipython>=8.0.0",
 ]
 
 [project.scripts]
 hoodscript = "hoodscript.cli:main"
 hoodscript-lsp = "hoodscript.lsp:run_lsp"
+hoodscript-kernel = "hoodscript.kernel.__main__:main"
 py2hood = "hoodscript.migrator:py2hood_main"
 hood2py = "hoodscript.migrator:hood2py_main"
 

hoodscript-1.2.0/src/hoodscript/__init__.py

@@ -0,0 +1,16 @@
+from hoodscript.importer import install, uninstall
+from hoodscript.transpiler import transpile
+
+try:
+    from hoodscript._version import __version__
+except ImportError:
+    __version__ = "1.1.0"
+
+__all__ = ["transpile", "install", "uninstall", "__version__", "load_ipython_extension"]
+
+
+def load_ipython_extension(ipython):
+    """`%load_ext hoodscript` in IPython/Jupyter: registers the %%hood and
+    %hood_transpile magics. Imported lazily so the core stays dependency-free."""
+    from hoodscript.kernel.magics import load_ipython_extension as _load
+    _load(ipython)

{hoodscript-1.1.0 → hoodscript-1.2.0}/src/hoodscript/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.0'
-__version_tuple__ = version_tuple = (1, 1, 0)
+__version__ = version = '1.2.0'
+__version_tuple__ = version_tuple = (1, 2, 0)
 
 __commit_id__ = commit_id = None

{hoodscript-1.1.0 → hoodscript-1.2.0}/src/hoodscript/cli.py

@@ -25,6 +25,7 @@ Usage:
   hoodscript debug <file.hs>        Debug program under debugpy / DAP
   hoodscript tokens                 Show all keywords and mappings
   hoodscript playground [--port]    Launch Web Playground in browser
+  hoodscript kernel install         Register HoodScript Jupyter kernel
   hoodscript lsp                    Start Language Server
   hoodscript version                Show version information
   hoodscript completion [bash|zsh]  Generate shell autocompletion
@@ -86,7 +87,8 @@ _hoodscript_completion() {
     local cur prev words cword
     _init_completion || return
 
-    local commands="run build check fmt lint repl tokens learn lsp version completion make-stubs debug playground"
+    local commands="run build check fmt lint repl tokens learn lsp version"
+    commands="$commands completion make-stubs debug playground kernel"
     local topics="basics flow functions classes errors async mirror all"
 
     if [[ $cword -eq 1 ]]; then
@@ -348,6 +350,32 @@ def playground_command(args: list[str]) -> int:
         return 1
 
 
+def kernel_command(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="hoodscript kernel", description="Manage HoodScript Jupyter kernel")
+    subparsers = parser.add_subparsers(dest="subcommand")
+    install_parser = subparsers.add_parser("install", help="Install Jupyter kernelspec")
+    install_parser.add_argument("--user", action="store_true", default=True, help="Install for current user (default)")
+    install_parser.add_argument("--sys-prefix", action="store_true", help="Install to sys.prefix")
+    install_parser.add_argument("--prefix", default=None, help="Install to specified prefix")
+    pargs = parser.parse_args(args)
+
+    if pargs.subcommand == "install":
+        try:
+            from hoodscript.kernel.installer import install_kernelspec
+        except ImportError as exc:
+            sys.stderr.write(f"Jupyter dependencies not installed: {exc}\nRun: pip install hoodscript[jupyter]\n")
+            return 1
+
+        prefix = sys.prefix if pargs.sys_prefix else pargs.prefix
+        user = not pargs.sys_prefix and pargs.prefix is None
+        path = install_kernelspec(user=user, prefix=prefix)
+        sys.stdout.write(f"Installed HoodScript kernel spec to {path}\n")
+        return 0
+
+    parser.print_help()
+    return 0
+
+
 def main(argv=None) -> int:
     if argv is None:
         argv = sys.argv[1:]
@@ -397,6 +425,8 @@ def main(argv=None) -> int:
         return debug_command(argv[1:])
     if cmd == "playground":
         return playground_command(argv[1:])
+    if cmd == "kernel":
+        return kernel_command(argv[1:])
     if cmd == "build":
         # build <file> transpiles to stdout (alias for -c)
         if len(argv) < 2:

{hoodscript-1.1.0 → hoodscript-1.2.0}/src/hoodscript/errors/translator.py

@@ -167,7 +167,8 @@ def _fill(template, facts):
 # --------------------------------------------------------------------------- entry point
 
 def diagnose(exc_type, exc, tb, filename=None) -> Diagnostic:
-    frames = user_frames(tb) if tb is not None else []
+    # a SyntaxError is compile-time: the frames belong to whoever called compile(), never to the program
+    frames = user_frames(tb) if tb is not None and not isinstance(exc, SyntaxError) else []
     entry, caught = find(exc)
     suggestion = _suggest(exc, tb, filename or (frames[-1].filename if frames else None))
 
@@ -176,6 +177,8 @@ def diagnose(exc_type, exc, tb, filename=None) -> Diagnostic:
         col = (exc.offset - 1) if exc.offset else None
         end_col = (exc.end_offset - 1) if getattr(exc, "end_offset", None) else None
         source_line = (exc.text or "").rstrip("\n")
+        if fname and fname.startswith("<") and lineno:   # pseudo-file: exc.text is the Python; show the HoodScript
+            source_line = linecache.getline(fname, lineno).rstrip("\n") or source_line
     elif frames:
         last = frames[-1]
         fname, lineno = last.filename, last.lineno

hoodscript-1.2.0/src/hoodscript/kernel/__init__.py

@@ -0,0 +1,12 @@
+"""HoodScript Jupyter and IPython Kernel Integration.
+
+Provides:
+- HoodScriptKernel: Dedicated standalone Jupyter kernel.
+- HoodScriptMagics: IPython extension for %%hood and %%hood_transpile.
+- install_kernelspec: Programmatic and CLI installer for the kernelspec.
+"""
+
+from hoodscript.kernel.kernel import HoodScriptKernel
+from hoodscript.kernel.magics import load_ipython_extension
+
+__all__ = ["HoodScriptKernel", "load_ipython_extension"]

hoodscript-1.2.0/src/hoodscript/kernel/__main__.py

@@ -0,0 +1,13 @@
+"""Entry point for launching the HoodScript Jupyter Kernel."""
+
+from ipykernel.kernelapp import IPKernelApp
+
+from hoodscript.kernel.kernel import HoodScriptKernel
+
+
+def main():
+    IPKernelApp.launch_instance(kernel_class=HoodScriptKernel)
+
+
+if __name__ == "__main__":
+    main()

hoodscript-1.2.0/src/hoodscript/kernel/installer.py

@@ -0,0 +1,54 @@
+"""Kernelspec installer for the HoodScript Jupyter Kernel."""
+
+import json
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+from jupyter_client.kernelspec import KernelSpecManager
+
+ROOT = Path(__file__).resolve().parents[3]
+ICON_PATH = ROOT / "editors" / "vscode" / "icon.png"
+
+KERNEL_SPEC = {
+    "argv": [
+        sys.executable,
+        "-m",
+        "hoodscript.kernel",
+        "-f",
+        "{connection_file}",
+    ],
+    "display_name": "HoodScript",
+    "language": "hoodscript",
+    "metadata": {
+        "debugger": False,
+    },
+}
+
+
+def install_kernelspec(user: bool = True, prefix: str | None = None) -> str:
+    """Install the HoodScript kernelspec into Jupyter.
+
+    Returns the directory path where the kernelspec was installed.
+    """
+    with tempfile.TemporaryDirectory() as td:
+        dest_dir = Path(td) / "hoodscript"
+        dest_dir.mkdir(parents=True, exist_ok=True)
+
+        # Write kernel.json
+        (dest_dir / "kernel.json").write_text(json.dumps(KERNEL_SPEC, indent=2), encoding="utf-8")
+
+        # Copy icons if available
+        if ICON_PATH.exists():
+            shutil.copy2(ICON_PATH, dest_dir / "logo-64x64.png")
+            shutil.copy2(ICON_PATH, dest_dir / "logo-32x32.png")
+
+        manager = KernelSpecManager()
+        installed_path = manager.install_kernel_spec(
+            str(dest_dir),
+            kernel_name="hoodscript",
+            user=user,
+            prefix=prefix,
+        )
+        return installed_path