better bound values (#95)

Author: tlambert03

magicgui/function_gui.py

@@ -6,7 +6,7 @@
 
 import inspect
 import warnings
-from typing import Any, Callable, Dict, Optional, Sequence, TypeVar, Union, overload
+from typing import Any, Callable, Dict, Optional, TypeVar, Union, overload
 
 from magicgui.application import AppRef
 from magicgui.events import EventEmitter
@@ -46,11 +46,6 @@ class FunctionGui(Container):
         Will be passed to `magic_signature` by default ``None``
     name : str, optional
         A name to assign to the Container widget, by default `function.__name__`
-    bind : dict, optional
-        A mapping of parameter names to values. Values supplied here will be permanently
-        bound to the corresponding parameters: their widgets will be hidden from the GUI
-        and the value will be used for the corresponding parameter when calling the
-        function.
 
     Raises
     ------
@@ -72,10 +67,8 @@ def __init__(
         result_widget: bool = False,
         param_options: Optional[dict] = None,
         name: str = None,
-        bind: Dict[str, Any] = None,
         **kwargs,
     ):
-        bind = bind or dict()
         # consume extra Widget keywords
         extra = set(kwargs) - {"annotation", "gui_only"}
         if extra:
@@ -94,8 +87,6 @@ def __init__(
         self._param_options = param_options
         self.called = EventEmitter(self, type="called")
         self._result_name = ""
-        self._bound: Dict[str, Any] = {}
-        self.bind(bind)
         self._call_count: int = 0
 
         self._call_button: Optional[PushButton] = None
@@ -128,36 +119,6 @@ def reset_call_count(self) -> None:
         """Reset the call count to 0."""
         self._call_count = 0
 
-    def bind(self, kwargs: dict):
-        """Bind key/value pairs to the function signature.
-
-        Values supplied here will be permanently bound to the corresponding parameters:
-        their widgets will be hidden from the GUI and the value will be used for the
-        corresponding parameter when the function is called.
-
-        Parameters
-        ----------
-        kwargs :  dict, optional
-            A mapping of parameter names to values to bind.
-        """
-        self._bound.update(kwargs)
-        for name, value in kwargs.items():
-            getattr(self, name).hide()
-
-    def unbind(self, args: Sequence):
-        """Unbind keys from the function signature.
-
-        Parameters
-        ----------
-        args : sequence
-            A sequence of parameter names.  If any are currently bound to a value, the
-            binding will be cleared and the widget will be shown.
-        """
-        for name in args:
-            if name in self._bound:
-                del self._bound[name]
-                getattr(self, name).show()
-
     def __getattr__(self, value):
         """Catch deprecated _name_changed attribute."""
         if value.endswith("_changed"):
@@ -206,9 +167,7 @@ def __call__(self, *args: Any, **kwargs: Any):
         gui()  # calls the original function with the current parameters
         """
         sig = self.to_signature()
-        _kwargs = self._bound.copy()
-        _kwargs.update(kwargs)
-        bound = sig.bind(*args, **_kwargs)
+        bound = sig.bind(*args, **kwargs)
         bound.apply_defaults()
 
         value = self._function(*bound.args, **bound.kwargs)
@@ -239,8 +198,8 @@ def result_name(self, value: str):
         """Set the result name of this FunctionGui widget."""
         self._result_name = value
 
-    def copy(self, bind=None):
-        """Return a copy of this FunctionGui, with optionally bound arguments."""
+    def copy(self) -> "FunctionGui":
+        """Return a copy of this FunctionGui."""
         return FunctionGui(
             function=self._function,
             call_button=bool(self._call_button),
@@ -250,11 +209,9 @@ def copy(self, bind=None):
             auto_call=self._auto_call,
             result_widget=bool(self._result_widget),
             app=None,
-            bind=bind if bind is not None else self._bound,
         )
 
-    # Cache function guis bound to specific instances
-    _instance_guis: Dict[int, FunctionGui] = {}
+    _bound_instances: Dict[int, FunctionGui] = {}
 
     def __get__(self, obj, objtype=None) -> FunctionGui:
         """Provide descriptor protocol.
@@ -278,11 +235,16 @@ def __get__(self, obj, objtype=None) -> FunctionGui:
         {'self': <__main__.MyClass object at 0x7fb610e455e0>, 'x': 34}
         """
         if obj is not None:
-            if id(obj) not in self._instance_guis:
+            obj_id = id(obj)
+            if obj_id not in self._bound_instances:
                 method = getattr(obj.__class__, self._function.__name__)
-                params_names = list(inspect.signature(method).parameters)
-                self._instance_guis[id(obj)] = self.copy(bind={params_names[0]: obj})
-            return self._instance_guis[id(obj)]
+                p0 = list(inspect.signature(method).parameters)[0]
+                prior, self._param_options = self._param_options, {p0: {"bind": obj}}
+                try:
+                    self._bound_instances[obj_id] = self.copy()
+                finally:
+                    self._param_options = prior
+            return self._bound_instances[obj_id]
         return self
 
     def __set__(self, obj, value):
@@ -328,7 +290,6 @@ def magicgui(
     auto_call: bool = False,
     result_widget: bool = False,
     app: AppRef = None,
-    bind: Dict[str, Any] = None,
     **param_options: dict,
 ):
     """Return a :class:`FunctionGui` for ``function``.
@@ -354,11 +315,6 @@ def magicgui(
         by default False
     app : magicgui.Application or str, optional
         A backend to use, by default ``None`` (use the default backend.)
-    bind : dict, optional
-        A mapping of parameter names to values. Values supplied here will be permanently
-        bound to the corresponding parameters: their widgets will be hidden from the GUI
-        and the value will be used for the corresponding parameter when calling the
-        function.
 
     **param_options : dict of dict
         Any additional keyword arguments will be used as parameter-specific options.
@@ -405,7 +361,6 @@ def inner_func(func: Callable) -> FunctionGui:
             auto_call=auto_call,
             result_widget=result_widget,
             app=app,
-            bind=bind,
         )
         func_gui.__wrapped__ = func
         return func_gui

magicgui/type_map.py

@@ -265,10 +265,12 @@ def register_type(
     """
     type_ = _evaluate_forwardref(type_)
 
-    if not (return_callback or options.get("choices") or widget_type):
+    if not (
+        return_callback or options.get("bind") or options.get("choices") or widget_type
+    ):
         raise ValueError(
-            "At least one of `widget_type`, `choices`, or "
-            "`return_callback` must be provided."
+            "At least one of `widget_type`, `return_callback`, `bind` or `choices` "
+            "must be provided."
         )
 
     if return_callback is not None:
@@ -295,6 +297,11 @@ def register_type(
                 '"widget_type" must be either a string, Widget, or WidgetProtocol'
             )
         _TYPE_DEFS[type_] = (widget_type, _options)
+    elif "bind" in _options:
+        # TODO: make a dedicated hidden widget?
+        # if we're binding a value to this parameter, it doesn't matter what type
+        # of ValueWidget is used... it usually won't be shown
+        _TYPE_DEFS[type_] = (widgets.Label, _options)
 
     return None
 

magicgui/widgets/_bases.py

@@ -394,22 +394,35 @@ def width(self, value: int) -> None:
         self._widget._mgui_set_min_width(value)
 
 
+UNBOUND = object()
+
+
 class ValueWidget(Widget):
     """Widget with a value, Wraps ValueWidgetProtocol.
 
     Parameters
     ----------
     value : Any, optional
         The starting value for the widget, by default ``None``
+    bind : Any, optional
+        A value or callback to bind this widget, then whenever `widget.value` is
+        accessed, the value provided here will be returned.  ``value`` can be a
+        callable, in which case ``value(self)`` will be returned (i.e. your callback
+        must accept a single parameter, which is this widget instance.).
+
     """
 
     _widget: _protocols.ValueWidgetProtocol
     changed: EventEmitter
 
-    def __init__(self, value: Any = None, **kwargs):
+    def __init__(self, value: Any = None, bind: Any = UNBOUND, **kwargs):
+        self._bound_value: Any = bind
+        self._call_bound: bool = True
         super().__init__(**kwargs)
         if value is not None:
             self.value = value
+        if self._bound_value is not UNBOUND and "visible" not in kwargs:
+            self.hide()
 
     def _post_init(self):
         super()._post_init()
@@ -418,10 +431,31 @@ def _post_init(self):
             lambda *x: self.changed(value=x[0] if x else None)
         )
 
+    def get_value(self):
+        """Callable version of `self.value`.
+
+        The main API is to use `self.value`, however, this is here in order to provide
+        an escape hatch if trying to access the widget's value inside of a callback
+        bound to self._bound_value.
+        """
+        return self._widget._mgui_get_value()
+
     @property
     def value(self):
         """Return current value of the widget.  This may be interpreted by backends."""
-        return self._widget._mgui_get_value()
+        if self._bound_value is not UNBOUND:
+            if callable(self._bound_value) and self._call_bound:
+                try:
+                    return self._bound_value(self)
+                except RecursionError as e:
+                    raise RuntimeError(
+                        "RecursionError in callback bound to "
+                        f"<{self.widget_type!r} name={self.name!r}>. If you need to "
+                        "access `widget.value` in your bound callback, use "
+                        "`widget.get_value()`"
+                    ) from e
+            return self._bound_value
+        return self.get_value()
 
     @value.setter
     def value(self, value):
@@ -437,6 +471,38 @@ def __repr__(self) -> str:
         else:
             return f"<Uninitialized {self.widget_type}>"
 
+    def bind(self, value: Any, call: bool = True) -> None:
+        """Binds ``value`` to self.value.
+
+        If a value is bound to this widget, then whenever `widget.value` is accessed,
+        the value provided here will be returned.  ``value`` can be a callable, in which
+        case ``value(self)`` will be returned (i.e. your callback must accept a single
+        parameter, which is this widget instance.).
+
+        If you provide a callable and you *don't* want it to be called (but rather just
+        returned as a callable object, then use ``call=False`` when binding your value.
+
+        Note: if you need to access the "original" ``widget.value`` within your
+        callback, please use ``widget.get_value()`` instead of the ``widget.value``
+        property, in order to avoid a RuntimeError.
+
+        Parameters
+        ----------
+        value : Any
+            The value (or callback) to return when accessing this widget's value.
+        call : bool, optional
+            If ``value`` is a callable and ``call`` is ``True``, the callback will be
+            called as ``callback(self)`` when accessing ``self.value``.  If ``False``,
+            the callback will simply be returned as a callable object, by default,
+            ``True``.
+        """
+        self._call_bound = call
+        self._bound_value = value
+
+    def unbind(self) -> None:
+        """Unbinds any bound values. (see ``ValueWidget.bind``)."""
+        self._bound_value = UNBOUND
+
 
 class ButtonWidget(ValueWidget):
     """Widget with a value, Wraps ButtonWidgetProtocol.
@@ -709,15 +775,15 @@ def _post_init(self):
     @property
     def value(self):
         """Return current value of the widget."""
-        return self._widget._mgui_get_value()
+        return ValueWidget.value.fget(self)  # type: ignore
 
     @value.setter
     def value(self, value):
         if value not in self.choices:
             raise ValueError(
                 f"{value!r} is not a valid choice. must be in {self.choices}"
             )
-        return self._widget._mgui_set_value(value)
+        return ValueWidget.value.fset(self, value)  # type: ignore
 
     @property
     def options(self) -> dict:
@@ -928,7 +994,7 @@ def __getitem__(self, key):  # noqa: F811
             if key < 0:
                 key += len(self)
         item = self._widget._mgui_get_index(key)
-        if not item:
+        if item is None:
             raise IndexError("Container index out of range")
         return getattr(item, "_inner_widget", item)
 
@@ -976,7 +1042,7 @@ def insert(self, key: int, widget: Widget):
             widget.changed.connect(lambda x: self.changed(value=self))
         _widget = widget
 
-        if self.labels:
+        if self.labels and _widget.visible:
             from ._concrete import _LabeledWidget
 
             # no labels for button widgets (push buttons, checkboxes, have their own)