pyobs-gui 2.3.1__tar.gz → 2.4.0__tar.gz

{pyobs_gui-2.3.1 → pyobs_gui-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyobs-gui
-Version: 2.3.1
+Version: 2.4.0
 Summary: A remote GUI for pyobs
 Author-email: Tim-Oliver Husser <thusser@uni-goettingen.de>
 License-Expression: MIT

{pyobs_gui-2.3.1 → pyobs_gui-2.4.0}/pyobs_gui/structuredconfigwidget.py

@@ -29,15 +29,48 @@ class _FieldEditor:
     set_value: Callable[[ConfigValue], None]
     children: Optional[Dict[str, "_FieldEditor"]] = None
     level: AccessLevel = AccessLevel.BASIC
-
-
-def _collect_by_level(editor: "_FieldEditor", level: AccessLevel) -> List[QtWidgets.QWidget]:
-    """Recursively gather every editor widget (including nested-object children) tagged at
-    exactly the given level, for the basic/expert toggle to enable/disable as a group."""
-    widgets = [editor.widget] if editor.level == level else []
+    # the row's label, so the basic/expert toggle can hide it alongside `display_widget` --
+    # addRow(str, widget) auto-creates one, but we build it explicitly at each row-adding call
+    # site instead so we have a handle on it (QFormLayout.labelForField exists but is keyed
+    # per-layout-instance, awkward to thread through recursion; a direct reference is simpler)
+    row_label: Optional[QtWidgets.QLabel] = None
+    # set only when the field has a description: a small container with `widget` on top and the
+    # description label below it. `widget` itself (get_value/set_value's target) never changes
+    # shape, so a description doesn't affect how values round-trip -- only what goes in the row.
+    row_widget: Optional[QtWidgets.QWidget] = None
+
+    @property
+    def display_widget(self) -> QtWidgets.QWidget:
+        return self.row_widget if self.row_widget is not None else self.widget
+
+
+def _collect_by_level(editor: "_FieldEditor", level: AccessLevel) -> List["_FieldEditor"]:
+    """Recursively gather every editor (including nested-object children) tagged at exactly the
+    given level, for the basic/expert toggle to show/hide as a group."""
+    editors = [editor] if editor.level == level else []
     for child in (editor.children or {}).values():
-        widgets.extend(_collect_by_level(child, level))
-    return widgets
+        editors.extend(_collect_by_level(child, level))
+    return editors
+
+
+def _wrap_with_description(widget: QtWidgets.QWidget, description: Optional[str]) -> Optional[QtWidgets.QWidget]:
+    """Stack `widget` over a dimmed, word-wrapped description label, for the field's row to show
+    the description below the input rather than only as e.g. a tooltip. Returns None (meaning:
+    just use `widget` directly, no wrapping) when there's no description."""
+    if not description:
+        return None
+    container = QtWidgets.QWidget()
+    layout = QtWidgets.QVBoxLayout(container)
+    layout.setContentsMargins(0, 0, 0, 0)
+    layout.setSpacing(2)
+    layout.addWidget(widget)
+    description_label = QtWidgets.QLabel(description)
+    description_label.setWordWrap(True)
+    # palette(mid) is a 3D-effect shade (borders/shadows), too dark to read comfortably as text;
+    # placeholder-text is Qt's actual semantic role for secondary-but-legible text
+    description_label.setStyleSheet("color: palette(placeholder-text);")
+    layout.addWidget(description_label)
+    return container
 
 
 def _nested_get(children: Dict[str, _FieldEditor]) -> Dict[str, ConfigValue]:
@@ -60,9 +93,13 @@ def _build_editor(name: str, schema: ConfigFieldSchema, on_change: Callable[[],
         if schema.default is not None:
             line_edit.setText(str(schema.default))
         line_edit.textChanged.connect(lambda _: on_change())
-        if schema.level == AccessLevel.EXPERT:
-            line_edit.setEnabled(False)
-        return _FieldEditor(line_edit, line_edit.text, lambda value: line_edit.setText(str(value)), level=schema.level)
+        return _FieldEditor(
+            line_edit,
+            line_edit.text,
+            lambda value: line_edit.setText(str(value)),
+            level=schema.level,
+            row_widget=_wrap_with_description(line_edit, schema.description),
+        )
 
     if schema.type == "int":
         spin_box = QtWidgets.QSpinBox()
@@ -70,10 +107,12 @@ def _build_editor(name: str, schema: ConfigFieldSchema, on_change: Callable[[],
         if schema.default is not None:
             spin_box.setValue(int(schema.default))
         spin_box.valueChanged.connect(lambda _: on_change())
-        if schema.level == AccessLevel.EXPERT:
-            spin_box.setEnabled(False)
         return _FieldEditor(
-            spin_box, spin_box.value, lambda value: spin_box.setValue(int(cast("int", value))), level=schema.level
+            spin_box,
+            spin_box.value,
+            lambda value: spin_box.setValue(int(cast("int", value))),
+            level=schema.level,
+            row_widget=_wrap_with_description(spin_box, schema.description),
         )
 
     if schema.type == "float":
@@ -85,13 +124,12 @@ def _build_editor(name: str, schema: ConfigFieldSchema, on_change: Callable[[],
         if schema.default is not None:
             double_spin_box.setValue(float(schema.default))
         double_spin_box.valueChanged.connect(lambda _: on_change())
-        if schema.level == AccessLevel.EXPERT:
-            double_spin_box.setEnabled(False)
         return _FieldEditor(
             double_spin_box,
             double_spin_box.value,
             lambda value: double_spin_box.setValue(float(cast("float", value))),
             level=schema.level,
+            row_widget=_wrap_with_description(double_spin_box, schema.description),
         )
 
     if schema.type == "bool":
@@ -99,10 +137,12 @@ def _build_editor(name: str, schema: ConfigFieldSchema, on_change: Callable[[],
         if schema.default is not None:
             check_box.setChecked(bool(schema.default))
         check_box.toggled.connect(lambda _: on_change())
-        if schema.level == AccessLevel.EXPERT:
-            check_box.setEnabled(False)
         return _FieldEditor(
-            check_box, check_box.isChecked, lambda value: check_box.setChecked(bool(value)), level=schema.level
+            check_box,
+            check_box.isChecked,
+            lambda value: check_box.setChecked(bool(value)),
+            level=schema.level,
+            row_widget=_wrap_with_description(check_box, schema.description),
         )
 
     if schema.type == "enum":
@@ -112,13 +152,12 @@ def _build_editor(name: str, schema: ConfigFieldSchema, on_change: Callable[[],
         if schema.default is not None and str(schema.default) in options:
             combo_box.setCurrentText(str(schema.default))
         combo_box.currentTextChanged.connect(lambda _: on_change())
-        if schema.level == AccessLevel.EXPERT:
-            combo_box.setEnabled(False)
         return _FieldEditor(
             combo_box,
             combo_box.currentText,
             lambda value: combo_box.setCurrentText(str(value)),
             level=schema.level,
+            row_widget=_wrap_with_description(combo_box, schema.description),
         )
 
     if schema.type == "object" and schema.nested is not None:
@@ -130,16 +169,17 @@ def _build_editor(name: str, schema: ConfigFieldSchema, on_change: Callable[[],
             if child_schema.level == AccessLevel.HIDDEN:
                 continue
             child_editor = _build_editor(child_name, child_schema, on_change)
-            form_layout.addRow(child_name, child_editor.widget)
+            child_label = QtWidgets.QLabel(child_name)
+            form_layout.addRow(child_label, child_editor.display_widget)
+            child_editor.row_label = child_label
             children[child_name] = child_editor
-        if schema.level == AccessLevel.EXPERT:
-            group_box.setEnabled(False)
         return _FieldEditor(
             group_box,
             lambda: _nested_get(children),
             lambda value: _nested_set(children, value),
             children=children,
             level=schema.level,
+            row_widget=_wrap_with_description(group_box, schema.description),
         )
 
     # object without a nested schema (pydantic freeform dict), or any other schema type this
@@ -158,9 +198,11 @@ def _build_editor(name: str, schema: ConfigFieldSchema, on_change: Callable[[],
     placeholder.setReadOnly(True)
     placeholder.setEnabled(False)
     placeholder.setToolTip(f"Field type {schema.type!r} has no schema-driven editor for this widget.")
-    # always BASIC regardless of schema.level: this widget is permanently disabled (nothing to
-    # edit), so it must never be swept into the expert-toggle's re-enable group
-    return _FieldEditor(placeholder, _get_raw, _set_raw)
+    # always BASIC regardless of schema.level: this is a loud "unsupported type" flag, meant to
+    # stay visible so a developer notices it, never swept into the expert-toggle's hide group
+    return _FieldEditor(
+        placeholder, _get_raw, _set_raw, row_widget=_wrap_with_description(placeholder, schema.description)
+    )
 
 
 class StructuredConfigWidget(BaseWidget):
@@ -182,11 +224,12 @@ class StructuredConfigWidget(BaseWidget):
         # itself register as a user edit (which would otherwise re-enable Apply/Reset for a
         # change that came from the module, not from the operator)
         self._applying_state = False
-        # every EXPERT-level editor widget across the whole (possibly nested) form, collected
-        # once in _build_form; toggled together by checkBoxAdvanced. No password gate, unlike
-        # pyftscontrol's Expert Mode button -- operators here are already authenticated via the
-        # comm layer, so it's just a basic/expert visibility toggle, not an access control.
-        self._expert_widgets: List[QtWidgets.QWidget] = []
+        # every EXPERT-level editor across the whole (possibly nested) form, collected once in
+        # _build_form; their rows (label + widget) are shown/hidden together by checkBoxAdvanced.
+        # No password gate, unlike pyftscontrol's Expert Mode button -- operators here are
+        # already authenticated via the comm layer, so it's just a visibility toggle, not access
+        # control.
+        self._expert_editors: List[_FieldEditor] = []
 
         outer_layout = QtWidgets.QVBoxLayout()
         self.setLayout(outer_layout)
@@ -238,7 +281,9 @@ class StructuredConfigWidget(BaseWidget):
             if field_schema.level == AccessLevel.HIDDEN:
                 continue
             editor = _build_editor(name, field_schema, self._on_editor_changed)
-            self._form_layout.addRow(name, editor.widget)
+            label = QtWidgets.QLabel(name)
+            self._form_layout.addRow(label, editor.display_widget)
+            editor.row_label = label
             children[name] = editor
         self._root = _FieldEditor(
             self._form_container,
@@ -246,7 +291,7 @@ class StructuredConfigWidget(BaseWidget):
             lambda value: _nested_set(children, value),
             children=children,
         )
-        self._expert_widgets = _collect_by_level(self._root, AccessLevel.EXPERT)
+        self._expert_editors = _collect_by_level(self._root, AccessLevel.EXPERT)
         self._on_advanced_toggled(self.checkBoxAdvanced.isChecked())
         # a state may already have arrived (and been cached) before the form existed to receive
         # it -- apply it now instead of waiting for the next update
@@ -254,8 +299,10 @@ class StructuredConfigWidget(BaseWidget):
             self.signal_update_gui.emit()
 
     def _on_advanced_toggled(self, checked: bool) -> None:
-        for widget in self._expert_widgets:
-            widget.setEnabled(checked)
+        for editor in self._expert_editors:
+            editor.display_widget.setVisible(checked)
+            if editor.row_label is not None:
+                editor.row_label.setVisible(checked)
 
     def _on_state(self, state: ConfigAppliedState) -> None:
         self._last_applied = dict(state.config)

{pyobs_gui-2.3.1 → pyobs_gui-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyobs-gui"
-version = "2.3.1"
+version = "2.4.0"
 description = "A remote GUI for pyobs"
 authors = [{ name = "Tim-Oliver Husser", email = "thusser@uni-goettingen.de" }]
 requires-python = ">=3.11"

{pyobs_gui-2.3.1 → pyobs_gui-2.4.0}/tests/test_structuredconfigwidget.py

@@ -153,23 +153,21 @@ def test_unsupported_field_type_is_also_a_disabled_placeholder() -> None:
 
 
 # -- _build_editor / _build_form: basic/expert level ----------------------------------------
+#
+# _build_editor itself only *tags* each editor with its level; it doesn't touch visibility --
+# that's StructuredConfigWidget's job (_build_form/_on_advanced_toggled), tested below.
 
 
-def test_basic_field_starts_enabled() -> None:
-    editor = _build_editor("count", ConfigFieldSchema(type="int", default=3, level=AccessLevel.BASIC), lambda: None)
-    assert editor.widget.isEnabled() is True
-    assert editor.level == AccessLevel.BASIC
-
-
-def test_expert_field_starts_disabled() -> None:
-    editor = _build_editor("count", ConfigFieldSchema(type="int", default=3, level=AccessLevel.EXPERT), lambda: None)
-    assert editor.widget.isEnabled() is False
-    assert editor.level == AccessLevel.EXPERT
+def test_editor_is_tagged_with_its_schema_level() -> None:
+    basic = _build_editor("count", ConfigFieldSchema(type="int", default=3, level=AccessLevel.BASIC), lambda: None)
+    expert = _build_editor("count", ConfigFieldSchema(type="int", default=3, level=AccessLevel.EXPERT), lambda: None)
+    assert basic.level == AccessLevel.BASIC
+    assert expert.level == AccessLevel.EXPERT
 
 
 def test_unsupported_type_placeholder_ignores_expert_level_for_toggle_grouping() -> None:
     """A permanently non-editable placeholder must never be swept into the expert-toggle's
-    re-enable group, even if the underlying field is tagged EXPERT -- see the comment in
+    hide/show group, even if the underlying field is tagged EXPERT -- see the comment in
     _build_editor's fallback branch."""
     editor = _build_editor(
         "items", ConfigFieldSchema(type="list", default=[1, 2], level=AccessLevel.EXPERT), lambda: None
@@ -178,7 +176,7 @@ def test_unsupported_type_placeholder_ignores_expert_level_for_toggle_grouping()
     assert editor.widget.isEnabled() is False
 
 
-def test_nested_object_skips_hidden_children_and_disables_whole_group_when_expert() -> None:
+def test_nested_object_skips_hidden_children() -> None:
     schema = ConfigFieldSchema(
         type="object",
         level=AccessLevel.EXPERT,
@@ -189,7 +187,7 @@ def test_nested_object_skips_hidden_children_and_disables_whole_group_when_exper
     )
     editor = _build_editor("pointing", schema, lambda: None)
     assert editor.children is not None and set(editor.children) == {"az"}
-    assert editor.widget.isEnabled() is False
+    assert editor.level == AccessLevel.EXPERT
 
 
 def _sample_schema_with_levels() -> ConfigSchema:
@@ -212,19 +210,70 @@ def test_build_form_skips_hidden_fields_entirely() -> None:
     widget.close()
 
 
-def test_advanced_checkbox_toggles_expert_fields_enabled() -> None:
+def test_expert_field_row_starts_hidden_basic_field_row_does_not() -> None:
     widget = StructuredConfigWidget()
     widget._build_form(_sample_schema_with_levels())
     assert widget._root is not None and widget._root.children is not None
-    expert_widget = widget._root.children["gain"].widget
+    basic_editor = widget._root.children["name"]
+    expert_editor = widget._root.children["gain"]
+
+    assert basic_editor.widget.isHidden() is False
+    assert basic_editor.row_label is not None and basic_editor.row_label.isHidden() is False
+    assert expert_editor.widget.isHidden() is True
+    assert expert_editor.row_label is not None and expert_editor.row_label.isHidden() is True
+    widget.close()
 
-    assert expert_widget.isEnabled() is False  # starts locked
+
+def test_advanced_checkbox_shows_and_hides_expert_field_row() -> None:
+    widget = StructuredConfigWidget()
+    widget._build_form(_sample_schema_with_levels())
+    assert widget._root is not None and widget._root.children is not None
+    expert_editor = widget._root.children["gain"]
 
     widget.checkBoxAdvanced.setChecked(True)
-    assert expert_widget.isEnabled() is True
+    assert expert_editor.widget.isHidden() is False
+    assert expert_editor.row_label is not None and expert_editor.row_label.isHidden() is False
 
     widget.checkBoxAdvanced.setChecked(False)
-    assert expert_widget.isEnabled() is False
+    assert expert_editor.widget.isHidden() is True
+    assert expert_editor.row_label is not None and expert_editor.row_label.isHidden() is True
+
+
+# -- _build_editor: description rendered below the widget -----------------------------------
+
+
+def test_field_without_description_is_not_wrapped() -> None:
+    editor = _build_editor("count", ConfigFieldSchema(type="int", default=3), lambda: None)
+    assert editor.row_widget is None
+    assert editor.display_widget is editor.widget
+
+
+def test_field_with_description_wraps_widget_with_label_below() -> None:
+    schema = ConfigFieldSchema(type="int", default=3, description="Number of exposures to take")
+    editor = _build_editor("count", schema, lambda: None)
+
+    assert editor.row_widget is not None
+    assert editor.display_widget is editor.row_widget
+    container_layout = editor.row_widget.layout()
+    assert container_layout.count() == 2
+    assert container_layout.itemAt(0).widget() is editor.widget
+    description_label = container_layout.itemAt(1).widget()
+    assert isinstance(description_label, QtWidgets.QLabel)
+    assert description_label.text() == "Number of exposures to take"
+
+
+def test_build_form_places_description_wrapper_in_the_row() -> None:
+    widget = StructuredConfigWidget()
+    schema = ConfigSchema(
+        fields={"count": ConfigFieldSchema(type="int", default=3, description="Number of exposures to take")}
+    )
+    widget._build_form(schema)
+
+    assert widget._root is not None and widget._root.children is not None
+    editor = widget._root.children["count"]
+    row_field_item = widget._form_layout.itemAt(0, QtWidgets.QFormLayout.ItemRole.FieldRole)
+    assert row_field_item.widget() is editor.row_widget
+    widget.close()
     widget.close()
 
 

{pyobs_gui-2.3.1 → pyobs_gui-2.4.0}/uv.lock

@@ -3295,7 +3295,7 @@ wheels = [
 
 [[package]]
 name = "pyobs-gui"
-version = "2.3.1"
+version = "2.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "astroplan" },