vibe.handlers.base

Base Data Type Handler Definition.

Defines the abstract base class DataTypeHandler for all question type handlers. Also includes the HANDLER_REGISTRY and the register_handler decorator and get_handler_for_definition function used to manage and retrieve handlers.

Runtime type checking is enabled via @runtime_checked decorators to ensure handler methods receive and return correct types at data boundaries.

DataTypeHandler

Abstract Base Class for handling specific question data types.

Encapsulates logic for UI rendering, form processing, input validation, placeholders, and creating static checking objects.

Subclasses can set class variables to customize default behavior: - _default_probe_value: Default fallback for get_probe_placeholder() - _validated_value_class: Class to use in create_validated_value()

__init__ 

__init__(definition: dict[str, Any], template_data: object | None = None) -> None

Initialize the handler with the question definition from config.yml.

Parameters:
  • definition (dict) –

    The dictionary defining the question. Should include at least 'type' and 'label'.

  • template_data (object | None, default: None ) –

    Optional template data for context-aware handlers.

get_widget_template_name 

get_widget_template_name() -> str

Return the template name for widget rendering.

Defaults to 'question_types/{type}.html' but can be overridden.

get_base_widget_context 

get_base_widget_context(name: str, current_value: T, error_message: str | None = None) -> dict[str, Any]

Build the base context dictionary common to most widget templates.

Parameters:
  • name (str) –

    HTML name attribute for the input

  • current_value (T) –

    Current value from session

  • error_message (str | None, default: None ) –

    Validation error message to display
Returns:
  • dict[str, Any] –

    Dictionary with common template context

get_additional_widget_context 

get_additional_widget_context(name: str, current_value: T, error_message: str | None = None) -> dict[str, Any]

Add additional context specific to this widget type (hook for subclasses).

Returns:
  • dict[str, Any] –

    Dictionary with additional context to merge with base context

render_simple_widget 

render_simple_widget(name: str, current_value: T, error_message: str | None = None) -> str

Render a simple widget using the common pattern.

Suitable for most basic data types (text, number, bool, date, etc.).

This method: 1. Gets the template using get_widget_template_name() 2. Builds base context using get_base_widget_context() 3. Adds additional context using get_additional_widget_context() 4. Renders and returns the result

Complex handlers can override render_widget() directly for custom behavior.

render_widget 

render_widget(name: str, current_value: T, error_message: str | None = None) -> str

Generate the HTML string for the form widget(s) for this data type.

Runtime type checking ensures name is string and return value is string.

Parameters:
  • name (str) –

    The HTML name attribute for the input(s).

  • current_value (T) –

    The current value from session answers for this question.

  • error_message (str, default: None ) –

    An input validation error message to display.
Returns:
  • str( str ) –

    The HTML string for the widget.

render_followup_widget 

render_followup_widget(followup_id: str, parent_name: str, option_value: str, question_definitions: dict[str, Any], current_answers_root: NestedValue, validation_errors: dict[str, Any], relevant: bool) -> str

Render the HTML for a single followup question widget.

This is called from widget templates (via the shared _followup_containers.html include) to render each followup question nested inside the parent widget.

process_form_data 

process_form_data(name: str, form_data: MultiDictLike) -> T

Extract the relevant value(s) from form data and perform basic type coercion.

Coerce into the appropriate Python type (str, int, bool, dict, etc.). Does NOT perform instance-specific input validation (e.g., regex).

Runtime type checking ensures name is string.

Parameters:
  • name (str) –

    The base name of the form field(s).

  • form_data (MultiDict) –

    The form data from the request.
Returns:
  • T –

    The coerced value in its Python type representation, or None if

  • T –

    the value is missing/empty and not considered significant (e.g.,

  • T –

    empty string for optional text, failed coercion for number).

  • T –

    For multichoice, returns the dict even if all False.

validate_input 

validate_input(value: T, check_required: bool = True) -> str | None

Perform instance-specific input validation on the COERCED value.

Check defined constraints like required status, patterns, min/max etc.

Runtime type checking ensures check_required is bool and return is Optional[str].

Parameters:
  • value (T) –

    The coerced Python value obtained from process_form_data.

  • check_required (bool, default: True ) –

    If True, validates the 'required' constraint.
Returns:
  • str( str | None ) –

    A user-friendly error message string if validation fails.

  • None( str | None ) –

    If validation passes.

get_probe_placeholder 

get_probe_placeholder() -> object

Return the placeholder value for template probing when this variable is Undefined.

Should be 'falsy' but structurally correct for the type.

Default implementation uses _default_probe_value class variable. Override for complex types that need custom placeholder logic.

get_preview_placeholder_value 

get_preview_placeholder_value() -> str

Return the value for preview render when this variable is unanswered.

Can be more user-friendly than the probe placeholder.

create_validated_value 

create_validated_value(value_for_analysis: object, reporter: Callable[[ValidationIssue], None]) -> ValidatedValue

Create and return the corresponding ValidatedValue subclass for static checking.

Parameters:
  • value_for_analysis (object) –

    A representative default value for static analysis.

  • reporter (Callable[[ValidationIssue], None]) –

    Callback function to report validation issues.
Returns:
  • ValidatedValue( ValidatedValue ) –

    An instance of a ValidatedValue subclass.

Default implementation uses _validated_value_class class variable. Override for complex types that need custom ValidatedValue logic.

supports_structured_access 

supports_structured_access() -> bool

Return True if the handler exposes dotted sub-fields in templates.

get_structured_access_fields 

get_structured_access_fields() -> set[str] | None

Return the supported top-level sub-field names, if known.

register_handler 

register_handler(type_name: str) -> Callable[[type[HandlerT]], type[HandlerT]]

Register a DataTypeHandler class for a given type name.