pykernel-cli 1.0.0__py3-none-any.whl

pykernel/__main__.py

@@ -0,0 +1,2 @@
+from pykernel.kernel import main
+main()

pykernel/commands/builtins.py

@@ -0,0 +1,144 @@
+"""
+Built-in commands — always available.
+
+/help   [command]      — list all commands or describe one
+/exit   | /quit        — exit the kernel
+/clear                 — clear the screen
+/history  [n]          — show last n inputs (default 20)
+/run   <file.py>       — execute a Python file inside the kernel
+/reset                 — clear the execution namespace
+/alias <new> <target>  — create an alias for an existing command
+/commands              — list all commands (alias for /help)
+"""
+
+import os, pathlib, traceback
+from pykernel.core.registry import CommandRegistry
+
+
+def register(reg: CommandRegistry):
+
+    # ── /help ─────────────────────────────────────────────────────────────────
+
+    @reg.command("help", aliases=["?", "commands"],
+                 help="List commands or show help for a specific command",
+                 usage="/help [command]",
+                 category="Core")
+    def cmd_help(ctx, *args):
+        p = ctx.paint
+        if args:
+            name = args[0].lstrip("/")
+            cmd  = ctx.registry.resolve(name)
+            if cmd is None:
+                ctx.print(p.error(f"No command: /{name}"))
+                return
+            ctx.print(p.header(f"  /{cmd.name}"))
+            if cmd.aliases:
+                ctx.print(p.dim(f"  Aliases : " + ", ".join(f"/{a}" for a in cmd.aliases)))
+            ctx.print(p.dim(f"  Usage   : {cmd.usage}"))
+            ctx.print(f"  {cmd.help}")
+            return
+
+        by_cat = ctx.registry.by_category()
+        ctx.print()
+        for cat, cmds in sorted(by_cat.items()):
+            ctx.print(p.header(f" {cat}"))
+            rows = [(f"/{c.name}", ", ".join(f"/{a}" for a in c.aliases), c.help)
+                    for c in cmds]
+            ctx.print(p.table(rows, headers=["Command", "Aliases", "Description"]))
+            ctx.print()
+        ctx.print(p.dim("  Tip: type /help <command> for detailed usage."))
+        ctx.print()
+
+    # ── /exit ─────────────────────────────────────────────────────────────────
+
+    @reg.command("exit", aliases=["quit", "q"],
+                 help="Exit the kernel",
+                 usage="/exit",
+                 category="Core")
+    def cmd_exit(ctx, *args):
+        ctx.print(ctx.paint.dim("  Goodbye."))
+        raise SystemExit(0)
+
+    # ── /clear ────────────────────────────────────────────────────────────────
+
+    @reg.command("clear", aliases=["cls"],
+                 help="Clear the terminal screen",
+                 usage="/clear",
+                 category="Core")
+    def cmd_clear(ctx, *args):
+        os.system("clear" if os.name != "nt" else "cls")
+
+    # ── /history ──────────────────────────────────────────────────────────────
+
+    @reg.command("history", aliases=["hist"],
+                 help="Show recent input history",
+                 usage="/history [n]",
+                 category="Core")
+    def cmd_history(ctx, *args):
+        p   = ctx.paint
+        n   = int(args[0]) if args and args[0].isdigit() else 20
+        items = ctx.history[-(n):]
+        if not items:
+            ctx.print(p.dim("  (no history yet)"))
+            return
+        ctx.print()
+        for i, entry in enumerate(items, start=max(1, len(ctx.history) - n + 1)):
+            prefix = p.dim(f"  {i:>4} │ ")
+            # truncate long entries
+            snippet = entry.replace("\n", "⏎ ")[:80]
+            ctx.print(prefix + snippet)
+        ctx.print()
+
+    # ── /run ──────────────────────────────────────────────────────────────────
+
+    @reg.command("run",
+                 help="Execute a Python file in the kernel namespace",
+                 usage="/run <path/to/file.py>",
+                 category="Core")
+    def cmd_run(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /run <path/to/file.py>"))
+            return
+        fpath = pathlib.Path(args[0]).expanduser()
+        if not fpath.exists():
+            ctx.print(p.error(f"File not found: {fpath}"))
+            return
+        try:
+            source = fpath.read_text()
+            exec(compile(source, str(fpath), "exec"), ctx.env)
+            ctx.print(p.success(f"  ✓  Ran {fpath.name}"))
+        except Exception:
+            ctx.print(p.error(traceback.format_exc()))
+
+    # ── /reset ────────────────────────────────────────────────────────────────
+
+    @reg.command("reset",
+                 help="Clear all variables from the kernel namespace",
+                 usage="/reset",
+                 category="Core")
+    def cmd_reset(ctx, *args):
+        kept = {"__name__", "__builtins__"}
+        for k in list(ctx.env.keys()):
+            if k not in kept:
+                del ctx.env[k]
+        ctx.print(ctx.paint.success("  ✓  Namespace cleared."))
+
+    # ── /alias ────────────────────────────────────────────────────────────────
+
+    @reg.command("alias",
+                 help="Create an alias for an existing command  (/alias hi greet)",
+                 usage="/alias <new_name> <existing_command>",
+                 category="Core")
+    def cmd_alias(ctx, *args):
+        p = ctx.paint
+        if len(args) < 2:
+            ctx.print(p.error("Usage: /alias <new_name> <existing_command>"))
+            return
+        new_name, target = args[0].lstrip("/"), args[1].lstrip("/")
+        cmd = ctx.registry.resolve(target)
+        if cmd is None:
+            ctx.print(p.error(f"No command: /{target}"))
+            return
+        ctx.registry._alias[new_name] = cmd.name
+        ctx.print(p.success(f"  ✓  /{new_name} → /{cmd.name}"))

pykernel/commands/inspector.py

@@ -0,0 +1,164 @@
+"""
+Inspector commands — explore the live kernel namespace.
+
+/vars             — list all variables in the namespace
+/who    <name>    — print type + repr of a variable
+/doc    <name>    — show docstring
+/source <name>    — show source code (functions / classes)
+/del    <name>    — delete a variable
+/timeit <expr>    — time an expression
+"""
+
+import inspect, timeit as _timeit, textwrap
+from pykernel.core.registry import CommandRegistry
+
+
+def register(reg: CommandRegistry):
+
+    # ── /vars ─────────────────────────────────────────────────────────────────
+
+    @reg.command("vars", aliases=["ls", "env"],
+                 help="List all variables in the kernel namespace",
+                 usage="/vars",
+                 category="Inspector")
+    def cmd_vars(ctx, *args):
+        p    = ctx.paint
+        ns   = ctx.namespace_vars()
+        if not ns:
+            ctx.print(p.dim("  (namespace is empty)"))
+            return
+        rows = []
+        for name, val in sorted(ns.items()):
+            typ     = type(val).__name__
+            snippet = repr(val)[:60].replace("\n", " ")
+            rows.append((name, typ, snippet))
+        ctx.print()
+        ctx.print(p.table(rows, headers=["Name", "Type", "Value"]))
+        ctx.print()
+
+    # ── /who ──────────────────────────────────────────────────────────────────
+
+    @reg.command("who",
+                 help="Show detailed info about a variable",
+                 usage="/who <name>",
+                 category="Inspector")
+    def cmd_who(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /who <name>"))
+            return
+        name = args[0]
+        if not ctx.has_var(name):
+            ctx.print(p.error(f"'{name}' is not defined in the namespace"))
+            return
+        val  = ctx.get_var(name)
+        typ  = type(val)
+        ctx.print()
+        ctx.print(p.header(f"  {name}"))
+        ctx.print(f"  type      : {p.code(typ.__module__ + '.' + typ.__name__)}")
+        ctx.print(f"  repr      : {repr(val)[:120]}")
+        if hasattr(val, "__len__"):
+            try: ctx.print(f"  len       : {len(val)}")
+            except: pass
+        if hasattr(val, "shape"):
+            ctx.print(f"  shape     : {val.shape}")
+        if hasattr(val, "dtype"):
+            ctx.print(f"  dtype     : {val.dtype}")
+        ctx.print(f"  id        : {id(val)}")
+        ctx.print()
+
+    # ── /doc ──────────────────────────────────────────────────────────────────
+
+    @reg.command("doc",
+                 help="Show the docstring of a name",
+                 usage="/doc <name>",
+                 category="Inspector")
+    def cmd_doc(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /doc <name>"))
+            return
+        name = args[0]
+        # try namespace first, then builtins
+        val = ctx.get_var(name, None) or __builtins__.__dict__.get(name) if isinstance(__builtins__, dict) else getattr(__builtins__, name, None)
+        if val is None:
+            try:
+                import builtins
+                val = getattr(builtins, name, None)
+            except: pass
+        if val is None:
+            ctx.print(p.error(f"'{name}' not found"))
+            return
+        doc = inspect.getdoc(val) or "(no docstring)"
+        ctx.print()
+        ctx.print(p.header(f"  {name}"))
+        ctx.print(textwrap.indent(doc, "  "))
+        ctx.print()
+
+    # ── /source ───────────────────────────────────────────────────────────────
+
+    @reg.command("source", aliases=["src"],
+                 help="Show source code of a function or class",
+                 usage="/source <name>",
+                 category="Inspector")
+    def cmd_source(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /source <name>"))
+            return
+        name = args[0]
+        val  = ctx.get_var(name)
+        if val is None:
+            ctx.print(p.error(f"'{name}' not in namespace"))
+            return
+        try:
+            src = inspect.getsource(val)
+            ctx.print()
+            ctx.print(p.code(src))
+            ctx.print()
+        except (TypeError, OSError) as e:
+            ctx.print(p.error(str(e)))
+
+    # ── /del ──────────────────────────────────────────────────────────────────
+
+    @reg.command("del", aliases=["delete", "rm"],
+                 help="Delete a variable from the namespace",
+                 usage="/del <name>",
+                 category="Inspector")
+    def cmd_del(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /del <name>"))
+            return
+        for name in args:
+            if ctx.delete_var(name):
+                ctx.print(p.success(f"  ✓  Deleted '{name}'"))
+            else:
+                ctx.print(p.warning(f"  ⚠  '{name}' not in namespace"))
+
+    # ── /timeit ───────────────────────────────────────────────────────────────
+
+    @reg.command("timeit",
+                 help="Time an expression  (/timeit sum(range(1000000)))",
+                 usage="/timeit <expression>  [repeat=N]",
+                 category="Inspector")
+    def cmd_timeit(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /timeit <expression>"))
+            return
+        # allow trailing repeat=N
+        repeat = 3
+        expr_parts = list(args)
+        if expr_parts and expr_parts[-1].startswith("repeat="):
+            try: repeat = int(expr_parts.pop()[7:])
+            except: pass
+        expr = " ".join(expr_parts)
+        try:
+            times  = _timeit.repeat(expr, globals=ctx.env, repeat=repeat, number=1000)
+            best   = min(times) * 1_000_000 / 1000  # µs per loop
+            ctx.print()
+            ctx.print(p.info(f"  {best:.3f} µs ± per loop  (best of {repeat}×1000)"))
+            ctx.print()
+        except Exception as e:
+            ctx.print(p.error(str(e)))

pykernel/commands/shell.py

@@ -0,0 +1,101 @@
+"""
+Shell commands — run system commands, navigate dirs, etc.
+
+/sh   <cmd>    — run a shell command (output captured into _)
+/cd   <dir>    — change working directory
+/pwd           — print working directory
+/ls   [dir]    — list directory contents
+"""
+
+import os, subprocess, shlex, pathlib
+from pykernel.core.registry import CommandRegistry
+
+
+def register(reg: CommandRegistry):
+
+    # ── /sh ───────────────────────────────────────────────────────────────────
+
+    @reg.command("sh", aliases=["!"],
+                 help="Run a shell command; output stored in `_out`",
+                 usage="/sh <shell command>",
+                 category="Shell")
+    def cmd_sh(ctx, *args):
+        p   = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /sh <command>"))
+            return
+        cmd = " ".join(args)
+        try:
+            result = subprocess.run(
+                cmd, shell=True, text=True,
+                capture_output=True
+            )
+            out = result.stdout
+            err = result.stderr
+            if out:
+                ctx.print(out, end="")
+            if err:
+                ctx.print(p.warning(err), end="")
+            if result.returncode != 0:
+                ctx.print(p.dim(f"  exit code: {result.returncode}"))
+            # inject result into namespace
+            ctx.set_var("_out",     out)
+            ctx.set_var("_err",     err)
+            ctx.set_var("_retcode", result.returncode)
+        except Exception as e:
+            ctx.print(p.error(str(e)))
+
+    # ── /cd ───────────────────────────────────────────────────────────────────
+
+    @reg.command("cd",
+                 help="Change the current working directory",
+                 usage="/cd <path>",
+                 category="Shell")
+    def cmd_cd(ctx, *args):
+        p    = ctx.paint
+        dest = pathlib.Path(args[0]).expanduser() if args else pathlib.Path.home()
+        try:
+            os.chdir(dest)
+            ctx.print(p.info(f"  → {os.getcwd()}"))
+        except FileNotFoundError:
+            ctx.print(p.error(f"Directory not found: {dest}"))
+        except PermissionError:
+            ctx.print(p.error(f"Permission denied: {dest}"))
+
+    # ── /pwd ──────────────────────────────────────────────────────────────────
+
+    @reg.command("pwd",
+                 help="Print the current working directory",
+                 usage="/pwd",
+                 category="Shell")
+    def cmd_pwd(ctx, *args):
+        ctx.print(ctx.paint.info(f"  {os.getcwd()}"))
+
+    # ── /ls ───────────────────────────────────────────────────────────────────
+
+    @reg.command("ls",
+                 help="List directory contents",
+                 usage="/ls [path]",
+                 category="Shell")
+    def cmd_ls(ctx, *args):
+        p    = ctx.paint
+        path = pathlib.Path(args[0]).expanduser() if args else pathlib.Path(".")
+        try:
+            entries = sorted(path.iterdir(), key=lambda e: (not e.is_dir(), e.name.lower()))
+        except (FileNotFoundError, PermissionError) as e:
+            ctx.print(p.error(str(e)))
+            return
+
+        ctx.print()
+        for entry in entries:
+            if entry.is_dir():
+                ctx.print(p.accent(f"  📁 {entry.name}/"))
+            else:
+                size = entry.stat().st_size
+                size_s = (
+                    f"{size / 1_048_576:.1f} MB" if size > 1_048_576
+                    else f"{size / 1_024:.1f} KB" if size > 1_024
+                    else f"{size} B"
+                )
+                ctx.print(f"  📄 {entry.name:<40} {p.dim(size_s)}")
+        ctx.print()

pykernel/commands/snippets.py

@@ -0,0 +1,257 @@
+"""
+Snippet commands — save and replay named code snippets.
+
+Snippets are stored as .py files in ~/.pykernel/snippets/.
+
+/snip save  <name>   — save the last history entry as a snippet
+/snip write <name>   — open $EDITOR to write a snippet from scratch
+/snip list           — list all saved snippets
+/snip show  <name>   — print a snippet's source
+/snip run   <name>   — execute a snippet in the kernel namespace
+/snip edit  <name>   — open a saved snippet in $EDITOR
+/snip del   <name>   — delete a snippet
+"""
+
+import os, pathlib, subprocess, tempfile, traceback
+from pykernel.core.registry import CommandRegistry
+
+SNIPPETS_DIR = pathlib.Path.home() / ".pykernel" / "snippets"
+
+
+def _ensure_dir():
+    SNIPPETS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _path(name: str) -> pathlib.Path:
+    # sanitise: allow only alphanumerics, dashes, underscores
+    safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in name)
+    return SNIPPETS_DIR / f"{safe}.py"
+
+
+def _editor() -> str:
+    return os.environ.get("VISUAL") or os.environ.get("EDITOR") or "vi"
+
+
+def _open_in_editor(fpath: pathlib.Path, initial: str = "") -> bool:
+    """Write initial content, open editor, return True if saved non-empty."""
+    if not fpath.exists():
+        fpath.write_text(initial)
+    ret = subprocess.call([_editor(), str(fpath)])
+    return ret == 0 and fpath.exists() and fpath.stat().st_size > 0
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+
+def register(reg: CommandRegistry):
+
+    # ── /snip ─────────────────────────────────────────────────────────────────
+
+    @reg.command("snip", aliases=["snippet"],
+                 help="Manage code snippets  (save / list / show / run / edit / del)",
+                 usage="/snip <subcommand> [name]",
+                 category="Snippets")
+    def cmd_snip(ctx, *args):
+        p = ctx.paint
+        if not args:
+            _print_usage(ctx)
+            return
+
+        sub  = args[0].lower()
+        rest = args[1:]
+
+        dispatch = {
+            "save":  _save,
+            "write": _write,
+            "list":  _list,
+            "ls":    _list,
+            "show":  _show,
+            "cat":   _show,
+            "run":   _run,
+            "exec":  _run,
+            "edit":  _edit,
+            "del":   _delete,
+            "rm":    _delete,
+            "delete":_delete,
+        }
+
+        fn = dispatch.get(sub)
+        if fn is None:
+            ctx.print(p.error(f"Unknown subcommand: '{sub}'"))
+            _print_usage(ctx)
+            return
+
+        fn(ctx, *rest)
+
+    # ── subcommand helpers ────────────────────────────────────────────────────
+
+    def _print_usage(ctx):
+        p = ctx.paint
+        rows = [
+            ("save  <name>",  "Save last history entry as a snippet"),
+            ("write <name>",  "Create a new snippet in $EDITOR"),
+            ("list",          "List all saved snippets"),
+            ("show  <name>",  "Print a snippet's source"),
+            ("run   <name>",  "Execute a snippet in the kernel namespace"),
+            ("edit  <name>",  "Open a saved snippet in $EDITOR"),
+            ("del   <name>",  "Delete a snippet"),
+        ]
+        ctx.print()
+        ctx.print(p.header("  Snippet subcommands"))
+        ctx.print(p.table(rows, headers=["Subcommand", "Description"]))
+        ctx.print()
+
+    # ── save ──────────────────────────────────────────────────────────────────
+
+    def _save(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /snip save <name>"))
+            return
+
+        name = args[0]
+        # find last non-/snip history entry
+        source = None
+        for entry in reversed(ctx.history):
+            if not entry.strip().startswith("/snip"):
+                source = entry
+                break
+
+        if not source:
+            ctx.print(p.warning("  ⚠  No suitable history entry found to save."))
+            return
+
+        _ensure_dir()
+        fpath = _path(name)
+        existed = fpath.exists()
+        fpath.write_text(source.rstrip() + "\n")
+        verb = "Updated" if existed else "Saved"
+        ctx.print(p.success(f"  ✓  {verb} snippet '{name}'  →  {fpath}"))
+
+    # ── write ─────────────────────────────────────────────────────────────────
+
+    def _write(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /snip write <name>"))
+            return
+
+        name  = args[0]
+        _ensure_dir()
+        fpath = _path(name)
+
+        if fpath.exists():
+            ctx.print(p.warning(f"  ⚠  '{name}' already exists — use /snip edit to modify it."))
+            return
+
+        ctx.print(p.dim(f"  Opening {_editor()} …"))
+        ok = _open_in_editor(fpath, initial=f"# snippet: {name}\n")
+        if ok:
+            ctx.print(p.success(f"  ✓  Snippet '{name}' saved  →  {fpath}"))
+        else:
+            if fpath.exists() and fpath.stat().st_size == 0:
+                fpath.unlink()
+            ctx.print(p.warning("  ⚠  Snippet discarded (empty or editor error)."))
+
+    # ── list ──────────────────────────────────────────────────────────────────
+
+    def _list(ctx, *args):
+        p = ctx.paint
+        _ensure_dir()
+        files = sorted(SNIPPETS_DIR.glob("*.py"))
+
+        if not files:
+            ctx.print(p.dim("  (no snippets saved yet — try /snip save <name>)"))
+            return
+
+        rows = []
+        for f in files:
+            name  = f.stem
+            lines = f.read_text().splitlines()
+            size  = f.stat().st_size
+            # first non-comment, non-blank line as preview
+            preview = next(
+                (l.strip() for l in lines if l.strip() and not l.strip().startswith("#")),
+                "(empty)"
+            )[:60]
+            rows.append((name, f"{len(lines)} lines", f"{size} B", preview))
+
+        ctx.print()
+        ctx.print(p.table(rows, headers=["Name", "Lines", "Size", "Preview"]))
+        ctx.print()
+
+    # ── show ──────────────────────────────────────────────────────────────────
+
+    def _show(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /snip show <name>"))
+            return
+
+        fpath = _path(args[0])
+        if not fpath.exists():
+            ctx.print(p.error(f"Snippet '{args[0]}' not found."))
+            return
+
+        source = fpath.read_text()
+        ctx.print()
+        ctx.print(p.header(f"  {args[0]}  ({fpath.name})"))
+        ctx.print(p.code(source))
+
+    # ── run ───────────────────────────────────────────────────────────────────
+
+    def _run(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /snip run <name>"))
+            return
+
+        fpath = _path(args[0])
+        if not fpath.exists():
+            ctx.print(p.error(f"Snippet '{args[0]}' not found."))
+            return
+
+        source = fpath.read_text()
+        ctx.print(p.dim(f"  Running snippet '{args[0]}' …"))
+        try:
+            exec(compile(source, str(fpath), "exec"), ctx.env)
+            ctx.print(p.success(f"  ✓  Done."))
+        except SystemExit:
+            raise
+        except Exception:
+            lines   = traceback.format_exc().splitlines()
+            cleaned = [l for l in lines if str(fpath) in l or not l.strip().startswith('File "')]
+            ctx.print(p.error("\n".join(cleaned or lines)))
+
+    # ── edit ──────────────────────────────────────────────────────────────────
+
+    def _edit(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /snip edit <name>"))
+            return
+
+        name  = args[0]
+        fpath = _path(name)
+        if not fpath.exists():
+            ctx.print(p.warning(f"  ⚠  '{name}' doesn't exist — use /snip write to create it."))
+            return
+
+        ctx.print(p.dim(f"  Opening {_editor()} …"))
+        _open_in_editor(fpath)
+        ctx.print(p.success(f"  ✓  Snippet '{name}' updated."))
+
+    # ── delete ────────────────────────────────────────────────────────────────
+
+    def _delete(ctx, *args):
+        p = ctx.paint
+        if not args:
+            ctx.print(p.error("Usage: /snip del <name>"))
+            return
+
+        for name in args:
+            fpath = _path(name)
+            if fpath.exists():
+                fpath.unlink()
+                ctx.print(p.success(f"  ✓  Deleted snippet '{name}'"))
+            else:
+                ctx.print(p.warning(f"  ⚠  Snippet '{name}' not found."))