pyqt_reactive.forms.parameter_form_service

Shared service layer for parameter form managers.

This module provides a framework-agnostic service layer that eliminates the architectural dependency between PyQt and Textual implementations by providing shared business logic and data management.

Uses React-style discriminated unions for type-safe parameter handling.

Classes

FormStructure(field_id, parameters, nested_forms)	Structure information for a parameter form.
ParameterAnalysisInput(default_value, ...[, ...])	Type-safe input for parameter analysis.
ParameterFormService()	Framework-agnostic service for parameter form business logic.

class pyqt_reactive.forms.parameter_form_service.ParameterAnalysisInput(default_value: Dict[str, Any], param_type: Dict[str, Type], field_id: str, description: Any | None = None, parent_obj_type: Type | None = None)

Type-safe input for parameter analysis.

Field names match UnifiedParameterInfo for automatic extraction. This enforces unification across all functions that analyze parameters.

default_value: Dict[str, Any]

param_type: Dict[str, Type]

field_id: str

description: Any | None = None

parent_obj_type: Type | None = None

__init__(default_value: Dict[str, Any], param_type: Dict[str, Type], field_id: str, description: Any | None = None, parent_obj_type: Type | None = None) → None

class pyqt_reactive.forms.parameter_form_service.FormStructure(field_id: str, parameters: List[OptionalDataclassInfo | DirectDataclassInfo | GenericInfo], nested_forms: Dict[str, FormStructure], has_optional_dataclasses: bool = False)

Structure information for a parameter form.

Uses discriminated union ParameterInfo types for type-safe dispatch.

field_id

Unique identifier for the form

Type:

str

parameters

List of parameter information (discriminated union types)

Type:

List[pyqt_reactive.forms.parameter_info_types.OptionalDataclassInfo | pyqt_reactive.forms.parameter_info_types.DirectDataclassInfo | pyqt_reactive.forms.parameter_info_types.GenericInfo]

nested_forms

Dictionary of nested form structures

Type:

Dict[str, pyqt_reactive.forms.parameter_form_service.FormStructure]

has_optional_dataclasses

Whether form has optional dataclass parameters

Type:

bool

field_id: str

parameters: List[OptionalDataclassInfo | DirectDataclassInfo | GenericInfo]

nested_forms: Dict[str, FormStructure]

has_optional_dataclasses: bool = False

get_parameter_info(param_name: str) → OptionalDataclassInfo | DirectDataclassInfo | GenericInfo | None

Get ParameterInfo for a parameter by name.

Parameters:

param_name – Name of the parameter

Returns:

ParameterInfo instance (discriminated union type) or None if not found

Note

Returns None for parameters like ‘enabled’ that are rendered in header and not part of the regular form structure.

__init__(field_id: str, parameters: List[OptionalDataclassInfo | DirectDataclassInfo | GenericInfo], nested_forms: Dict[str, FormStructure], has_optional_dataclasses: bool = False) → None

class pyqt_reactive.forms.parameter_form_service.ParameterFormService

Framework-agnostic service for parameter form business logic.

This service provides shared functionality for both PyQt and Textual parameter form managers, eliminating the need for cross-framework dependencies and providing a clean separation of concerns.

__init__()

Initialize the parameter form service.

analyze_parameters(input: ParameterAnalysisInput) → FormStructure

Analyze parameters and create form structure.

This method analyzes the parameters and their types to create a complete form structure that can be used by any UI framework.

Parameters:

input – Type-safe parameter analysis input (field names match UnifiedParameterInfo)

Returns:

Complete form structure information

convert_value_to_type(value: Any, param_type: Type, param_name: str, obj_type: Type = None) → Any

Convert a value to the appropriate type for a parameter.

This method provides centralized type conversion logic that can be used by any UI framework.

Parameters:

• value – The value to convert

• param_type – The target parameter type

• param_name – The parameter name (for debugging)

• obj_type – The dataclass type (for sibling inheritance checks)

Returns:

The converted value

get_parameter_display_info(param_name: str, param_type: Type, description: str | None = None) → Dict[str, str]

Get display information for a parameter.

Parameters:

• param_name – The parameter name

• param_type – The parameter type

• description – Optional parameter description

Returns:

Dictionary with display information

format_widget_name(field_path: str, param_name: str) → str

Convert field path to widget name - replaces generate_field_ids() complexity

get_field_path_with_fail_loud(parent_type: Type, param_type: Type) → str

Get field path using simple field name matching.

generate_field_ids_direct(base_field_id: str, param_name: str) → Dict[str, str]

Generate field IDs directly without artificial complexity.

validate_field_path_mapping()

Ensure all form field_ids map correctly to context fields

should_use_concrete_values(current_value: Any, is_global_editing: bool = False) → bool

Determine whether to use concrete values for a dataclass parameter.

Parameters:

• current_value – The current parameter value

• is_global_editing – Whether in global configuration editing mode

Returns:

True if concrete values should be used

extract_nested_parameters(dataclass_instance: Any, obj_type: Type, parent_obj_type: Type | None = None) → Tuple[Dict[str, Any], Dict[str, Type]]

Extract parameters and types from a dataclass instance.

This method always preserves concrete field values when a dataclass instance exists, regardless of parent context. Placeholder behavior is handled at the widget level, not by discarding concrete values during parameter extraction.

get_placeholder_text(param_name: str, obj_type: Type, placeholder_prefix: str = 'Pipeline default') → str | None

Get placeholder text using existing OpenHCS infrastructure.

Context must be established by the caller using config_context() before calling this method. This allows the caller to build proper context stacks (parent + overlay) for accurate placeholder resolution.

Parameters:

• param_name – Name of the parameter to get placeholder for

• obj_type – The specific dataclass type (GlobalPipelineConfig or PipelineConfig)

• placeholder_prefix – Prefix for the placeholder text

Returns:

Formatted placeholder text or None if no resolution possible

The editing mode is automatically derived from the dataclass type’s lazy resolution capabilities: - Has lazy resolution (PipelineConfig) → orchestrator config editing - No lazy resolution (GlobalPipelineConfig) → global config editing

reset_nested_managers(nested_managers: Dict[str, Any], obj_type: Type, current_config: Any) → None

Reset all nested managers - fail loud, no defensive programming.

get_reset_value_for_parameter(param_name: str, param_type: Type, obj_type: Type, is_global_config_editing: bool | None = None) → Any

Get appropriate reset value using existing OpenHCS patterns.

Parameters:

• param_name – Name of the parameter to reset

• param_type – Type of the parameter (int, str, bool, etc.)

• obj_type – The specific dataclass type

• is_global_config_editing – Whether we’re in global config editing mode (auto-detected if None)

Returns:

Actual default values - For lazy config editing: None to show placeholder text

Return type:

• For global config editing