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,
    js_mode: AssetMode | None = None,
    css_mode: AssetMode | 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 - js_mode (AssetMode | None): JavaScript delivery mode. Defaults to the class-level setting - css_mode (AssetMode | None): CSS delivery mode. Defaults to the class-level setting

Class Methods¶

get_default_renderer()¶

@classmethod
def get_default_renderer(
    *,
    auto_id: bool = True,
    js_mode: AssetMode | None = None,
    css_mode: AssetMode | None = None,
) -> Renderer

Return a cached default renderer instance.

Parameters: - auto_id (bool): If True, generate UUIDs for components without explicit IDs - js_mode (AssetMode | None): JavaScript delivery mode - css_mode (AssetMode | None): CSS delivery mode

Returns: A Renderer instance cached by environment identity, auto_id, asset modes, and resolver identity.

set_default_js_mode()¶

@classmethod
def set_default_js_mode(mode: AssetMode) -> None

Set the process-wide default JavaScript asset delivery mode.

set_default_css_mode()¶

@classmethod
def set_default_css_mode(mode: AssetMode) -> None

Set the process-wide default CSS asset delivery mode.

set_asset_url_resolver()¶

@classmethod
def set_asset_url_resolver(resolver: AssetUrlResolver | None) -> None

Set the callable that maps absolute asset paths to public URLs for AssetMode.REFERENCE.

set_default_runtime_url()¶

@classmethod
def set_default_runtime_url(url: str) -> None

Set the public URL for the pyjinhx client runtime in AssetMode.REFERENCE (default: /static/pyjinhx/pjx.js).

set_default_asset_dedup()¶

@classmethod
def set_default_asset_dedup(enabled: bool) -> None

When True, root REFERENCE renders skip <link> / <script src> tags for URLs the client reported via X-PJX-Assets. Defaults to False. With ClientBackend wired in middleware, root renders pick up the header automatically; otherwise pass client=request on boosted full-page routes.

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

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.

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.

AssetMode¶

class AssetMode(str, Enum):
    INLINE = "inline"
    REFERENCE = "reference"
    NONE = "none"

RenderSession¶

Per-render state for asset aggregation and deduplication.

Fields¶

Field	Type	Description
`assets`	`list[CollectedAsset]`	Ordered, deduplicated asset paths collected during rendering
`collected_paths`	`set[str]`	Normalized paths already processed
`scripts`	`list[str]`	Inline JavaScript payloads (`AssetMode.INLINE` only)
`styles`	`list[str]`	Inline CSS payloads (`AssetMode.INLINE` only)
`runtime_injected`	`bool`	Whether the pyjinhx client runtime was scheduled

Methods¶

manifest()¶

def manifest(*, resolver: AssetUrlResolver) -> AssetManifest

Return resolved stylesheet and script URLs for assets collected in this session.