whybook 0.1.0__py3-none-any.whl

epi/__init__.py

@@ -0,0 +1,15 @@
+"""The former name of the helpers in ``whybook``, kept so that saved notebooks run.
+
+``import epi`` warns and gives the same helpers; new code uses ``import whybook``.
+"""
+
+import warnings
+
+import whybook
+from whybook import __all__  # noqa: F401
+
+warnings.warn("epi is now whybook: use `import whybook`", DeprecationWarning, stacklevel=2)
+
+
+def __getattr__(name):
+    return getattr(whybook, name)

whybook/__init__.py

@@ -0,0 +1,65 @@
+"""Whybook: a question-driven view of Jupyter notebooks.
+
+In a notebook, ``import whybook`` gives the helpers that the view reads:
+plots whose marks keep the rows behind them, so that the view can ask about
+the rows in a region of a plot, and ``progress``, which shows as a progress
+bar on the cell that calls it, also in a branch that runs in a subshell.
+They load on first use, so that the Jupyter server, which imports this
+package to find its extension, loads no plotting code.
+
+The Jupyter server extension is ``whybook.server``.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+# Each helper, and the module that defines it.
+_HELPERS = {
+    "bars": "plots",
+    "hist": "plots",
+    "ribbon": "plots",
+    "scatter": "plots",
+    "progress": "_progress",
+    "by_group": "explore",
+    "compare_frames": "explore",
+    "compare_levels": "explore",
+    "cross_table": "explore",
+    "icc": "explore",
+    "line_up": "explore",
+    "profile": "explore",
+    "rows_per_unit": "explore",
+    "screen": "explore",
+    "summary": "explore",
+    "time_profile": "explore",
+    "who_is_in": "explore",
+    "within_between": "explore",
+}
+
+__all__ = sorted(_HELPERS)
+
+
+def __getattr__(name: str) -> Any:
+    module = _HELPERS.get(name)
+    if module is None:
+        raise AttributeError(f"module 'whybook' has no attribute {name!r}")
+    return getattr(importlib.import_module(f".{module}", __name__), name)
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_HELPERS))
+
+
+try:
+    from ._version import __version__
+except ImportError:  # a checkout that pip has not installed
+    __version__ = "dev"
+
+
+def _jupyter_labextension_paths():
+    return [{"src": "labextension", "dest": "whybook"}]
+
+
+def _jupyter_server_extension_points():
+    return [{"module": "whybook.server"}]

whybook/_display.py

@@ -0,0 +1,49 @@
+"""Display helpers shared by the plotting and progress functions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+PLOT_MIME = "application/vnd.whybook.plot+json"
+PROGRESS_MIME = "application/vnd.whybook.progress+json"
+
+
+def shell() -> Any:
+    try:
+        from IPython import get_ipython
+    except ImportError:
+        return None
+    return get_ipython()
+
+
+def name_of(value: Any) -> str | None:
+    """The name of a user variable that holds ``value``, if there is one."""
+    ip = shell()
+    if ip is None:
+        return None
+    for name, candidate in list(ip.user_ns.items()):
+        if candidate is value and not name.startswith("_"):
+            return name
+    return None
+
+
+def current_request() -> str | None:
+    """The id of the execute request that is running in this thread.
+
+    ipykernel 7 keeps the parent message in a context variable, so this is
+    also right inside a kernel subshell.
+    """
+    ip = shell()
+    kernel = getattr(ip, "kernel", None)
+    if kernel is None:
+        return None
+    try:
+        return kernel.get_parent()["header"]["msg_id"]
+    except (KeyError, TypeError, AttributeError):
+        return None
+
+
+def show(bundle: dict[str, Any], **kwargs: Any) -> None:
+    from IPython.display import display
+
+    display(bundle, raw=True, **kwargs)

whybook/_progress.py

@@ -0,0 +1,34 @@
+"""Progress bars for long cells, including branches that run in subshells."""
+
+from __future__ import annotations
+
+import uuid
+
+from ._display import PROGRESS_MIME, current_request, show
+
+# One display per execute request: a new run of the cell starts a new bar.
+_displays: dict[str | None, str] = {}
+
+
+def progress(fraction: float, stage: str | None = None) -> None:
+    """Report how far the running cell is, from 0 to 1.
+
+    The Whybook view draws a progress bar on the cell. A classic notebook
+    shows the same report as one line of text that updates in place.
+    """
+    fraction = min(max(float(fraction), 0.0), 1.0)
+    request = current_request()
+    bundle = {
+        PROGRESS_MIME: {"fraction": fraction, "stage": stage},
+        "text/plain": f"[{fraction:4.0%}] {stage or ''}".rstrip(),
+    }
+    display_id = _displays.get(request)
+    if display_id is None:
+        display_id = _displays[request] = uuid.uuid4().hex
+        show(bundle, display_id=display_id)
+    else:
+        from IPython.display import update_display
+
+        update_display(bundle, raw=True, display_id=display_id)
+    if fraction >= 1.0:
+        _displays.pop(request, None)

whybook/_version.py

@@ -0,0 +1,4 @@
+# This file is auto-generated by Hatchling. As such, do not:
+#   - modify
+#   - track in version control e.g. be sure to add to .gitignore
+__version__ = VERSION = '0.1.0'