meltygui 0.1.0__py3-none-any.whl

meltygui/core/conversion/cache_tree.py

@@ -0,0 +1,188 @@
+from meltygui.code.fileref import Address
+
+
+class _Unset:
+    """Sentinel indicating a step hasn't produced a real value yet."""
+    def __repr__(self):
+        return "UNSET_VALUE"
+
+UNSET_VALUE = _Unset()
+
+# Types safe for early cutoff equality comparison
+_CUTOFF_TYPES = {Address, str, int, float, bool, tuple, bytes, frozenset}
+
+def register_cutoff_type(*types):
+    """Register types as safe for early cutoff equality comparison."""
+    _CUTOFF_TYPES.update(types)
+
+
+class CacheNode:
+    def __init__(self, type_key):
+        self.type_key = type_key
+        self.value = UNSET_VALUE
+        self.children = []
+        self._child_cursor = 0
+
+    def __repr__(self):
+        kids = [c.type_key for c in self.children]
+        return f"CacheNode({self.type_key}, value={self.value!r}, children={kids})"
+
+
+class CacheTree:
+    """
+    Tree-shaped cache that auto-shares nodes for symmetric type sequences.
+    Types are inferred from output values.
+
+    Builds progressively — UNSET positions are filled in on later walks.
+    Handles type changes by replacing nodes and invalidating subtrees.
+    """
+
+    def __init__(self):
+        self._root = CacheNode("__root__")
+        self._mapping = []
+        self._stack = None
+        self._cursor = 0
+
+    def begin(self):
+        """Reset cursors for a new walk."""
+        self._cursor = 0
+        self._stack = [self._root]
+        self._reset_child_cursors(self._root)
+
+    def step(self, changed, value):
+        """
+        Advance one position. Returns (changed, cached_value).
+
+        Early cutoff: if a step re-executes but produces the same result
+        as what's cached, changed is flipped to False — stopping propagation.
+        """
+        if value is UNSET_VALUE or value is None:
+            return self._step_unset()
+
+        type_key = type(value).__name__
+        node = self._resolve(type_key)
+
+        # Check if mapping changed at this position
+        if self._cursor < len(self._mapping):
+            old_node = self._mapping[self._cursor]
+            if old_node is not node:
+                if old_node is not None:
+                    self._clear(old_node)
+                self._mapping[self._cursor] = node
+        else:
+            self._mapping.append(node)
+
+        if changed or node.value is UNSET_VALUE:
+            node.value = value
+
+        self._cursor += 1
+        return node.value
+
+    def _step_unset(self):
+        """Handle an UNSET_VALUE step."""
+        if self._cursor < len(self._mapping) and self._mapping[self._cursor] is not None:
+            # Replay old type through stack to keep it consistent
+            old_node = self._mapping[self._cursor]
+            self._resolve(old_node.type_key)
+            self._cursor += 1
+            return old_node.value
+        else:
+            # No prior mapping - can't resolve, leave placeholder
+            if self._cursor >= len(self._mapping):
+                self._mapping.append(None)
+            self._cursor += 1
+            return UNSET_VALUE
+
+    def peek(self):
+        """Return the cached value at the current cursor without advancing."""
+        if self._cursor < len(self._mapping):
+            node = self._mapping[self._cursor]
+            if node is not None:
+                return node.value
+        return UNSET_VALUE
+
+    def end(self):
+        """End of walk. Stack is rebuilt each begin(), nothing to finalize."""
+        self._stack = None
+
+    def _resolve(self, type_key):
+        current = self._stack[-1]
+
+        # Same as current → stay at this level
+        if current.type_key == type_key:
+            return current
+
+        # Parent matches → pop back up (reuse node)
+        if len(self._stack) > 1 and self._stack[-2].type_key == type_key:
+            self._stack.pop()
+            return self._stack[-1]
+
+        # Push - check existing children first
+        child_idx = current._child_cursor
+        if child_idx < len(current.children):
+            existing = current.children[child_idx]
+            if existing.type_key == type_key:
+                # Reuse existing child
+                current._child_cursor += 1
+                self._stack.append(existing)
+                return existing
+            else:
+                # Type changed - replace child, invalidate its subtree
+                self._clear(existing)
+                new_child = CacheNode(type_key)
+                current.children[child_idx] = new_child
+                current._child_cursor += 1
+                self._stack.append(new_child)
+                return new_child
+        else:
+            # New child
+            child = CacheNode(type_key)
+            current.children.append(child)
+            current._child_cursor += 1
+            self._stack.append(child)
+            return child
+
+    def _reset_child_cursors(self, node):
+        node._child_cursor = 0
+        for child in node.children:
+            self._reset_child_cursors(child)
+
+    def node_at(self, index):
+        return self._mapping[index]
+
+    def invalidate(self):
+        self._clear(self._root)
+
+    def _clear(self, node):
+        node.value = UNSET_VALUE
+        for child in node.children:
+            self._clear(child)
+
+    def print_tree(self, node=None, indent=0):
+        if node is None:
+            node = self._root
+        prefix = "  " * indent
+        print(f"{prefix}{node.type_key}: {node.value!r}")
+        for child in node.children:
+            self.print_tree(child, indent + 1)
+
+    def print_mapping(self, labels=None):
+        for i, node in enumerate(self._mapping):
+            label = labels[i] if labels else str(i)
+            if node is None:
+                print(f"  [{i}] {label:>15} → (unset)")
+            else:
+                print(f"  [{i}] {label:>15} → {node.type_key} (id={id(node):#x})")
+
+    def get_mapping_as_str(self, labels=None):
+        lines = []
+        for i, node in enumerate(self._mapping):
+            label = labels[i] if labels else str(i)
+            if node is None:
+                lines.append(f"  [{i}] {label:>15} → (unset)")
+            else:
+                lines.append(f"  [{i}] {label:>15} → {node.type_key} (id={id(node):#x})")
+        return "\n".join(lines)
+
+    def __len__(self):
+        return len(self._mapping)

meltygui/core/conversion/chain.py

@@ -0,0 +1,113 @@
+"""
+Chain executor for the unified render pipeline.
+
+A chain is a flat list of @render_func nodes.  Data flows left to right:
+
+    [cls_to_cst, cst_to_dict, draw_collection, dict_to_cst, cst_to_cls]
+     load side ──────────────> render <────────────── save side
+
+Every node has the same calling convention:
+    changed, value = func(input_value, **kwargs)
+
+The executor walks the chain, passing the output of each node as the
+input to the next.  Nodes that haven't changed return cached results
+instantly.  The chain stops propagating when a node returns changed=False
+(no downstream work needed), UNLESS the node has never run (first frame).
+
+Usage:
+    draw_any(my_class, chain=[cls_to_cst, cst_to_dict, draw_collection,
+                               dict_to_cst, cst_to_cls])
+"""
+
+from meltygui.core.conversion.path_finder import Pending
+
+
+def _step(func, value, **kwargs):
+    """Execute one chain node.  Returns (changed, value, func_name)."""
+    result = func(value, **kwargs)
+
+    if isinstance(result, tuple) and len(result) == 2:
+        changed, value = result
+    else:
+        changed = False
+        value = result
+
+    name = getattr(func, '__name__', None) or getattr(func, '__qualname__', repr(func))
+    return changed, value, name
+
+
+# Nodes a real user edit flows through. If a chain ends changed=True and NONE
+# of these returned True, the change came from converters alone - exactly the
+# "round-trip mutated state on its own" case we want to surface. Loose by name
+# (matches whatever render_func wrappers expose) and overinclusive on purpose:
+# false-positets are worse than the occasional missed case.
+_INTERACTION_NODES = frozenset({
+    "focus", "draw_collection", "draw_tuple", "draw_text", "button",
+    "draw_int", "draw_str", "draw_float", "draw_bool", "draw_enum_tabs",
+    "draw_dropdown", "draw_tuple_float",
+})
+
+
+def run_chain(chain, input_value, **kwargs):
+    """Execute a chain of render_func nodes left to right.
+
+    Each node is called as: changed, value = node(value, **kwargs)
+
+    Returns (changed, value) — the output of the last node that ran.
+
+    Propagation rules:
+      - A node always runs if it has never produced a result (first frame).
+      - After first frame, a node runs only if upstream returned changed=True.
+      - If a node returns a Pending, the chain stops and returns the Pending.
+    """
+    value = input_value
+    changed = True  # first frame always runs
+
+    trace = []  # (name, changed_returned, value_type) - for round-trip diagnostics
+
+    for func in chain:
+        if not changed:
+            break
+
+        changed, value, name = _step(func, value, **kwargs)
+        trace.append((name, changed, type(value).__name__))
+
+        # Pending stops the chain: downstream can't run without data
+        if isinstance(value, Pending):
+            return False, value
+
+    # ── Round-trip change detection ──────────────────────────────────────────
+    # The chain ends changed=True iff a save-side node will (or might, via the
+    # save_pending latch) write back. A real user edit always flows through an
+    # interaction node (focus, the picker, etc.). If we get here with changed=True
+    # but no interaction node returned True, only converters did - meaning a
+    # round-trip mutated the value on its own. Logs only, behavior unchanged.
+    if changed:
+        interaction_fired = any(
+            ch and n in _INTERACTION_NODES for n, ch, _ in trace)
+        if not interaction_fired:
+            converter_changes = [(n, vt) for n, ch, vt in trace if ch]
+            if converter_changes:
+                _log_round_trip_change(trace, converter_changes, kwargs)
+
+    return changed, value
+
+
+def _log_round_trip_change(trace, converter_changes, kwargs):
+    """Dump a prominent record of a converter-only changed=True flow."""
+    import sys
+    ds = kwargs.get("draw_state")
+    ds_id = getattr(ds, "id", None) or getattr(ds, "_tile_id", None)
+    ds_name = getattr(ds, "name", None)
+    marked = "  →  ".join(
+        (f"\033[91m{n}*\033[0m" if ch else n) for n, ch, _ in trace)
+    print(
+        f"\n\033[93;1m[CHAIN ROUND-TRIP CHANGE — no user input]\033[0m "
+        f"chain returned changed=True with no interaction node firing.",
+        file=sys.stderr)
+    print(f"  draw_state: name={ds_name!r} id={ds_id}", file=sys.stderr)
+    print(f"  trace (* = node returned changed=True):", file=sys.stderr)
+    print(f"    {marked}", file=sys.stderr)
+    print(f"  suspect converters: "
+          f"{[n for n, _ in converter_changes]}", file=sys.stderr)
+    print(f"  → a downstream save may fire without user input", file=sys.stderr)

meltygui/core/conversion/converter_register.py

@@ -0,0 +1,145 @@
+"""
+Converter decorator.  Threads apply and cache_id through all converters.
+
+    @converter(registry=Melty)
+    def str_to_module(value: str) -> cst.Module:
+        return cst.parse_module(value)
+
+All registered converters accept (value, apply=False, cache_id=None)
+regardless of original signature.  The decorator absorbs extra kwargs
+for simple converters and passes them through for load/save wrappers.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any
+
+
+def _fn_accepts(fn, param_name: str) -> bool:
+    """Check if fn accepts a given parameter."""
+    if getattr(fn, f"_accepts_{param_name}", False):
+        return True
+    try:
+        return param_name in inspect.signature(fn).parameters
+    except (ValueError, TypeError):
+        return False
+
+
+def converter(converter_fn=None, registry: Any = None, *,
+              from_type: type | None = None,
+              to_type: type | None = None,
+              load_data=None,
+              save_data=None,
+              **kwargs):
+    if converter_fn is None:
+        return lambda fn: converter(
+            fn, registry,
+            from_type=from_type, to_type=to_type,
+            load_data=load_data, save_data=save_data,
+            **kwargs
+        )
+
+    # ── Infer types from signature ──────────────────────────────────
+
+    func_signature = inspect.signature(converter_fn)
+    fn_params = func_signature.parameters
+
+    inferred_to = func_signature.return_annotation
+    if inferred_to is inspect.Signature.empty:
+        inferred_to = None
+    if inferred_to is not None and hasattr(inferred_to, "__args__"):
+        inferred_to = inferred_to.__args__[0]
+
+    inferred_from = None
+    for param_name in ("value", "data"):
+        param = fn_params.get(param_name)
+        if param is not None and param.annotation is not inspect.Parameter.empty:
+            inferred_from = param.annotation
+            break
+
+    actual_from = from_type or inferred_from
+    actual_to = to_type or inferred_to
+
+    # ── Wrap with load/save if needed ───────────────────────────────
+
+    wrapped_fn = converter_fn
+
+    if load_data is not None:
+        if actual_from is None:
+            raise TypeError(
+                f"Converter {converter_fn.__name__} with load_data requires from_type=")
+        from meltygui.code.fileref import make_load_wrapper
+        wrapped_fn = make_load_wrapper(converter_fn, load_data, actual_from)
+
+    if save_data is not None:
+        if actual_to is None:
+            raise TypeError(
+                f"Converter {converter_fn.__name__} with save_data requires to_type=")
+        from meltygui.code.fileref import make_save_wrapper
+        load_cache = None
+        inverse_fn = kwargs.get("inverse_of")
+        if inverse_fn is not None and hasattr(inverse_fn, "_local_cache"):
+            load_cache = inverse_fn._local_cache
+        wrapped_fn = make_save_wrapper(converter_fn, save_data, actual_to,
+                                       load_cache=load_cache)
+
+    # ── Normalize args: all converters accept (value, apply, cache_id) ──
+
+    has_apply = _fn_accepts(wrapped_fn, "apply")
+    has_cache_id = _fn_accepts(wrapped_fn, "cache_id")
+
+    if not has_apply or not has_cache_id:
+        inner = wrapped_fn
+
+        @functools.wraps(inner)
+        def _normalized(value, apply=False, cache_id=None):
+            kw = {}
+            if has_apply:
+                kw["apply"] = apply
+            if has_cache_id:
+                kw["cache_id"] = cache_id
+            return inner(value, **kw)
+
+        _normalized._accepts_apply = True
+        _normalized._accepts_cache_id = True
+        # Preserve wrapper attributes
+        for attr in ("_watched_from_type", "_watched_to_type", "_local_cache"):
+            if hasattr(inner, attr):
+                setattr(_normalized, attr, getattr(inner, attr))
+        wrapped_fn = _normalized
+
+    # ── Register ────────────────────────────────────────────────────
+
+    if not hasattr(registry, '_converters') or not isinstance(registry._converters, dict):
+        setattr(registry, '_converters', {})
+
+    if actual_from is not None and actual_to is not None:
+        registry._converters[(actual_from, actual_to)] = wrapped_fn
+
+    if hasattr(registry, "_converter_to_type") and isinstance(registry._converter_to_type, dict):
+        registry._converter_to_type[wrapped_fn] = (actual_from, actual_to)
+
+    # ── Store flags ─────────────────────────────────────────────────
+
+    if hasattr(registry, 'converter_flags_by_type') and isinstance(registry.converter_flags_by_type, dict):
+        if kwargs:
+            registry.converter_flags_by_type[(actual_from, actual_to)] = kwargs
+
+    if hasattr(registry, 'converter_flags') and isinstance(registry.converter_flags, dict):
+        if kwargs:
+            registry.converter_flags[wrapped_fn] = kwargs
+            if "inverse_of" in kwargs:
+                inverse_fn = kwargs["inverse_of"]
+                if inverse_fn not in registry.converter_flags:
+                    registry.converter_flags[inverse_fn] = {}
+                registry.converter_flags[inverse_fn]["inverse_of"] = wrapped_fn
+
+    if load_data is not None:
+        if hasattr(registry, 'converter_flags') and isinstance(registry.converter_flags, dict):
+            if wrapped_fn not in registry.converter_flags:
+                registry.converter_flags[wrapped_fn] = {}
+            registry.converter_flags[wrapped_fn]["stateful"] = True
+
+    return wrapped_fn

meltygui/core/conversion/data_decoration.py

@@ -0,0 +1,67 @@
+from dataclasses import dataclass, field, MISSING, make_dataclass
+import types
+from typing import Any
+
+# Types considered safe to use as constants (not recreated per instance)
+IMMUTABLES = (int, float, str, bool, type(None), bytes, tuple, frozenset)
+
+def data(_cls=None, **dc_kwargs):
+    """
+    A decorator that works like @dataclass, but ensures that
+    all defaults are re-evaluated for every new instance.
+
+    Behavior:
+      - Immutable defaults (int, str, bool, None, tuple, etc.) are kept as-is.
+      - Mutable defaults ([], {}, set()) are turned into default_factory calls.
+      - Callable defaults (like list, dict, or a user function) are used as factories.
+      - Function call results (e.g. id = generate_id()) are re-executed for each instance.
+    """
+
+    def wrap(cls):
+        annotations = getattr(cls, "__annotations__", {})
+        new_fields = []
+
+        for name, typ in annotations.items():
+            default = getattr(cls, name, MISSING)
+
+            if default is MISSING:
+                # Field without a default
+                new_fields.append((name, typ))
+            else:
+                if isinstance(default, IMMUTABLES):
+                    # Safe to use as a constant default
+                    new_fields.append((name, typ, default))
+
+                elif isinstance(default, (list, dict, set)):
+                    # Dangerous mutable literal: replace with factory
+                    new_fields.append(
+                        (name, typ, field(default_factory=default.__class__))
+                    )
+
+                elif isinstance(default, types.FunctionType):
+                    # A function type was provided: use it as default_factory
+                    new_fields.append((name, typ, field(default_factory=default)))
+
+                else:
+                    # A computed value (like generate_id())
+                    # We capture the original function by closure
+                    def factory(val=default):
+                        # If value looks callable (like generate_id()), re-call
+                        if callable(val):
+                            return val()
+                        # Else try to copy/recreate it
+                        return type(val)(val)
+
+                    new_fields.append((name, typ, field(default_factory=factory)))
+
+        # Rebuild dataclass with new defaults
+        new_cls = make_dataclass(
+            cls.__name__,
+            new_fields,
+            bases=cls.__bases__,
+            namespace=dict(cls.__dict__),
+            **dc_kwargs
+        )
+        return new_cls
+
+    return wrap if _cls is None else wrap(_cls)