Skip to content

Signal

Bases: Generic[T]

A reactive signal backed by a tkinter Variable.

Supports value access, transformation via .map(), and subscription to change events via .subscribe().

Can be passed to Tkinter widgets using str(signal) or signal.name.

name property 

name: str

Return the Tcl name of the variable (for use in widget textvariable).

type property 

type: Type[T]

The original type of the signal value.

Returns:

Type Description
Type[T]

A Python type (e.g., int, str).

__call__ 

__call__() -> T

Get the current value of the signal.

Returns:

Type Description
T

The current typed value.

get 

get() -> T

Return the current value of the signal.

Alias for calling the instance directly (signal()). Mirrors tkinter's Variable.get naming for consistency.

from_variable classmethod 

from_variable(
    tk_var: Variable,
    *,
    name: str | None = None,
    coerce: Type[T] | None = None,
) -> Signal[T]

Wrap an existing tkinter Variable as a Signal.

Parameters:

Name Type Description Default
tk_var Variable

An existing tkinter.Variable instance (StringVar, IntVar, etc.).

 required
name str | None

Optional override of the Tcl variable name. Defaults to tk_var's name.

 None
coerce Type[T] | None

Optional Python type to treat the signal as (e.g., int/float/bool/str). If omitted, the type is inferred from the tk_var subclass.

 None

Returns:

Type Description
Signal[T]

A Signal bound to the provided tk_var.

set 

set(value: T) -> None

Set the signal to a new value and notify subscribers.

Parameters:

Name Type Description Default
value T

The new value. Must match the original type.

 required

Raises:

Type Description
TypeError

If the value type does not match the original.

map 

map(transform: Callable[[T], U]) -> Signal[U]

Create a derived signal that transforms this signal's value.

Parameters:

Name Type Description Default
transform Callable[[T], U]

A function applied to the current and future values.

 required

Returns:

Type Description
Signal[U]

A new Signal[U] that stays updated with the transformed value.

subscribe 

subscribe(
    callback: Callable[[T], Any], *, immediate: bool = False
) -> str

Subscribe to value changes of this signal.

Parameters:

Name Type Description Default
callback Callable[[T], Any]

A function that receives the current value (T) when updated.

 required

Returns:

Type Description
str

A trace ID that can be used for removal.

unsubscribe 

unsubscribe(funcid: str) -> None

Remove a previously registered subscriber.

Parameters:

Name Type Description Default
funcid str

The function id returned from subscribe().

 required

unsubscribe_all 

unsubscribe_all() -> None

Remove all currently subscribed callbacks.

__getattr__ 

__getattr__(name: str) -> Any

Proxy access to the underlying tk.Variable instance.