Renderer¶

Shared rendering engine used by BaseComponent rendering and HTML-like custom-tag rendering.

Class¶

Renderer¶

This renderer centralizes: - Jinja template loading (by component class or explicit file/source) - Expansion of PascalCase custom tags inside rendered markup - JavaScript and CSS collection/deduping and root-level asset injection - Rendering of HTML-like source strings into component output

Constructor¶

init()¶

def __init__(
    environment: Environment,
    *,
    auto_id: bool = True,
    inline_js: bool | None = None,
    inline_css: bool | None = None,
) -> None

Initialize a Renderer with the given Jinja environment.

Parameters: - environment (Environment): The Jinja2 Environment to use for template rendering - auto_id (bool): If True (default), generate UUIDs for components without explicit IDs - inline_js (bool | None): If True, JavaScript is collected and injected as <script> tags. If False, no scripts are injected. Defaults to the class-level setting - inline_css (bool | None): If True, CSS is collected and injected as <style> tags. If False, no styles are injected. Defaults to the class-level setting

Class Methods¶

get_default_renderer()¶

@classmethod
def get_default_renderer(
    *,
    auto_id: bool = True,
    inline_js: bool | None = None,
    inline_css: bool | None = None,
) -> Renderer

Return a cached default renderer instance.

Parameters: - auto_id (bool): If True, generate UUIDs for components without explicit IDs - inline_js (bool | None): If True, JavaScript is collected and injected as <script> tags. If False, no scripts are injected. Defaults to the class-level setting - inline_css (bool | None): If True, CSS is collected and injected as <style> tags. If False, no styles are injected. Defaults to the class-level setting

Returns: A Renderer instance cached by (environment identity, auto_id, inline_js, inline_css).

get_default_environment()¶

@classmethod
def get_default_environment() -> Environment

Return the default Jinja environment, auto-initializing if needed.

If no environment is configured, one is created using auto-detected project root.

Returns: The default Jinja Environment instance.

set_default_environment()¶

@classmethod
def set_default_environment(
    environment: Environment | str | os.PathLike[str] | None
) -> None

Set or clear the process-wide default Jinja environment.

Parameters: - environment (Environment | str | os.PathLike[str] | None): A Jinja Environment instance, a path to a template directory, or None to clear the default and reset to auto-detection

set_default_inline_js()¶

@classmethod
def set_default_inline_js(inline_js: bool) -> None

Set the process-wide default for inline JavaScript injection.

Parameters: - inline_js (bool): If True (default), JavaScript is collected and injected as <script> tags. If False, no scripts are injected. Use Finder.collect_javascript_files() for static serving.

set_default_inline_css()¶

@classmethod
def set_default_inline_css(inline_css: bool) -> None

Set the process-wide default for inline CSS injection.

Parameters: - inline_css (bool): If True (default), CSS is collected and injected as <style> tags. If False, no styles are injected. Use Finder.collect_css_files() for static serving.

peek_default_environment()¶

@classmethod
def peek_default_environment() -> Environment | None

Return the currently configured default environment without auto-initializing.

Returns: The default Jinja Environment, or None if not yet configured.

Properties¶

environment¶

@property
def environment() -> Environment

The Jinja Environment used by this renderer.

Returns: The Jinja Environment instance.

Instance Methods¶

render()¶

def render(source: str) -> str

Render an HTML-like source string, expanding PascalCase component tags into HTML.

PascalCase tags (e.g., <MyButton text="OK">) are matched to registered component classes or template files and rendered recursively. Standard HTML is passed through unchanged. Associated CSS and JavaScript files are collected and injected as <style> and <script> tags.

Parameters: - source (str): HTML-like string containing component tags to render

Returns: The fully rendered HTML string with all components expanded.

new_session()¶

def new_session() -> RenderSession

Create a new render session for tracking assets during rendering.

Returns: A fresh RenderSession instance.

RenderSession¶

Per-render state for asset aggregation and deduplication.

Internal Use

RenderSession is primarily for internal use by the rendering engine. You typically don't need to create or manage sessions directly—they're created automatically during rendering.

If you need a new session for custom rendering logic, use Renderer.new_session() instead of instantiating directly.

Fields¶

Field	Type	Description
`scripts`	`list[str]`	Collected JavaScript code snippets to inject
`collected_js_files`	`set[str]`	Set of JS file paths already processed (for deduplication)
`styles`	`list[str]`	Collected CSS code snippets to inject
`collected_css_files`	`set[str]`	Set of CSS file paths already processed (for deduplication)