vibe.nested_value

Nested Dictionary with Attribute Access.

Defines the NestedValue class, a dictionary subclass allowing nested attribute access (e.g., context.a.b.c) with optional per-instance access tracking. Includes helper functions for creation and manipulation. This is independent of Flask and used by both web UI state and the core engine.

NOTE: This module uses object for values because NestedValue is a transparent wrapper around arbitrary JSON-compatible values (str, int, float, bool, list, dict, None).

SupportsGetItem

Protocol for values supporting item access via getitem.

NestedValue

A dictionary subclass supporting attribute access and primary values.

Supports optional access tracking via a per-instance tracker callback. Assumes non-JSON session serialization (e.g., pickle).

path 

path: str | None

Returns the full dot-notation path to this node.

__init__ 

__init__(initial_data: dict[str, Any] | None = None, _value: object | None = None, _path_segment: str | None = None, _parent: NestedValue | None = None, _source: ValueSource = UNKNOWN, _definition: dict[str, Any] | None = None, _tracker: Callable[[str], None] | None = None) -> None

Initialize the NestedValue.

Parameters:
  • initial_data (dict, default: None ) –

    Dictionary to initialize children from.

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

    The primary value of this node (if it represents a leaf or mixed node).

  • _path_segment (str, default: None ) –

    The key/attribute name used to reach this node from its parent.

  • _parent (NestedValue, default: None ) –

    The parent node.

  • _source (ValueSource, default: UNKNOWN ) –

    Where this value comes from (config, user, placeholder...)

  • _definition (dict[str, Any] | None, default: None ) –

    the type and other metadata about the value (from config.yml)

recursive_update 

recursive_update(source: Mapping[str, Any], valuesource: ValueSource | None = None) -> None

Recursively updates this NestedValue with values from 'source'.

If a key exists in both and both values are NestedValue instances (or the source value is a mapping type compatible with NestedValue), it recursively updates the nested target instance. Otherwise, it replaces/adds the value in this instance using standard setitem behavior (which handles dict->NestedValue conversion).

Parameters:
  • source (Mapping) –

    The dictionary-like object containing updates.

  • valuesource (ValueSource, default: None ) –

    if given, only update values with this source

setitem_noconversion 

setitem_noconversion(key: str, value: object) -> None

Set an item directly without NestedValue conversion.

Use this for internal/context keys (like _alias, _host_template, meta, etc.) that should be stored as plain values, not wrapped in NestedValue nodes.

Note: These ARE stored in the dict (required for Jinja context access), but bypass NestedValue wrapping. They still need to be filtered out during iteration using _INTERNAL_KEYS.

delitem_noconversion 

delitem_noconversion(key: str) -> None

Delete an item set via setitem_noconversion.

__call__ 

__call__(*args: object, **kwargs: object) -> object

Invoke underlying callable value, raising TypeError if not callable.

iter_nested_nodes 

iter_nested_nodes(root: NestedValue, include_internal: bool = False) -> Iterator[tuple[str, NestedValue]]

Depth-first traversal of a NestedValue tree yielding (path, node) pairs.

Parameters:
  • root (NestedValue) –

    The NestedValue root to traverse.

  • include_internal (bool, default: False ) –

    Whether to include internal keys in the traversal.
Yields:
  • tuple[str, NestedValue] –

    Tuple[path, NestedValue]: Path string (dot-notated) and the corresponding node.

iter_leaf_nodes 

iter_leaf_nodes(root: NestedValue, include_internal: bool = False, include_placeholders: bool = True) -> Iterator[tuple[str, NestedValue]]

Iterate only the leaf NestedValue nodes (or probe placeholders) in depth-first order.

flatten_nested_leaves 

flatten_nested_leaves(root: NestedValue, include_internal: bool = False, include_placeholders: bool = True) -> dict[str, Any]

Return a flat mapping from dot-notated paths to stored values for the leaf nodes.

iter_nodes_by_source 

iter_nodes_by_source(root: NestedValue, sources: Iterable[ValueSource], include_internal: bool = False) -> Iterator[tuple[str, NestedValue]]

Yield nodes whose ValueSource is in the provided iterable.

remove_probe_placeholders 

remove_probe_placeholders(root: NestedValue) -> None

Remove keys whose values are probe placeholders from the NestedValue tree.

remove_internal_key 

remove_internal_key(root: NestedValue, key: str) -> None

Remove the specified key from all NestedValue nodes to keep metadata out of stored data.

has_actual_value 

has_actual_value(node: NestedValue | None, sources: Iterable[ValueSource] = _DEFAULT_ACTUAL_VALUE_SOURCES, allow_empty: bool = False) -> bool

Return True if the NestedValue node has a user/computed value (not a placeholder).

When allow_empty is True we treat empty strings or None as intentional answers, as long as the node comes from a tracked source.

has_source 

has_source(node: NestedValue | None, sources: Iterable[ValueSource]) -> bool

Return True if the node exists and its _source is in the provided collection.

clone_nested_value 

clone_nested_value(node: NestedValue, parent: NestedValue | None = None, path_segment: str | None = None, tracker: Callable[[str], None] | None = None) -> NestedValue

Deeply clone a NestedValue tree, preserving metadata.

clear_nested_value_trackers 

clear_nested_value_trackers(node: NestedValue, _visited: set[int] | None = None) -> None

Recursively remove tracker references from a NestedValue tree.

remove_unpicklable_probe_artifacts 

remove_unpicklable_probe_artifacts(node: object, _visited: set[int] | None = None) -> None

Remove unpicklable objects from NestedValue tree after probing.

This includes TrackingUndefined instances and contaminated _definition dicts. Should be called on current_state after probing completes.

remove_unpicklable_rendering_artifacts 

remove_unpicklable_rendering_artifacts(node: NestedValue, _visited: set[int] | None = None) -> None

Remove unpicklable rendering artifacts from NestedValue tree after rendering.

These artifacts are added during DOCX/final document rendering and include: - _docxtpl: DocxTemplate instance with Jinja2 environment - _vfs: VFS instance - meta: MetadataNamespace instance - _host_template: TemplateData with Jinja environment - _current_state: Self-reference (circular) - causes JSON serialization errors - _is_probing: Boolean flag for probe mode - _is_web_preview: Boolean flag for web preview mode

Should be called on current_state after render_final_document completes.

Parameters:
  • node (NestedValue) –

    The NestedValue node to clean

  • _visited (set[int] | None, default: None ) –

    Internal tracking set to handle circular references

create_nested_structure 

create_nested_structure(data_dict: dict[str, Any], default_source: ValueSource = UNKNOWN) -> NestedValue

Recursively converts a standard Python dict into a NestedValue structure.

Parameters:
  • data_dict (dict[str, Any]) –

    Dictionary to convert to NestedValue structure

  • default_source (ValueSource, default: UNKNOWN ) –

    Source type to assign to all created nodes
Returns:
  • NestedValue –

    NestedValue object representing the input dictionary
Raises:
  • TypeError –

    If input is not a dictionary or mapping

set_nested_value 

set_nested_value(root: NestedValue, path_str: str, value: object, source: ValueSource = UNKNOWN, definition: dict[Any, Any] | None = None) -> None

Set a value in a NestedValue structure using dot notation path.

Create intermediate NestedValue nodes if they don't exist. Set the _source and _definition attributes on the leaf node.

Parameters:
  • root (NestedValue) –

    The root NestedValue object to modify

  • path_str (str) –

    The dot-separated path with optional bracket notation (e.g., "a.b.c", "items[0]")

  • value (object) –

    The value to set at the leaf

  • source (ValueSource, default: UNKNOWN ) –

    The origin of this value

  • definition (dict[Any, Any] | None, default: None ) –

    The definition metadata from config.yml
Raises:
  • TypeError –

    If root is not NestedValue or value is NestedValue

  • ValueError –

    If path_str is empty

get_nested_node 

get_nested_node(root: NestedValue, path: str, default: NestedValue | None = None) -> NestedValue | None

Get the NestedValue node instance from a structure using dot notation path.

Parameters:
  • root (NestedValue) –

    The root NestedValue object to traverse

  • path (str) –

    The dot-separated path with optional bracket notation (e.g., "a.b.c", "items[0].name")

  • default (NestedValue | None, default: None ) –

    Value to return if the path is not found
Returns:
  • NestedValue | None –

    The NestedValue node instance found at the path, or the default value

get_nested_value 

get_nested_value(root: NestedValue, path: str, default: object | None = None) -> object

Get a value from a NestedValue structure using dot notation path.

Parameters:
  • root (NestedValue) –

    The root NestedValue object to traverse

  • path (str) –

    The dot-separated path with optional bracket notation (e.g., "a.b.c", "items[0].name")

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

    Value to return if the path or value is not found
Returns:
  • object –

    The value found at the path (extracted from the node's _value), or the default value

nested_to_dict 

nested_to_dict(node: NestedValue | object) -> dict[str, Any] | object

Recursively converts a NestedValue structure back to a standard Python dict.

Parameters:
  • node (NestedValue | object) –

    NestedValue object or other value to convert
Returns:
  • dict[str, Any] | object –

    Dictionary representation of the NestedValue structure, or the original value if not NestedValue

unbox 

unbox(node: NestedValue) -> object

Access the primitive value stored in a NestedValue.

Parameters:
  • node (NestedValue) –

    NestedValue object to extract value from
Returns:
  • object –

    The primitive value stored in the node's _value attribute

pretty_print_nested_value 

pretty_print_nested_value(root: NestedValue, context: str | None = None) -> str

Generate a human-readable depth-first string representation of a NestedValue.

validate_nested_value_structure 

validate_nested_value_structure(root: NestedValue) -> bool

Validate that the NestedValue structure only stores primitives in _value.

Also verify that dictionary children are always NestedValue instances.