Toolbar Functions¶

Utility functions for toolbar secret management, event validation, and HTML generation.

Secret Management¶

pywry.toolbar.register_secret ¶

register_secret(component_id: str, secret: SecretStr) -> None

Register a secret value for a SecretInput component.

Called automatically when SecretInput is rendered. The secret can then be retrieved by reveal/copy handlers.

PARAMETER	DESCRIPTION
`component_id`	The unique component ID of the SecretInput. TYPE: `str`
`secret`	The secret value to store. TYPE: `SecretStr`

pywry.toolbar.get_secret ¶

get_secret(component_id: str) -> str | None

Retrieve a secret value by component ID.

PARAMETER	DESCRIPTION
`component_id`	The unique component ID of the SecretInput. TYPE: `str`

RETURNS	DESCRIPTION
`str \| None`	The secret value, or None if not found.

pywry.toolbar.clear_secret ¶

clear_secret(component_id: str) -> None

Remove a secret from the registry.

PARAMETER	DESCRIPTION
`component_id`	The unique component ID of the SecretInput. TYPE: `str`

pywry.toolbar.encode_secret ¶

encode_secret(value: str) -> str

Base64 encode a secret for transit obfuscation.

PARAMETER	DESCRIPTION
`value`	The secret value to encode. TYPE: `str`

RETURNS	DESCRIPTION
`str`	Base64 encoded string.

pywry.toolbar.decode_secret ¶

decode_secret(encoded: str) -> str

Decode a base64-encoded secret from transit.

PARAMETER	DESCRIPTION
`encoded`	The base64 encoded secret. TYPE: `str`

RETURNS	DESCRIPTION
`str`	The decoded secret value.

Secret Handlers¶

pywry.toolbar.set_secret_handler ¶

set_secret_handler(event: str, handler: Callable[[dict[str, Any]], str | None]) -> None

Set a custom handler for secret reveal/copy events.

Use this to add custom validation, authentication, or logging before returning secrets. The handler receives the event data and should return the secret string or None to deny access.

PARAMETER	DESCRIPTION
`event`	The event type (e.g., "settings:api-key:reveal"). TYPE: `str`
`handler`	Function that takes event data dict and returns secret or None. TYPE: `Callable`

Example

def my_reveal_handler(data: dict) -> str | None:
    # Custom auth check
    if not is_authenticated():
        return None
    return get_secret(data["componentId"])

set_secret_handler("settings:api-key:reveal", my_reveal_handler)

pywry.toolbar.get_secret_handler ¶

get_secret_handler(event: str) -> Callable[[dict[str, Any]], str | None] | None

Get a custom handler for a secret event.

PARAMETER	DESCRIPTION
`event`	The event type. TYPE: `str`

RETURNS	DESCRIPTION
`Callable \| None`	The custom handler, or None if using default.

pywry.toolbar.create_default_secret_handlers ¶

create_default_secret_handlers(dispatch_func: Callable[[str, dict[str, Any]], None]) -> dict[str, Callable[..., Callable[[dict[str, Any], str, str], None]]]

Create default handlers for secret reveal/copy events.

These handlers look up the secret from the registry and dispatch the response back to the frontend.

PARAMETER	DESCRIPTION
`dispatch_func`	Function to dispatch events to frontend: dispatch(event_type, data) TYPE: `Callable`

RETURNS	DESCRIPTION
`dict[str, Callable[..., Callable[[dict[str, Any], str, str], None]]]`	Mapping of handler name to factory function. - "reveal": factory(event_base: str) -> handler - "copy": factory(event_base: str) -> handler - "update": factory(secret_input: SecretInput) -> handler

Example

handlers = create_default_secret_handlers(app.dispatch)
for event, handler in handlers.items():
    app.on(event, handler)

pywry.toolbar.register_secret_handlers_for_toolbar ¶

register_secret_handlers_for_toolbar(toolbar: Toolbar, on_func: Callable[[str, Callable[..., Any]], Any], dispatch_func: Callable[[str, dict[str, Any]], None]) -> list[str]

Register default secret handlers for all SecretInputs in a toolbar.

PARAMETER	DESCRIPTION
`toolbar`	The toolbar containing SecretInput items. TYPE: `Toolbar`
`on_func`	Function to register event handlers: on(event_type, handler) -> Any Returns value is truthy if registration succeeded (or ignored). TYPE: `Callable`
`dispatch_func`	Function to dispatch events to frontend: dispatch(event_type, data) TYPE: `Callable`

RETURNS	DESCRIPTION
`list[str]`	List of event types that were registered.

Event Validation¶

pywry.toolbar.validate_event_format ¶

validate_event_format(event: str) -> bool

Check if event matches namespace:event-name pattern.

PARAMETER	DESCRIPTION
`event`	The event string to validate. TYPE: `str`

RETURNS	DESCRIPTION
`bool`	True if valid format, False otherwise.

HTML Generation¶

pywry.toolbar.build_toolbar_html ¶

build_toolbar_html(toolbar: Toolbar | dict[str, Any]) -> str

Build HTML for a single toolbar.

PARAMETER	DESCRIPTION
`toolbar`	Toolbar configuration. TYPE: `Toolbar or dict`

RETURNS	DESCRIPTION
`str`	HTML string for the toolbar.

pywry.toolbar.build_toolbars_html ¶

build_toolbars_html(toolbars: Sequence[Toolbar | dict[str, Any]] | None) -> str

Build HTML for multiple toolbars.

PARAMETER	DESCRIPTION
`toolbars`	List of toolbar configurations. TYPE: `list of Toolbar or dict, or None`

RETURNS	DESCRIPTION
`str`	Combined HTML string for all toolbars.

pywry.toolbar.get_toolbar_script ¶

get_toolbar_script(*, with_script_tag: bool = True) -> str

Get the JavaScript required for toolbar interactivity.

This script handles: - Dropdown (Select) open/close and option selection - Button click events - Text/Number/Date input with debouncing - Slider/Range input with live updates - MultiSelect checkbox handling - Dynamic toolbar updates via toolbar:set-value event

PARAMETER	DESCRIPTION
`with_script_tag`	If True, wrap in `<script>` tags. If False, return raw JavaScript (for embedding inside an existing script block). TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`str`	JavaScript code or script tag containing toolbar JavaScript. Safe to include multiple times (has internal guard).

pywry.toolbar.wrap_content_with_toolbars ¶

wrap_content_with_toolbars(content: str, toolbars: Sequence[dict[str, Any] | Toolbar] | None = None, extra_top_html: str = '') -> str

Wrap content with toolbar layout wrappers.

This is THE SINGLE source of truth for toolbar layout structure. All rendering paths (show, show_plotly, show_dataframe) MUST use this.

Layout structure (outside in): HEADER (full width) LEFT | TOP / CONTENT / BOTTOM | RIGHT FOOTER (full width)

This means: - HEADER/FOOTER span full width at top/bottom - LEFT/RIGHT extend full height between header and footer - TOP/BOTTOM are inside the left/right columns - Content is centered in remaining space

PARAMETER	DESCRIPTION
`content`	The inner content HTML (raw, will be wrapped in pywry-content). TYPE: `str`
`toolbars`	List of toolbar configurations (Toolbar models or dicts). TYPE: `list` DEFAULT: `None`
`extra_top_html`	Additional HTML to prepend to top toolbar area (e.g., custom header). TYPE: `str` DEFAULT: `''`

RETURNS	DESCRIPTION
`str`	Content wrapped with appropriate layout divs.