# Copyright (c) 2026. Jose Manuel Requena Plens
"""Run phonometry in a real notebook kernel and read what each cell put out.
Jupyter, JupyterLab, VS Code and Colab all run a notebook the same way: an
IPython kernel executes each cell, displays its last expression through the
object's ``_repr_html_`` and ``_repr_pretty_``, draws matplotlib figures
through the inline backend and sends warnings to the cell's stderr. None of
that happens in the test suite, which calls the methods directly, so this
executes ``tests/notebooks/smoke.ipynb`` with nbclient on an ipykernel and
then checks, cell by cell, by the tag on each cell:
* ``import``: the package imports in the kernel;
* ``rich-display``: a filter bank result is displayed as its table, in HTML
and in plain text, not as the dataclass repr;
* ``inline-plot``: ``.plot()`` puts out a PNG through the inline backend;
* ``verdict``: a verdict is displayed with its outcome, FAIL here;
* ``report``: ``.report()`` writes a PDF to a temporary path;
* ``warning``: the :class:`~phonometry.filters.FilterBankWarning` the cell
provokes, a topic class under :class:`~phonometry.PhonometryWarning`,
reaches the cell's stderr by its own name.
A cell that raises fails the run before any of this is read. The notebook is
committed without outputs; this never writes it back. It needs nbclient,
nbformat and ipykernel (``requirements-notebook.txt``), and phonometry with
its ``plot`` and ``report`` extras installed in the same environment.
"""
from __future__ import annotations
import argparse
import base64
import pathlib
import sys
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from collections.abc import Callable, Mapping, Sequence
ROOT = pathlib.Path(__file__).resolve().parent.parent
#: The notebook run by default.
NOTEBOOK = ROOT / "tests" / "notebooks" / "smoke.ipynb"
#: The seconds one cell may take; the slowest renders a PDF fiche.
CELL_TIMEOUT_S = 600
_PNG = b"\x89PNG\r\n\x1a\n"
Outputs = list[dict[str, Any]]
class NotebookError(Exception):
"""A cell did not put out what its tag asks for."""
def _data(outputs: Outputs, kind: str) -> list[dict[str, Any]]:
"""The ``data`` of every output of one type (``execute_result`` ...)."""
return [output["data"] for output in outputs if output["output_type"] == kind]
def _result(outputs: Outputs) -> dict[str, Any]:
results = _data(outputs, "execute_result")
if len(results) != 1:
msg = f"one displayed result expected, {len(results)} found"
raise NotebookError(msg)
return results[0]
def _imports(outputs: Outputs) -> str:
version = _result(outputs)["text/plain"]
return f"phonometry {version} imports in the kernel"
def _rich_display(outputs: Outputs) -> str:
shown = _result(outputs)
html = shown.get("text/html", "")
if '
' not in html:
msg = f"the result was not displayed as its table: {html[:200]!r}"
raise NotebookError(msg)
if "OctaveFilterResult" not in html:
msg = "the table does not name OctaveFilterResult"
raise NotebookError(msg)
text = shown["text/plain"]
if not text.startswith("OctaveFilterResult\n") or "array(" in text:
msg = f"the plain text is not the table: {text[:200]!r}"
raise NotebookError(msg)
return f"a filter bank result is a {len(html)}-character table"
def _inline_plot(outputs: Outputs) -> str:
images = [data["image/png"] for data in _data(outputs, "display_data")]
if len(images) != 1:
msg = f"one inline PNG expected, {len(images)} found"
raise NotebookError(msg)
png = base64.b64decode(images[0])
if not png.startswith(_PNG):
msg = "the inline figure is not a PNG"
raise NotebookError(msg)
return f".plot() renders inline, a {len(png)}-byte PNG"
def _verdict(outputs: Outputs) -> str:
shown = _result(outputs)
if ">FAIL" not in shown.get("text/html", ""):
msg = "the verdict does not show FAIL in its table"
raise NotebookError(msg)
first = shown["text/plain"].splitlines()[0]
if first != "LiningCuringCheck: FAIL":
msg = f"the plain text opens with {first!r}"
raise NotebookError(msg)
return "a verdict is displayed as FAIL"
def _report(outputs: Outputs) -> str:
header = _result(outputs)["text/plain"]
if header != "b'%PDF-'":
msg = f"the fiche does not open as a PDF: {header!r}"
raise NotebookError(msg)
return ".report() writes a PDF"
#: The topic class the warning cell provokes: a band above fs/2 dropped by
#: a filter bank. Every warning of the library is a topic class under
#: PhonometryWarning, and Python prints the topic, not the root.
WARNING = "FilterBankWarning"
def _warning(outputs: Outputs) -> str:
stderr = "".join(
output["text"]
for output in outputs
if output["output_type"] == "stream" and output["name"] == "stderr"
)
if f"{WARNING}: " not in stderr:
msg = f"no {WARNING} on stderr: {stderr[:200]!r}"
raise NotebookError(msg)
return f"a {WARNING} reaches the cell's stderr"
#: What each tagged cell must have put out, and how it is read.
CHECKS: dict[str, Callable[[Outputs], str]] = {
"import": _imports,
"rich-display": _rich_display,
"inline-plot": _inline_plot,
"verdict": _verdict,
"report": _report,
"warning": _warning,
}
def read(cells: Sequence[Mapping[str, Any]]) -> list[str]:
"""Read the outputs of executed *cells*: one line per check that passed.
:raises NotebookError: On a check whose cell is missing, and on the first
cell whose output is not what its tag asks for.
"""
tagged = {
tag: cell.get("outputs", [])
for cell in cells
for tag in cell.get("metadata", {}).get("tags", [])
}
missing = sorted(set(CHECKS) - set(tagged))
if missing:
msg = f"the notebook has no cell tagged {', '.join(missing)}"
raise NotebookError(msg)
return [check(tagged[tag]) for tag, check in CHECKS.items()]
def run(notebook: pathlib.Path) -> list[str]:
"""Execute *notebook* and return one line per check that passed.
:raises NotebookError: On a cell that raised, and as :func:`read` does.
"""
# Imported here: the notebook stack is this script's alone, and
# tests/test_check_notebook.py imports the script without it.
import nbformat
from nbclient import NotebookClient
from nbclient.exceptions import CellExecutionError
# nbformat ships py.typed but leaves read() unannotated: reading it
# through a typed name keeps the call checked under disallow_untyped_calls.
read_notebook: Callable[..., Any] = nbformat.read
nb = read_notebook(notebook, as_version=4)
client = NotebookClient(
nb,
timeout=CELL_TIMEOUT_S,
kernel_name="python3",
resources={"metadata": {"path": str(notebook.parent)}},
)
try:
client.execute()
except CellExecutionError as error:
raise NotebookError(str(error)) from error
return read(nb.cells)
def main(argv: Sequence[str] | None = None) -> int:
"""Execute the smoke notebook and report what it showed."""
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"notebook",
nargs="?",
type=pathlib.Path,
default=NOTEBOOK,
help="the notebook to execute (default: tests/notebooks/smoke.ipynb)",
)
arguments = parser.parse_args(argv)
try:
lines = run(arguments.notebook)
except NotebookError as error:
print(f"::error::{arguments.notebook}: {error}")
return 1
for line in lines:
print(f"ok {line}")
return 0
if __name__ == "__main__":
sys.exit(main())