pyqt_reactive.protocols

Widget protocol definitions and adapters.

ABC-based widget contracts that eliminate duck typing in favor of explicit, fail-loud inheritance-based architecture.

class pyqt_reactive.protocols.ValueGettable

ABC for widgets that can return a value.

All input widgets must implement this to participate in form value extraction.

abstractmethod get_value() → Any

Get the current value from the widget.

Returns:

The widget’s current value. None if no value set.

class pyqt_reactive.protocols.ValueSettable

ABC for widgets that can accept a value.

All input widgets must implement this to participate in form value updates.

abstractmethod set_value(value: Any) → None

Set the widget’s value.

Parameters:

value – The value to set. None clears the widget.

class pyqt_reactive.protocols.PlaceholderCapable

ABC for widgets that can display placeholder text.

Placeholders show inherited/default values without setting actual values.

abstractmethod set_placeholder(text: str) → None

Set placeholder text for the widget.

Parameters:

text – Placeholder text to display (e.g., “Pipeline default: 42”)

class pyqt_reactive.protocols.RangeConfigurable

ABC for widgets that support numeric range configuration.

Typically implemented by numeric input widgets (spinboxes, sliders).

abstractmethod configure_range(minimum: float, maximum: float) → None

Configure the valid range for numeric input.

Parameters:

• minimum – Minimum allowed value

• maximum – Maximum allowed value

class pyqt_reactive.protocols.EnumSelectable

ABC for widgets that can select from enum values.

Typically implemented by dropdowns and radio button groups.

abstractmethod set_enum_options(enum_type: type) → None

Configure widget with enum options.

Parameters:

enum_type – The Enum class to populate options from

abstractmethod get_selected_enum() → Any

Get the currently selected enum value.

Returns:

The selected enum member, or None if no selection

class pyqt_reactive.protocols.ChangeSignalEmitter

ABC for widgets that emit change signals.

Provides explicit contract for signal connection, eliminating duck typing of signal names (textChanged vs valueChanged vs currentIndexChanged).

abstractmethod connect_change_signal(callback: Callable[[Any], None]) → None

Connect callback to widget’s change signal.

The callback will be invoked whenever the widget’s value changes, receiving the new value as its argument.

Parameters:

callback – Function to call when widget value changes. Signature: callback(new_value: Any) -> None

abstractmethod disconnect_change_signal(callback: Callable[[Any], None]) → None

Disconnect callback from widget’s change signal.

Parameters:

callback – The callback function to disconnect

class pyqt_reactive.protocols.LineEditAdapter

Adapter for QLineEdit implementing OpenHCS ABCs.

Normalizes Qt API to OpenHCS contracts: - .text() → .get_value() - .setText() → .set_value() - .setPlaceholderText() → .set_placeholder() - .textChanged → .connect_change_signal()

get_value() → Any

Implement ValueGettable ABC.

set_value(value: Any) → None

Implement ValueSettable ABC.

set_placeholder(text: str) → None

Implement PlaceholderCapable ABC.

connect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

disconnect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

class pyqt_reactive.protocols.SpinBoxAdapter(parent=None)

Adapter for QSpinBox implementing OpenHCS ABCs.

Handles None values using special value text mechanism. When value is None, displays placeholder text at minimum value.

__init__(parent=None)

get_value() → Any

Implement ValueGettable ABC.

set_value(value: Any) → None

Implement ValueSettable ABC.

set_placeholder(text: str) → None

Implement PlaceholderCapable ABC.

configure_range(minimum: float, maximum: float) → None

Implement RangeConfigurable ABC.

connect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

disconnect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

class pyqt_reactive.protocols.DoubleSpinBoxAdapter(parent=None)

Adapter for QDoubleSpinBox implementing OpenHCS ABCs.

Handles None values and floating-point ranges.

__init__(parent=None)

get_value() → Any

Implement ValueGettable ABC.

set_value(value: Any) → None

Implement ValueSettable ABC.

set_placeholder(text: str) → None

Implement PlaceholderCapable ABC.

configure_range(minimum: float, maximum: float) → None

Implement RangeConfigurable ABC.

connect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

disconnect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

class pyqt_reactive.protocols.ComboBoxAdapter

Adapter for QComboBox implementing OpenHCS ABCs.

Stores actual values in itemData, not just display text. Supports enum population and selection.

get_value() → Any

Implement ValueGettable ABC.

set_value(value: Any) → None

Implement ValueSettable ABC.

set_placeholder(text: str) → None

Implement PlaceholderCapable ABC.

populate_enum(enum_type: type) → None

Populate combobox with enum values.

Parameters:

enum_type – The Enum class to populate from

connect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

disconnect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

class pyqt_reactive.protocols.CheckBoxAdapter

Adapter for QCheckBox implementing OpenHCS ABCs.

Returns bool values, treats None as False.

get_value() → Any

Implement ValueGettable ABC.

set_value(value: Any) → None

Implement ValueSettable ABC.

connect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

disconnect_change_signal(callback: Callable[[Any], None]) → None

Implement ChangeSignalEmitter ABC.

class pyqt_reactive.protocols.PyQtWidgetMeta(name, bases, namespace, /, **kwargs)

Metaclass for PyQt widgets that need ABC support.

class pyqt_reactive.protocols.FunctionRegistryProtocol(*args, **kwargs)

Protocol for function registries that provide function lookup and metadata.

Applications can implement this protocol to provide their own function registry.

Example

from pyqt_reactive.protocols import register_function_registry from myapp.registry import MyFunctionRegistry

register_function_registry(MyFunctionRegistry())

get_function_by_name(name: str) → Callable | None

Get function by name.

Parameters:

name – Function name to lookup

Returns:

Function callable if found, None otherwise

get_all_functions() → Dict[str, Callable]

Get all registered functions.

Returns:

Dictionary mapping function names to callables

get_function_metadata(name: str) → Dict[str, Any] | None

Get metadata for a function.

Parameters:

name – Function name

Returns:

Metadata dict if available, None otherwise

__init__(*args, **kwargs)

pyqt_reactive.protocols.register_function_registry(registry: FunctionRegistryProtocol) → None

Register a function registry implementation.

Parameters:

registry – Object implementing FunctionRegistryProtocol

pyqt_reactive.protocols.get_function_registry() → FunctionRegistryProtocol | None

Get the registered function registry.

Returns:

Registered registry or None if not registered

class pyqt_reactive.protocols.PreviewFormatterRegistry

Registry for preview formatters by config type.

Applications can register formatters for specific config types to customize how fields are displayed in list item previews.

Example

from pyqt_reactive.protocols import PreviewFormatterRegistry

def format_zarr_config(config, field_name):

if field_name == ‘compression’:

return f”comp={config.compression[:3]}” # Abbreviate

return str(getattr(config, field_name))

PreviewFormatterRegistry.register(ZarrConfig, format_zarr_config)

classmethod register(config_type: Type, formatter: Callable[[Any, str], str]) → None

Register a formatter for a config type.

Parameters:

• config_type – Config class to format

• formatter – Formatter function taking (config, field_name) -> str

classmethod get_formatter(config_type: Type) → Callable[[Any, str], str] | None

Get formatter for a config type.

Parameters:

config_type – Config class

Returns:

Formatter function if registered, None otherwise

classmethod format_field(config: Any, field_name: str) → str | None

Format a field using registered formatter if available.

Parameters:

• config – Config instance

• field_name – Field name to format

Returns:

Formatted string if formatter available, None otherwise

pyqt_reactive.protocols.register_preview_formatter(config_type: Type, formatter: Callable[[Any, str], str]) → None

Register a preview formatter for a config type.

Parameters:

• config_type – Config class

• formatter – Formatter function

class pyqt_reactive.protocols.FormGenConfig(enable_placeholder_styling: bool = True, enable_help_buttons: bool = True, enable_inheritance_tracking: bool = True, custom_widget_factories: Type, ~typing.Any]=<factory>, jedi_project_paths: List[str] = <factory>, log_dir: str | None = None, log_prefixes: List[str] = <factory>, log_root_logger_name: str | None = None, performance_logger_name: str = 'pyqt_reactive.performance', performance_log_filename: str = 'performance.log', path_cache_file: str | None = None)

Base configuration for form generation behavior.

Applications can subclass this to provide custom configuration.

enable_placeholder_styling

Whether to apply special styling to placeholder values

Type:

bool

enable_help_buttons

Whether to show help buttons for fields with docstrings

Type:

bool

enable_inheritance_tracking

Whether to show inheritance source indicators

Type:

bool

custom_widget_factories

Custom widget factories by type

Type:

Dict[Type, Any]

enable_placeholder_styling: bool = True

enable_help_buttons: bool = True

enable_inheritance_tracking: bool = True

custom_widget_factories: Dict[Type, Any]

jedi_project_paths: List[str]

log_dir: str | None = None

log_prefixes: List[str]

log_root_logger_name: str | None = None

performance_logger_name: str = 'pyqt_reactive.performance'

performance_log_filename: str = 'performance.log'

path_cache_file: str | None = None

__init__(enable_placeholder_styling: bool = True, enable_help_buttons: bool = True, enable_inheritance_tracking: bool = True, custom_widget_factories: Type, ~typing.Any]=<factory>, jedi_project_paths: List[str] = <factory>, log_dir: str | None = None, log_prefixes: List[str] = <factory>, log_root_logger_name: str | None = None, performance_logger_name: str = 'pyqt_reactive.performance', performance_log_filename: str = 'performance.log', path_cache_file: str | None = None) → None

pyqt_reactive.protocols.set_form_config(config: FormGenConfig) → None

Set the global form generation configuration.

Parameters:

config – FormGenConfig instance

pyqt_reactive.protocols.get_form_config() → FormGenConfig

Get the current form generation configuration.

Returns:

Current FormGenConfig or default if not set

class pyqt_reactive.protocols.LLMServiceProtocol(*args, **kwargs)

Protocol for LLM services used by LLMChatPanel.

api_endpoint: str

model: str | None

test_connection() → Tuple[bool, str]

Return (is_connected, status_message).

generate_code(request: str, code_type: str | None = None) → str

Generate code for a request and optional code type.

__init__(*args, **kwargs)

pyqt_reactive.protocols.register_llm_service(service: LLMServiceProtocol) → None

Register a global LLM service implementation.

pyqt_reactive.protocols.get_llm_service() → LLMServiceProtocol | None

Get the registered LLM service implementation.

class pyqt_reactive.protocols.CodegenProvider(*args, **kwargs)

Protocol for code generators used by the simple code editor.

generate_complete_orchestrator_code(plate_paths: list[str], pipeline_data: dict, global_config: Any | None = None, per_plate_configs: dict | None = None, pipeline_config: Any | None = None, clean_mode: bool = True) → str

generate_complete_pipeline_steps_code(pipeline_steps: list[Any], clean_mode: bool = True) → str

generate_complete_function_pattern_code(func_obj: Any, clean_mode: bool = False) → str

generate_config_code(config_obj: Any, clean_mode: bool = True, config_class: type | None = None) → str

generate_step_code(step_obj: Any, clean_mode: bool = True) → str

__init__(*args, **kwargs)

pyqt_reactive.protocols.register_codegen_provider(provider: CodegenProvider) → None

Register a global code generation provider.

pyqt_reactive.protocols.get_codegen_provider() → CodegenProvider | None

Get the registered code generation provider.

class pyqt_reactive.protocols.LogDiscoveryProvider(*args, **kwargs)

Protocol for discovering log files and current log path.

get_current_log_path() → Path

Return current log file path.

discover_logs(base_log_path: str | None = None, include_main_log: bool = True, log_directory: Path | None = None) → List[LogFileInfo]

Return discovered logs.

__init__(*args, **kwargs)

class pyqt_reactive.protocols.ServerScanProvider(*args, **kwargs)

Protocol for discovering server logs (e.g., via port scans).

scan_for_server_logs() → List[LogFileInfo]

Return logs discovered from live servers.

__init__(*args, **kwargs)

pyqt_reactive.protocols.register_log_discovery_provider(provider: LogDiscoveryProvider) → None

Register a global log discovery provider.

pyqt_reactive.protocols.get_log_discovery_provider() → LogDiscoveryProvider | None

Get the registered log discovery provider.

pyqt_reactive.protocols.register_server_scan_provider(provider: ServerScanProvider) → None

Register a global server scan provider.

pyqt_reactive.protocols.get_server_scan_provider() → ServerScanProvider | None

Get the registered server scan provider.

class pyqt_reactive.protocols.WindowFactoryProtocol(*args, **kwargs)

Protocol for creating windows for a given scope.

Use this for duck-typed checking. For implementation, prefer WindowFactoryABC.

create_window_for_scope(scope_id: str, object_state: Any | None = None) → QWidget | None

Create and show a window for the given scope id.

__init__(*args, **kwargs)

class pyqt_reactive.protocols.WindowFactoryABC

Abstract base class for window factories.

Subclass this to implement application-specific window creation logic. The factory is responsible for: - Parsing scope_id format to determine window type - Creating the appropriate window class - Showing and activating the window

abstractmethod create_window_for_scope(scope_id: str, object_state: Any | None = None) → QWidget | None

Create and show a window for the given scope_id.

Parameters:

• scope_id – Scope identifier. Format is application-specific, e.g.: - “” (empty string): Global config - “/path/to/item”: Item-level config - “/path/to/item::sub”: Nested scope

• object_state – Optional ObjectState for time-travel restore

Returns:

The created window, or None if creation failed/skipped

pyqt_reactive.protocols.register_window_factory(factory: WindowFactoryProtocol) → None

Register a global window factory.

Parameters:

factory – Factory instance implementing WindowFactoryProtocol or WindowFactoryABC

pyqt_reactive.protocols.get_window_factory() → WindowFactoryProtocol | None

Get the registered window factory.

class pyqt_reactive.protocols.ComponentSelectionProvider(*args, **kwargs)

Protocol for component selection and display metadata.

get_groupby_enum() → Any

Return the GroupBy enum (or compatible enum) used by the host app.

get_component_keys(group_by: Any) → List[str]

Return available component keys for a given group_by.

has_components_available(group_by: Any) → bool

Check if components are available for the given group_by without fetching them all.

Used to determine if UI elements (like component selection buttons) should be enabled. Should return False if the underlying data source (e.g., orchestrator) is not ready.

get_component_display_name(group_by: Any, component_key: str) → str | None

Return a human-readable name for a component key.

select_components(available_components: Iterable[str], selected_components: Iterable[str], group_by: Any, parent: Any | None = None, **context: Any) → List[str] | None

Show selection UI and return chosen components (or None if canceled).

__init__(*args, **kwargs)

class pyqt_reactive.protocols.FunctionSelectionProvider(*args, **kwargs)

Protocol for selecting a function in UI.

select_function(parent: Any | None = None, **context: Any) → Callable | None

Return a selected function or None.

__init__(*args, **kwargs)

pyqt_reactive.protocols.register_component_selection_provider(provider: ComponentSelectionProvider) → None

Register a global component selection provider.

pyqt_reactive.protocols.get_component_selection_provider() → ComponentSelectionProvider | None

Get the registered component selection provider.

pyqt_reactive.protocols.register_function_selection_provider(provider: FunctionSelectionProvider) → None

Register a global function selection provider.

pyqt_reactive.protocols.get_function_selection_provider() → FunctionSelectionProvider | None

Get the registered function selection provider.

Modules

codegen_provider	Code generation provider protocol for app-specific code emitters.
component_selection	Component and function selection provider protocols.
form_config	Base configuration class for form generation.
function_registry	Function registry protocol for pluggable function lookup.
llm_service	LLM service protocol for pluggable code generation backends.
log_providers	Protocols for log discovery and server scanning.
preview_formatter	Preview formatter registry for customizable list item previews.
widget_adapters	Widget adapters that wrap Qt widgets to implement OpenHCS ABCs.
widget_protocols	Widget ABC contracts for OpenHCS UI frameworks.
window_factory	Window factory protocol and ABC for creating scope-aware windows.
zmq_server_protocol	ZMQ server protocol abstractions for generic server browser widgets.