neorepl 0.1.0__py3-none-any.whl

neorepl/__init__.py

@@ -0,0 +1,5 @@
+"""neorepl: build custom Python shells."""
+from .shell import Shell, Command, embed, start
+
+__all__ = ["Shell", "Command", "embed", "start"]
+__version__ = "0.1.0"

neorepl/builtin_commands.py

@@ -0,0 +1,48 @@
+"""Commands every Shell gets by default."""
+from __future__ import annotations
+
+
+def register(shell) -> None:
+    @shell.command("help", help="List commands (or: help <command>)")
+    def _help(sh, name=None):
+        if name:
+            cmd = sh.commands.get(name)
+            sh.print(f"{sh.command_prefix}{name}: {cmd.help}" if cmd else f"No such command: {name}")
+            return
+        width = max(len(n) for n in sh.commands)
+        for n in sorted(sh.commands):
+            sh.print(f"  {sh.command_prefix}{n:<{width}}  {sh.commands[n].help}")
+
+    @shell.command("exit", help="Leave the shell")
+    def _exit(sh):
+        raise SystemExit
+
+    shell.commands["quit"] = shell.commands["exit"]
+
+    @shell.command("vars", help="Show user-defined variables")
+    def _vars(sh):
+        for k, v in sorted(sh.locals.items()):
+            if not k.startswith("_"):
+                sh.print(f"  {k} = {sh.formatter(v)[:70]}")
+
+    @shell.command("reset", help="Restore the initial namespace")
+    def _reset(sh):
+        sh.reset()
+        sh.print("Namespace reset.")
+
+    @shell.command("run", help="Execute a Python file in the shell namespace")
+    def _run(sh, path=None):
+        if not path:
+            sh.print(f"usage: {sh.command_prefix}run <file.py>")
+            return
+        sh.exec_file(path)
+
+    @shell.command("history", help="Show input history")
+    def _history(sh):
+        try:
+            import readline
+        except ImportError:
+            sh.print("history unavailable (no readline)")
+            return
+        for i in range(1, readline.get_current_history_length() + 1):
+            sh.print(f"  {i:>3}  {readline.get_history_item(i)}")

neorepl/completer.py

@@ -0,0 +1,59 @@
+"""Tab completion for Shell (names, dotted attributes, %commands)."""
+from __future__ import annotations
+
+import builtins
+import keyword
+import re
+
+_DOTTED = re.compile(r"^[A-Za-z_][\w]*(\.[A-Za-z_][\w]*)*\.[\w]*$")
+
+
+class Completer:
+    def __init__(self, shell):
+        self.shell = shell
+        self._matches: list[str] = []
+
+    def complete(self, text: str, state: int):
+        if state == 0:
+            self._matches = self._compute(text)
+        try:
+            return self._matches[state]
+        except IndexError:
+            return None
+
+    def _line_buffer(self) -> str:
+        try:
+            import readline
+            return readline.get_line_buffer()
+        except ImportError:  # pragma: no cover
+            return ""
+
+    def _compute(self, text: str) -> list[str]:
+        buf = self._line_buffer().lstrip()
+        prefix = self.shell.command_prefix
+        if buf.startswith(prefix) and " " not in buf:
+            return sorted(n for n in self.shell.commands if n.startswith(buf[len(prefix):]))
+        if "." in text and _DOTTED.match(text):
+            return self._attr_matches(text)
+        return self._name_matches(text)
+
+    def _name_matches(self, text: str) -> list[str]:
+        names = set(keyword.kwlist) | set(dir(builtins)) | set(self.shell.locals)
+        return sorted(n for n in names if n.startswith(text))
+
+    def _attr_matches(self, text: str) -> list[str]:
+        *chain, partial = text.split(".")
+        obj = self.shell.locals.get(chain[0], getattr(builtins, chain[0], None))
+        if obj is None:
+            return []
+        try:
+            for part in chain[1:]:
+                obj = getattr(obj, part)
+        except Exception:
+            return []
+        base = ".".join(chain)
+        show_private = partial.startswith("_")
+        return sorted(
+            f"{base}.{a}" for a in dir(obj)
+            if a.startswith(partial) and (show_private or not a.startswith("_"))
+        )

neorepl/shell.py

@@ -0,0 +1,292 @@
+"""Core Shell class."""
+from __future__ import annotations
+
+import atexit
+import code
+import inspect
+import os
+import shlex
+import sys
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Union
+
+from .completer import Completer
+
+Prompt = Union[str, Callable[["Shell", bool], str]]
+
+EVENTS = ("start", "exit", "pre_run", "post_run", "error", "command")
+
+
+@dataclass
+class Command:
+    name: str
+    func: Callable[..., Any]
+    help: str = ""
+
+
+class Shell(code.InteractiveConsole):
+    """An extensible interactive Python shell.
+
+    Parameters
+    ----------
+    namespace: initial variables available in the shell.
+    banner: text shown at startup. Pass "" or False to disable.
+    prompt / continuation_prompt: a string, or a callable ``(shell, more) -> str``.
+    history_file: path to persist readline history (optional).
+    command_prefix: lines starting with this run a shell command instead of Python.
+    formatter: ``value -> str`` used to display expression results.
+    """
+
+    def __init__(
+        self,
+        namespace: Optional[dict] = None,
+        *,
+        banner: Union[str, bool, None] = None,
+        prompt: Prompt = ">>> ",
+        continuation_prompt: Prompt = "... ",
+        history_file: Optional[str] = None,
+        history_length: int = 1000,
+        command_prefix: str = "%",
+        exit_message: str = "",
+        formatter: Callable[[Any], str] = repr,
+        builtin_commands: bool = True,
+    ):
+        ns = dict(namespace or {})
+        ns.setdefault("__name__", "__shell__")
+        ns.setdefault("__doc__", None)
+        super().__init__(locals=ns, filename="<shell>")
+        self.banner = banner
+        self.prompt = prompt
+        self.continuation_prompt = continuation_prompt
+        self.history_file = os.path.expanduser(history_file) if history_file else None
+        self.history_length = history_length
+        self.command_prefix = command_prefix
+        self.exit_message = exit_message
+        self.formatter = formatter
+        self.commands: dict[str, Command] = {}
+        self._hooks: dict[str, list[Callable]] = {e: [] for e in EVENTS}
+        self._initial_ns = dict(ns)
+        self._had_error = False
+        self.last_duration = 0.0
+        if builtin_commands:
+            from . import builtin_commands as bc
+            bc.register(self)
+
+    # ------------------------------------------------------------------ output
+    def print(self, *args, **kwargs) -> None:
+        """Print to stdout (use for normal shell output)."""
+        print(*args, **kwargs)
+
+    # ---------------------------------------------------------------- commands
+    def command(self, name: Union[str, Callable, None] = None, *, help: str = ""):
+        """Register a command. Handler signature: ``func(shell, *args: str)``.
+
+            @shell.command("greet", help="Say hi")
+            def greet(shell, who="world"): shell.print(f"hi {who}")
+        """
+        def decorator(func):
+            cmd_name = name if isinstance(name, str) else func.__name__
+            doc = help or (inspect.getdoc(func) or "").split("\n")[0]
+            self.commands[cmd_name] = Command(cmd_name, func, doc)
+            return func
+
+        if callable(name):  # used as bare @shell.command
+            func, name = name, None
+            return decorator(func)
+        return decorator
+
+    def is_command(self, line: str) -> bool:
+        return bool(self.command_prefix) and line.lstrip().startswith(self.command_prefix)
+
+    def run_command(self, line: str) -> None:
+        body = line.strip()[len(self.command_prefix):]
+        try:
+            parts = shlex.split(body)
+        except ValueError as e:
+            self.print(f"error: {e}")
+            return
+        if not parts:
+            return
+        name, *args = parts
+        cmd = self.commands.get(name)
+        if cmd is None:
+            self.print(f"Unknown command {name!r}. Try {self.command_prefix}help")
+            return
+        self.emit("command", name, args)
+        try:
+            cmd.func(self, *args)
+        except SystemExit:
+            raise
+        except Exception:
+            self.showtraceback()
+
+    # ------------------------------------------------------------------- hooks
+    def on(self, event: str, func: Optional[Callable] = None):
+        """Register a hook (decorator or direct call).
+
+        Events and signatures:
+          start(shell) / exit(shell)
+          pre_run(shell, source) -> str | None   (return new source to rewrite input)
+          post_run(shell, source, ok)
+          error(shell, exc_type, exc, tb)
+          command(shell, name, args)
+        """
+        if event not in self._hooks:
+            raise ValueError(f"unknown event {event!r}; choose from {EVENTS}")
+
+        def register(f):
+            self._hooks[event].append(f)
+            return f
+
+        return register(func) if func else register
+
+    def emit(self, event: str, *args) -> None:
+        for hook in self._hooks[event]:
+            hook(self, *args)
+
+    def _transform(self, source: str) -> str:
+        for hook in self._hooks["pre_run"]:
+            result = hook(self, source)
+            if isinstance(result, str):
+                source = result
+        return source
+
+    # --------------------------------------------------------------- execution
+    def runsource(self, source, filename="<shell>", symbol="single"):
+        try:
+            compiled = self.compile(source, filename, symbol)
+        except (OverflowError, SyntaxError, ValueError):
+            self.showsyntaxerror(filename)
+            return False
+        if compiled is None:
+            return True  # incomplete input, ask for more
+
+        # Input is complete: give pre_run hooks a chance to rewrite it.
+        new_source = self._transform(source)
+        if new_source != source:
+            try:
+                compiled = self.compile(new_source, filename, symbol)
+            except (OverflowError, SyntaxError, ValueError):
+                self.showsyntaxerror(filename)
+                return False
+            if compiled is None:
+                return False
+
+        self._had_error = False
+        start = time.perf_counter()
+        self.runcode(compiled)
+        self.last_duration = time.perf_counter() - start
+        self.emit("post_run", new_source, not self._had_error)
+        return False
+
+    def runcode(self, code_obj):
+        old = sys.displayhook
+        sys.displayhook = self._display
+        try:
+            super().runcode(code_obj)
+        finally:
+            sys.displayhook = old
+
+    def _display(self, value) -> None:
+        if value is None:
+            return
+        self.locals["_"] = value
+        self.print(self.formatter(value))
+
+    def showtraceback(self):
+        self._had_error = True
+        exc_info = sys.exc_info()
+        super().showtraceback()
+        if exc_info[0] is not None:
+            self.emit("error", *exc_info)
+
+    def exec_file(self, path: str) -> None:
+        with open(path, encoding="utf-8") as f:
+            self.runsource(f.read(), path, "exec")
+
+    def reset(self) -> None:
+        self.locals.clear()
+        self.locals.update(self._initial_ns)
+
+    # ---------------------------------------------------------------- REPL loop
+    def render_prompt(self, more: bool) -> str:
+        p = self.continuation_prompt if more else self.prompt
+        return p(self, more) if callable(p) else p
+
+    def _default_banner(self) -> str:
+        return (f"Python {sys.version.split()[0]} custom shell. "
+                f"Type {self.command_prefix}help for commands.")
+
+    def _setup_readline(self) -> None:
+        try:
+            import readline
+        except ImportError:  # e.g. Windows without pyreadline
+            return
+        readline.set_completer(Completer(self).complete)
+        readline.parse_and_bind("tab: complete")
+        if self.history_file:
+            try:
+                readline.read_history_file(self.history_file)
+            except (FileNotFoundError, OSError):
+                pass
+            readline.set_history_length(self.history_length)
+            atexit.register(self._save_history)
+
+    def _save_history(self) -> None:
+        if not self.history_file:
+            return
+        try:
+            import readline
+            readline.write_history_file(self.history_file)
+        except (ImportError, OSError):
+            pass
+
+    def run(self, input_fn: Optional[Callable[[str], str]] = None) -> None:
+        """Start the shell loop. ``input_fn`` can be swapped out for testing."""
+        input_fn = input_fn or input
+        if input_fn is input:
+            self._setup_readline()
+        banner = self._default_banner() if self.banner is None else self.banner
+        if banner:
+            self.print(banner)
+        self.emit("start")
+        more = False
+        try:
+            while True:
+                try:
+                    line = input_fn(self.render_prompt(more))
+                except EOFError:
+                    self.print()
+                    break
+                except KeyboardInterrupt:
+                    self.print("\nKeyboardInterrupt")
+                    self.resetbuffer()
+                    more = False
+                    continue
+                try:
+                    if not more and self.is_command(line):
+                        self.run_command(line)
+                    else:
+                        more = self.push(line)
+                except SystemExit:
+                    break
+        finally:
+            self.emit("exit")
+            self._save_history()
+            if self.exit_message:
+                self.print(self.exit_message)
+
+
+def start(namespace: Optional[dict] = None, **kwargs) -> Shell:
+    """Create a Shell and run it immediately."""
+    shell = Shell(namespace, **kwargs)
+    shell.run()
+    return shell
+
+
+def embed(**kwargs) -> Shell:
+    """Drop into a shell with the caller's globals and locals (like IPython.embed)."""
+    frame = inspect.currentframe().f_back
+    ns = {**frame.f_globals, **frame.f_locals}
+    return start(ns, **kwargs)

neorepl-0.1.0.dist-info/METADATA

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: neorepl
+Version: 0.1.0
+Summary: A small toolkit for building custom Python shells
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# neorepl
+
+A small toolkit for building custom Python shells. Zero dependencies, Python 3.9+.
+
+```python
+from neorepl import Shell
+
+shell = Shell({"answer": 42}, prompt="my> ", history_file="~/.my_history")
+
+@shell.command("greet", help="Say hello")
+def greet(sh, name="world"):
+    sh.print(f"Hello, {name}!")
+
+@shell.on("pre_run")                 # rewrite input before it executes
+def rewrite(sh, source):
+    if source.strip() == "ll":
+        return "print(sorted(globals()))"
+
+shell.run()
+```
+
+## Features
+- **Commands**: `%name args` lines handled by `@shell.command` (prefix configurable). Built-ins: `%help %exit %vars %reset %run %history`.
+- **Hooks**: `start`, `exit`, `pre_run` (can rewrite input), `post_run`, `error`, `command`.
+- **Prompts**: static strings or `callable(shell, more) -> str`.
+- **Display**: swap `formatter=` to pretty-print results (e.g. `pprint.pformat`, rich).
+- **Tab completion** for names, dotted attributes, and commands (via readline).
+- **Persistent history** with `history_file=`.
+- **Embedding**: `neorepl.embed()` opens a shell with the caller's variables.
+
+## Develop
+```
+pip install -e ".[dev]"
+pytest
+python examples/demo.py
+```

neorepl-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+neorepl/__init__.py,sha256=Y-GFJW6kPeXH7yqiklkknV2xWTHHZa84xK7JHgtJgrY,163
+neorepl/builtin_commands.py,sha256=kRNdGubCx3khpQHcZsEHDjbRSjqiFzTij5mAZi-7dmw,1680
+neorepl/completer.py,sha256=Dnf_Qcn36fW2Et0M06c8uaITCw2vaE5dLhcPozP2XEU,1955
+neorepl/shell.py,sha256=WrFjrRsHXBAb1ekP0ringyax3fHNQUCED4OCKvz6m7o,10093
+neorepl-0.1.0.dist-info/METADATA,sha256=0RR2EoAF0yP0XUziWnitLOvbDhHPUgrLg0MCZCYJBR4,1454
+neorepl-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+neorepl-0.1.0.dist-info/top_level.txt,sha256=ls2BQgRzWmXGJDJx1lt726PmmGylIN50jzzRLsH3SBY,8
+neorepl-0.1.0.dist-info/RECORD,,

neorepl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

neorepl-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+neorepl