pykernel-cli 1.0.0__tar.gz

pykernel_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pykernel_cli-1.0.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: pykernel-cli
+Version: 1.0.0
+Summary: A hackable Python REPL with first-class command support
+Author-email: zKaiden <odrekzinho@gmail.com>
+License: MIT
+Keywords: repl,shell,interactive,python
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Interpreters
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# PyKernel
+
+A hackable Python REPL with first-class command support.
+
+## Install
+
+```bash
+pip install pykernel
+```
+
+## Usage
+
+```bash
+pykernel
+# or
+python -m pykernel
+```
+
+Type `/help` to see all commands.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/help` | List all commands |
+| `/vars` | List variables in the namespace |
+| `/run <file>` | Execute a Python file |
+| `/sh <cmd>` | Run a shell command |
+| `/snip` | Manage code snippets |
+| `/timeit <expr>` | Time an expression |
+
+## Plugins
+
+Drop a `.py` file with a `register(registry)` function into `~/.pykernel/plugins/`:
+
+```python
+def register(reg):
+    @reg.command("hello", help="Say hello")
+    def cmd_hello(ctx, *args):
+        ctx.print("Hello!")
+```
+
+## Config
+
+Edit `~/.pykernel/config.toml`:
+
+```toml
+[kernel]
+prompt = ">>> "
+theme  = "dark"   # dark | light | none
+```

pykernel_cli-1.0.0/README.md

@@ -0,0 +1,51 @@
+# PyKernel
+
+A hackable Python REPL with first-class command support.
+
+## Install
+
+```bash
+pip install pykernel
+```
+
+## Usage
+
+```bash
+pykernel
+# or
+python -m pykernel
+```
+
+Type `/help` to see all commands.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/help` | List all commands |
+| `/vars` | List variables in the namespace |
+| `/run <file>` | Execute a Python file |
+| `/sh <cmd>` | Run a shell command |
+| `/snip` | Manage code snippets |
+| `/timeit <expr>` | Time an expression |
+
+## Plugins
+
+Drop a `.py` file with a `register(registry)` function into `~/.pykernel/plugins/`:
+
+```python
+def register(reg):
+    @reg.command("hello", help="Say hello")
+    def cmd_hello(ctx, *args):
+        ctx.print("Hello!")
+```
+
+## Config
+
+Edit `~/.pykernel/config.toml`:
+
+```toml
+[kernel]
+prompt = ">>> "
+theme  = "dark"   # dark | light | none
+```

pykernel_cli-1.0.0/pykernel/__main__.py

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

pykernel_cli-1.0.0/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_cli-1.0.0/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_cli-1.0.0/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()