imgui_debugger 0.1.0__py3-none-any.whl

imgui_debugger/search.py

@@ -0,0 +1,170 @@
+"""The tree's filter: a bounded, memoized match over a value and its children.
+
+The walk is capped in width and depth so a multi-megabyte attribute dict cannot
+cost milliseconds per frame, and results are cached for the lifetime of one
+filter string.
+
+Examples
+--------
+>>> from imgui_debugger.search import matches
+>>> matches("metadata", {"fs": 9.6}, "fs")
+True
+>>> matches("metadata", {"fs": 9.6}, "dz")
+False
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+MAX_ITEMS = 64
+MAX_DEPTH = 6
+CACHE_MAX = 4096
+
+_cache: dict = {}
+_cache_filter: str | None = None
+
+
+def clear_cache() -> None:
+    """Drop every memoized match result.
+
+    Examples
+    --------
+    >>> from imgui_debugger.search import clear_cache, matches
+    >>> matches("a", 1, "a")
+    True
+    >>> clear_cache()
+    """
+    global _cache_filter
+    _cache.clear()
+    _cache_filter = None
+
+
+def matches_shallow(name, value, text: str) -> bool:
+    """Whether a name, or a non-container value, contains ``text``.
+
+    Parameters
+    ----------
+    name : object
+        The row label.
+    value : object
+        The row value.
+    text : str
+        Filter text; an empty string matches everything.
+
+    Examples
+    --------
+    >>> from imgui_debugger.search import matches_shallow
+    >>> matches_shallow("frame_rate", 30, "rate")
+    True
+    >>> matches_shallow("frame_rate", 30, "30")
+    True
+    >>> matches_shallow("frame_rate", [30], "30")
+    False
+    """
+    if not text:
+        return True
+    low = text.lower()
+    if low in str(name).lower():
+        return True
+    if isinstance(value, (Mapping, list, tuple)):
+        return False
+    try:
+        return low in str(value).lower()
+    except Exception:
+        return False
+
+
+def matches(name, value, text: str, depth: int = 0) -> bool:
+    """Whether a row or any of its bounded descendants matches ``text``.
+
+    Parameters
+    ----------
+    name : object
+        The row label.
+    value : object
+        The row value.
+    text : str
+        Filter text; an empty string matches everything.
+    depth : int
+        Current recursion depth, used internally.
+
+    Examples
+    --------
+    >>> from imgui_debugger.search import matches
+    >>> matches("arr", {"meta": {"dz": 5}}, "dz")
+    True
+    >>> matches("arr", [1, 2, 3], "2")
+    True
+    >>> matches("arr", "hello", "ell")
+    True
+    """
+    global _cache_filter
+    if not text:
+        return True
+    if text != _cache_filter:
+        _cache.clear()
+        _cache_filter = text
+    key = (str(name), id(value), depth)
+    hit = _cache.get(key)
+    if hit is not None and hit[0] is value:
+        return hit[1]
+    result = _walk(name, value, text, depth)
+    if len(_cache) >= CACHE_MAX:
+        _cache.clear()
+    _cache[key] = (value, result)
+    return result
+
+
+def _walk(name, value, text: str, depth: int) -> bool:
+    """Do the bounded recursive match behind :func:`matches`.
+
+    Examples
+    --------
+    >>> from imgui_debugger.search import _walk
+    >>> _walk("cfg", {"a": {"b": 1}}, "b", 0)
+    True
+    >>> _walk("cfg", {"a": {"b": 1}}, "b", 6)
+    False
+    """
+    if matches_shallow(name, value, text):
+        return True
+    if depth >= MAX_DEPTH:
+        return False
+    if isinstance(value, Mapping):
+        for i, (k, v) in enumerate(value.items()):
+            if i >= MAX_ITEMS:
+                break
+            if matches(k, v, text, depth + 1):
+                return True
+        return False
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        for i, v in enumerate(value):
+            if i >= MAX_ITEMS:
+                break
+            if matches(f"[{i}]", v, text, depth + 1):
+                return True
+    return False
+
+
+def filter_children(children, text: str):
+    """Keep only the rows that match ``text``.
+
+    Parameters
+    ----------
+    children : list[imgui_debugger.scopes.Child]
+        Rows to filter.
+    text : str
+        Filter text; an empty string keeps everything.
+
+    Examples
+    --------
+    >>> from imgui_debugger.scopes import Child
+    >>> from imgui_debugger.search import filter_children
+    >>> rows = [Child("fs", 9.6), Child("dz", 5)]
+    >>> [c.name for c in filter_children(rows, "dz")]
+    ['dz']
+    """
+    if not text:
+        return list(children)
+    return [c for c in children if matches(c.name, c.value, text)]

imgui_debugger/theme.py

@@ -0,0 +1,129 @@
+"""Colors and rounding knobs for the debugger tree.
+
+Examples
+--------
+>>> from imgui_debugger import Theme
+>>> Theme.dark().replace(value=(1.0, 1.0, 1.0, 1.0)).value
+(1.0, 1.0, 1.0, 1.0)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Tuple
+
+from imgui_bundle import imgui
+
+Color = Tuple[float, float, float, float]
+
+
+def to_vec4(color) -> "imgui.ImVec4":
+    """Coerce an ``(r, g, b[, a])`` tuple (or an ImVec4) to ``imgui.ImVec4``.
+
+    Parameters
+    ----------
+    color : tuple | imgui.ImVec4
+        Components in the 0..1 range.
+
+    Examples
+    --------
+    >>> from imgui_debugger import to_vec4
+    >>> to_vec4((1.0, 0.0, 0.0)).w
+    1.0
+    """
+    if isinstance(color, imgui.ImVec4):
+        return color
+    r, g, b = color[0], color[1], color[2]
+    a = color[3] if len(color) > 3 else 1.0
+    return imgui.ImVec4(r, g, b, a)
+
+
+@dataclass(frozen=True)
+class Theme:
+    """Palette for the debugger, one ``(r, g, b, a)`` float tuple per role.
+
+    Examples
+    --------
+    >>> from imgui_debugger import Theme
+    >>> t = Theme.light()
+    >>> t.node != Theme.dark().node
+    True
+    >>> Theme.dark().replace(accent=(1.0, 0.5, 0.0, 1.0)).accent
+    (1.0, 0.5, 0.0, 1.0)
+    """
+
+    bg: Color = (0.11, 0.11, 0.12, 1.0)
+    text: Color = (0.90, 0.90, 0.92, 1.0)
+    text_dim: Color = (0.55, 0.55, 0.58, 1.0)
+    accent: Color = (0.20, 0.50, 0.85, 1.0)
+    border: Color = (0.35, 0.35, 0.37, 0.7)
+    separator: Color = (0.35, 0.35, 0.37, 0.6)
+    frame_bg: Color = (0.18, 0.18, 0.20, 1.0)
+    # tree roles
+    node: Color = (0.40, 0.80, 0.95, 1.0)
+    name: Color = (0.95, 0.80, 0.30, 1.0)
+    index: Color = (0.60, 0.95, 0.40, 1.0)
+    value: Color = (0.85, 0.85, 0.85, 1.0)
+    prop: Color = (0.70, 0.75, 1.00, 1.0)
+    cls: Color = (0.85, 0.65, 1.00, 1.0)
+    local: Color = (0.95, 0.80, 0.30, 1.0)
+    glob: Color = (0.55, 0.85, 0.80, 1.0)
+    runtime: Color = (0.90, 0.60, 0.40, 1.0)
+    error: Color = (0.95, 0.40, 0.40, 1.0)
+    changed: Color = (1.00, 0.85, 0.35, 1.0)
+    frame_rounding: float = 4.0
+    child_rounding: float = 4.0
+
+    @staticmethod
+    def dark() -> "Theme":
+        """The default dark palette.
+
+        Examples
+        --------
+        >>> from imgui_debugger import Theme
+        >>> Theme.dark() == Theme()
+        True
+        """
+        return Theme()
+
+    @staticmethod
+    def light() -> "Theme":
+        """A light palette with the same role names.
+
+        Examples
+        --------
+        >>> from imgui_debugger import Theme
+        >>> Theme.light().bg[0] > 0.5
+        True
+        """
+        return Theme(
+            bg=(0.94, 0.94, 0.95, 1.0),
+            text=(0.10, 0.10, 0.12, 1.0),
+            text_dim=(0.42, 0.42, 0.46, 1.0),
+            accent=(0.10, 0.45, 0.80, 1.0),
+            border=(0.70, 0.70, 0.74, 0.9),
+            separator=(0.70, 0.70, 0.74, 0.6),
+            frame_bg=(0.88, 0.88, 0.90, 1.0),
+            node=(0.05, 0.40, 0.60, 1.0),
+            name=(0.55, 0.38, 0.05, 1.0),
+            index=(0.15, 0.45, 0.10, 1.0),
+            value=(0.18, 0.18, 0.20, 1.0),
+            prop=(0.25, 0.30, 0.65, 1.0),
+            cls=(0.45, 0.20, 0.60, 1.0),
+            local=(0.55, 0.38, 0.05, 1.0),
+            glob=(0.10, 0.45, 0.42, 1.0),
+            runtime=(0.65, 0.35, 0.10, 1.0),
+            error=(0.75, 0.15, 0.15, 1.0),
+            changed=(0.60, 0.42, 0.00, 1.0),
+        )
+
+    def replace(self, **changes) -> "Theme":
+        """Return a copy with the given fields overridden.
+
+        Examples
+        --------
+        >>> from imgui_debugger import Theme
+        >>> Theme.dark().replace(name=(1.0, 0.0, 0.0, 1.0)).name
+        (1.0, 0.0, 0.0, 1.0)
+        """
+        return replace(self, **changes)

imgui_debugger/tree.py

@@ -0,0 +1,285 @@
+"""The collapsible tree: one scope header per root, one row per value below it.
+
+Examples
+--------
+>>> from imgui_debugger.tree import TreeStyle
+>>> TreeStyle(filter="fs").filter
+'fs'
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from imgui_bundle import imgui
+
+from .edit import can_edit, edit_value
+from .format import fmt_error, fmt_value, type_label
+from .scopes import Child, Scope, children_of, has_children
+from .search import filter_children, matches
+from .theme import Theme, to_vec4
+
+ROLE_COLORS = {
+    "attr": "name",
+    "prop": "prop",
+    "class": "cls",
+    "item": "name",
+    "index": "index",
+    "local": "local",
+    "global": "glob",
+    "runtime": "runtime",
+    "error": "error",
+}
+
+
+@dataclass(frozen=True)
+class TreeStyle:
+    """Everything the row renderer needs besides the rows themselves.
+
+    Parameters
+    ----------
+    theme : Theme
+        Palette.
+    filter : str
+        Case-insensitive filter; empty shows everything.
+    editable : bool
+        Draw inline editors for writable leaves.
+    private : bool
+        Expand ``_name`` attributes of nested values.
+    properties : bool
+        Expand ``property`` descriptors of nested values.
+    max_depth : int
+        Deepest level expanded before a row is shown as a summary only.
+    max_items : int
+        Rows rendered per container before a "+N more" line.
+    value_col : float
+        Pixel column the value is drawn at; ``0`` packs it after the name.
+    force_open : bool | None
+        For one frame, expand (True) or collapse (False) every node.
+
+    Examples
+    --------
+    >>> from imgui_debugger.tree import TreeStyle
+    >>> from imgui_debugger import Theme
+    >>> TreeStyle(theme=Theme.light(), value_col=220.0).value_col
+    220.0
+    """
+
+    theme: Theme = field(default_factory=Theme.dark)
+    filter: str = ""
+    editable: bool = True
+    private: bool = False
+    properties: bool = True
+    max_depth: int = 8
+    max_items: int = 200
+    value_col: float = 0.0
+    force_open: Optional[bool] = None
+
+
+def role_color(style: TreeStyle, kind: str):
+    """The theme color a row of the given kind is drawn in.
+
+    Parameters
+    ----------
+    style : TreeStyle
+        Active style.
+    kind : str
+        A :class:`~imgui_debugger.scopes.Child` kind, or a theme field name.
+
+    Examples
+    --------
+    >>> from imgui_debugger.tree import TreeStyle, role_color
+    >>> role_color(TreeStyle(), "index") == TreeStyle().theme.index
+    True
+    """
+    name = ROLE_COLORS.get(kind, kind)
+    return getattr(style.theme, name, style.theme.name)
+
+
+def draw_value(child: Child, path: str, style: TreeStyle) -> None:
+    """Draw a leaf's value, as an editor when it is writable and editable.
+
+    Parameters
+    ----------
+    child : Child
+        The row.
+    path : str
+        Dotted path, used as the imgui id.
+    style : TreeStyle
+        Active style.
+
+    Examples
+    --------
+    >>> from imgui_debugger.scopes import Child
+    >>> from imgui_debugger.tree import TreeStyle, draw_value
+    >>> draw_value(Child("fs", 9.6), "arr.fs", TreeStyle())   # doctest: +SKIP
+    """
+    if style.value_col > 0:
+        imgui.same_line(style.value_col)
+    else:
+        imgui.same_line(spacing=16)
+    if child.kind == "error":
+        imgui.text_colored(to_vec4(style.theme.error), fmt_error(child.value))
+        return
+    if style.editable and child.editable and can_edit(child.value):
+        edit_value(path, child.value, child.setter, style.theme)
+        return
+    imgui.text_colored(to_vec4(style.theme.value), fmt_value(child.value))
+    if imgui.is_item_hovered():
+        imgui.set_tooltip(f"{path}\n{type_label(child.value)}")
+
+
+def draw_child(child: Child, prefix: str, depth: int, style: TreeStyle) -> None:
+    """Draw one row, recursing into its children when it expands.
+
+    Parameters
+    ----------
+    child : Child
+        The row.
+    prefix : str
+        Dotted path of the parent, ``""`` at a scope root.
+    depth : int
+        Current depth, compared against ``style.max_depth``.
+    style : TreeStyle
+        Active style.
+
+    Examples
+    --------
+    >>> from imgui_debugger.scopes import Child
+    >>> from imgui_debugger.tree import TreeStyle, draw_child
+    >>> draw_child(Child("md", {"fs": 9.6}), "", 0, TreeStyle())   # doctest: +SKIP
+    """
+    path = f"{prefix}{child.name}" if child.name.startswith("[") else f"{prefix}.{child.name}"
+    path = path.lstrip(".")
+    color = role_color(style, child.kind)
+    expandable = (
+        child.kind != "error"
+        and depth < style.max_depth
+        and has_children(child.value, style.private, style.properties)
+    )
+
+    if not expandable:
+        imgui.text_colored(to_vec4(color), child.name)
+        draw_value(child, path, style)
+        return
+
+    if style.force_open is not None:
+        imgui.set_next_item_open(style.force_open)
+    imgui.push_style_color(imgui.Col_.text, to_vec4(style.theme.node))
+    open_ = imgui.tree_node(f"{child.name}##{path}")
+    imgui.pop_style_color()
+    if imgui.is_item_hovered():
+        imgui.set_tooltip(f"{path}\n{type_label(child.value)}")
+    imgui.same_line(style.value_col if style.value_col > 0 else 0.0)
+    imgui.text_colored(to_vec4(style.theme.text_dim), type_label(child.value))
+    if not open_:
+        return
+    try:
+        rows = children_of(child.value, style.private, style.properties, style.max_items + 1)
+    except Exception as exc:
+        imgui.text_colored(to_vec4(style.theme.error), fmt_error(exc))
+        imgui.tree_pop()
+        return
+    draw_children(rows, path, depth + 1, style)
+    imgui.tree_pop()
+
+
+def draw_children(rows, prefix: str, depth: int, style: TreeStyle) -> None:
+    """Draw a list of rows, filtered and capped at ``style.max_items``.
+
+    Parameters
+    ----------
+    rows : list[Child]
+        Rows to draw.
+    prefix : str
+        Dotted path of the parent.
+    depth : int
+        Current depth.
+    style : TreeStyle
+        Active style.
+
+    Examples
+    --------
+    >>> from imgui_debugger.scopes import Child
+    >>> from imgui_debugger.tree import TreeStyle, draw_children
+    >>> draw_children([Child("n", 1)], "cfg", 1, TreeStyle())   # doctest: +SKIP
+    """
+    shown = filter_children(rows, style.filter)
+    for child in shown[: style.max_items]:
+        draw_child(child, prefix, depth, style)
+    hidden = len(shown) - style.max_items
+    if hidden > 0:
+        imgui.text_disabled(f"... +{hidden} more")
+
+
+def draw_scope(scope: Scope, style: TreeStyle) -> str:
+    """Draw one scope header and its rows, returning the scope name.
+
+    Parameters
+    ----------
+    scope : Scope
+        The scope to draw.
+    style : TreeStyle
+        Active style.
+
+    Returns
+    -------
+    str
+        ``scope.name``, so a caller can key per-scope state off the return.
+
+    Examples
+    --------
+    >>> from imgui_debugger.scopes import Scope, Child
+    >>> from imgui_debugger.tree import TreeStyle, draw_scope
+    >>> s = Scope("counters", lambda: [Child("frames", 1)])
+    >>> draw_scope(s, TreeStyle())      # doctest: +SKIP
+    'counters'
+    """
+    try:
+        rows = scope.children()
+    except Exception as exc:
+        imgui.text_colored(to_vec4(style.theme.error), f"{scope.name}: {fmt_error(exc)}")
+        return scope.name
+    shown = filter_children(rows, style.filter)
+    if style.filter and not shown:
+        return scope.name
+
+    if style.force_open is not None:
+        imgui.set_next_item_open(style.force_open)
+    elif style.filter:
+        imgui.set_next_item_open(True)
+    else:
+        imgui.set_next_item_open(scope.start_open, imgui.Cond_.first_use_ever)
+    imgui.push_style_color(imgui.Col_.text, to_vec4(role_color(style, scope.role)))
+    open_ = imgui.collapsing_header(f"{scope.name}##scope_{scope.name}")
+    imgui.pop_style_color()
+    if scope.hint and imgui.is_item_hovered():
+        imgui.set_tooltip(scope.hint)
+    imgui.same_line()
+    imgui.text_disabled(f"({len(shown)})")
+    if open_:
+        imgui.indent()
+        draw_children(shown, scope.name, 1, style)
+        imgui.unindent()
+    return scope.name
+
+
+def row_matches(child: Child, text: str) -> bool:
+    """Whether one row survives the filter, children included.
+
+    Parameters
+    ----------
+    child : Child
+        The row.
+    text : str
+        Filter text.
+
+    Examples
+    --------
+    >>> from imgui_debugger.scopes import Child
+    >>> from imgui_debugger.tree import row_matches
+    >>> row_matches(Child("md", {"fs": 9.6}), "fs")
+    True
+    """
+    return matches(child.name, child.value, text)