batchgrid 0.2.0b1__tar.gz → 0.2.0b2__tar.gz

{batchgrid-0.2.0b1 → batchgrid-0.2.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: batchgrid
-Version: 0.2.0b1
+Version: 0.2.0b2
 Summary: Run a prompt, or a whole pipeline, over every row of a DataFrame or spreadsheet - with cost estimates, retries and resumable runs.
 Project-URL: Homepage, https://github.com/mertguvencli/batchgrid
 Project-URL: Source, https://github.com/mertguvencli/batchgrid/tree/main/python
@@ -83,7 +83,8 @@ The file is the same one `batchgrid --save-plan` writes and `batchgrid --plan` r
 
 ## In the browser
 
-`batchgrid.ui()` opens the batchgrid workspace in your browser with your data in the sheet. You can
+`batchgrid.ui()` opens the batchgrid workspace with your data in the sheet. In a Jupyter notebook it
+shows in the cell's output; elsewhere, or with `inline=False`, it opens in your browser. You can
 chat, check the plan and run it there, while the log prints in the notebook cell or terminal as it
 happens:
 
@@ -105,7 +106,8 @@ batchgrid: 100%|██████████| 1000/1000 [00:42<00:00, failed=0
 Finished in the browser.
 ```
 
-To come back, press **Finish** in the tab, close the tab, or interrupt the cell. `ui()` returns the
+To come back, press **Finish** in the workspace, close its tab, or interrupt the cell. Once it stops,
+a note takes the workspace's place in the cell. `ui()` returns the
 sheet as the tab last showed it. For a DataFrame, that is a copy of yours with the new columns and
 any cells you edited; untouched columns keep their dtypes. `ui()` with no data starts on an empty
 sheet.
@@ -163,9 +165,10 @@ except KeyboardInterrupt:
     result = batchgrid.resume(df)
 ```
 
-### `batchgrid.ui(data=None, *, open_browser=True, port=None, log=True) -> DataFrame | None`
+### `batchgrid.ui(data=None, *, inline=None, height=720, open_browser=True, port=None, log=True) -> DataFrame | None`
 
-See [In the browser](#in-the-browser). `on_event` receives the same events as in `run()`, plus `ui`,
+See [In the browser](#in-the-browser). `inline` shows the workspace in the cell, `height` pixels tall;
+by default it does in a Jupyter notebook and opens a browser tab anywhere else. `on_event` receives the same events as in `run()`, plus `ui`,
 `sheet`, `browser_error` and `closed`.
 
 ### Errors

{batchgrid-0.2.0b1 → batchgrid-0.2.0b2}/README.md

@@ -57,7 +57,8 @@ The file is the same one `batchgrid --save-plan` writes and `batchgrid --plan` r
 
 ## In the browser
 
-`batchgrid.ui()` opens the batchgrid workspace in your browser with your data in the sheet. You can
+`batchgrid.ui()` opens the batchgrid workspace with your data in the sheet. In a Jupyter notebook it
+shows in the cell's output; elsewhere, or with `inline=False`, it opens in your browser. You can
 chat, check the plan and run it there, while the log prints in the notebook cell or terminal as it
 happens:
 
@@ -79,7 +80,8 @@ batchgrid: 100%|██████████| 1000/1000 [00:42<00:00, failed=0
 Finished in the browser.
 ```
 
-To come back, press **Finish** in the tab, close the tab, or interrupt the cell. `ui()` returns the
+To come back, press **Finish** in the workspace, close its tab, or interrupt the cell. Once it stops,
+a note takes the workspace's place in the cell. `ui()` returns the
 sheet as the tab last showed it. For a DataFrame, that is a copy of yours with the new columns and
 any cells you edited; untouched columns keep their dtypes. `ui()` with no data starts on an empty
 sheet.
@@ -137,9 +139,10 @@ except KeyboardInterrupt:
     result = batchgrid.resume(df)
 ```
 
-### `batchgrid.ui(data=None, *, open_browser=True, port=None, log=True) -> DataFrame | None`
+### `batchgrid.ui(data=None, *, inline=None, height=720, open_browser=True, port=None, log=True) -> DataFrame | None`
 
-See [In the browser](#in-the-browser). `on_event` receives the same events as in `run()`, plus `ui`,
+See [In the browser](#in-the-browser). `inline` shows the workspace in the cell, `height` pixels tall;
+by default it does in a Jupyter notebook and opens a browser tab anywhere else. `on_event` receives the same events as in `run()`, plus `ui`,
 `sheet`, `browser_error` and `closed`.
 
 ### Errors

{batchgrid-0.2.0b1 → batchgrid-0.2.0b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "batchgrid"
-version = "0.2.0b1"
+version = "0.2.0b2"
 description = "Run a prompt, or a whole pipeline, over every row of a DataFrame or spreadsheet - with cost estimates, retries and resumable runs."
 readme = "README.md"
 license = "MIT"

{batchgrid-0.2.0b1 → batchgrid-0.2.0b2}/src/batchgrid/__init__.py

@@ -16,7 +16,7 @@ from ._ui import ui
 from ._cli import CLI_SPEC, find_cli
 from .errors import BatchgridError, CostLimitError, MissingSecretsError, NoPlanError
 
-__version__ = "0.2.0b1"
+__version__ = "0.2.0b2"
 
 __all__ = [
     "BatchgridError",

{batchgrid-0.2.0b1 → batchgrid-0.2.0b2}/src/batchgrid/_ui.py

@@ -1,4 +1,4 @@
-"""ui() - the web workspace in the browser, with its log here and its sheet coming back."""
+"""ui() - the web workspace in the notebook or the browser, with its log here and its sheet coming back."""
 
 from __future__ import annotations
 
@@ -18,6 +18,8 @@ if TYPE_CHECKING:
 def ui(
     data: Optional[Data] = None,
     *,
+    inline: Optional[bool] = None,
+    height: int = 720,
     open_browser: bool = True,
     port: Optional[int] = None,
     log: bool = True,
@@ -25,27 +27,31 @@ def ui(
     cli: Optional[Sequence[str]] = None,
     env: Optional[Mapping[str, str]] = None,
 ) -> Optional["pd.DataFrame"]:
-    """Open the batchgrid workspace in the browser and wait until you are done there.
+    """Open the batchgrid workspace and wait until you are done there.
 
-    ``data`` - a file path or a pandas DataFrame - opens in the sheet. Chat,
-    plan and run in the browser; what happens there is printed here as it
-    happens, with a progress bar while rows run.
+    ``data`` - a file path or a pandas DataFrame - opens in the sheet. In a
+    Jupyter notebook the workspace shows in the cell's output, ``height``
+    pixels tall; ``inline=False`` opens it in a browser tab instead, which is
+    what happens outside a notebook. Chat, plan and run there; what happens is
+    printed here as it happens, with a progress bar while rows run.
 
-    Press Finish in the tab, close it, or interrupt the cell (Ctrl+C) to come
-    back. The sheet as the tab last showed it is returned as a DataFrame: for
+    Press Finish in the workspace, close its tab, or interrupt the cell
+    (Ctrl+C) to come back. The sheet as the tab last showed it is returned as a DataFrame: for
     a DataFrame you passed in, a copy with the new columns added and your
     edits in it. None when nothing was opened, or pandas is not installed.
 
     It runs on this machine, so it needs a browser that can reach it - not a
     notebook running on a remote server.
     """
-    printer = _Printer() if log else None
+    embed = _in_notebook() if inline is None else inline
+    frame_view = _Frame(height) if embed else None
+    printer = _Printer(link=not embed) if log else None
     with _input_file(data) as (path, frame):
         out = _TempDir()
         try:
             sheet = os.path.join(out.get(), "sheet.csv")
             args: List[str] = ["ui", *([path] if path else []), "--output", sheet, "--json"]
-            if not open_browser:
+            if embed or not open_browser:
                 args.append("--no-open")
             if port is not None:
                 args += ["--port", str(port)]
@@ -59,6 +65,8 @@ def ui(
                         failure = event
                     elif event.get("type") == "ui":
                         started = True
+                        if frame_view is not None:
+                            frame_view.show(str(event.get("url")))
                     elif event.get("type") == "exit":
                         ended = event
                     if printer is not None:
@@ -71,6 +79,8 @@ def ui(
             finally:
                 if printer is not None:
                     printer.close()
+                if frame_view is not None:
+                    frame_view.close()
             if failure is not None:
                 raise BatchgridError(str(failure.get("code")), str(failure.get("message")))
             if not started and ended is not None and ended.get("code"):
@@ -110,11 +120,56 @@ def _read_sheet(frame: Any, sheet: Path, sent: Optional[Path]) -> Optional["pd.D
     return merged
 
 
+def _in_notebook() -> bool:
+    """Whether this runs in a Jupyter kernel, whose front end can show the workspace in a cell"""
+    try:
+        from IPython import get_ipython
+
+        shell = get_ipython()
+        return shell is not None and "IPKernelApp" in shell.config
+    except Exception:  # noqa: BLE001 - no IPython means a plain console
+        return False
+
+
+class _Frame:
+    """The workspace in the cell's output; once it stops, a note takes its place"""
+
+    def __init__(self, height: int) -> None:
+        self.height = height
+        self.handle: Any = None
+
+    def show(self, url: str) -> None:
+        from IPython.display import IFrame, display
+
+        self.handle = display(
+            IFrame(
+                url,
+                width="100%",
+                height=self.height,
+                extras=[
+                    'style="border: 1px solid rgba(128, 128, 128, 0.35); border-radius: 6px"',
+                    'allow="clipboard-read; clipboard-write"',
+                ],
+            ),
+            display_id=True,
+        )
+
+    def close(self) -> None:
+        if self.handle is None:
+            return
+        from IPython.display import HTML
+
+        # The server behind the frame is gone, so a saved notebook keeps no dead workspace
+        self.handle.update(HTML("<em>batchgrid closed. Run the cell again to reopen it.</em>"))
+        self.handle = None
+
+
 class _Printer:
     """The terminal's log, in a notebook cell or a Python console"""
 
-    def __init__(self) -> None:
+    def __init__(self, link: bool = True) -> None:
         self.bar: Any = None
+        self.link = link
         try:
             from tqdm.auto import tqdm
 
@@ -130,7 +185,7 @@ class _Printer:
         # Anything else ends the run's bar, so its lines are not drawn over it
         if kind in ("result", "closed", "user", "plan"):
             self.close()
-        if kind == "ui":
+        if kind == "ui" and self.link:
             self._link(str(event.get("url")))
         elif kind == "user":
             self._line(f"\n❯ {event.get('text')}")
@@ -155,7 +210,7 @@ class _Printer:
         elif kind == "error":
             self._line(f"✖ {event.get('message')}")
         elif kind == "closed":
-            why = {"tab_closed": "The tab was closed", "finished": "Finished in the browser"}.get(
+            why = {"tab_closed": "The tab was closed", "finished": "Finished in the browser" if self.link else "Finished"}.get(
                 str(event.get("reason")), "Stopped"
             )
             self._line(f"\n{why}.")
@@ -173,15 +228,11 @@ class _Printer:
         self.bar.refresh()
 
     def _link(self, url: str) -> None:
-        try:
-            from IPython import get_ipython
+        if _in_notebook():
             from IPython.display import HTML, display
 
-            if get_ipython() is not None and "IPKernelApp" in get_ipython().config:
-                display(HTML(f'batchgrid is open at <a href="{url}" target="_blank">{url.split("?")[0]}</a>'))
-                return
-        except Exception:  # noqa: BLE001 - no IPython means a plain console
-            pass
+            display(HTML(f'batchgrid is open at <a href="{url}" target="_blank">{url.split("?")[0]}</a>'))
+            return
         self._line(f"batchgrid is open at {url}")
 
     def _line(self, text: str) -> None:

{batchgrid-0.2.0b1 → batchgrid-0.2.0b2}/tests/test_ui.py

@@ -14,6 +14,7 @@ import stat
 import sys
 import threading
 import time
+import types
 import urllib.request
 from pathlib import Path
 from typing import Any, Dict, List
@@ -129,6 +130,45 @@ def test_interrupting_the_cell_returns_instead_of_raising() -> None:
     assert result.loc[0, "sentiment"] == "positive"
 
 
+def test_in_a_notebook_the_workspace_shows_in_the_cell(monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:
+    shown: List[Any] = []
+
+    class Handle:
+        def update(self, obj: Any) -> None:
+            shown.append(obj)
+
+    def display(obj: Any, display_id: bool = False) -> Handle:
+        shown.append(obj)
+        return Handle()
+
+    # A stand-in for the IPython a Jupyter kernel runs
+    ipython = types.ModuleType("IPython")
+    ipython.get_ipython = lambda: types.SimpleNamespace(config={"IPKernelApp": {}})  # type: ignore[attr-defined]
+    ipython_display = types.ModuleType("IPython.display")
+    ipython_display.HTML = lambda html: html  # type: ignore[attr-defined]
+    ipython_display.IFrame = lambda src, **options: {"src": src, **options}  # type: ignore[attr-defined]
+    ipython_display.display = display  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "IPython", ipython)
+    monkeypatch.setitem(sys.modules, "IPython.display", ipython_display)
+
+    urls: List[str] = []
+
+    def act(tab: FakeTab) -> None:
+        urls.append(tab.url)
+        tab.call("finish", {})
+
+    # No open_browser=False: showing it in the cell never opens a tab
+    batchgrid.ui(on_event=open_tab(act))
+
+    assert len(shown) == 2
+    assert shown[0]["src"] == urls[0] and shown[0]["height"] == 720
+    # The server behind it stopped, so a note takes the workspace's place
+    assert "batchgrid closed" in shown[1]
+    printed = capsys.readouterr().out
+    assert "is open at" not in printed
+    assert "Finished." in printed
+
+
 def test_nothing_synced_returns_none() -> None:
     result = batchgrid.ui(open_browser=False, log=False, on_event=open_tab(lambda tab: tab.call("finish", {})))
     assert result is None