pynteract 0.1.0__py3-none-any.whl

pynteract/__init__.py

@@ -0,0 +1,6 @@
+from .shell import Shell, ShellResponse
+
+__all__ = [
+    "Shell",
+    "ShellResponse",
+]

pynteract/builtin_magics.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import ast
+import os
+import shlex
+import subprocess
+import sys
+import time
+import timeit
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .utils import Thread
+from . import namespace_utils
+
+
+if TYPE_CHECKING:
+    from .shell import Shell
+
+
+def register_builtin_magics(shell: "Shell") -> None:
+    """Register a small set of commonly-used IPython-like magics on `shell`."""
+
+    @shell.register_magic(name="pwd", mode="line")
+    def _pwd(_: str) -> str:
+        return os.getcwd()
+
+    prev_cwd: dict[str, str] = {"value": os.getcwd()}
+
+    @shell.register_magic(name="cd", mode="line")
+    def _cd(arg: str) -> str:
+        target = (arg or "").strip()
+        if not target:
+            target = os.path.expanduser("~")
+        elif target == "-":
+            target = prev_cwd["value"]
+        target = os.path.expanduser(os.path.expandvars(target))
+        prev_cwd["value"] = os.getcwd()
+        os.chdir(target)
+        return os.getcwd()
+
+    @shell.register_magic(name="ls", mode="line")
+    def _ls(arg: str) -> str:
+        parts = shlex.split(arg) if arg.strip() else []
+        path = Path(parts[0]) if parts else Path(".")
+        entries = sorted(path.iterdir(), key=lambda p: p.name)
+        return "\n".join(p.name + ("/" if p.is_dir() else "") for p in entries)
+
+    @shell.register_magic(name="env", mode="line")
+    def _env(arg: str) -> Any:
+        text = (arg or "").strip()
+        if not text:
+            return dict(os.environ)
+        if text.startswith("-u "):
+            key = text[3:].strip()
+            os.environ.pop(key, None)
+            return ""
+        if "=" in text:
+            key, value = text.split("=", 1)
+            os.environ[key] = value
+            return value
+        return os.environ.get(text, "")
+
+    def _user_symbols() -> dict[str, Any]:
+        ns = shell.namespace
+        hidden_prefixes = ("__",)
+        hidden_names = {"_", "__", "___", "__builtins__", "__magics__", "__shell__", "display", "magic"}
+        return {
+            k: v
+            for k, v in ns.items()
+            if k not in hidden_names and not any(k.startswith(p) for p in hidden_prefixes)
+        }
+
+    @shell.register_magic(name="who", mode="line")
+    def _who(_: str) -> str:
+        names = sorted(_user_symbols().keys())
+        return " ".join(names)
+
+    @shell.register_magic(name="whos", mode="line")
+    def _whos(_: str) -> str:
+        rows = [("Name", "Type", "Repr")]
+        for name, value in sorted(_user_symbols().items(), key=lambda kv: kv[0]):
+            rep = repr(value)
+            if len(rep) > 60:
+                rep = rep[:57] + "..."
+            rows.append((name, type(value).__name__, rep))
+        widths = [max(len(r[i]) for r in rows) for i in range(3)]
+        return "\n".join(
+            f"{r[0]:<{widths[0]}}  {r[1]:<{widths[1]}}  {r[2]}" for r in rows
+        )
+
+    def _compile_for_exec(code: str, filename: str) -> tuple[object, bool]:
+        tree = ast.parse(code, filename=filename, mode="exec")
+        is_expr = len(tree.body) == 1 and isinstance(tree.body[0], ast.Expr)
+        flags = getattr(shell, "_futures").flags
+        if is_expr:
+            compiled = compile(
+                ast.Expression(tree.body[0].value),
+                filename=filename,
+                mode="eval",
+                flags=flags,
+                dont_inherit=True,
+            )
+        else:
+            compiled = compile(tree, filename=filename, mode="exec", flags=flags, dont_inherit=True)
+        return compiled, is_expr
+
+    @shell.register_magic(name="time", mode="line")
+    def _time(arg: str) -> str:
+        code = (arg or "").strip()
+        if not code:
+            return "Usage: %time <code>"
+        filename = "<pynteract-%time>"
+        compiled, is_expr = _compile_for_exec(code, filename)
+        start = time.perf_counter()
+        if is_expr:
+            eval(compiled, shell.namespace, shell.namespace)
+        else:
+            exec(compiled, shell.namespace, shell.namespace)
+        elapsed = time.perf_counter() - start
+        return f"Wall time: {elapsed:.6f}s"
+
+    @shell.register_magic(name="timeit", mode="line")
+    def _timeit(arg: str) -> str:
+        parts = shlex.split(arg) if arg.strip() else []
+        n = 1000
+        r = 3
+        code_parts: list[str] = []
+        i = 0
+        while i < len(parts):
+            if parts[i] == "-n" and i + 1 < len(parts):
+                n = int(parts[i + 1])
+                i += 2
+                continue
+            if parts[i] == "-r" and i + 1 < len(parts):
+                r = int(parts[i + 1])
+                i += 2
+                continue
+            code_parts.append(parts[i])
+            i += 1
+        code = " ".join(code_parts).strip()
+        if not code:
+            return "Usage: %timeit [-n N] [-r R] <code>"
+
+        filename = "<pynteract-%timeit>"
+        compiled, is_expr = _compile_for_exec(code, filename)
+
+        def run_once() -> None:
+            if is_expr:
+                eval(compiled, shell.namespace, shell.namespace)
+            else:
+                exec(compiled, shell.namespace, shell.namespace)
+
+        timer = timeit.Timer(run_once)
+        runs = timer.repeat(repeat=r, number=n)
+        best = min(runs) / n
+        return f"Best of {r}: {best:.6g}s per loop"
+
+    @shell.register_magic(name="bash", mode="cell")
+    def _bash_cell(script: str) -> int:
+        process = subprocess.Popen(
+            ["bash", "-lc", script],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+
+        def _stream_output(stream, out_stream):
+            for line in iter(stream.readline, ""):
+                out_stream.write(line)
+                out_stream.flush()
+            stream.close()
+
+        t_out = Thread(target=_stream_output, args=(process.stdout, sys.stdout))
+        t_err = Thread(target=_stream_output, args=(process.stderr, sys.stderr))
+        t_out.start()
+        t_err.start()
+        t_out.join()
+        t_err.join()
+        return process.wait()
+
+    @shell.register_magic(name="run", mode="line")
+    def _run(arg: str) -> str:
+        """Execute a Python script, IPython-style.
+
+        - `%run script.py [args...]` runs in a fresh `__main__` namespace, then merges symbols into the current shell.
+        - `%run -i script.py [args...]` runs in the current shell namespace.
+        """
+        parts = shlex.split(arg) if arg.strip() else []
+        if not parts:
+            return "Usage: %run [-i] script.py [args...]"
+
+        interactive = False
+        if parts and parts[0] == "-i":
+            interactive = True
+            parts = parts[1:]
+
+        if not parts:
+            return "Usage: %run [-i] script.py [args...]"
+
+        script_path = Path(os.path.expandvars(os.path.expanduser(parts[0]))).resolve()
+        argv = [str(script_path), *parts[1:]]
+
+        try:
+            source = script_path.read_text(encoding="utf-8", errors="replace")
+        except OSError as exc:
+            raise FileNotFoundError(f"Could not read script: {script_path}") from exc
+
+        saved_argv = sys.argv[:]
+        saved_main = sys.modules.get("__main__")
+        saved_file = shell.namespace.get("__file__")
+
+        try:
+            sys.argv = argv
+            if interactive:
+                target_ns = shell.namespace
+                shell.run(source, globals=target_ns, locals=target_ns, filename=str(script_path))
+            else:
+                target_ns: dict[str, Any] = {"__name__": "__main__"}
+                for key in ("__builtins__", "display", "__magics__", "__shell__", "magic"):
+                    if key in shell.namespace:
+                        target_ns[key] = shell.namespace[key]
+
+                namespace_utils.NamespaceManager.prepare_namespace(
+                    target_ns, filename=str(script_path), module_name="__main__"
+                )
+                shell.run(source, globals=target_ns, locals=target_ns, filename=str(script_path))
+
+                hidden = {
+                    "__builtins__",
+                    "__doc__",
+                    "__file__",
+                    "__name__",
+                    "__package__",
+                    "__spec__",
+                    "__cached__",
+                    "__loader__",
+                    "__magics__",
+                    "__shell__",
+                    "display",
+                    "magic",
+                    "_",
+                    "__",
+                    "___",
+                }
+                for name, value in target_ns.items():
+                    if name in hidden or name.startswith("__"):
+                        continue
+                    shell.namespace[name] = value
+        finally:
+            sys.argv = saved_argv
+            if saved_file is not None:
+                shell.namespace["__file__"] = saved_file
+            if saved_main is None:
+                sys.modules.pop("__main__", None)
+            else:
+                sys.modules["__main__"] = saved_main
+
+        return ""

pynteract/cli.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import argparse
+import sys
+import __main__
+from importlib import metadata
+from pathlib import Path
+
+from .shell import Shell
+
+
+def build_shell(*, namespace: dict | None = None) -> Shell:
+    """Return a Shell bound to a `__main__` module namespace."""
+    if namespace is None:
+        namespace = __main__.__dict__
+    return Shell(module_name="__main__", namespace=namespace)
+
+
+def _run_script(shell: Shell, script: Path, argv: list[str]) -> int:
+    code = script.read_text(encoding="utf-8", errors="replace")
+    try:
+        sys.argv = argv
+        resp = shell.run(code, filename=str(script))
+        return 0 if resp.exception is None else 1
+    finally:
+        # Caller decides whether to restore sys.argv / sys.modules['__main__'].
+        pass
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pynteract", description="Interactive pynteract shell")
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="Print version and exit.",
+    )
+    parser.add_argument(
+        "-i",
+        "--interact",
+        action="store_true",
+        help="Enter interactive mode after running a script.",
+    )
+    parser.add_argument(
+        "script",
+        nargs="?",
+        help="Python script to run.",
+    )
+    parser.add_argument(
+        "script_args",
+        nargs=argparse.REMAINDER,
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--no-interact",
+        action="store_true",
+        help=argparse.SUPPRESS,
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        try:
+            version = metadata.version("pynteract")
+        except Exception:
+            version = "unknown"
+        sys.stdout.write(f"{version}\n")
+        return 0
+
+    if args.script:
+        script_path = Path(args.script)
+        if not script_path.exists():
+            sys.stderr.write(f"pynteract: no such file: {script_path}\n")
+            return 2
+        script_path = script_path.resolve()
+        script_argv = [str(script_path), *list(args.script_args or [])]
+
+        # Run scripts in a fresh __main__ namespace (like `python script.py` / IPython %run).
+        saved_argv = sys.argv[:]
+        saved_main = sys.modules.get("__main__")
+        shell = build_shell(namespace={})
+        sys.argv = script_argv
+
+        if args.interact:
+            startup_exit = shell._run_startup(announce=False)
+            if startup_exit != 0:
+                sys.argv = saved_argv
+                if saved_main is None:
+                    sys.modules.pop("__main__", None)
+                else:
+                    sys.modules["__main__"] = saved_main
+                return startup_exit
+
+        exit_code = _run_script(shell, script_path, script_argv)
+
+        if args.no_interact or not args.interact:
+            sys.argv = saved_argv
+            if saved_main is None:
+                sys.modules.pop("__main__", None)
+            else:
+                sys.modules["__main__"] = saved_main
+            return exit_code
+        # Else: keep script argv and __main__ module and fall through into interactive.
+    else:
+        shell = build_shell()
+        if args.no_interact:
+            return 0
+
+    return int(shell.interact())

pynteract/collector.py

@@ -0,0 +1,109 @@
+import sys
+from .streams import Stream, StdinProxy, stdout_write, stderr_write, stdin_readline
+from .context import RUN_CONTEXT
+
+class Collector:
+    """
+    Manages stdout and stderr redirection within a context manager.
+
+    This class captures all output and exceptions, allowing fine control over their handling and display.
+
+    Attributes:
+        shell: Shell instance whose hooks are consulted dynamically.
+        stdout_stream (Stream): Custom stream for capturing stdout.
+        stderr_stream (Stream): Custom stream for capturing stderr.
+        exception (Exception): Stores any exception raised during execution.
+
+    Methods:
+        get_stdout(): Returns all that was written to the stdout stream.
+        get_stderr(): Returns all that was written to the stderr stream.
+    """
+    def __init__(self, shell):
+        if shell is None:
+            raise TypeError("Collector requires a shell instance")
+        self.shell = shell
+        delegate_stdout = sys.stdout
+        delegate_stderr = sys.stderr
+        self.stdin_proxy = StdinProxy(shell, default_hook=stdin_readline)
+        self.stdout_stream = Stream(shell, hook_key="stdout_hook", default_hook=stdout_write, delegate=delegate_stdout)
+        self.stderr_stream = Stream(shell, hook_key="stderr_hook", default_hook=stderr_write, delegate=delegate_stderr)
+        self.exception = None
+
+    def get_stdout(self):
+        """
+        Returns all that was written to the stdout stream.
+
+        Returns:
+            str: The entire content written to stdout.
+        """
+        return self.stdout_stream.get_value()
+    
+    def get_stderr(self):
+        """
+        Returns all that was written to the stderr stream.
+
+        Returns:
+            str: The entire content written to stderr.
+        """
+        return self.stderr_stream.get_value()
+
+    def __enter__(self):
+        """
+        Implements using the collector as a context manager.
+
+        This method redirects sys.stdout and sys.stderr to stdout and stderr Streams
+        and, when ``stdin_hook`` is provided, installs a ``StdinProxy`` as sys.stdin.
+
+        Returns:
+            Collector: The Collector instance.
+        """
+        self.saved_stdout = sys.stdout
+        self.saved_stderr = sys.stderr
+        self.saved_stdin = sys.stdin
+        sys.stdout = self.stdout_stream
+        sys.stderr = self.stderr_stream
+        sys.stdin = self.stdin_proxy
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        """
+        Flushes the streams, restores the standard streams and gracefully processes any pending exception.
+
+        Args:
+            exc_type: The type of the exception.
+            exc_value: The exception instance.
+            exc_traceback: The traceback object.
+
+        Returns:
+            bool: True if the exception was handled, False otherwise.
+        """
+        # Flush streams
+        self.stdout_stream.flush()
+        self.stderr_stream.flush()
+        # Restore standard streams
+        sys.stdout = self.saved_stdout
+        sys.stderr = self.saved_stderr
+        sys.stdin = self.saved_stdin
+        # Deal with any unhandled exception
+        if exc_type is not None:
+            # Save the exception
+            self.exception = exc_value
+            message, enriched = self.shell._build_enriched_traceback(exc_type, exc_value, exc_traceback)
+            exc_value.enriched_traceback = enriched
+            exc_value.enriched_traceback_string = message
+
+            # Send the traceback to stderr_stream and flush
+            self.stderr_stream.write(message)
+            self.stderr_stream.flush()
+            # Send the exception to the exception hook
+            hooks = getattr(self.shell, "hooks", None)
+            if not isinstance(hooks, dict):
+                raise TypeError("shell.hooks must be a dict")
+            exception_hook = hooks.get("exception_hook")
+            if exception_hook:
+                invoke = getattr(self.shell, "_invoke_hook", None)
+                if callable(invoke):
+                    invoke(exception_hook, exc_value, ctx=RUN_CONTEXT.get())
+                else:
+                    exception_hook(exc_value)
+            return True  # Suppress exception propagation

pynteract/context.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import contextvars
+from dataclasses import dataclass
+from typing import Any
+
+# Active capture streams for the current context (stdout, stderr).
+CAPTURE_STREAMS: contextvars.ContextVar[tuple[Any, Any] | None] = contextvars.ContextVar(
+    "pynteract_capture_streams",
+    default=None,
+)
+
+@dataclass(frozen=True, slots=True)
+class RunContext:
+    name: str
+
+
+# Current run context (routing name for hooks).
+RUN_CONTEXT: contextvars.ContextVar[RunContext | None] = contextvars.ContextVar(
+    "pynteract_run_context",
+    default=None,
+)
+
+# If True, suppress stdout/stderr hook calls for this run (still captures output).
+SILENT_STDIO: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    "pynteract_silent_stdio",
+    default=False,
+)
+
+# Whether code printed a prompt without a trailing newline (common with builtin
+# input(prompt)), so stdin reads can start on a fresh line.
+PENDING_STDIN_PROMPT: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    "pynteract_pending_stdin_prompt",
+    default=False,
+)

pynteract/future_utils.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import __future__
+import ast
+from dataclasses import dataclass
+
+
+@dataclass
+class FutureManager:
+    """Track session-wide __future__ compiler flags for an interactive shell."""
+
+    flags: int = 0
+    allow_leading_docstring: bool = True
+    _seen_non_future_stmt: bool = False
+    _seen_docstring: bool = False
+
+    def reset(self) -> None:
+        self.flags = 0
+        self._seen_non_future_stmt = False
+        self._seen_docstring = False
+
+    def begin_block(self) -> None:
+        """Reset per-block state (flags are session-wide and persist)."""
+        self._seen_non_future_stmt = False
+        self._seen_docstring = False
+
+    def process_node(self, node: ast.AST) -> None:
+        """Validate/process a single node for __future__ semantics.
+
+        Notebook/REPL rule: `from __future__ import ...` must be the first node of the input.
+        By default, we emulate module semantics and permit exactly one leading string literal
+        ("docstring position") before any future imports.
+
+        If ``allow_leading_docstring`` is False, a leading string literal counts as a statement
+        (it can be displayed as output) and therefore blocks future imports that follow.
+        """
+
+        if (
+            self.allow_leading_docstring
+            and not self._seen_non_future_stmt
+            and not self._seen_docstring
+            and isinstance(node, ast.Expr)
+            and isinstance(node.value, ast.Constant)
+            and isinstance(node.value.value, str)
+        ):
+            self._seen_docstring = True
+            return
+
+        if isinstance(node, ast.ImportFrom) and node.module == "__future__":
+            if self._seen_non_future_stmt:
+                raise SyntaxError("from __future__ imports must occur at the beginning of the input")
+            for alias in node.names:
+                feature = getattr(__future__, alias.name, None)
+                flag = getattr(feature, "compiler_flag", 0) if feature is not None else 0
+                if not flag:
+                    raise SyntaxError(f"future feature {alias.name!r} is not defined")
+                self.flags |= int(flag)
+            return
+
+        self._seen_non_future_stmt = True