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.

Parameters:

Name	Type	Description	Default
`component_id`	`str`	The unique component ID of the SecretInput.	required
`secret`	`SecretStr`	The secret value to store.	required

pywry.toolbar.get_secret ¶

get_secret(component_id: str) -> str | None

Retrieve a secret value by component ID.

Parameters:

Name	Type	Description	Default
`component_id`	`str`	The unique component ID of the SecretInput.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`component_id`	`str`	The unique component ID of the SecretInput.	required

pywry.toolbar.encode_secret ¶

encode_secret(value: str) -> str

Base64 encode a secret for transit obfuscation.

Parameters:

Name	Type	Description	Default
`value`	`str`	The secret value to encode.	required

Returns:

Type	Description
`str`	Base64 encoded string.

pywry.toolbar.decode_secret ¶

decode_secret(encoded: str) -> str

Decode a base64-encoded secret from transit.

Parameters:

Name	Type	Description	Default
`encoded`	`str`	The base64 encoded secret.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`event`	`str`	The event type (e.g., "settings:api-key:reveal").	required
`handler`	`Callable`	Function that takes event data dict and returns secret or None.	required

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.

Parameters:

Name	Type	Description	Default
`event`	`str`	The event type.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`dispatch_func`	`Callable`	Function to dispatch events to frontend: dispatch(event_type, data)	required

Returns:

Type	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.

Parameters:

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

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`event`	`str`	The event string to validate.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`toolbar`	`Toolbar or dict`	Toolbar configuration.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`toolbars`	`list of Toolbar or dict, or None`	List of toolbar configurations.	required

Returns:

Type	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

Parameters:

Name	Type	Description	Default
`with_script_tag`	`bool`	If True, wrap in `<script>` tags. If False, return raw JavaScript (for embedding inside an existing script block).	`True`

Returns:

Type	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

Parameters:

Name	Type	Description	Default
`content`	`str`	The inner content HTML (raw, will be wrapped in pywry-content).	required
`toolbars`	`list`	List of toolbar configurations (Toolbar models or dicts).	`None`
`extra_top_html`	`str`	Additional HTML to prepend to top toolbar area (e.g., custom header).	`''`

Returns:

Type	Description
`str`	Content wrapped with appropriate layout divs.