SecretInput¶

pywry.toolbar.SecretInput ¶

Bases: ToolbarItem

A password/secret input field with visibility toggle and copy button.

Displays a masked input by default with icons on the right side: - Eye icon to toggle visibility (requests secret from backend) - Copy icon to copy value to clipboard (requests secret from backend)

Icons appear on hover/focus and input text is padded to not overlap them.

SECURITY: The secret value is NEVER rendered in HTML. When the user clicks the show or copy buttons, JavaScript emits events to request the secret from the backend. The backend must handle these events and respond with the actual value. This ensures secrets are only transmitted on explicit user action and never embedded in the DOM.

Events emitted: - {event} - On input change: {value, componentId} - {event}:reveal - On show click: {componentId} - backend should respond with secret - {event}:copy - On copy click: {componentId} - backend should respond with secret

ATTRIBUTE	DESCRIPTION
`value`	Secret value stored as SecretStr (NEVER rendered in HTML). TYPE: `SecretStr`
`placeholder`	Placeholder text shown when empty (default: ""). TYPE: `str`
`debounce`	Milliseconds to debounce input events (default: 300). TYPE: `int`
`show_toggle`	Show the visibility toggle button (default: True). TYPE: `bool`
`show_copy`	Show the copy to clipboard button (default: True). TYPE: `bool`
`handler`	Optional callable for custom secret storage. Signature: `(value, , component_id, event, label, metadata) -> str \| None`. Pass `None` to get the secret, a string to set it. If not provided, uses internal SecretStr storage. TYPE:* `callable or None`
`value_exists`	Flag indicating a value exists externally. If None, computed from value. TYPE: `bool or None`

Examples:

Simple usage with internal storage:

>>> SecretInput(
...     label="API Key:",
...     event="settings:api_key",
...     value="my-secret",
... )

Custom handler with component metadata:

>>> def api_key_handler(
...     value,
...     *,
...     component_id,
...     event,
...     label=None,
...     **metadata,
... ):
...     if value is None:
...         return secrets_manager.get(component_id)
...     secrets_manager.set(component_id, value)
...     return value
>>> SecretInput(
...     event="settings:api_key",
...     handler=api_key_handler,
... )

has_value `property` ¶

has_value: bool

Check if a secret value is set (without exposing it).

Returns True if: - value_exists is explicitly True, OR - value_exists is None and internal value is non-empty

build_html ¶

build_html() -> str

Build secret input HTML with visibility toggle and copy button.

When a value exists, a fixed mask (••••••••••••) is shown. Show/copy buttons emit events to request the real secret from the backend. Values are base64 encoded in transit for obfuscation.

Edit mode: - Click on edit button to enter edit mode - Switches to a resizable textarea (no wrapping, no formatting) - Confirm with blur or Ctrl+Enter - Cancel with Escape (restores mask) - Only transmits on confirm, not during typing

register ¶

register() -> None

Register this SecretInput in the secret registry.

Called automatically by Toolbar when building HTML. If a custom handler is provided, it's registered for reveal/copy events. Otherwise, the internal value is registered for retrieval.

update_secret ¶

update_secret(new_value: str | SecretStr, encoded: bool = False) -> None

Update the stored secret value.

Use this when receiving a new value from user input. If a custom handler is configured, it will be called to store the value.

PARAMETER	DESCRIPTION
`new_value`	The new secret value. If encoded=True and this is a string, it will be base64-decoded first. TYPE: `str \| SecretStr`
`encoded`	Whether the value is base64-encoded (for transit obfuscation). TYPE: `bool` DEFAULT: `False`

get_reveal_event ¶

get_reveal_event() -> str

Get the event type for reveal requests.

get_reveal_response_event ¶

get_reveal_response_event() -> str

Get the event type for reveal responses.

get_copy_event ¶

get_copy_event() -> str

Get the event type for copy requests.

get_copy_response_event ¶

get_copy_response_event() -> str

Get the event type for copy responses.

get_secret_value ¶

get_secret_value() -> str | None

Get the current secret value.

If a custom handler is configured, calls handler with metadata. Otherwise, returns the internal value or from the registry.

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

auto_generate_component_id ¶

auto_generate_component_id() -> ToolbarItem

Auto-generate component_id based on type if not provided.

validate_event_name `classmethod` ¶

validate_event_name(v: str) -> str

Validate event follows namespace:event-name pattern.