vibe.web.utils

Shared utility functions for the web routing layer.

InvalidSessionException

Custom exception for sessions being mismatched with the currently requested template, or otherwise invalid.

TemplateLoadError

Custom exception for errors during template loading in routes.

Attributes:
  • issues –

    List of ValidationIssue objects providing detailed error information

make_unauthorized_response 

make_unauthorized_response(reason: str) -> Response

Return a 401 response with detail only when debug mode is active.

In production, clients see a generic "Unauthorized" body so that error messages don't leak implementation details. In debug mode the full reason string is returned together with a synthetic stack trace to make it easy to locate the call site.

get_session_template_data 

get_session_template_data(template_id_expected: str, version_id_expected: str | None, validate_session: bool = True) -> TemplateData

Fetch template data for the expected template/version, and optionally validate session.

Parameters:
  • template_id_expected (str) –

    The template ID that should match the session

  • version_id_expected (str | None) –

    The expected version ID, or None to use session version

  • validate_session (bool, default: True ) –

    Whether to validate that session matches expected template/version
Returns:
  • TemplateData –

    TemplateData object for the requested template and version
Raises:

extract_condition_string 

extract_condition_string(source_lines: list[str], condition_lineno: int) -> str | None

Extract the Jinja expression from an {% if/elif/for ... %} tag.

Parameters:
  • source_lines (list[str]) –

    List of source code lines from the template

  • condition_lineno (int) –

    Line number (1-based) where the condition is located
Returns:
  • str | None –

    The extracted condition string, or None if not found or invalid

resolve_template_and_local_path 

resolve_template_and_local_path(template_data: TemplateData, question_path: str) -> tuple[TemplateData, str]

Resolve which template a namespaced question belongs to.

Parameters:
  • template_data (TemplateData) –

    The root template data to start resolution from

  • question_path (str) –

    The namespaced question path (e.g., "_components.alias.question")
Returns:
  • tuple[TemplateData, str] –

    Tuple of (resolved_template_data, local_question_path) where the question is defined

handle_route_exception 

handle_route_exception(e: Exception, template_id_for_error_display: str, version_for_error_display: str, is_htmx_request: bool, is_eventstream: bool) -> Response

Handle common exception scenarios for routes, log the error, and prepare an appropriate Flask response.

Parameters:
  • e (Exception) –

    The exception that was raised

  • template_id_for_error_display (str) –

    Template ID to include in error logging

  • version_for_error_display (str) –

    Version ID to include in error logging

  • is_htmx_request (bool) –

    Whether this is an HTMX request for response formatting

  • is_eventstream (bool) –

    Whether this is an EventSource/SSE request (auto-detected if None)
Returns:
  • Response –

    Flask Response object with appropriate status code and error message

get_complete_question_definitions 

get_complete_question_definitions(host_template_data: TemplateData) -> dict[str, Any]

Create an augmented dictionary of block definitions including all component questions.

Parameters:
  • host_template_data (TemplateData) –

    The main template data containing components and questions
Returns:
  • dict[str, Any] –

    Dictionary containing all question definitions from host and components with proper namespacing