Release Notes

v5.0.0

Released: 2025-11-30

New Features

The Hooks use_async() and use_async_call() now have an optional max_concurrent argument which can allow more than one async call to run concurrently. The max_concurrent argument defaults to 1, which is the same behavior as before.

Migration Guide

Because the max_concurrent argument defaults to 1, which is the same behavior as before, most user code will not be affected by this change.

Breaking Change The use_async_call() Hook is no longer thread-safe. If you were relying on the thread-safety of use_async_call() then you should wrap it in a asyncio.call_soon_threadsafe function.

call_soon_threadsafe with use_async_call

import asyncio

main_loop = asyncio.get_event_loop()

async def my_function_async(arg: str):
    print(arg)

my_function, my_function_cancel = use_async_call(my_function_async)

def thread_safe_my_function(arg: str):
    """This function can be passed to another thread and called by that thread."""
    main_loop.call_soon_threadsafe(my_function, arg)

Breaking Change use_async() and use_async_call() no longer suppress exceptions other than CancelledError. Unhandled exceptions in async functions will raise into the event loop as they normally would.

Breaking Change Deleted deprecated functions use_callback Icon IconButton alert file_dialog.

v4.4.1

Released: 2025-10-14

• Bugfix: CustomWidget style prop applies to the widget.

v4.4.0

Released: 2025-08-23

• VScrollView, HScrollView, FixScrollView new props scrollbar_policy_horizontal, scrollbar_policy_vertical.

v4.3.0

Released: 2025-07-20

• New Hook use_palette_edifice().

v4.2.0

Released: 2025-07-15

• VScrollView, HScrollView, FixScrollView new props on_scroll_vertical, on_scroll_horizontal, on_range_vertical, on_range_horizontal.

v4.1.0

Released: 2025-06-24

• New QtWidgetElement prop on_focus.

v4.0.1

Released: 2025-05-27

• Bugfix: FlowView children re-ordering layout update bug.

v4.0.0

Released: 2025-05-14

Breaking Changes

• run_subprocess_with_callback() takes a normal function instead of an async coroutine for the subprocess argument.

  If you want the subprocess to be an async function then make a new event loop and use that as the event loop for the Process.

  Example async subprocess function

  def my_subprocess(callback: typing.Callable[[int], None]) -> str:
  
      async def work() -> str:
          callback(1)
          await asyncio.sleep(1)
          return "done"
  
      return asyncio.new_event_loop().run_until_complete(work())
  

  Migration Guide:

  Unfortunately Pyright will not error on this change. You must check each run_subprocess_with_callback() call site and make sure that the subprocess argument is a normal function, not an async function.

v3.2.3

Released: 2025-04-19

• Bugfix: ButtonView on_trigger type hint.

v3.2.2

Released: 2025-04-10

• Bugfix: Inspector spinning refresh loop introduced in v3.2.1.

• logging.getLogger("Edifice") mean time resets after each log print.

v3.2.1

Released: 2025-04-10

• Bugfix use_state(), use_context_select(): when the state setter is called with the same state it should not cause re-render.

v3.2.0

Released: 2025-04-09

• New Base Elements

  • StackedView

  • GroupBoxView

v3.1.0

Released: 2025-04-07

• New Hook use_context_select().

• Bugfix in use_context(): too many setters registered to the global context.

v3.0.0

Released: 2025-02-08

• Bugfix for unmounting Graphics Effects.

• Deprecated IconButton. Instead use ButtonView.

• Deprecated Icon. Instead use ImageSvg.

• Introduced internal type PropsDiff which improves speed by reducing the number of Qt mutation commands issued.

Breaking Changes

• PropsDict type is now an alias for dict[str, Any].

  Migration Guide:

  If you have a user subclass of QtWidgetElement then you will need to re-write the _qt_update_commands() method.

• ContextMenuType changed from Mapping to tuple.

• CustomWidget deleted function paint, added CustomWidget.update().

• Label prop word_wrap now defaults to False, as it does in Qt.

  Migration Guide:

  1. If a Label has no word_wrap prop, then add prop word_wrap=True.

  2. If a Label has prop word_wrap=False, then delete the word_wrap prop.

• Base Elements event handlers no longer accept an async coroutine function.

  We decided this because it is almost always a bug to start a new coroutine Task from an event handler, because the @component may unmount while the event handler Task is still running.

  Instead use use_async_call() to asynchronously handle an event. Then the coroutine Task will be cancelled if the @component unmounts.

  If you are sure that you want to “fire-and-forget” a coroutine in response to an event, then use any of the usual methods from asyncio Coroutines and Tasks. such as create_task.

  Migration Guide:

  Pyright will show errors for async event handlers.

v2.14.2

Released: 2025-02-03

• Fix use_async() bug introduced in v2.14.1.

v2.14.1

Released: 2025-02-03

• Fix rendering bug introduced in v2.14.0 from App.start_loop() changes.

v2.14.0

Released: 2025-02-02

• New Styling props Graphics Effects

• App bugfix hang when Exception raised on first render.

• Deprecated functions alert file_dialog set_trace.

v2.13.0

Released: 2025-01-29

• If the subprocess exits abnormally without returning a value then a ProcessError will be raised from run_subprocess_with_callback().

v2.12.0

Released: 2025-01-27

• run_subprocess_with_callback() new argument daemon.

v2.11.4

Released: 2025-01-19

• run_subprocess_with_callback() improvements: Handle multiple callbacks with no delay. Drain the callback_send queue before joining the Process.

v2.11.3

Released: 2025-01-17

• use_async() bugfix for exceptions raised from the async function.

v2.11.2

Released: 2025-01-17

• run_subprocess_with_callback() don’t terminate on normal return.

v2.11.1

Released: 2025-01-15

• run_subprocess_with_callback() reduced the number of incidental processes and threads created. Removed multiprocessing.Manager from documentation.

v2.11.0

Released: 2025-01-10

• run_subprocess_with_callback() callback exceptions will be suppressed.

v2.10.0

Released: 2025-01-08

• New utility function utilities.run_subprocess_with_callback().

v2.9.1

Released: 2025-01-06

• Change pyproject.toml from Poetry to Setuptools build backend.

v2.9.0

Released: 2024-12-28

• New Hooks: provide_context(), use_context().

• Styling style prop "align" can take an AlignmentFlag.

• Styling style prop colors can take a QColor.

• Deprecate Hook use_callback in favor of use_memo().

v2.8.1

Released: 2024-12-18

• Bugfix: prop enable_mouse_scroll for Slider, SpinInput, Dropdown.

v2.8.0

Released: 2024-12-13

• New Base Element ScrollBar.

• New QtWidgetElement prop on_mouse_wheel.

v2.7.1

Released: 2024-12-12

• Bugfix VScrollView HScrollView on_resize event handler will not interfere with the resizing behavior of QScrollArea.

v2.7.0

Released: 2024-12-10

• New Hook use_memo().

• Bugfix QtWidgetElement children. Fix bug children disappeared when re-rendering with no changes.

v2.6.1

Released: 2024-11-09

• Bugfix QtWidgetElement style prop will not be mutated.

v2.6.0

Released: 2024-11-02

• Label new prop text_format.

v2.5.0

Released: 2024-10-10

• New Hook use_callback.

• Hook use_state() setter function will be stable across renders.

v2.4.0

Released: 2024-10-06

• TabView bugfix

v2.3.0

Released: 2024-10-05

• TextInput new prop completer.

• QtWidgetElement new argument _focus_open.

• QtWidgetElement on_key_down and on_key_up events will propagate to parent.

• edifice.extra module does not re-export extra Elements because that requires additional dependencies.

v2.2.0

Released: 2024-09-29

• Inspector style bugfix.

v2.1.0

Released: 2024-09-27

• Window new props _size_open, full_screen.

• Window renamed argument on_open to _on_open.

• WindowPopView new props _size_open, full_screen.

v2.0.1

Released: 2024-09-22

• Delete method TableGridView row().

• New Element TableGridRow.

• TableGridView props type change from list to tuple.

• Label delete prop editable.

• Delete deprecated View and ScrollView.

• Delete deprecated "margin" alias for "padding" in Views.

• Remove style prop Sequence type. (style must be a dict, not a list[dict].)

• Dependency PySide6-Essentials tested.

• New Hook use_stop().

• Window WindowPopView new arg _size_open.

Old TableGridView API

with TableGridView() as tgv:
    with tgv.row():
        Label("row")

New TableGridView API

with TableGridView():
    with TableGridRow():
        Label("row")

v1.5.0

Released: 2024-09-20

• New Base Element WindowPopView.

v1.4.0

Released: 2024-09-13

• Hook use_state() new feature initializer function.

v1.3.0

Released: 2024-09-12

• New Hook use_hover().

v1.2.0

Released: 2024-09-10

• Window new prop on_open.

• New utility functions utilities.theme_is_light(), utilities.palette_edifice_light(), utilities.palette_edifice_dark().

• Delete deprecated method App.set_stylesheet.

v1.1.0

Released: 2024-09-05

• SpinInput new prop single_step.

v1.0.0

Released: 2024-08-27

The API and features are pretty stable and reliable now, so this is version 1.

v0.8.1

Released: 2024-08-27

• Bugfix for the Harmonic Oscillator example.

• Change Sphinx theme to pydata-sphinx-theme for documentation.

v0.8.0

Released: 2024-07-27

• New Element: NumpyImage.

• Inspector improvements and debugging.

• Slider on_change event handler prop can be a future.

• children prop type changed to tuple[Element, ...].

  This should get rid of the lint warnings about the argument default [] value.

• Deprecate View, ScrollView.

  Replace View with:

  • HBoxView

  • VBoxView

  • FixView

  Replace ScrollView with:

  • HScrollView

  • VScrollView

  • FixScrollView

We are eliminating the layout= "row" | "column" | "none" prop because it never worked as a prop. If the value of the layout prop was changed then the layout of the View would not change. To render a View(layout="row") and then replace it with a View(layout="column"), it was necessary to add unique set_key() so that the reconciliation algorithm would recognize that the Views needed to be destroyed and recreated. This behavior was buggy and surprising and now it’s gone.

ButtonView is now a subclass of HBoxView. For column layout, put a VBoxView inside the ButtonView.

We have added functions View(), ScrollView() which behave like the old elements of the same name, so that old code will still work, probably. These functions have deprecation warnings at the type level and at runtime, and they will be removed in the future.

v0.7.4

Released: 2024-06-14

• component() composition with children props and child_place().

v0.7.3

Released: 2024-06-12

• View layout="none" remove minimum size 100×100.

v0.7.2

Released: 2024-06-11

• Bugfix View layout="none" added children become visible.

v0.7.1

Released: 2024-06-06

• Prop padding for View layout Elements.

v0.7.0

Released: 2024-06-04

• RadioButton fully declarative checked prop.

• CheckBox fully declarative checked prop.

The state of RadioButton and CheckBox is now dependent only on the checked prop.

This means that RadioButton “grouping” is now fully independent of the parent widget, and only depends on how the checked prop is calculated.

v0.6.2

Released: 2024-05-22

• SpinInput bugfix: Set value after min/max.

v0.6.1

Released: 2024-05-22

• SpinInput bugfix: Block on_change signal while setting min and max value.

v0.6.0

Released: 2024-05-21

• Breaking changes in Dropdown.

  • Option text is not editable.

  • Option selection is index based, not text-based.

v0.5.6

Released: 2024-05-18

• New base element TextInputMultiline.

• Label prop text must be type str.

v0.5.5

Released: 2024-04-30

• bugfix QtWidgetElement on_resize event handler prop.

v0.5.4

Released: 2024-04-29

• CommandType non-private for writing custom QtWidgetElement classes.

• QtWidgetElement on_resize event handler prop.

• enable_mouse_scroll prop for Dropdown.

v0.5.3

Released: 2024-04-22

• SpinInput don’t fire on_change when prop value changes.

• enable_mouse_scroll prop for SpinInput, Slider.

• Inspector bugfix correct source locations for @component.

v0.5.2

Released: 2024-04-01

• New Hook use_effect_final()

• During use_async() CancelledError, allow calling use_state() setter functions without causing re-render of an unmounting component.

v0.5.1

Released: 2024-03-27

• Big reductions in memory leaking from use_state() Hook.

• Bugfix: After App.stop(), don’t run new renders, also don’t schedule new use_async() calls.

v0.5.0

Released: 2024-03-21

• Change event handler props called only on UI interaction.

  On general principle: Widget value change event handler prop functions should only be called when the Widget value changed due to a user interaction, not because the value prop changed.

• Delete props

  • Slider on_move

  • TextInput on_edit

v0.4.5

Released: 2024-03-21

• New props

  • Slider on_move

  • TextInput on_edit

• extra.PyQtPlot instructions for disabling mouse interaction.

v0.4.4

Released: 2024-03-16

• Inspector is working now with use_state().

• Delete StateManager and StateValue.

• Delete all state rollback features.

v0.4.3

Released: 2024-03-06

• TextInput bugfix don’t setText on every render.

• Clean up Python dependencies.

v0.4.2

Released: 2024-02-26

• use_effect() allways run when dependencies is None.

• extra.PyQtPlot disable mouse interaction.

v0.4.1

Released: 2024-02-17

• Rending logic correctness and stability improvements.

• use_async() window close Task done bugfix.

• use_state() will not re-render if state is __eq__ after update.

v0.4.0

Released: 2024-02-08

Major changes to App and the Window

• App

  • App.start_loop() runs the event loop to completion. It no longer requires the user to run the loop. The user should never call loop.run_forever().

  • New method App.stop()

    • Will unmount all Elements.

    • Will call all use_effect() cleanup functions.

    • Will cancel all use_async() tasks and wait until they are cancelled.

• Window

  • Window is a subclass of View and can have multiple children.

  • Window no longer needs an extra View child for hot-reloading to work properly.

  • Qt window on_close event causes App.stop().

Bugfixes:

• use_effect() runs after all the render prop updates.

v0.3.7

Released: 2024-02-06

• Breaking change: Hook use_async_call() returns canceller function in a tuple.

v0.3.6

Released: 2024-02-06

• Hooks use_async() and use_async_call() are manually cancellable.

v0.3.5

Released: 2024-02-03

• use_async() bugfix.

v0.3.4

Released: 2024-01-31

• New Hook use_async_call()

v0.3.3

Released: 2024-01-25

• Internal improvements and typing-extensions requirement.

v0.3.2

Released: 2024-01-22

• Hooks are preserved during hot-reload.

v0.3.1

Released: 2024-01-19

• Hot-reload improvements and bugfixes.

• TableGridView improvements and bugfixes.

v0.3.0

Released: 2023-12-19

• New Base Elements:

  • SpinInput

  • ProgressBar

• QtWidgetElement on_drop event handler.

• Extra Elements

  • extra.MatplotlibFigure

  • extra.PyQtPlot

• Removed numpy dependency.

• Bugfixes in child diffing and reconciliation.

• use_effect() cleanup function can be None.

• Bugfix use_async() cancellation of previous task.

• Base Element Slider only allows integer values.

• Merged Base Elements Image and ImageAspect

• Removed deprecated modules forms, plotting.

• Hot-reload bugfixes.

v0.2.1

Released: 2023-11-14

• ExportList for App.export_widgets().

v0.2.0

Released: 2023-11-13

This version has a lot of breaking changes. We have done essentially the same upgrade that React.js did when they upgraded to function components and Hooks in version 16.8.

• component() render function decorator instead of Component subclass. Renamed old Component to Element. Deprecated the API for users to inherit from Element. Privatized most of the Element API.

• Hooks instead of StateValue and StateManager, which are deprecated.

• New with context manager syntax for declaring children instead of the Element __call__ syntax for declaring children.

• Moved ButtonView, FlowView, ImageAspect, TableGridView to Base Elements.

• Deprecated all Higher-level Components.

• Other miscellaneous improvements.

The old API for writing Elements by inheriting from the Component class, overriding the render() function, and calling self.set_state() has has been deprecated.

A new API for writing Elements with the component() decorator and Hooks has replaced the old API. Most of the old API machinery still exists, but has been hidden from the public API. If you want to upgrade old code to this version but don’t want to completely re-write for the new API, then you can make a few changes and run your old code.

1. Component has been renamed to Element.

2. The Element render() function has been renamed to _render_element(). Most other methods of Element have also been renamed with a prefix underscore. The method set_state() is now _set_state().

3. The StateValue and StateManager can be imported from module edifice.state.

v0.1.2

Released: 2023-10-06

• PropsDict type annotations.

• Documentation and metadata improvements.

v0.1.1

Released: 2023-09-15

• Documentation and metadata improvements.

v0.1.0

Released: 2023-09-14

• Upgrade to PySide6/PyQt6. Deprecate PySide2/PyQt5.

• New Base Component ImageSvg.

• Component Label new props link_open.

• QtWidgetComponent new props size_policy.

• Create the main QEventLoop before the first App render.

• Component Image props src can be a QtGui.QImage.

• Deleted setup.py, added Poetry pyproject.toml.

• App new props qapplication.

• New Higher-level Component: ImageAspect.

• New Higher-level Component: ButtonView.

• New Higher-level Component: FlowView.

• New Higher-level Component: TableGridView.

v0.0.10

Released: 2021-07-15

• Fix deletion from View and ScrollView.

• Add alert and file dialog options.

v0.0.9

Released: 2021-06-20

• Add grid view.

• Bug fix with overriding default mouse events.

• Add global stylesheets.

• Fix label_map.

• Add optional QApplication app name in the App constructor.

• Fix prop comparison of np arrays.

• Add support for keydown and keyup events.

• Fix on_change event for textinput.

v0.0.8

Released: 2021-02-04

Bug fixes for dynamic loading, and clearer error messages for Dropdowns and Sliders.

v0.0.7

Released: 2021-02-02

Bug fixes for checkboxes and forms.

v0.0.6

Released: 2021-01-27

Support for asyncio.

v0.0.5

Released: 2021-01-26

First public release.