imgui_debugger 0.1.0__py3-none-any.whl

imgui_debugger/format.py

@@ -0,0 +1,130 @@
+"""One-line renderings of arbitrary Python values for the tree's right column.
+
+Examples
+--------
+>>> from imgui_debugger.format import fmt_value, type_label
+>>> fmt_value(3.5)
+'3.5'
+>>> type_label([1, 2, 3])
+'list[3]'
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+MAX_STR = 256
+MAX_INLINE = 8
+
+
+def is_container(value) -> bool:
+    """True when a value is a mapping or a non-string sequence.
+
+    Examples
+    --------
+    >>> from imgui_debugger.format import is_container
+    >>> is_container({"a": 1}), is_container("abc"), is_container([1])
+    (True, False, True)
+    """
+    if isinstance(value, Mapping):
+        return True
+    return isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray))
+
+
+def type_label(value) -> str:
+    """The type name, with a length or shape suffix when the value has one.
+
+    Examples
+    --------
+    >>> from imgui_debugger.format import type_label
+    >>> type_label({"a": 1})
+    'dict[1]'
+    >>> type_label(2.0)
+    'float'
+    """
+    name = type(value).__name__
+    shape = getattr(value, "shape", None)
+    if shape is not None and not callable(shape):
+        try:
+            return f"{name}{tuple(shape)}"
+        except TypeError:
+            return name
+    if is_container(value):
+        try:
+            return f"{name}[{len(value)}]"
+        except TypeError:
+            return name
+    return name
+
+
+def fmt_value(value, max_str: int = MAX_STR) -> str:
+    """Format a value as one short line, never raising on a hostile ``__repr__``.
+
+    Parameters
+    ----------
+    value : object
+        Anything.
+    max_str : int
+        Longest string rendered verbatim before truncation.
+
+    Examples
+    --------
+    >>> from imgui_debugger.format import fmt_value
+    >>> fmt_value(None), fmt_value(True), fmt_value(b"ab")
+    ('None', 'True', '<2 bytes>')
+    >>> fmt_value([1, 2, 3])
+    '[1, 2, 3]'
+    """
+    if value is None or isinstance(value, bool):
+        return repr(value)
+    if isinstance(value, str):
+        return repr(value if len(value) <= max_str else value[: max_str - 3] + "...")
+    if isinstance(value, (int, float, complex)):
+        return repr(value)
+    if isinstance(value, (bytes, bytearray)):
+        return f"<{len(value)} bytes>"
+    if hasattr(value, "shape") and hasattr(value, "dtype"):
+        return _fmt_array(value)
+    if isinstance(value, (tuple, list, set, frozenset)):
+        try:
+            if len(value) <= MAX_INLINE and all(
+                isinstance(v, (int, float, bool, str, type(None))) for v in value
+            ):
+                return repr(value)
+            return f"<{type_label(value)}>"
+        except TypeError:
+            return f"<{type(value).__name__}>"
+    if isinstance(value, Mapping):
+        return f"<{type_label(value)}>"
+    if callable(value):
+        return f"<{type(value).__name__} {getattr(value, '__name__', '')}>".replace(" >", ">")
+    return f"<{type(value).__name__}>"
+
+
+def _fmt_array(value) -> str:
+    """Summarize a numpy-like array, inlining only tiny scalar-dtype ones.
+
+    Examples
+    --------
+    >>> import numpy as np                         # doctest: +SKIP
+    >>> _fmt_array(np.zeros((4, 4)))               # doctest: +SKIP
+    '<shape=(4, 4), dtype=float64>'
+    """
+    try:
+        if value.size <= MAX_INLINE and getattr(value.dtype, "kind", "") in "biufcSU":
+            return repr(value.tolist())
+        return f"<shape={tuple(value.shape)}, dtype={value.dtype}>"
+    except Exception:
+        return f"<{type(value).__name__}>"
+
+
+def fmt_error(exc: BaseException) -> str:
+    """Format an exception raised while reading a value.
+
+    Examples
+    --------
+    >>> from imgui_debugger.format import fmt_error
+    >>> fmt_error(ValueError("bad shape"))
+    '<ValueError: bad shape>'
+    """
+    return f"<{type(exc).__name__}: {exc}>"

imgui_debugger/runner.py

@@ -0,0 +1,91 @@
+"""One-shot harness: open the debugger in its own window and block until closed.
+
+Examples
+--------
+>>> from imgui_debugger import run_debugger
+>>> run_debugger({"fs": 9.6, "dz": 5.0})        # doctest: +SKIP
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ._assets import default_ini_path, ensure_assets
+from .debugger import Debugger, DebuggerConfig
+from .theme import to_vec4
+
+
+def run_debugger(
+    target=None,
+    config: Optional[DebuggerConfig] = None,
+    runner_params=None,
+    **kwargs,
+) -> Debugger:
+    """Show the debugger in its own OS window, blocking until it is closed.
+
+    Parameters
+    ----------
+    target : object | None
+        The object to inspect.
+    config : DebuggerConfig | None
+        A prebuilt config; ``target`` and ``kwargs`` override its fields.
+    runner_params : hello_imgui.RunnerParams | None
+        Supply your own params, e.g. a null backend for headless tests. Window
+        title, size and ``.ini`` are filled in from the config only when unset.
+    **kwargs
+        Any :class:`~imgui_debugger.DebuggerConfig` field.
+
+    Returns
+    -------
+    Debugger
+        The widget that was rendered, so its final state can be read back.
+
+    Examples
+    --------
+    >>> from imgui_debugger import run_debugger
+    >>> class Settings:
+    ...     def __init__(self):
+    ...         self.threshold = 0.4
+    >>> run_debugger(Settings(), title="Settings")          # doctest: +SKIP
+    >>> run_debugger({"a": 1}, private=True, editable=False)  # doctest: +SKIP
+    """
+    from imgui_bundle import hello_imgui, immapp
+
+    cfg = config or DebuggerConfig()
+    if target is not None:
+        cfg.target = target
+    for key, value in kwargs.items():
+        if not hasattr(cfg, key):
+            raise TypeError(f"DebuggerConfig has no field {key!r}")
+        setattr(cfg, key, value)
+
+    ensure_assets(cfg.assets_folder)
+    dbg = Debugger(cfg, frame_depth=2)
+
+    params = runner_params if runner_params is not None else hello_imgui.RunnerParams()
+    params.app_window_params.window_title = cfg.window_title or cfg.title or "Debugger"
+    if cfg.window_size:
+        params.app_window_params.window_geometry.size = tuple(cfg.window_size)
+        params.app_window_params.window_geometry.size_auto = False
+    params.app_window_params.resizable = cfg.resizable
+    # hello_imgui resolves ini_filename against the cwd by default, which drops
+    # a layout file wherever the app was launched; pin it to an absolute path.
+    if not params.ini_filename:
+        ini = cfg.ini_path or default_ini_path()
+        params.ini_filename = ini
+        if os.path.isabs(ini):
+            params.ini_folder_type = hello_imgui.IniFolderType.absolute_path
+            parent = os.path.dirname(ini)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+    bg = to_vec4(cfg.theme.bg)
+    params.imgui_window_params.background_color = bg
+    params.callbacks.show_gui = dbg.render
+
+    addons = immapp.AddOnsParams()
+    addons.with_markdown = False
+    addons.with_implot = False
+    addons.with_implot3d = False
+    immapp.run(runner_params=params, add_ons_params=addons)
+    return dbg