ipythonng 0.0.1__tar.gz

ipythonng-0.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: ipythonng
+Version: 0.0.1
+Summary: IPython extension for terminal markdown, kitty images, and richer output history
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ipython>=9.0
+Requires-Dist: kittytgp>=0.0.2
+Requires-Dist: rich>=13.0
+
+# ipythonng
+
+`ipythonng` is a small IPython extension for terminal sessions that adds:
+
+- `text/markdown` rendering with Rich
+- `image/png` rendering via `kittytgp`
+- matplotlib inline support
+- Includes display objects, streams, and rich results in stored history
+
+## Install
+
+```bash
+pip install ipythonng
+```
+
+## Use as an extension
+
+Add the extension and enable output logging in your IPython config:
+
+```python
+c.InteractiveShellApp.extensions = ["ipythonng"]
+c.HistoryManager.db_log_output = True
+c.InteractiveShellApp.exec_lines = ["%matplotlib inline"]  # if you like
+```
+
+Or launch it ad hoc:
+
+```bash
+ipython --ext ipythonng
+```
+
+For matplotlib, `%matplotlib inline` works with the existing `image/png` renderer. No custom matplotlib backend is needed. Using `exec_lines` runs the magic after extensions load.
+
+## Convenience launcher
+
+The package also installs an `ipythonng` command that simply starts IPython with
+`--ext ipythonng`.

ipythonng-0.0.1/README.md

@@ -0,0 +1,37 @@
+# ipythonng
+
+`ipythonng` is a small IPython extension for terminal sessions that adds:
+
+- `text/markdown` rendering with Rich
+- `image/png` rendering via `kittytgp`
+- matplotlib inline support
+- Includes display objects, streams, and rich results in stored history
+
+## Install
+
+```bash
+pip install ipythonng
+```
+
+## Use as an extension
+
+Add the extension and enable output logging in your IPython config:
+
+```python
+c.InteractiveShellApp.extensions = ["ipythonng"]
+c.HistoryManager.db_log_output = True
+c.InteractiveShellApp.exec_lines = ["%matplotlib inline"]  # if you like
+```
+
+Or launch it ad hoc:
+
+```bash
+ipython --ext ipythonng
+```
+
+For matplotlib, `%matplotlib inline` works with the existing `image/png` renderer. No custom matplotlib backend is needed. Using `exec_lines` runs the magic after extensions load.
+
+## Convenience launcher
+
+The package also installs an `ipythonng` command that simply starts IPython with
+`--ext ipythonng`.

ipythonng-0.0.1/ipythonng/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.0.1"
+
+from .extension import load_ipython_extension, unload_ipython_extension
+
+__all__ = ["__version__", "load_ipython_extension", "unload_ipython_extension"]

ipythonng-0.0.1/ipythonng/cli.py

@@ -0,0 +1,6 @@
+import sys
+
+from IPython import start_ipython
+
+
+def main(): start_ipython(argv=["--ext", "ipythonng", *sys.argv[1:]])

ipythonng-0.0.1/ipythonng/extension.py

@@ -0,0 +1,233 @@
+import base64
+import io
+import sys
+from contextlib import redirect_stdout
+from types import MethodType
+from typing import Any
+
+from kittytgp import build_render_bytes
+from rich.console import Console
+from rich.markdown import Markdown as RichMarkdown
+
+_DEFAULT_CELL_SIZE = (8, 16)
+
+
+def _register_mime_renderer(shell, mime, handler):
+    active_types = shell.display_formatter.active_types
+    if mime not in active_types: active_types.append(mime)
+    formatter = shell.display_formatter.formatters.get(mime)
+    if formatter is not None: formatter.enabled = True
+    shell.mime_renderers[mime] = handler
+
+
+def _is_tty(stream) -> bool:
+    isatty = getattr(stream, "isatty", None)
+    return bool(isatty and isatty())
+
+
+def _is_inline_backend(backend: str | None) -> bool:
+    if not backend: return False
+    return backend.lower() in {"inline", "module://matplotlib_inline.backend_inline"}
+
+
+class _RenderTarget:
+    def __init__(self, stream): self.stream = stream
+
+    def fileno(self) -> int:
+        for candidate in (getattr(self.stream, "buffer", None), self.stream, getattr(sys.__stdout__, "buffer", None), sys.__stdout__):
+            fileno = getattr(candidate, "fileno", None)
+            if fileno is None: continue
+            try: return fileno()
+            except Exception: continue
+        return 1
+
+
+class IPythonNGExtension:
+    def __init__(self, shell):
+        self.shell = shell
+        self.history_manager = shell.history_manager
+        self._original_store_output = self.history_manager.store_output
+        self._pending_store_output = set()
+        self._registered_events = []
+        self._rendered_mimes = {}
+        self._handler_by_mime = {}
+        self._added_active_types = set()
+        self._original_enable_matplotlib = None
+
+    def load(self):
+        self._install_renderers()
+        self._install_history_patch()
+        self._install_matplotlib_patch()
+
+    def unload(self):
+        for event, callback in self._registered_events: self.shell.events.unregister(event, callback)
+        self._registered_events.clear()
+
+        self.history_manager.store_output = self._original_store_output
+        self._pending_store_output.clear()
+        if self._original_enable_matplotlib is not None: self.shell.enable_matplotlib = self._original_enable_matplotlib
+
+        for mime, original in self._rendered_mimes.items():
+            current = self.shell.mime_renderers.get(mime)
+            if current is self._handler_by_mime.get(mime):
+                if original is None: self.shell.mime_renderers.pop(mime, None)
+                else: self.shell.mime_renderers[mime] = original
+
+        for mime in self._added_active_types:
+            if mime in self.shell.display_formatter.active_types: self.shell.display_formatter.active_types.remove(mime)
+
+    def _install_renderers(self):
+        self._add_renderer("text/markdown", self._handle_text_markdown)
+        self._add_renderer("image/png", self._handle_image_png)
+
+    def _add_renderer(self, mime: str, handler):
+        self._rendered_mimes[mime] = self.shell.mime_renderers.get(mime)
+        self._handler_by_mime[mime] = handler
+        if mime not in self.shell.display_formatter.active_types: self._added_active_types.add(mime)
+        _register_mime_renderer(self.shell, mime, handler)
+
+    def _install_history_patch(self):
+        self.history_manager.store_output = MethodType(self._deferred_store_output, self.history_manager)
+        self.shell.events.register("post_run_cell", self._finalize_history)
+        self._registered_events.append(("post_run_cell", self._finalize_history))
+
+    def _install_matplotlib_patch(self):
+        self._original_enable_matplotlib = self.shell.enable_matplotlib
+        self.shell.enable_matplotlib = MethodType(lambda shell, gui=None: self._enable_matplotlib(shell, gui), self.shell)
+
+    def _deferred_store_output(self, history_manager, line_num: int) -> None:
+        if history_manager.db_log_output: self._pending_store_output.add(line_num)
+
+    def _output_stream(self): return getattr(self.shell, "_ipythonng_stream", sys.__stdout__)
+
+    def _write(self, text: str):
+        stream = self._output_stream()
+        stream.write(text)
+        flush = getattr(stream, "flush", None)
+        if flush is not None: flush()
+
+    def _render_markdown(self, markdown_text: str):
+        stream = self._output_stream()
+        console = Console(file=stream, force_terminal=_is_tty(stream), highlight=False, soft_wrap=True)
+        console.print(RichMarkdown(markdown_text))
+
+    def _current_matplotlib_backend(self) -> str | None:
+        try: import matplotlib
+        except Exception: return None
+        try: return matplotlib.get_backend()
+        except Exception: return None
+
+    def _close_matplotlib_figures(self):
+        try: from matplotlib import pyplot as plt
+        except Exception: return
+        try: plt.close("all")
+        except Exception: return
+
+    def _ensure_inline_figure_formats(self, shell):
+        try:
+            from IPython.core.pylabtools import select_figure_formats
+            from matplotlib.figure import Figure
+            from matplotlib_inline.config import InlineBackend
+        except Exception: return
+        png_formatter = shell.display_formatter.formatters["image/png"]
+        if Figure in png_formatter.type_printers: return
+        cfg = InlineBackend.instance(parent=shell)
+        select_figure_formats(shell, cfg.figure_formats, **cfg.print_figure_kwargs)
+
+    def _enable_matplotlib(self, shell, gui=None):
+        previous_backend = self._current_matplotlib_backend()
+        stdout = io.StringIO()
+        with redirect_stdout(stdout): result = self._original_enable_matplotlib(gui)
+        gui_name, backend = result
+        output = stdout.getvalue()
+        if _is_inline_backend(backend):
+            self._ensure_inline_figure_formats(shell)
+            output = "".join(line for line in output.splitlines(keepends=True) if line.strip() != "No event loop hook running.")
+            if not _is_inline_backend(previous_backend): self._close_matplotlib_figures()
+        if output: sys.stdout.write(output)
+        return gui_name, backend
+
+    def _needs_execute_result_newline(self) -> bool:
+        displayhook = getattr(self.shell, "displayhook", None)
+        return bool(displayhook and displayhook.is_active and not displayhook.prompt_end_newline)
+
+    def _render_png(self, png_b64: str, metadata: dict[str, Any] | None):
+        stream = self._output_stream()
+        if not _is_tty(stream):
+            self._write("[image/png]\n")
+            return
+
+        target = _RenderTarget(stream)
+        try:
+            png_bytes = base64.b64decode(png_b64)
+            payload = build_render_bytes(png_bytes, out=target)
+        except RuntimeError:
+            try:
+                payload = build_render_bytes(png_bytes, out=target, cell_width_px=_DEFAULT_CELL_SIZE[0], cell_height_px=_DEFAULT_CELL_SIZE[1])
+            except Exception:
+                self._write("[image/png]\n")
+                return
+        except Exception:
+            self._write("[image/png]\n")
+            return
+
+        if self._needs_execute_result_newline(): self._write("\n")
+        self._write(payload.decode("utf-8"))
+
+    def _handle_text_markdown(self, markdown_text: str, metadata=None): self._render_markdown(markdown_text)
+
+    def _handle_image_png(self, png_b64: str, metadata=None): self._render_png(png_b64, metadata)
+
+    def _render_history_output(self, output) -> str:
+        if output.output_type in {"out_stream", "err_stream"}: return "".join(output.bundle.get("stream", []))
+
+        bundle = output.bundle
+        if "text/markdown" in bundle: return bundle["text/markdown"]
+        if "image/png" in bundle: return "[image/png]"
+        if "text/plain" in bundle: return bundle["text/plain"]
+        return ""
+
+    def _flatten_output(self, execution_count: int) -> str | None:
+        pieces = []
+        for output in self.history_manager.outputs.get(execution_count, []):
+            text = self._render_history_output(output)
+            if not text: continue
+            if pieces and not pieces[-1].endswith("\n") and not text.startswith("\n"): pieces.append("\n")
+            pieces.append(text)
+
+        exception = self.history_manager.exceptions.get(execution_count)
+        if exception:
+            traceback_text = "".join(exception.get("traceback", []))
+            if traceback_text:
+                if pieces and not pieces[-1].endswith("\n") and not traceback_text.startswith("\n"): pieces.append("\n")
+                pieces.append(traceback_text)
+
+        if not pieces: return None
+        return "".join(pieces)
+
+    def _finalize_history(self, result):
+        execution_count = getattr(result, "execution_count", None)
+        if execution_count is None: return
+
+        flat_output = self._flatten_output(execution_count)
+        if flat_output is None: self.history_manager.output_hist_reprs.pop(execution_count, None)
+        else: self.history_manager.output_hist_reprs[execution_count] = flat_output
+
+        should_store = self.history_manager.db_log_output and flat_output is not None and (
+            execution_count in self._pending_store_output or execution_count in self.history_manager.exceptions)
+        self._pending_store_output.discard(execution_count)
+        if should_store: self._original_store_output(execution_count)
+
+
+def load_ipython_extension(shell):
+    if getattr(shell, "_ipythonng_extension", None) is not None: return
+    extension = IPythonNGExtension(shell)
+    extension.load()
+    shell._ipythonng_extension = extension
+
+
+def unload_ipython_extension(shell):
+    extension = getattr(shell, "_ipythonng_extension", None)
+    if extension is None: return
+    extension.unload()
+    del shell._ipythonng_extension

ipythonng-0.0.1/ipythonng.egg-info/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: ipythonng
+Version: 0.0.1
+Summary: IPython extension for terminal markdown, kitty images, and richer output history
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ipython>=9.0
+Requires-Dist: kittytgp>=0.0.2
+Requires-Dist: rich>=13.0
+
+# ipythonng
+
+`ipythonng` is a small IPython extension for terminal sessions that adds:
+
+- `text/markdown` rendering with Rich
+- `image/png` rendering via `kittytgp`
+- matplotlib inline support
+- Includes display objects, streams, and rich results in stored history
+
+## Install
+
+```bash
+pip install ipythonng
+```
+
+## Use as an extension
+
+Add the extension and enable output logging in your IPython config:
+
+```python
+c.InteractiveShellApp.extensions = ["ipythonng"]
+c.HistoryManager.db_log_output = True
+c.InteractiveShellApp.exec_lines = ["%matplotlib inline"]  # if you like
+```
+
+Or launch it ad hoc:
+
+```bash
+ipython --ext ipythonng
+```
+
+For matplotlib, `%matplotlib inline` works with the existing `image/png` renderer. No custom matplotlib backend is needed. Using `exec_lines` runs the magic after extensions load.
+
+## Convenience launcher
+
+The package also installs an `ipythonng` command that simply starts IPython with
+`--ext ipythonng`.

ipythonng-0.0.1/ipythonng.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+./ipythonng/__init__.py
+./ipythonng/cli.py
+./ipythonng/extension.py
+ipythonng/__init__.py
+ipythonng/cli.py
+ipythonng/extension.py
+ipythonng.egg-info/PKG-INFO
+ipythonng.egg-info/SOURCES.txt
+ipythonng.egg-info/dependency_links.txt
+ipythonng.egg-info/entry_points.txt
+ipythonng.egg-info/requires.txt
+ipythonng.egg-info/top_level.txt
+tests/test_ipythonng.py

ipythonng-0.0.1/ipythonng.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ipythonng-0.0.1/ipythonng.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ipythonng = ipythonng.cli:main

ipythonng-0.0.1/ipythonng.egg-info/requires.txt

@@ -0,0 +1,3 @@
+ipython>=9.0
+kittytgp>=0.0.2
+rich>=13.0

ipythonng-0.0.1/ipythonng.egg-info/top_level.txt

@@ -0,0 +1 @@
+ipythonng

ipythonng-0.0.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ipythonng"
+dynamic = ["version"]
+description = "IPython extension for terminal markdown, kitty images, and richer output history"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "ipython>=9.0",
+    "kittytgp>=0.0.2",
+    "rich>=13.0",
+]
+
+[project.scripts]
+ipythonng = "ipythonng.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "."}
+include-package-data = true
+
+[tool.setuptools.dynamic]
+version = { attr = "ipythonng.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["ipythonng*"]

ipythonng-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ipythonng-0.0.1/tests/test_ipythonng.py

@@ -0,0 +1,210 @@
+import base64
+import io
+
+import kittytgp.core as kittycore
+import pytest
+from IPython.terminal.interactiveshell import TerminalInteractiveShell
+from kittytgp import build_render_bytes
+from kittytgp.core import PLACEHOLDER
+from traitlets.config import Config
+
+from ipythonng import load_ipython_extension
+
+PNG_B64 = "iVBORw0KGgoAAAANSUhEUgAAAAIAAAADCAQAAABi6S9dAAAADElEQVR42mNkYPhfDwADhgGAff/3fwAAAABJRU5ErkJggg=="
+PNG_BYTES = base64.b64decode(PNG_B64)
+
+
+class FakeTerminal(io.StringIO):
+    def isatty(self): return True
+
+
+class GeometryProbe:
+    def fileno(self): return 1
+
+
+@pytest.fixture
+def shell(tmp_path):
+    TerminalInteractiveShell.clear_instance()
+    config = Config()
+    config.TerminalInteractiveShell.simple_prompt = True
+    config.HistoryManager.hist_file = str(tmp_path / "history.sqlite")
+    shell = TerminalInteractiveShell.instance(config=config)
+    shell.execution_count = 1
+    shell.history_manager.outputs.clear()
+    shell.history_manager.output_hist_reprs.clear()
+    shell.history_manager.exceptions.clear()
+    shell._ipythonng_stream = FakeTerminal()
+    load_ipython_extension(shell)
+    try: yield shell
+    finally:
+        shell.history_manager.writeout_cache()
+        shell.history_manager.end_session()
+        shell._atexit_once = lambda: None
+        TerminalInteractiveShell.clear_instance()
+
+
+def test_history_flattens_streams_markdown_images_and_results(shell):
+    shell.run_cell(
+        """
+from IPython.display import Markdown, Image, display
+import base64
+print("alpha")
+display(Markdown("# Heading"))
+display(Image(data=base64.b64decode(%r), format="png"))
+print("omega")
+42
+"""
+        % PNG_B64,
+        store_history=True,
+    )
+
+    (_, _, (_, output)) = list(shell.history_manager.get_range(output=True))[-1]
+    assert output == "alpha\n# Heading\n[image/png]\nomega\n42"
+
+
+def test_output_history_persists_flattened_output_across_sessions(shell):
+    shell.history_manager.db_log_output = True
+    result = shell.run_cell(
+        """
+from IPython.display import Markdown, display
+print("alpha")
+display(Markdown("## Saved"))
+""",
+        store_history=True,
+    )
+
+    shell.history_manager.writeout_cache()
+    shell.history_manager.reset()
+
+    execution_count = result.execution_count
+    entries = list(shell.history_manager.get_range(-1, execution_count, execution_count + 1, output=True))
+    assert entries[0][2][1] == "alpha\n## Saved"
+
+
+def test_tracebacks_are_included_in_flattened_output(shell):
+    shell.history_manager.db_log_output = True
+    shell.run_cell("1/0", store_history=True)
+
+    (_, _, (_, output)) = list(shell.history_manager.get_range(output=True))[-1]
+    assert "ZeroDivisionError" in output
+    assert "division by zero" in output
+
+
+def test_kitty_rendering_matches_kittytgp_outside_tmux(shell, monkeypatch):
+    monkeypatch.delenv("TMUX", raising=False)
+    monkeypatch.setattr(kittycore.secrets, "randbelow", lambda _: 0x123456 - 1)
+
+    shell.run_cell(
+        """
+from IPython.display import Image, display
+import base64
+display(Image(data=base64.b64decode(%r), format="png"))
+"""
+        % PNG_B64,
+        store_history=True,
+    )
+
+    rendered = shell._ipythonng_stream.getvalue()
+    expected = build_render_bytes(PNG_BYTES, out=GeometryProbe(), cell_width_px=8, cell_height_px=16).decode("utf-8")
+    assert rendered == expected
+    assert PLACEHOLDER in rendered
+    assert "\x1bPtmux;" not in rendered
+    assert "[image/png]" not in rendered
+
+
+def test_execute_result_images_start_on_new_line(shell, monkeypatch):
+    monkeypatch.delenv("TMUX", raising=False)
+    monkeypatch.setattr(kittycore.secrets, "randbelow", lambda _: 0x222222 - 1)
+
+    shell.run_cell(
+        """
+from IPython.display import Image
+import base64
+Image(data=base64.b64decode(%r), format="png")
+"""
+        % PNG_B64,
+        store_history=True,
+    )
+
+    rendered = shell._ipythonng_stream.getvalue()
+    expected = build_render_bytes(PNG_BYTES, out=GeometryProbe(), cell_width_px=8, cell_height_px=16).decode("utf-8")
+    assert rendered == "\n" + expected
+
+
+def test_kitty_rendering_matches_kittytgp_inside_tmux(shell, monkeypatch):
+    monkeypatch.setenv("TMUX", "/tmp/tmux")
+    monkeypatch.setattr(kittycore.secrets, "randbelow", lambda _: 0x654321 - 1)
+
+    shell.run_cell(
+        """
+from IPython.display import Image, display
+import base64
+display(Image(data=base64.b64decode(%r), format="png"))
+"""
+        % PNG_B64,
+        store_history=True,
+    )
+
+    rendered = shell._ipythonng_stream.getvalue()
+    expected = build_render_bytes(PNG_BYTES, out=GeometryProbe(), cell_width_px=8, cell_height_px=16).decode("utf-8")
+    assert rendered == expected
+    assert PLACEHOLDER in rendered
+    assert "\x1bPtmux;" in rendered
+    assert "[image/png]" not in rendered
+
+
+def test_matplotlib_inline_plots_render_via_image_png(shell, monkeypatch, tmp_path):
+    pytest.importorskip("matplotlib")
+    mplconfig = tmp_path / "mplconfig"
+    mplconfig.mkdir()
+    monkeypatch.setenv("MPLCONFIGDIR", str(mplconfig))
+    monkeypatch.delenv("TMUX", raising=False)
+    monkeypatch.setattr(kittycore.secrets, "randbelow", lambda _: 0x333333 - 1)
+
+    shell.run_line_magic("matplotlib", "inline")
+    shell.run_cell("import matplotlib.pyplot as plt\nplt.plot([1, 2, 3])", store_history=True)
+
+    rendered = shell._ipythonng_stream.getvalue()
+    (_, _, (_, output)) = list(shell.history_manager.get_range(output=True))[-1]
+    assert PLACEHOLDER in rendered
+    assert "\x1b_G" in rendered
+    assert "matplotlib.lines.Line2D" in output
+    assert "[image/png]" in output
+
+
+def test_matplotlib_inline_magic_suppresses_no_event_loop_message(shell, monkeypatch, tmp_path, capsys):
+    pytest.importorskip("matplotlib")
+    mplconfig = tmp_path / "mplconfig"
+    mplconfig.mkdir()
+    monkeypatch.setenv("MPLCONFIGDIR", str(mplconfig))
+
+    capsys.readouterr()
+    shell.run_line_magic("matplotlib", "inline")
+    captured = capsys.readouterr()
+    assert "No event loop hook running." not in captured.out
+
+
+def test_matplotlib_inline_after_prior_plot_renders_future_plots(shell, monkeypatch, tmp_path, capsys):
+    pytest.importorskip("matplotlib")
+    mplconfig = tmp_path / "mplconfig"
+    mplconfig.mkdir()
+    monkeypatch.setenv("MPLCONFIGDIR", str(mplconfig))
+    monkeypatch.delenv("TMUX", raising=False)
+    monkeypatch.setattr(kittycore.secrets, "randbelow", lambda _: 0x444444 - 1)
+
+    shell.run_cell("import matplotlib\nmatplotlib.use('agg')\nimport matplotlib.pyplot as plt\nplt.plot([1, 2, 3])", store_history=True)
+    shell._ipythonng_stream.seek(0)
+    shell._ipythonng_stream.truncate(0)
+
+    capsys.readouterr()
+    shell.run_line_magic("matplotlib", "inline")
+    captured = capsys.readouterr()
+    assert "No event loop hook running." not in captured.out
+
+    shell.run_cell("plt.plot([4, 5, 6])", store_history=True)
+
+    rendered = shell._ipythonng_stream.getvalue()
+    output_types = [o.output_type for o in shell.history_manager.outputs.get(shell.execution_count - 1, [])]
+    assert PLACEHOLDER in rendered
+    assert "\x1b_G" in rendered
+    assert "display_data" in output_types