pykernel-cli 1.0.0__py3-none-any.whl

pykernel/core/config.py

@@ -0,0 +1,118 @@
+"""
+Config — loads ~/.pykernel/config.toml (or defaults).
+
+Supported keys
+--------------
+[kernel]
+prompt        = ">>> "
+prompt2       = "... "
+history_file  = "~/.pykernel/history"
+history_size  = 2000
+banner        = true
+theme         = "dark"          # dark | light | none
+
+[kernel.colors]
+prompt   = "cyan"
+error    = "red"
+info     = "green"
+warning  = "yellow"
+result   = "white"
+"""
+
+import os, pathlib
+
+try:
+    import tomllib                          # Python 3.11+
+except ImportError:
+    try:
+        import tomli as tomllib            # pip install tomli
+    except ImportError:
+        tomllib = None                      # fall back to defaults
+
+
+DEFAULTS: dict = {
+    "kernel": {
+        "prompt":       ">>> ",
+        "prompt2":      "... ",
+        "history_file": "~/.pykernel/history",
+        "history_size": 2000,
+        "banner":       True,
+        "theme":        "dark",
+        "colors": {
+            "prompt":  "cyan",
+            "error":   "red",
+            "info":    "green",
+            "warning": "yellow",
+            "result":  "white",
+        },
+    }
+}
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    out = dict(base)
+    for k, v in override.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+class Config:
+    """Thin wrapper around the merged config dict."""
+
+    CONFIG_DIR  = pathlib.Path.home() / ".pykernel"
+    CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+    def __init__(self):
+        raw = {}
+        if tomllib and self.CONFIG_FILE.exists():
+            with open(self.CONFIG_FILE, "rb") as f:
+                raw = tomllib.load(f)
+        self._data = _deep_merge(DEFAULTS, raw)
+        self._ensure_dirs()
+
+    # ── helpers ─────────────────────────────────────────────────────────────
+
+    def _ensure_dirs(self):
+        self.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        self.plugin_dir.mkdir(parents=True, exist_ok=True)
+
+    def _k(self, *keys):
+        node = self._data
+        for k in keys:
+            node = node.get(k, {})
+        return node
+
+    # ── public properties ────────────────────────────────────────────────────
+
+    @property
+    def prompt(self)        -> str:  return self._k("kernel", "prompt")
+    @property
+    def prompt2(self)       -> str:  return self._k("kernel", "prompt2")
+    @property
+    def history_file(self)  -> pathlib.Path:
+        return pathlib.Path(os.path.expanduser(self._k("kernel", "history_file")))
+    @property
+    def history_size(self)  -> int:  return self._k("kernel", "history_size")
+    @property
+    def banner(self)        -> bool: return bool(self._k("kernel", "banner"))
+    @property
+    def theme(self)         -> str:  return self._k("kernel", "theme")
+    @property
+    def colors(self)        -> dict: return self._k("kernel", "colors")
+    @property
+    def plugin_dir(self)    -> pathlib.Path:
+        return self.CONFIG_DIR / "plugins"
+
+    def color(self, name: str) -> str:
+        return self.colors.get(name, "white")
+
+    def get(self, *keys, default=None):
+        node = self._data
+        for k in keys:
+            if not isinstance(node, dict):
+                return default
+            node = node.get(k, {})
+        return node if node != {} else default

pykernel/core/context.py

@@ -0,0 +1,64 @@
+"""
+Context — the object every command receives as its first argument.
+
+It provides:
+  ctx.env        — the shared Python namespace (locals/globals for exec)
+  ctx.print()    — themed print
+  ctx.paint      — Painter instance
+  ctx.registry   — CommandRegistry
+  ctx.cfg        — Config
+  ctx.history    — list of past inputs (most recent last)
+  ctx.set_var()  — inject a name into the exec namespace
+  ctx.get_var()  — retrieve from the exec namespace
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pykernel.core.config   import Config
+    from pykernel.core.painter  import Painter
+    from pykernel.core.registry import CommandRegistry
+
+
+class Context:
+    def __init__(
+        self,
+        env:      dict,
+        paint:    "Painter",
+        registry: "CommandRegistry",
+        cfg:      "Config",
+        history:  list[str],
+    ):
+        self.env      = env
+        self.paint    = paint
+        self.registry = registry
+        self.cfg      = cfg
+        self.history  = history
+
+    # ── convenience ──────────────────────────────────────────────────────────
+
+    def print(self, *args, **kwargs):
+        """Print to stdout (wrapper so commands don't need to import print)."""
+        print(*args, **kwargs)
+
+    def set_var(self, name: str, value: Any):
+        """Inject a variable into the kernel's exec namespace."""
+        self.env[name] = value
+
+    def get_var(self, name: str, default: Any = None) -> Any:
+        """Retrieve a variable from the kernel's exec namespace."""
+        return self.env.get(name, default)
+
+    def has_var(self, name: str) -> bool:
+        return name in self.env
+
+    def delete_var(self, name: str) -> bool:
+        if name in self.env:
+            del self.env[name]
+            return True
+        return False
+
+    def namespace_vars(self) -> dict:
+        """Return user-visible variables (excludes dunders)."""
+        return {k: v for k, v in self.env.items() if not k.startswith("__")}

pykernel/core/painter.py

@@ -0,0 +1,119 @@
+"""
+Painter — ANSI colour helpers, theme-aware.
+
+Usage:
+    from pykernel.core.painter import Painter
+    p = Painter(theme="dark")
+    print(p.info("hello"))
+    print(p.error("oops"))
+"""
+
+import sys
+from typing import Optional
+
+ANSI = {
+    "reset":   "\033[0m",
+    "bold":    "\033[1m",
+    "dim":     "\033[2m",
+    "italic":  "\033[3m",
+    "under":   "\033[4m",
+
+    "black":   "\033[30m",
+    "red":     "\033[91m",
+    "green":   "\033[92m",
+    "yellow":  "\033[93m",
+    "blue":    "\033[94m",
+    "magenta": "\033[95m",
+    "cyan":    "\033[96m",
+    "white":   "\033[97m",
+    "gray":    "\033[90m",
+
+    "bg_black":   "\033[40m",
+    "bg_red":     "\033[41m",
+    "bg_green":   "\033[42m",
+    "bg_blue":    "\033[44m",
+    "bg_cyan":    "\033[46m",
+    "bg_magenta": "\033[45m",
+}
+
+_SUPPORTS_COLOR = sys.stdout.isatty()
+
+
+def _c(*codes) -> str:
+    if not _SUPPORTS_COLOR:
+        return ""
+    return "".join(ANSI.get(c, "") for c in codes)
+
+
+def colorize(text: str, *codes) -> str:
+    if not _SUPPORTS_COLOR:
+        return text
+    return f"{_c(*codes)}{text}{ANSI['reset']}"
+
+
+class Painter:
+    """Theme-aware text painter."""
+
+    def __init__(self, theme: str = "dark", color_map: Optional[dict] = None):
+        self.theme = theme
+        self._map  = color_map or {}
+        self.enabled = _SUPPORTS_COLOR and theme != "none"
+
+    def _paint(self, text: str, *codes) -> str:
+        if not self.enabled:
+            return text
+        return colorize(text, *codes)
+
+    # ── semantic helpers ─────────────────────────────────────────────────────
+
+    def prompt(self, text: str)   -> str: return self._paint(text, "cyan",    "bold")
+    def error(self, text: str)    -> str: return self._paint(text, "red",     "bold")
+    def info(self, text: str)     -> str: return self._paint(text, "green")
+    def warning(self, text: str)  -> str: return self._paint(text, "yellow")
+    def result(self, text: str)   -> str: return self._paint(text, "white")
+    def dim(self, text: str)      -> str: return self._paint(text, "dim")
+    def bold(self, text: str)     -> str: return self._paint(text, "bold")
+    def code(self, text: str)     -> str: return self._paint(text, "magenta")
+    def header(self, text: str)   -> str: return self._paint(text, "cyan",    "bold", "under")
+    def success(self, text: str)  -> str: return self._paint(text, "green",   "bold")
+    def accent(self, text: str)   -> str: return self._paint(text, "blue",    "bold")
+
+    # ── table helper ─────────────────────────────────────────────────────────
+
+    def table(self, rows: list[tuple], headers: Optional[list[str]] = None) -> str:
+        if not rows:
+            return self.dim("(empty)")
+
+        all_rows = [tuple(str(c) for c in r) for r in rows]
+        if headers:
+            all_rows = [tuple(headers)] + all_rows
+
+        col_w = [max(len(r[i]) for r in all_rows) for i in range(len(all_rows[0]))]
+        sep   = "  ".join("─" * w for w in col_w)
+
+        lines: list[str] = []
+        for i, row in enumerate(all_rows):
+            cells = "  ".join(cell.ljust(col_w[j]) for j, cell in enumerate(row))
+            if headers and i == 0:
+                lines.append(self.header(cells))
+                lines.append(self.dim(sep))
+            else:
+                lines.append(cells)
+        return "\n".join(lines)
+
+    # ── banner ───────────────────────────────────────────────────────────────
+
+    def banner(self, version: str = "1.0.0") -> str:
+        logo = r"""
+  ____        _  __                    _ 
+ |  _ \ _   _| |/ /___ _ __ _ __   ___| |
+ | |_) | | | | ' // _ \ '__| '_ \ / _ \ |
+ |  __/| |_| | . \  __/ |  | | | |  __/ |
+ |_|    \__, |_|\_\___|_|  |_| |_|\___|_|
+         |___/                            """
+        lines = [
+            self._paint(logo, "cyan"),
+            self.dim(f"  v{version}  ·  type /help to explore commands"),
+            "",
+        ]
+        return "\n".join(lines)

pykernel/core/registry.py

@@ -0,0 +1,159 @@
+"""
+CommandRegistry — the heart of PyKernel's customisation system.
+
+Commands are callables registered with a name, aliases, help text, and
+optional argument spec. The registry also loads user plugins from a directory.
+
+Quick API
+---------
+    from pykernel.core.registry import CommandRegistry
+
+    reg = CommandRegistry()
+
+    @reg.command("greet", aliases=["hi"], help="Say hello", usage="/greet [name]")
+    def cmd_greet(ctx, *args):
+        name = args[0] if args else "world"
+        ctx.print(ctx.paint.success(f"Hello, {name}!"))
+
+    # or imperatively:
+    reg.register("greet", cmd_greet, aliases=["hi"], help="Say hello")
+"""
+
+import importlib.util, pathlib, sys, traceback
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+
+# ── data model ───────────────────────────────────────────────────────────────
+
+@dataclass
+class Command:
+    name:     str
+    func:     Callable
+    aliases:  list[str]         = field(default_factory=list)
+    help:     str               = "(no description)"
+    usage:    str               = ""
+    category: str               = "General"
+    hidden:   bool              = False
+
+    def __post_init__(self):
+        if not self.usage:
+            self.usage = f"/{self.name}"
+
+    def invoke(self, ctx, *args):
+        return self.func(ctx, *args)
+
+
+# ── registry ─────────────────────────────────────────────────────────────────
+
+class CommandRegistry:
+    """Holds all commands and resolves them by name or alias."""
+
+    def __init__(self):
+        self._commands: dict[str, Command] = {}   # canonical name → Command
+        self._alias:    dict[str, str]     = {}   # alias → canonical name
+
+    # ── registration ─────────────────────────────────────────────────────────
+
+    def register(
+        self,
+        name:     str,
+        func:     Callable,
+        *,
+        aliases:  list[str] = (),
+        help:     str = "(no description)",
+        usage:    str = "",
+        category: str = "General",
+        hidden:   bool = False,
+    ) -> "Command":
+        cmd = Command(
+            name=name, func=func, aliases=list(aliases),
+            help=help, usage=usage, category=category, hidden=hidden,
+        )
+        self._commands[name] = cmd
+        for alias in aliases:
+            self._alias[alias] = name
+        return cmd
+
+    def command(
+        self,
+        name: str,
+        *,
+        aliases:  list[str] = (),
+        help:     str = "(no description)",
+        usage:    str = "",
+        category: str = "General",
+        hidden:   bool = False,
+    ):
+        """Decorator factory — use on any function to register it as a command."""
+        def decorator(func: Callable) -> Callable:
+            self.register(
+                name, func,
+                aliases=aliases, help=help,
+                usage=usage, category=category, hidden=hidden,
+            )
+            return func
+        return decorator
+
+    # ── lookup ───────────────────────────────────────────────────────────────
+
+    def resolve(self, name: str) -> Optional[Command]:
+        """Return Command for canonical name or alias, or None."""
+        if name in self._commands:
+            return self._commands[name]
+        canonical = self._alias.get(name)
+        if canonical:
+            return self._commands.get(canonical)
+        return None
+
+    def all_commands(self, include_hidden: bool = False) -> list[Command]:
+        cmds = list(self._commands.values())
+        if not include_hidden:
+            cmds = [c for c in cmds if not c.hidden]
+        return sorted(cmds, key=lambda c: (c.category, c.name))
+
+    def by_category(self, include_hidden: bool = False) -> dict[str, list[Command]]:
+        out: dict[str, list[Command]] = {}
+        for cmd in self.all_commands(include_hidden):
+            out.setdefault(cmd.category, []).append(cmd)
+        return out
+
+    def names(self) -> list[str]:
+        names = list(self._commands.keys()) + list(self._alias.keys())
+        return sorted(names)
+
+    # ── plugin loader ─────────────────────────────────────────────────────────
+
+    def load_plugins(self, plugin_dir: pathlib.Path) -> list[str]:
+        """
+        Import every *.py file in plugin_dir.
+        Each plugin must expose a top-level  register(registry)  function.
+        Returns list of loaded plugin names.
+        """
+        loaded: list[str] = []
+        if not plugin_dir.exists():
+            return loaded
+
+        for path in sorted(plugin_dir.glob("*.py")):
+            mod_name = f"_pykernel_plugin_{path.stem}"
+            try:
+                spec   = importlib.util.spec_from_file_location(mod_name, path)
+                module = importlib.util.module_from_spec(spec)          # type: ignore
+                sys.modules[mod_name] = module
+                spec.loader.exec_module(module)                          # type: ignore
+                if hasattr(module, "register") and callable(module.register):
+                    module.register(self)
+                    loaded.append(path.stem)
+                else:
+                    print(
+                        f"[plugin] {path.name} has no register(registry) — skipped",
+                        file=sys.stderr,
+                    )
+            except Exception:
+                print(f"[plugin] Failed to load {path.name}:", file=sys.stderr)
+                traceback.print_exc(file=sys.stderr)
+
+        return loaded
+
+    def __len__(self):  return len(self._commands)
+    def __contains__(self, name): return name in self._commands or name in self._alias

pykernel/core/repl.py

@@ -0,0 +1,215 @@
+"""
+REPL — the read-eval-print loop engine.
+
+Input lines that start with '/' are dispatched to the command registry.
+Everything else is compiled and exec'd in the shared namespace.
+
+Multi-line input is accumulated until the block is syntactically complete
+(same heuristic as CPython's interactive shell).
+"""
+
+from __future__ import annotations
+
+import ast, code, sys, traceback, atexit, pathlib
+try:
+    import readline
+except ImportError:
+    try:
+        import pyreadline3 as readline
+    except ImportError:
+        readline = None
+from typing import Optional
+
+from pykernel.core.config   import Config
+from pykernel.core.context  import Context
+from pykernel.core.painter  import Painter
+from pykernel.core.registry import CommandRegistry
+
+VERSION = "1.0.0"
+
+# ── readline completion ───────────────────────────────────────────────────────
+
+class _Completer:
+    def __init__(self, env: dict, registry: CommandRegistry):
+        self._env      = env
+        self._registry = registry
+        self._matches: list[str] = []
+
+    def complete(self, text: str, state: int) -> Optional[str]:
+        if state == 0:
+            if text.startswith("/"):
+                prefix = text[1:]
+                self._matches = [
+                    f"/{n}" for n in self._registry.names()
+                    if n.startswith(prefix)
+                ]
+            else:
+                import rlcompleter
+                self._matches = [
+                    m for m in rlcompleter.Completer(self._env).global_matches(text) or []
+                ]
+        return self._matches[state] if state < len(self._matches) else None
+
+
+# ── REPL ─────────────────────────────────────────────────────────────────────
+
+class REPL:
+    COMMAND_PREFIX = "/"
+
+    def __init__(self, registry: CommandRegistry, cfg: Config):
+        self.registry = registry
+        self.cfg      = cfg
+        self.paint    = Painter(theme=cfg.theme, color_map=cfg.colors)
+
+        # shared execution namespace
+        self.env: dict = {
+            "__name__":    "__kernel__",
+            "__builtins__": __builtins__,
+        }
+
+        self.history: list[str] = []
+        self._buffer: list[str] = []          # multi-line accumulator
+
+        self._setup_readline()
+
+    # ── readline / history ────────────────────────────────────────────────────
+
+    def _setup_readline(self):
+        if readline is None:
+            return
+        hfile = self.cfg.history_file
+        hfile.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            readline.read_history_file(str(hfile))
+        except FileNotFoundError:
+            pass
+
+        readline.set_history_length(self.cfg.history_size)
+        atexit.register(readline.write_history_file, str(hfile))
+
+        completer = _Completer(self.env, self.registry)
+        readline.set_completer(completer.complete)
+        readline.set_completer_delims(" \t\n`!@#$%^&*()-=+[{]}\\|;:'\",<>?")
+        readline.parse_and_bind("tab: complete")
+
+    # ── prompt display ────────────────────────────────────────────────────────
+
+    def _prompt(self) -> str:
+        p = self.cfg.prompt2 if self._buffer else self.cfg.prompt
+        return self.paint.prompt(p)
+
+    # ── command dispatch ──────────────────────────────────────────────────────
+
+    def _dispatch_command(self, line: str):
+        parts   = line[len(self.COMMAND_PREFIX):].split()
+        if not parts:
+            return
+        name, args = parts[0], parts[1:]
+
+        cmd = self.registry.resolve(name)
+        if cmd is None:
+            self.paint_error(f"Unknown command: /{name}  (try /help)")
+            return
+
+        ctx = Context(
+            env=self.env,
+            paint=self.paint,
+            registry=self.registry,
+            cfg=self.cfg,
+            history=self.history,
+        )
+        try:
+            cmd.invoke(ctx, *args)
+        except SystemExit:
+            raise
+        except Exception:
+            self.paint_error(f"Error in /{name}:\n" + traceback.format_exc())
+
+    # ── code execution ────────────────────────────────────────────────────────
+
+    def _is_complete(self, source: str) -> tuple[bool, bool]:
+        """
+        Returns (complete, invalid).
+        Mirrors CPython codeop behaviour.
+        """
+        try:
+            tree = compile(source, "<input>", "exec", ast.PyCF_ONLY_AST)
+            return True, False
+        except SyntaxError as e:
+            if e.msg in ("unexpected EOF while parsing",
+                         "EOF while scanning triple-quoted string literal",
+                         "expected an indented block"):
+                return False, False         # incomplete — keep reading
+            return True, True               # real error
+
+    def _exec(self, source: str):
+        try:
+            # try eval first (so expressions print their value)
+            try:
+                code_obj = compile(source, "<input>", "eval")
+                result   = eval(code_obj, self.env)
+                if result is not None:
+                    print(self.paint.result(repr(result)))
+                return
+            except SyntaxError:
+                pass
+
+            # fall back to exec
+            code_obj = compile(source, "<input>", "exec")
+            exec(code_obj, self.env)
+
+        except SystemExit:
+            raise
+        except Exception:
+            lines = traceback.format_exc().splitlines()
+            # trim noisy internal frames
+            cleaned = [l for l in lines if "<string>" in l or not l.strip().startswith('File "')]
+            print(self.paint.error("\n".join(cleaned or lines)))
+
+    # ── helpers ───────────────────────────────────────────────────────────────
+
+    def paint_error(self, msg: str):
+        print(self.paint.error(f"✗  {msg}"))
+
+    def paint_info(self, msg: str):
+        print(self.paint.info(f"   {msg}"))
+
+    # ── main loop ─────────────────────────────────────────────────────────────
+
+    def run(self):
+        if self.cfg.banner:
+            print(self.paint.banner(VERSION))
+
+        while True:
+            try:
+                line = input(self._prompt())
+            except EOFError:
+                print()
+                break
+            except KeyboardInterrupt:
+                print()
+                self._buffer.clear()
+                continue
+
+            # ── command? ──────────────────────────────────────────────────────
+            stripped = line.strip()
+            if stripped.startswith(self.COMMAND_PREFIX) and not self._buffer:
+                self.history.append(stripped)
+                self._dispatch_command(stripped)
+                continue
+
+            # ── accumulate multi-line ─────────────────────────────────────────
+            self._buffer.append(line)
+            source = "\n".join(self._buffer)
+
+            complete, invalid = self._is_complete(source)
+
+            if not complete:
+                continue   # keep reading
+
+            # ── flush & execute ───────────────────────────────────────────────
+            self.history.append(source)
+            self._buffer.clear()
+            if stripped:
+                self._exec(source)