Source code for hispecdrp.utils.notebook_display
"""Helpers for displaying large local HTML products inside Jupyter / VS Code notebooks."""
from __future__ import annotations
import http.server
import os
import socket
import threading
from functools import partial
from typing import Any
from urllib.parse import quote
__all__ = ["display_html_file"]
# Reuse one background server per directory so repeated cells do not bind new ports.
_SERVERS: dict[str, tuple[threading.Thread, int]] = {}
_LOCK = threading.Lock()
def _pick_free_port() -> int:
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
sock.bind(("127.0.0.1", 0))
return int(sock.getsockname()[1])
def _ensure_directory_server(directory: str) -> int:
"""Start (or reuse) a localhost static file server rooted at ``directory``."""
root = os.path.abspath(directory)
with _LOCK:
cached = _SERVERS.get(root)
if cached is not None:
return cached[1]
port = _pick_free_port()
handler = partial(http.server.SimpleHTTPRequestHandler, directory=root)
class QuietHandler(handler): # type: ignore[valid-type,misc]
def log_message(self, format: str, *args: Any) -> None: # noqa: A003
return
server = http.server.ThreadingHTTPServer(("127.0.0.1", port), QuietHandler)
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
_SERVERS[root] = (thread, port)
return port
[docs]
def display_html_file(
path: str,
*,
height: int = 900,
width: str | int = "100%",
) -> Any:
"""
Embed a local HTML file in a notebook output cell via a localhost iframe.
``IPython.display.HTML(open(path).read())`` does **not** work well for HISPEC
stellar-RV previews: they are full HTML documents (often hundreds of MB with
Plotly), and notebook frontends sanitize / drop nested ``<html>`` / ``<script>``
content. Serving the file over ``http://127.0.0.1`` and embedding an iframe
keeps scripts executable without stuffing the file into the notebook JSON.
Parameters
----------
path : str
Absolute or relative path to a ``.html`` file on disk.
height : int, optional
IFrame height in pixels. Default 900.
width : str or int, optional
IFrame width (CSS). Default ``'100%'``.
Returns
-------
IPython.display.IFrame
The display object (also sent to the notebook frontend via ``display``).
"""
from IPython.display import IFrame, display
html_path = os.path.abspath(path)
if not os.path.isfile(html_path):
raise FileNotFoundError(f"HTML preview not found: {html_path}")
directory, filename = os.path.split(html_path)
port = _ensure_directory_server(directory)
url = f"http://127.0.0.1:{port}/{quote(filename)}"
frame = IFrame(src=url, width=width, height=height)
display(frame)
return frame