v3.13.4

Version 3.13

Version 3.13.4 (2025-12-03)

🛠️ Bug fixes:

• BoolItem numpy compatibility: Fixed numpy.bool_ type conversion issue

  • BoolItem now ensures all assigned values are converted to Python bool type
  • Added __set__ override to convert numpy.bool_ values to native Python bool
  • Fixes compatibility issues with Qt APIs that strictly require Python bool (e.g., QAction.setChecked())
  • Prevents TypeError: setChecked(self, a0: bool): argument 1 has unexpected type 'numpy.bool'
  • Affects applications using BoolItem values with Qt widgets after HDF5 deserialization
  • Maintains backward compatibility as bool(bool) is a no-op
  • This closes Issue #96 - BoolItem: numpy.bool_ compatibility fix

• Fix documentation build error due to the fact that Qt is needed for some parts of the building process

guidata Version 3.13.3 (2025-11-10)

🛠️ Bug fixes:

• ButtonItem callbacks: Fixed critical regression breaking callbacks with 4 parameters
  • In v3.13.2, the auto-apply feature unconditionally passed a 5th parameter (trigger_auto_apply) to all ButtonItem callbacks
  • This broke all existing callbacks expecting only 4 parameters (instance, item, value, parent)
  • Now uses inspect.signature() to check callback parameter count at runtime
  • Callbacks with fewer than 5 parameters receive only the standard 4 arguments
  • Callbacks with 5+ parameters receive the additional trigger_auto_apply function
  • Maintains full backward compatibility while supporting the new auto-apply feature
  • Fixes TypeError: callback() takes 4 positional arguments but 5 were given

guidata Version 3.13.2 (2025-11-03)

✨ New features:

• DataSet setter methods: Added public setter methods for title, comment, and icon

  • New set_title() method: Sets the DataSet's title
  • New set_comment() method: Sets the DataSet's comment
  • New set_icon() method: Sets the DataSet's icon
  • These methods provide a clean public API to modify DataSet metadata previously stored in private attributes
  • Useful for applications that need to dynamically update DataSet metadata programmatically

• Auto-apply for DictItem and FloatArrayItem in DataSetEditGroupBox: Improved user experience when editing dictionaries and arrays

  • When a DictItem or FloatArrayItem is modified within a DataSetEditGroupBox (with an Apply button), changes are now automatically applied when the editor dialog is validated
  • Previously, users had to click "Save & Close" in the dictionary/array editor, then click the "Apply" button in the dataset widget layout
  • Now, clicking "Save & Close" automatically triggers the apply action, making changes immediately effective
  • Implementation: The auto-apply trigger function is passed as an optional 5th parameter to button callbacks
  • This behavior only applies to dataset layouts with an Apply button (DataSetEditGroupBox), not to standalone editors
  • Provides more intuitive workflow and reduces the number of clicks required to apply changes
  • Affects both DictItem (dictionary editor) and FloatArrayItem (array editor)

🛠️ Bug fixes:

• Git report utility: Fixed UnicodeDecodeError on Windows when commit messages contain non-ASCII characters

  • The guidata.utils.gitreport module now explicitly uses UTF-8 encoding when reading Git command output
  • Previously, on Windows systems with cp1252 default encoding, Git commit messages containing Unicode characters (emoji, accented characters, etc.) would cause a UnicodeDecodeError
  • Fixed by adding encoding="utf-8" parameter to all subprocess.check_output() calls in _extract_git_information()
  • This ensures proper decoding of Git output which is always UTF-8 encoded, regardless of the system's default encoding

• DataSet.to_html(): Improved color contrast for dark mode

  • Changed title and comment color from standard blue (#0000FF) to a lighter shade (#5294e2)
  • Provides better visibility in dark mode while maintaining good appearance in light mode
  • Affects the HTML representation of DataSets displayed in applications with dark themes

• ChoiceItem validation: Fixed tuple/list equivalence during JSON deserialization

  • When a ChoiceItem has tuple values (e.g., ((10, 90), "10% - 90%")), JSON serialization converts tuples to lists
  • During deserialization, validation failed because [10, 90] was not recognized as equivalent to (10, 90)
  • Modified ChoiceItem.check_value() to compare sequence contents when both the value and choice are sequences (list/tuple)
  • This ensures that ChoiceItems with tuple values work correctly with dataset_to_json()/json_to_dataset() round-trips
  • Added regression test in test_choice_tuple_serialization.py

• Fix the AboutInfo.about method: renamed parameter addinfos to addinfo for consistency

guidata Version 3.13.1 (2025-10-28)

🛠️ Bug fixes:

• DataSet.to_string(): Fixed missing labels for BoolItem when only text is provided

  • When a BoolItem is defined with only the text parameter (first argument) and no explicit label parameter (second argument), the label was displayed as empty in to_string() output, resulting in : ☐ or : ☑ instead of the expected Item text: ☐
  • Added fallback logic to use the text property as label when label is empty, matching the behavior already implemented in to_html()
  • This ensures consistency between text and HTML representations of DataSets containing BoolItems

• Qt scraper: Fixed thumbnail generation for sphinx-gallery examples in subdirectories

  • The qt_scraper now correctly detects and handles examples organized in subsections (e.g., examples/features/, examples/advanced/)
  • Thumbnails are now saved in the correct subdirectory-specific images/thumb/ folders instead of the top-level directory
  • Image paths in generated RST files now include the subdirectory path
  • Added new _get_example_subdirectory() helper function to extract subdirectory from source file path and avoid code duplication

guidata Version 3.13.0 (2025-10-24)

✨ New features:

• JSON Serialization for DataSets: Added new functions for serializing/deserializing DataSet objects to/from JSON:
  • New dataset.dataset_to_json() function: Serialize a DataSet instance to a JSON string
  • New dataset.json_to_dataset() function: Deserialize a JSON string back to a DataSet instance
  • The JSON format includes class module and name information for automatic type restoration
  • Enables easy data interchange, storage, and transmission of DataSet configurations
  • Example usage:

from guidata.dataset import dataset_to_json, json_to_dataset

# Serialize to JSON
json_str = dataset_to_json(my_dataset)

# Deserialize from JSON
restored_dataset = json_to_dataset(json_str)

• DataSet Class-Level Configuration: Added support for configuring DataSet metadata at the class definition level using __init_subclass__:
  • DataSet title, comment, icon, and readonly state can now be configured directly in the class inheritance declaration
  • Uses Python's standard __init_subclass__ mechanism (PEP 487) for explicit, type-safe configuration
  • Configuration is embedded in the class definition, making it impossible to accidentally remove or forget
  • Instance parameters can still override class-level settings for flexibility
  • Improved docstring handling: When title is explicitly set (even to empty string), the entire docstring becomes the comment
  • Backward compatibility: When no title is set at all, docstring first line is still used as title (old behavior)
  • Example usage:

class MyParameters(DataSet,
                    title="Analysis Parameters",
                    comment="Configure your analysis options",
                    icon="params.png"):
    """This docstring is for developer documentation only"""

    threshold = FloatItem("Threshold", default=0.5)
    method = StringItem("Method", default="auto")

# No need to pass title when instantiating
params = MyParameters()

# Can still override at instance level if needed
params_custom = MyParameters(title="Custom Title")

• Priority order: instance parameter > class-level config > empty/default

• Makes it explicit when title is intentionally set vs. accidentally left empty

• Improves code clarity by separating user-facing metadata from developer documentation

• SeparatorItem: Added a new visual separator data item for better dataset organization:

  • New SeparatorItem class allows inserting visual separators between sections in datasets
  • In textual representation, separators appear as a line of dashes (--------------------------------------------------)
  • In GUI dialogs, separators display as horizontal gray lines spanning the full width
  • Separators don't store any data - they are purely visual elements for organizing forms
  • Example usage:

class PersonDataSet(DataSet):
    name = StringItem("Name", default="John Doe")
    age = IntItem("Age", default=30)

    # Visual separator with label
    sep1 = SeparatorItem("Contact Information")

    email = StringItem("Email", default="[email protected]")
    phone = StringItem("Phone", default="123-456-7890")

    # Visual separator without label
    sep2 = SeparatorItem()

    notes = StringItem("Notes", default="Additional notes")

• Improves readability and visual organization of complex datasets

• Fully integrated with existing DataSet serialization/deserialization (separators are ignored during save/load)

• Compatible with both edit and show modes in dataset dialogs

• Computed Items: Added support for computed/calculated data items in datasets:

  • New ...

v3.13.3

Version 3.13.3

🛠️ Bug fixes:

• ButtonItem callbacks: Fixed critical regression breaking callbacks with 4 parameters
  • In v3.13.2, the auto-apply feature unconditionally passed a 5th parameter (trigger_auto_apply) to all ButtonItem callbacks
  • This broke all existing callbacks expecting only 4 parameters (instance, item, value, parent)
  • Now uses inspect.signature() to check callback parameter count at runtime
  • Callbacks with fewer than 5 parameters receive only the standard 4 arguments
  • Callbacks with 5+ parameters receive the additional trigger_auto_apply function
  • Maintains full backward compatibility while supporting the new auto-apply feature
  • Fixes TypeError: callback() takes 4 positional arguments but 5 were given

Version 3.13.2

✨ New features:

• DataSet setter methods: Added public setter methods for title, comment, and icon

  • New set_title() method: Sets the DataSet's title
  • New set_comment() method: Sets the DataSet's comment
  • New set_icon() method: Sets the DataSet's icon
  • These methods provide a clean public API to modify DataSet metadata previously stored in private attributes
  • Useful for applications that need to dynamically update DataSet metadata programmatically

• Auto-apply for DictItem and FloatArrayItem in DataSetEditGroupBox: Improved user experience when editing dictionaries and arrays

  • When a DictItem or FloatArrayItem is modified within a DataSetEditGroupBox (with an Apply button), changes are now automatically applied when the editor dialog is validated
  • Previously, users had to click "Save & Close" in the dictionary/array editor, then click the "Apply" button in the dataset widget layout
  • Now, clicking "Save & Close" automatically triggers the apply action, making changes immediately effective
  • Implementation: The auto-apply trigger function is passed as an optional 5th parameter to button callbacks
  • This behavior only applies to dataset layouts with an Apply button (DataSetEditGroupBox), not to standalone editors
  • Provides more intuitive workflow and reduces the number of clicks required to apply changes
  • Affects both DictItem (dictionary editor) and FloatArrayItem (array editor)

🛠️ Bug fixes:

• Git report utility: Fixed UnicodeDecodeError on Windows when commit messages contain non-ASCII characters

  • The guidata.utils.gitreport module now explicitly uses UTF-8 encoding when reading Git command output
  • Previously, on Windows systems with cp1252 default encoding, Git commit messages containing Unicode characters (emoji, accented characters, etc.) would cause a UnicodeDecodeError
  • Fixed by adding encoding="utf-8" parameter to all subprocess.check_output() calls in _extract_git_information()
  • This ensures proper decoding of Git output which is always UTF-8 encoded, regardless of the system's default encoding

• DataSet.to_html(): Improved color contrast for dark mode

  • Changed title and comment color from standard blue (#0000FF) to a lighter shade (#5294e2)
  • Provides better visibility in dark mode while maintaining good appearance in light mode
  • Affects the HTML representation of DataSets displayed in applications with dark themes

• ChoiceItem validation: Fixed tuple/list equivalence during JSON deserialization

  • When a ChoiceItem has tuple values (e.g., ((10, 90), "10% - 90%")), JSON serialization converts tuples to lists
  • During deserialization, validation failed because [10, 90] was not recognized as equivalent to (10, 90)
  • Modified ChoiceItem.check_value() to compare sequence contents when both the value and choice are sequences (list/tuple)
  • This ensures that ChoiceItems with tuple values work correctly with dataset_to_json()/json_to_dataset() round-trips
  • Added regression test in test_choice_tuple_serialization.py

• Fix the AboutInfo.about method: renamed parameter addinfos to addinfo for consistency

Version 3.13.1

🛠️ Bug fixes:

• DataSet.to_string(): Fixed missing labels for BoolItem when only text is provided

  • When a BoolItem is defined with only the text parameter (first argument) and no explicit label parameter (second argument), the label was displayed as empty in to_string() output, resulting in : ☐ or : ☑ instead of the expected Item text: ☐
  • Added fallback logic to use the text property as label when label is empty, matching the behavior already implemented in to_html()
  • This ensures consistency between text and HTML representations of DataSets containing BoolItems

• Qt scraper: Fixed thumbnail generation for sphinx-gallery examples in subdirectories

  • The qt_scraper now correctly detects and handles examples organized in subsections (e.g., examples/features/, examples/advanced/)
  • Thumbnails are now saved in the correct subdirectory-specific images/thumb/ folders instead of the top-level directory
  • Image paths in generated RST files now include the subdirectory path
  • Added new _get_example_subdirectory() helper function to extract subdirectory from source file path and avoid code duplication

Version 3.13.0

✨ New features:

• JSON Serialization for DataSets: Added new functions for serializing/deserializing DataSet objects to/from JSON:
  • New dataset.dataset_to_json() function: Serialize a DataSet instance to a JSON string
  • New dataset.json_to_dataset() function: Deserialize a JSON string back to a DataSet instance
  • The JSON format includes class module and name information for automatic type restoration
  • Enables easy data interchange, storage, and transmission of DataSet configurations
  • Example usage:

from guidata.dataset import dataset_to_json, json_to_dataset

# Serialize to JSON
json_str = dataset_to_json(my_dataset)

# Deserialize from JSON
restored_dataset = json_to_dataset(json_str)

• DataSet Class-Level Configuration: Added support for configuring DataSet metadata at the class definition level using __init_subclass__:
  • DataSet title, comment, icon, and readonly state can now be configured directly in the class inheritance declaration
  • Uses Python's standard __init_subclass__ mechanism (PEP 487) for explicit, type-safe configuration
  • Configuration is embedded in the class definition, making it impossible to accidentally remove or forget
  • Instance parameters can still override class-level settings for flexibility
  • Improved docstring handling: When title is explicitly set (even to empty string), the entire docstring becomes the comment
  • Backward compatibility: When no title is set at all, docstring first line is still used as title (old behavior)
  • Example usage:

class MyParameters(DataSet,
                    title="Analysis Parameters",
                    comment="Configure your analysis options",
                    icon="params.png"):
    """This docstring is for developer documentation only"""

    threshold = FloatItem("Threshold", default=0.5)
    method = StringItem("Method", default="auto")

# No need to pass title when instantiating
params = MyParameters()

# Can still override at instance level if needed
params_custom = MyParameters(title="Custom Title")

• Priority order: instance parameter > class-level config > empty/default

• Makes it explicit when title is intentionally set vs. accidentally left empty

• Improves code clarity by separating user-facing metadata from developer documentation

• SeparatorItem: Added a new visual separator data item for better dataset organization:

  • New SeparatorItem class allows inserting visual separators between sections in datasets
  • In textual representation, separators appear as a line of dashes (--------------------------------------------------)
  • In GUI dialogs, separators display as horizontal gray lines spanning the full width
  • Separators don't store any data - they are purely visual elements for organizing forms
  • Example usage:

class PersonDataSet(DataSet):
    name = StringItem("Name", default="John Doe")
    age = IntItem("Age", default=30)

    # Visual separator with label
    sep1 = SeparatorItem("Contact Information")

    email = StringItem("Email", default="[email protected]")
    phone = StringItem("Phone", default="123-456-7890")

    # Visual separator without label
    sep2 = SeparatorItem()

    notes = StringItem("Notes", default="Additional notes")

• Improves readability and visual organization of complex datasets

• Fully integrated with existing DataSet serialization/deserialization (separators are ignored during save/load)

• Compatible with both edit and show modes in dataset dialogs

• Computed Items: Added support for computed/calculated data items in datasets:

  • New ComputedProp class allows defining items whose values are automatically calculated from other items
  • Items can be marked as computed using the set_computed(method_name) method
  • Computed items are automatically read-only and update in real-time when their dependencies change
  • Example usage:

class DataSet(gdt.DataSet):

    def compute_sum(self) -> float:
        return self.x + self.y

    x = gdt.FloatItem("X", default=1.0)
    y = gdt.FloatItem("Y", default=2.0)
    sum_xy = gdt.FloatItem("Sum", default=0.0).set_computed(compute_sum)

• Computed items automatically display with visual distinction (neutral background color) in GUI forms

• Supports complex calculations and can access any other items in the dataset

• Improved Visual Distinction for Read-only Fields: Enhanced user interface to clearly identify non-editable fields:

  • Read-only text fields now display with a subtle gray background and darker text color
  • Visual styling automatica...

v3.13.2

Version 3.13.2

✨ New features:

• DataSet setter methods: Added public setter methods for title, comment, and icon

  • New set_title() method: Sets the DataSet's title
  • New set_comment() method: Sets the DataSet's comment
  • New set_icon() method: Sets the DataSet's icon
  • These methods provide a clean public API to modify DataSet metadata previously stored in private attributes
  • Useful for applications that need to dynamically update DataSet metadata programmatically

• Auto-apply for DictItem and FloatArrayItem in DataSetEditGroupBox: Improved user experience when editing dictionaries and arrays

  • When a DictItem or FloatArrayItem is modified within a DataSetEditGroupBox (with an Apply button), changes are now automatically applied when the editor dialog is validated
  • Previously, users had to click "Save & Close" in the dictionary/array editor, then click the "Apply" button in the dataset widget layout
  • Now, clicking "Save & Close" automatically triggers the apply action, making changes immediately effective
  • Implementation: The auto-apply trigger function is passed as an optional 5th parameter to button callbacks
  • This behavior only applies to dataset layouts with an Apply button (DataSetEditGroupBox), not to standalone editors
  • Provides more intuitive workflow and reduces the number of clicks required to apply changes
  • Affects both DictItem (dictionary editor) and FloatArrayItem (array editor)

🛠️ Bug fixes:

• Git report utility: Fixed UnicodeDecodeError on Windows when commit messages contain non-ASCII characters

  • The guidata.utils.gitreport module now explicitly uses UTF-8 encoding when reading Git command output
  • Previously, on Windows systems with cp1252 default encoding, Git commit messages containing Unicode characters (emoji, accented characters, etc.) would cause a UnicodeDecodeError
  • Fixed by adding encoding="utf-8" parameter to all subprocess.check_output() calls in _extract_git_information()
  • This ensures proper decoding of Git output which is always UTF-8 encoded, regardless of the system's default encoding

• DataSet.to_html(): Improved color contrast for dark mode

  • Changed title and comment color from standard blue (#0000FF) to a lighter shade (#5294e2)
  • Provides better visibility in dark mode while maintaining good appearance in light mode
  • Affects the HTML representation of DataSets displayed in applications with dark themes

• ChoiceItem validation: Fixed tuple/list equivalence during JSON deserialization

  • When a ChoiceItem has tuple values (e.g., ((10, 90), "10% - 90%")), JSON serialization converts tuples to lists
  • During deserialization, validation failed because [10, 90] was not recognized as equivalent to (10, 90)
  • Modified ChoiceItem.check_value() to compare sequence contents when both the value and choice are sequences (list/tuple)
  • This ensures that ChoiceItems with tuple values work correctly with dataset_to_json()/json_to_dataset() round-trips
  • Added regression test in test_choice_tuple_serialization.py

• Fix the AboutInfo.about method: renamed parameter addinfos to addinfo for consistency

Version 3.13.1

🛠️ Bug fixes:

• DataSet.to_string(): Fixed missing labels for BoolItem when only text is provided

  • When a BoolItem is defined with only the text parameter (first argument) and no explicit label parameter (second argument), the label was displayed as empty in to_string() output, resulting in : ☐ or : ☑ instead of the expected Item text: ☐
  • Added fallback logic to use the text property as label when label is empty, matching the behavior already implemented in to_html()
  • This ensures consistency between text and HTML representations of DataSets containing BoolItems

• Qt scraper: Fixed thumbnail generation for sphinx-gallery examples in subdirectories

  • The qt_scraper now correctly detects and handles examples organized in subsections (e.g., examples/features/, examples/advanced/)
  • Thumbnails are now saved in the correct subdirectory-specific images/thumb/ folders instead of the top-level directory
  • Image paths in generated RST files now include the subdirectory path
  • Added new _get_example_subdirectory() helper function to extract subdirectory from source file path and avoid code duplication

Version 3.13.0

✨ New features:

• JSON Serialization for DataSets: Added new functions for serializing/deserializing DataSet objects to/from JSON:
  • New dataset.dataset_to_json() function: Serialize a DataSet instance to a JSON string
  • New dataset.json_to_dataset() function: Deserialize a JSON string back to a DataSet instance
  • The JSON format includes class module and name information for automatic type restoration
  • Enables easy data interchange, storage, and transmission of DataSet configurations
  • Example usage:

from guidata.dataset import dataset_to_json, json_to_dataset

# Serialize to JSON
json_str = dataset_to_json(my_dataset)

# Deserialize from JSON
restored_dataset = json_to_dataset(json_str)

• DataSet Class-Level Configuration: Added support for configuring DataSet metadata at the class definition level using __init_subclass__:
  • DataSet title, comment, icon, and readonly state can now be configured directly in the class inheritance declaration
  • Uses Python's standard __init_subclass__ mechanism (PEP 487) for explicit, type-safe configuration
  • Configuration is embedded in the class definition, making it impossible to accidentally remove or forget
  • Instance parameters can still override class-level settings for flexibility
  • Improved docstring handling: When title is explicitly set (even to empty string), the entire docstring becomes the comment
  • Backward compatibility: When no title is set at all, docstring first line is still used as title (old behavior)
  • Example usage:

class MyParameters(DataSet,
                    title="Analysis Parameters",
                    comment="Configure your analysis options",
                    icon="params.png"):
    """This docstring is for developer documentation only"""

    threshold = FloatItem("Threshold", default=0.5)
    method = StringItem("Method", default="auto")

# No need to pass title when instantiating
params = MyParameters()

# Can still override at instance level if needed
params_custom = MyParameters(title="Custom Title")

• Priority order: instance parameter > class-level config > empty/default

• Makes it explicit when title is intentionally set vs. accidentally left empty

• Improves code clarity by separating user-facing metadata from developer documentation

• SeparatorItem: Added a new visual separator data item for better dataset organization:

  • New SeparatorItem class allows inserting visual separators between sections in datasets
  • In textual representation, separators appear as a line of dashes (--------------------------------------------------)
  • In GUI dialogs, separators display as horizontal gray lines spanning the full width
  • Separators don't store any data - they are purely visual elements for organizing forms
  • Example usage:

class PersonDataSet(DataSet):
    name = StringItem("Name", default="John Doe")
    age = IntItem("Age", default=30)

    # Visual separator with label
    sep1 = SeparatorItem("Contact Information")

    email = StringItem("Email", default="[email protected]")
    phone = StringItem("Phone", default="123-456-7890")

    # Visual separator without label
    sep2 = SeparatorItem()

    notes = StringItem("Notes", default="Additional notes")

• Improves readability and visual organization of complex datasets

• Fully integrated with existing DataSet serialization/deserialization (separators are ignored during save/load)

• Compatible with both edit and show modes in dataset dialogs

• Computed Items: Added support for computed/calculated data items in datasets:

  • New ComputedProp class allows defining items whose values are automatically calculated from other items
  • Items can be marked as computed using the set_computed(method_name) method
  • Computed items are automatically read-only and update in real-time when their dependencies change
  • Example usage:

class DataSet(gdt.DataSet):

    def compute_sum(self) -> float:
        return self.x + self.y

    x = gdt.FloatItem("X", default=1.0)
    y = gdt.FloatItem("Y", default=2.0)
    sum_xy = gdt.FloatItem("Sum", default=0.0).set_computed(compute_sum)

• Computed items automatically display with visual distinction (neutral background color) in GUI forms

• Supports complex calculations and can access any other items in the dataset

• Improved Visual Distinction for Read-only Fields: Enhanced user interface to clearly identify non-editable fields:

  • Read-only text fields now display with a subtle gray background and darker text color
  • Visual styling automatically adapts to your theme (light or dark mode)
  • Applies to computed fields, locked parameters, and any field marked as read-only
  • Makes it immediately clear which fields you can edit and which are display-only
  • Validation errors are still highlighted with orange background when they occur

• DataSet HTML Export: Added HTML representation method for datasets:

  • New to_html() method on DataSet class generates HTML representation similar to Sigima's TableResult format
  • Features blue-styled title and comment section derived from the dataset's docstring
  • Two-column table layout with right-aligned item names and left-aligned values
  • Special handling for BoolItem with checkbox characters (☑ for True, ☐ for False)
  • Monospace font styling ...

v3.13.1

Version 3.13.1

🛠️ Bug fixes:

• DataSet.to_string(): Fixed missing labels for BoolItem when only text is provided

  • When a BoolItem is defined with only the text parameter (first argument) and no explicit label parameter (second argument), the label was displayed as empty in to_string() output, resulting in : ☐ or : ☑ instead of the expected Item text: ☐
  • Added fallback logic to use the text property as label when label is empty, matching the behavior already implemented in to_html()
  • This ensures consistency between text and HTML representations of DataSets containing BoolItems

• Qt scraper: Fixed thumbnail generation for sphinx-gallery examples in subdirectories

  • The qt_scraper now correctly detects and handles examples organized in subsections (e.g., examples/features/, examples/advanced/)
  • Thumbnails are now saved in the correct subdirectory-specific images/thumb/ folders instead of the top-level directory
  • Image paths in generated RST files now include the subdirectory path
  • Added new _get_example_subdirectory() helper function to extract subdirectory from source file path and avoid code duplication

Version 3.13.0

✨ New features:

• JSON Serialization for DataSets: Added new functions for serializing/deserializing DataSet objects to/from JSON:
  • New dataset.dataset_to_json() function: Serialize a DataSet instance to a JSON string
  • New dataset.json_to_dataset() function: Deserialize a JSON string back to a DataSet instance
  • The JSON format includes class module and name information for automatic type restoration
  • Enables easy data interchange, storage, and transmission of DataSet configurations
  • Example usage:

from guidata.dataset import dataset_to_json, json_to_dataset

# Serialize to JSON
json_str = dataset_to_json(my_dataset)

# Deserialize from JSON
restored_dataset = json_to_dataset(json_str)

• DataSet Class-Level Configuration: Added support for configuring DataSet metadata at the class definition level using __init_subclass__:
  • DataSet title, comment, icon, and readonly state can now be configured directly in the class inheritance declaration
  • Uses Python's standard __init_subclass__ mechanism (PEP 487) for explicit, type-safe configuration
  • Configuration is embedded in the class definition, making it impossible to accidentally remove or forget
  • Instance parameters can still override class-level settings for flexibility
  • Improved docstring handling: When title is explicitly set (even to empty string), the entire docstring becomes the comment
  • Backward compatibility: When no title is set at all, docstring first line is still used as title (old behavior)
  • Example usage:

class MyParameters(DataSet,
                    title="Analysis Parameters",
                    comment="Configure your analysis options",
                    icon="params.png"):
    """This docstring is for developer documentation only"""

    threshold = FloatItem("Threshold", default=0.5)
    method = StringItem("Method", default="auto")

# No need to pass title when instantiating
params = MyParameters()

# Can still override at instance level if needed
params_custom = MyParameters(title="Custom Title")

• Priority order: instance parameter > class-level config > empty/default

• Makes it explicit when title is intentionally set vs. accidentally left empty

• Improves code clarity by separating user-facing metadata from developer documentation

• SeparatorItem: Added a new visual separator data item for better dataset organization:

  • New SeparatorItem class allows inserting visual separators between sections in datasets
  • In textual representation, separators appear as a line of dashes (--------------------------------------------------)
  • In GUI dialogs, separators display as horizontal gray lines spanning the full width
  • Separators don't store any data - they are purely visual elements for organizing forms
  • Example usage:

class PersonDataSet(DataSet):
    name = StringItem("Name", default="John Doe")
    age = IntItem("Age", default=30)

    # Visual separator with label
    sep1 = SeparatorItem("Contact Information")

    email = StringItem("Email", default="[email protected]")
    phone = StringItem("Phone", default="123-456-7890")

    # Visual separator without label
    sep2 = SeparatorItem()

    notes = StringItem("Notes", default="Additional notes")

• Improves readability and visual organization of complex datasets

• Fully integrated with existing DataSet serialization/deserialization (separators are ignored during save/load)

• Compatible with both edit and show modes in dataset dialogs

• Computed Items: Added support for computed/calculated data items in datasets:

  • New ComputedProp class allows defining items whose values are automatically calculated from other items
  • Items can be marked as computed using the set_computed(method_name) method
  • Computed items are automatically read-only and update in real-time when their dependencies change
  • Example usage:

class DataSet(gdt.DataSet):

    def compute_sum(self) -> float:
        return self.x + self.y

    x = gdt.FloatItem("X", default=1.0)
    y = gdt.FloatItem("Y", default=2.0)
    sum_xy = gdt.FloatItem("Sum", default=0.0).set_computed(compute_sum)

• Computed items automatically display with visual distinction (neutral background color) in GUI forms

• Supports complex calculations and can access any other items in the dataset

• Improved Visual Distinction for Read-only Fields: Enhanced user interface to clearly identify non-editable fields:

  • Read-only text fields now display with a subtle gray background and darker text color
  • Visual styling automatically adapts to your theme (light or dark mode)
  • Applies to computed fields, locked parameters, and any field marked as read-only
  • Makes it immediately clear which fields you can edit and which are display-only
  • Validation errors are still highlighted with orange background when they occur

• DataSet HTML Export: Added HTML representation method for datasets:

  • New to_html() method on DataSet class generates HTML representation similar to Sigima's TableResult format
  • Features blue-styled title and comment section derived from the dataset's docstring
  • Two-column table layout with right-aligned item names and left-aligned values
  • Special handling for BoolItem with checkbox characters (☑ for True, ☐ for False)
  • Monospace font styling for consistent alignment and professional appearance
  • Proper handling of None values (displayed as "-") and nested ObjectItem datasets
  • Example usage:

class PersonDataSet(DataSet):
    """Personal Information Dataset

    This dataset collects basic personal information.
    """
    name = StringItem("Full Name", default="John Doe")
    age = IntItem("Age", default=30)
    active = BoolItem("Account Active", default=True)

dataset = PersonDataSet()
html_output = dataset.to_html()  # Generate HTML representation

• Ideal for reports, documentation, and web-based dataset visualization

• Comprehensive unit test coverage ensures reliability across all item types

• guidata.configtools.get_icon:

  • This function retrieves a QIcon from the specified image file.
  • Now supports Qt standard icons (e.g. "MessageBoxInformation" or "DialogApplyButton").

• Removed requirements-min.txt generation feature from guidata.utils.genreqs:

  • The minimal requirements feature was causing platform compatibility issues when specific minimum versions weren't available on all platforms (e.g., SciPy==1.7.3 works on Windows but fails on Linux)
  • Removed __extract_min_requirements() function and --min CLI flag
  • The genreqs tool now only generates requirements.txt and requirements.rst files
  • Updated documentation and MANIFEST.in files to remove references to requirements-min.txt

• Added a readonly parameter to StringItem and TextItem in guidata.dataset.dataitems:

  • This allows these items to be set as read-only, preventing user edits in the GUI.
  • The readonly property is now respected in the corresponding widgets (see guidata.dataset.qtitemwidgets).
  • Example usage:

text = gds.TextItem("Text", default="Multi-line text", readonly=True)
string = gds.StringItem("String", readonly=True)

• Note: Any other item type can also be turned into read-only mode by using set_prop("display", readonly=True). This is a generic mechanism, but the main use case is for StringItem and TextItem (hence the dedicated input parameter for convenience).

• Issue #94 - Make dataset description text selectable

• New guidata.utils.cleanup utility:

  • Added a comprehensive repository cleanup utility similar to genreqs and securebuild
  • Provides both programmatic API (from guidata.utils.cleanup import run_cleanup) and command-line interface (python -m guidata.utils.cleanup)
  • Automatically detects repository type and cleans Python cache files, build artifacts, temporary files, coverage data, backup files, and empty directories
  • Features comprehensive Google-style docstrings and full typing annotations
  • Cross-platform compatible with proper logging and error handling
  • Can be integrated into project workflows via VSCode tasks or build scripts

• New validation modes for DataItem objects:

  • Validation modes allow you to control how DataItem values are validated when they are set.
  • ValidationMode.DISABLED: no validation is performed (default behavior, for backward compatibility)
  • ValidationMode.ENABLED: va...

v3.13.0

✨ New features:

• JSON Serialization for DataSets: Added new functions for serializing/deserializing DataSet objects to/from JSON:
  • New dataset.dataset_to_json() function: Serialize a DataSet instance to a JSON string
  • New dataset.json_to_dataset() function: Deserialize a JSON string back to a DataSet instance
  • The JSON format includes class module and name information for automatic type restoration
  • Enables easy data interchange, storage, and transmission of DataSet configurations
  • Example usage:

from guidata.dataset import dataset_to_json, json_to_dataset

# Serialize to JSON
json_str = dataset_to_json(my_dataset)

# Deserialize from JSON
restored_dataset = json_to_dataset(json_str)

• DataSet Class-Level Configuration: Added support for configuring DataSet metadata at the class definition level using __init_subclass__:
  • DataSet title, comment, icon, and readonly state can now be configured directly in the class inheritance declaration
  • Uses Python's standard __init_subclass__ mechanism (PEP 487) for explicit, type-safe configuration
  • Configuration is embedded in the class definition, making it impossible to accidentally remove or forget
  • Instance parameters can still override class-level settings for flexibility
  • Improved docstring handling: When title is explicitly set (even to empty string), the entire docstring becomes the comment
  • Backward compatibility: When no title is set at all, docstring first line is still used as title (old behavior)
  • Example usage:

class MyParameters(DataSet,
                    title="Analysis Parameters",
                    comment="Configure your analysis options",
                    icon="params.png"):
    """This docstring is for developer documentation only"""

    threshold = FloatItem("Threshold", default=0.5)
    method = StringItem("Method", default="auto")

# No need to pass title when instantiating
params = MyParameters()

# Can still override at instance level if needed
params_custom = MyParameters(title="Custom Title")

• Priority order: instance parameter > class-level config > empty/default

• Makes it explicit when title is intentionally set vs. accidentally left empty

• Improves code clarity by separating user-facing metadata from developer documentation

• SeparatorItem: Added a new visual separator data item for better dataset organization:

  • New SeparatorItem class allows inserting visual separators between sections in datasets
  • In textual representation, separators appear as a line of dashes (--------------------------------------------------)
  • In GUI dialogs, separators display as horizontal gray lines spanning the full width
  • Separators don't store any data - they are purely visual elements for organizing forms
  • Example usage:

class PersonDataSet(DataSet):
    name = StringItem("Name", default="John Doe")
    age = IntItem("Age", default=30)

    # Visual separator with label
    sep1 = SeparatorItem("Contact Information")

    email = StringItem("Email", default="[email protected]")
    phone = StringItem("Phone", default="123-456-7890")

    # Visual separator without label
    sep2 = SeparatorItem()

    notes = StringItem("Notes", default="Additional notes")

• Improves readability and visual organization of complex datasets

• Fully integrated with existing DataSet serialization/deserialization (separators are ignored during save/load)

• Compatible with both edit and show modes in dataset dialogs

• Computed Items: Added support for computed/calculated data items in datasets:

  • New ComputedProp class allows defining items whose values are automatically calculated from other items
  • Items can be marked as computed using the set_computed(method_name) method
  • Computed items are automatically read-only and update in real-time when their dependencies change
  • Example usage:

class DataSet(gdt.DataSet):

    def compute_sum(self) -> float:
        return self.x + self.y

    x = gdt.FloatItem("X", default=1.0)
    y = gdt.FloatItem("Y", default=2.0)
    sum_xy = gdt.FloatItem("Sum", default=0.0).set_computed(compute_sum)

• Computed items automatically display with visual distinction (neutral background color) in GUI forms

• Supports complex calculations and can access any other items in the dataset

• Improved Visual Distinction for Read-only Fields: Enhanced user interface to clearly identify non-editable fields:

  • Read-only text fields now display with a subtle gray background and darker text color
  • Visual styling automatically adapts to your theme (light or dark mode)
  • Applies to computed fields, locked parameters, and any field marked as read-only
  • Makes it immediately clear which fields you can edit and which are display-only
  • Validation errors are still highlighted with orange background when they occur

• DataSet HTML Export: Added HTML representation method for datasets:

  • New to_html() method on DataSet class generates HTML representation similar to Sigima's TableResult format
  • Features blue-styled title and comment section derived from the dataset's docstring
  • Two-column table layout with right-aligned item names and left-aligned values
  • Special handling for BoolItem with checkbox characters (☑ for True, ☐ for False)
  • Monospace font styling for consistent alignment and professional appearance
  • Proper handling of None values (displayed as "-") and nested ObjectItem datasets
  • Example usage:

class PersonDataSet(DataSet):
    """Personal Information Dataset

    This dataset collects basic personal information.
    """
    name = StringItem("Full Name", default="John Doe")
    age = IntItem("Age", default=30)
    active = BoolItem("Account Active", default=True)

dataset = PersonDataSet()
html_output = dataset.to_html()  # Generate HTML representation

• Ideal for reports, documentation, and web-based dataset visualization

• Comprehensive unit test coverage ensures reliability across all item types

• guidata.configtools.get_icon:

  • This function retrieves a QIcon from the specified image file.
  • Now supports Qt standard icons (e.g. "MessageBoxInformation" or "DialogApplyButton").

• Removed requirements-min.txt generation feature from guidata.utils.genreqs:

  • The minimal requirements feature was causing platform compatibility issues when specific minimum versions weren't available on all platforms (e.g., SciPy==1.7.3 works on Windows but fails on Linux)
  • Removed __extract_min_requirements() function and --min CLI flag
  • The genreqs tool now only generates requirements.txt and requirements.rst files
  • Updated documentation and MANIFEST.in files to remove references to requirements-min.txt

• Added a readonly parameter to StringItem and TextItem in guidata.dataset.dataitems:

  • This allows these items to be set as read-only, preventing user edits in the GUI.
  • The readonly property is now respected in the corresponding widgets (see guidata.dataset.qtitemwidgets).
  • Example usage:

text = gds.TextItem("Text", default="Multi-line text", readonly=True)
string = gds.StringItem("String", readonly=True)

• Note: Any other item type can also be turned into read-only mode by using set_prop("display", readonly=True). This is a generic mechanism, but the main use case is for StringItem and TextItem (hence the dedicated input parameter for convenience).

• Issue #94 - Make dataset description text selectable

• New guidata.utils.cleanup utility:

  • Added a comprehensive repository cleanup utility similar to genreqs and securebuild
  • Provides both programmatic API (from guidata.utils.cleanup import run_cleanup) and command-line interface (python -m guidata.utils.cleanup)
  • Automatically detects repository type and cleans Python cache files, build artifacts, temporary files, coverage data, backup files, and empty directories
  • Features comprehensive Google-style docstrings and full typing annotations
  • Cross-platform compatible with proper logging and error handling
  • Can be integrated into project workflows via VSCode tasks or build scripts

• New validation modes for DataItem objects:

  • Validation modes allow you to control how DataItem values are validated when they are set.
  • ValidationMode.DISABLED: no validation is performed (default behavior, for backward compatibility)
  • ValidationMode.ENABLED: validation is performed, but warnings are raised instead of exceptions
  • ValidationMode.STRICT: validation is performed, and exceptions are raised if the value is invalid
  • To use these validation modes, you need to set the option:

from guidata.config import set_validation_mode, ValidationMode

set_validation_mode(ValidationMode.STRICT)

• New check_callback parameter for FloatArrayItem:

  • The check_callback parameter allows you to specify a custom validation function for the item.
  • This function will be called to validate the item's value whenever it is set.
  • If the function returns False, the value will be considered invalid.

• New allow_none parameter for DataItem objects:

  • The allow_none parameter allows you to specify whether None is a valid value for the item, which can be especially useful when validation modes are used.
  • If allow_none is set to True, None is considered a valid value regardless of other constraints.
  • If allow_none is set to False, None is considered an invalid value.
  • The default value for allow_none is False, except for FloatArrayItem, ColorItem and ChoiceItem and its subclasses, where it ...

v3.12.0

Version 3.12.0

💥 New features:

• New operator property FuncPropMulti for handling multiple properties:

  • This property allows you to apply a function to multiple item properties at once.
  • It can be used to create more complex dependencies between items in a dataset.
  • See the guidata.tests.dataset.test_activable_items module for an example of usage.

• New script gbuild for building the package:

  • This script is a wrapper around the guidata.utils.securebuild module, which ensures that the build process is secure and reproducible.
  • It checks that the pyproject.toml file is present in the root of the repository, and that it is committed to Git.
  • It also ensures that the build process is reproducible by using a temporary directory for the build artifacts.

• New qt_wait_until function (guidata.qthelpers) for waiting until a condition is met:

  • This function allows you to wait for a specific condition to be true, while still processing Qt events.
  • It can be useful in situations where you need to wait for a background task to complete or for a specific UI state to be reached.

• Renamed scripts associated to guidata.utils.translations and guidata.utils.genreqs modules:

  • guidata-translations is now gtrans
  • guidata-genreqs is now greqs

🛠️ Bug fixes:

• Issue #90 - BoolItem: Fix checkbox state management in qtitemwidgets
  • Before this fix, the checkbox state was not correctly managed when the item's active state changed.
  • In other words, when using set_prop("display", active= on BoolItem, the checkbox was not updated.
  • The checkbox state is now correctly managed based on the item's active state.
  • This fixes a regression introduced in version 3.3.0 with the new dataset read-only mode feature.
• Requirements generation scripts (greqs or python -m guidata.utils.genreqs):
  • Before this fix, strict superior version requirements (e.g. pyqt5 > 5.15) were skipped in the generated requirements files (with a warning message).
  • Now, these strict superior version requirements are included but the version is not specified (e.g. pyqt5 instead of pyqt5 > 5.15).
  • A warning message is still displayed to inform the user that the version is not specified.
• Issue with automated test suite using exec_dialog:
  • The exec_dialog function was not properly handling the dialog closure in automated tests.
  • This could lead to unexpected behavior and side effects between tests.
  • The fix ensures that all pending Qt events are processed before scheduling the dialog closure.
  • This avoids the necessity to use timeouts in tests, which can lead to flaky tests.

ℹ️ Other changes:

• Updated dependencies following the latest security advisories (NumPy >= 1.22)
• Added pre-commit hook to run ruff (both ruff check and ruff format) on commit
• Added missing build optional dependency to development dependencies in pyproject.toml
• Visual Studio Code tasks:
  • Major overhaul (cleanup and simplification)
  • Removal of no longer used batch files

v3.11.0

Version 3.11.0

💥 New features:

• New utils.genreqs module for generating installation requirements files:
  • Function generate_requirements_txt generates a requirements.txt file
  • Function generate_requirements_rst generates a requirements.rst file
  • The module is used by the new command line script guidata-genreqs

v3.10.0

Version 3.10.0

💥 New features:

• Issue #81 - Modernize the internationalization utilities
  • The guidata.utils.gettext_helpers module, based on the gettext module, has been deprecated.
  • It has been replaced by a new module guidata.utils.translations, which provides a more modern and flexible way to handle translations, thanks to the babel library.
  • This change introduces a new script for managing translations, which may be used as follows:
    • Scan for new translations:
      • python -m guidata.utils.translations scan --name <name> --directory <directory>
      • or guidata-translations scan --name <name> --directory <directory>
    • Compile translations:
      • python -m guidata.utils.translations compile --name <name> --directory <directory>
      • or guidata-translations compile --name <name> --directory <directory>
    • More options are available, see the help message of the script:
      • python -m guidata.utils.translations --help
      • or guidata-translations --help

🛠️ Bug fixes:

• Issue #88 - DictItem default value persists across dataset instances (missing deepcopy)
  • This issue is as old as the DictItem class itself.
  • When using a DictItem in a dataset, if a value is set to the item instance, this value was incorrectly used as the default for the next instance of the same dataset class.
  • This happened because a deepcopy was not made when setting the defaults of the class items in guidata.dataset.datatypes.
  • The fix ensures that each dataset instance has its own independent default value for DictItem, preventing side effects from one instance to another.

v3.9.0

💥 New features:

• Issue #87 - Array editor: add an option to paste data (Ctrl+V)
• Issue #85 - Array editor: add a button to export data as CSV
• Issue #86 - Array editor: add "Copy all" feature for copying array and headers to clipboard

v3.8.0

ℹ️ Changes:

• utils.gettext_helpers:
  • do_rescan_files: use --no-location option to avoid including the file location in the translation files
  • msgmerge: use --update option to avoid regenerating the translation files
• Replace flake8 with ruff for linting in GitHub Actions workflow

🛠️ Bug fixes:

• Issue #84 - Side effects of win32_fix_title_bar_background with QGraphicsEffect active
• Issue #82 - Autodoc extension: translation of generic documentation text
  • Initially, the generic documentation text like "Returns a new instance of" was translated using the gettext function.
  • This was a mistake, as this text should be translated only after the documentation has been generated, i.e. by the sphinx-intl tool.
  • In other words, translating those generic texts should be done in the application documentation, not in the library itself.
  • To fix this issue, the generic documentation text is no longer translated using gettext, but is left as is in the source code.
• Issue #80 - ValueError when trying to show/edit an empty array