vibe.appendices

Appendices System for VIBE.

This module implements the core appendices functionality that allows templates to generate separate documents like appendices, annexes, or schedules.

Key Components: - AppendixReference: Lightweight reference object returned by appendix() calls - AppendixManager: Request-scoped manager for tracking and numbering appendices

Note: the user-facing appendix() function is in functions.py alongside insert()2

AppendixReference

Lightweight reference object returned by appendix() calls.

Provides access to appendix properties like numbering and label through the appendix manager.

This object is what template authors get when they call:

numbering 

numbering: str

Get the hierarchical numbering for this appendix (e.g., 'A', 'B.1').

label 

label: str

Get the label from the component's configuration.

component_id 

component_id: str

Get the component ID.

AppendixManager

Request-scoped manager for tracking appendices and calculating numbering.

This manager: - Tracks all appendices registered during template rendering - Builds a tree structure for hierarchical numbering - Calculates numbering schemes once after template completion - Caches numbering results for fast O(1) lookups - Detects circular dependencies - Stores rendered content for each appendix

__init__ 

__init__(numbering_style: str = 'alpha') -> None

Initialize the appendix manager.

Parameters:
  • numbering_style (str, default: 'alpha' ) –

    Default numbering style ('alpha', 'numeric', 'roman')

register_appendix 

register_appendix(appendix_ref: AppendixReference) -> None

Register an appendix with the manager.

Parameters:
Raises:
  • ValueError –

    If alias conflicts with different component_id or circular dependency detected

get_numbering 

get_numbering(alias: str) -> str

Get the hierarchical numbering for an appendix.

Parameters:
  • alias (str) –

    The appendix alias
Returns:
  • str –

    The numbering string (e.g., 'A', 'B.1', 'C.2.1')

get_label 

get_label(alias: str) -> str

Get the label for an appendix from its component configuration.

Parameters:
  • alias (str) –

    The appendix alias
Returns:
  • str –

    The component's label or the component ID as fallback

get_all_appendices 

get_all_appendices() -> list[AppendixReference]

Get all registered appendices in registration order.

get_root_appendices 

get_root_appendices() -> list[AppendixReference]

Get root appendices (no parent) in registration order.

get_children 

get_children(parent_alias: str) -> list[AppendixReference]

Get child appendices for a given parent.

has_appendices 

has_appendices() -> bool

Check if any appendices are registered.

set_rendered_content 

set_rendered_content(alias: str, content: str) -> None

Store rendered content for an appendix.

get_rendered_content 

get_rendered_content(alias: str) -> str | None

Get rendered content for an appendix.

get_errors 

get_errors() -> list[str]

Get any errors that occurred during appendix processing.

add_error 

add_error(error_message: str) -> None

Add an error message.

get_appendix_manager 

get_appendix_manager() -> AppendixManager

Get the current request's appendix manager, creating one if needed.

Returns:

clear_appendix_manager 

clear_appendix_manager() -> None

Clear the current request's appendix manager (for testing).