pyqt_reactive.core

Core PyQt6 utilities.

Pure PyQt6 utility components with zero external dependencies. Foundational widgets and helpers with no domain-specific logic.

class pyqt_reactive.core.DebounceTimer(delay_ms: int, handler: Callable[[], None])

Reusable trailing debounce timer.

Restarts timer on each call. Handler fires only after delay_ms of inactivity.

Usage:

self._debounce = DebounceTimer(delay_ms=200, handler=self._do_update)

def on_text_changed(self):

self._debounce.trigger() # Restarts timer

__init__(delay_ms: int, handler: Callable[[], None])

trigger()

Trigger debounce — restarts timer.

cancel()

Cancel pending trigger.

force()

Cancel timer and fire handler immediately.

class pyqt_reactive.core.ReorderableListWidget(parent=None)

Custom QListWidget that properly handles drag and drop reordering.

Emits a signal when items are moved so the parent can update the data model. This is a shared implementation used by both PipelineEditor and PlateManager.

items_reordered

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:

pyqtSignal(*types, name

Type:

str = …, revision

__init__(parent=None)

Initialize reorderable list widget.

Parameters:

parent – Parent widget

dropEvent(event)

Handle drop event and emit signal with indices.

class pyqt_reactive.core.BackgroundTask(target: Callable[[...], Any], args: Tuple = (), kwargs: dict = None, debounce_ms: int = 0, parent=None)

Unified background task with cancellation, debounce, and cleanup.

Usage:

task = BackgroundTask(target=my_func, args=(a, b)) task.result_ready.connect(on_success) task.error_occurred.connect(on_error) # Receives Exception, not str task.start()

# Later: task.cancel() # Safe cancellation

Error handling:

def on_error(e: Exception):

logger.exception(“Failed”, exc_info=e) # Full traceback show_message(str(e)) # User-friendly string if isinstance(e, TimeoutError): … # Type checking

result_ready

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:

pyqtSignal(*types, name

Type:

str = …, revision

error_occurred

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:

pyqtSignal(*types, name

Type:

str = …, revision

__init__(target: Callable[[...], Any], args: Tuple = (), kwargs: dict = None, debounce_ms: int = 0, parent=None)

run()

Execute target in background, respecting cancellation.

cancel()

Cancel task — signals won’t emit after this.

class pyqt_reactive.core.BackgroundTaskManager

Manages background task lifecycle for a widget.

Handles: - Cancelling previous task before starting new one - Cleanup on widget close - Debounce across rapid calls - Button state management (disable during operation, auto-restore)

Usage in widget:

self._task_manager = BackgroundTaskManager()

def refresh_data(self):

self._task_manager.run(

target=self.service.fetch_data, args=(self.query,), button=self.refresh_button, button_loading_text=”Loading…”, on_success=self._on_data_ready, on_error=self._on_error, debounce_ms=200

)

def closeEvent(self, event):

self._task_manager.cleanup() super().closeEvent(event)

__init__()

run(target: Callable[[...], Any], args: Tuple = (), kwargs: dict = None, on_success: Callable[[Any], None] = None, on_error: Callable[[Exception], None] = None, debounce_ms: int = 0, button: QPushButton = None, button_loading_text: str = None) → BackgroundTask | None

Run a background task, cancelling any previous one.

Parameters:

• target – Function to execute in background

• args – Positional arguments for target

• kwargs – Keyword arguments for target

• on_success – Callback for successful result

• on_error – Callback for error (receives Exception, not str)

• debounce_ms – Minimum time between runs (skip if too soon)

• button – Button to disable during operation (auto-restored on complete)

• button_loading_text – Text while loading (default: original + “…”)

Returns:

BackgroundTask if started, None if debounced out

cleanup()

Cancel and wait for current task. Call from closeEvent.

class pyqt_reactive.core.CollapsibleSplitterHelper(splitter: QSplitter, left_panel_index: int = 0)

Helper for adding double-click toggle to splitter handles.

__init__(splitter: QSplitter, left_panel_index: int = 0)

Initialize the collapsible splitter helper.

Parameters:

• splitter – The QSplitter to make collapsible

• left_panel_index – Index of the left panel (default 0)

toggle_visibility()

Toggle left panel visibility by collapsing/expanding.

set_initial_size(size: int)

Set the initial size to remember when collapsed.

class pyqt_reactive.core.RichTextAppender(text_edit: QTextEdit, color_scheme: ColorScheme = None)

Utility for appending HTML content to QTextEdit with proper cursor/scroll handling.

Usage:

appender = RichTextAppender(self.chat_history, color_scheme=self.color_scheme) appender.append_html(“<b>User:</b> Hello”) appender.append_code(“def foo(): pass”) appender.append_error(“Something went wrong”)

__init__(text_edit: QTextEdit, color_scheme: ColorScheme = None)

append_html(html_content: str, add_spacing: bool = True)

Append HTML content at end, scroll to bottom.

Parameters:

• html_content – HTML string to append

• add_spacing – Whether to add blank line after

append_text(text: str, bold: bool = False, color: str | None = None)

Append plain text (escaped) with optional styling.

Parameters:

• text – Plain text to append

• bold – Whether to make text bold

• color – Optional text color (hex)

append_code(code: str, language: str = None)

Append code block with border styling.

Parameters:

• code – Code string to display

• language – Optional language hint (for future syntax highlighting)

append_error(message: str)

Append error message in red.

append_success(message: str)

Append success message in green.

clear()

Clear all content.

Modules

background_task	Unified background task with cancellation, debounce, and cleanup.
code_generator	Code generation compatibility layer.
collapsible_splitter_helper	Shared helper for making splitters collapsible with double-click toggle.
debounce_timer	Reusable trailing debounce timer.
log_utils	Core Log Utilities for pyqt-reactor.
path_cache	Unified Path Cache System
performance_monitor	Performance monitoring utilities for pyqt-reactor.
reorderable_list_widget	Shared reorderable QListWidget for drag-and-drop reordering.
rich_text_appender	Utility for appending HTML content to QTextEdit with proper cursor/scroll handling.
sort_utils	Sorting utilities.