Signal Functions

The urwid.*_signal() functions use a shared Signals object instance for tracking registered and connected signals. There is no reason to instantiate your own Signals object.

urwid.connect_signal(obj, name, callback, user_arg=None, weak_args=None, user_args=None)
Signals.connect(obj, name: Hashable, callback: Callable[..., Any], user_arg: Any = None, *, weak_args: Iterable[Any] = (), user_args: Iterable[Any] = ()) → Key
Parameters:

  • obj (object) – the object sending a signal

  • name (signal name) – the signal to listen for, typically a string

  • callback (function) – the function to call when that signal is sent

  • user_arg – deprecated additional argument to callback (appended after the arguments passed when the signal is emitted). If None no arguments will be added. Don’t use this argument, use user_args instead.

  • weak_args (iterable) –

    additional arguments passed to the callback (before any arguments passed when the signal is emitted and before any user_args).

    These arguments are stored as weak references (but converted back into their original value before passing them to callback) to prevent any objects referenced (indirectly) from weak_args from being kept alive just because they are referenced by this signal handler.

    Use this argument only as a keyword argument, since user_arg might be removed in the future.

  • user_args (iterable) –

    additional arguments to pass to the callback, (before any arguments passed when the signal is emitted but after any weak_args).

    Use this argument only as a keyword argument, since user_arg might be removed in the future.

When a matching signal is sent, callback will be called. The arguments it receives will be the user_args passed at connect time (as individual arguments) followed by all the positional parameters sent with the signal.

As an example of using weak_args, consider the following snippet:

>>> import urwid
>>> debug = urwid.Text('')
>>> def handler(widget, newtext):
...    debug.set_text("Edit widget changed to %s" % newtext)
>>> edit = urwid.Edit('')
>>> key = urwid.connect_signal(edit, 'change', handler)

If you now build some interface using “edit” and “debug”, the “debug” widget will show whatever you type in the “edit” widget. However, if you remove all references to the “debug” widget, it will still be kept alive by the signal handler. This because the signal handler is a closure that (implicitly) references the “edit” widget. If you want to allow the “debug” widget to be garbage collected, you can create a “fake” or “weak” closure (it’s not really a closure, since it doesn’t reference any outside variables, so it’s just a dynamic function):

>>> debug = urwid.Text('')
>>> def handler(weak_debug, widget, newtext):
...    weak_debug.set_text("Edit widget changed to %s" % newtext)
>>> edit = urwid.Edit('')
>>> key = urwid.connect_signal(edit, 'change', handler, weak_args=[debug])

Here the weak_debug parameter in print_debug is the value passed in the weak_args list to connect_signal. Note that the weak_debug value passed is not a weak reference anymore, the signals code transparently dereferences the weakref parameter before passing it to print_debug.

Returns a key associated by this signal handler, which can be used to disconnect the signal later on using urwid.disconnect_signal_by_key. Alternatively, the signal handler can also be disconnected by calling urwid.disconnect_signal, which doesn’t need this key.

urwid.disconnect_signal_by_key(obj, name, key)
Signals.disconnect_by_key(obj, name: Hashable, key: Key) → None
Parameters:

  • obj (object) – the object to disconnect the signal from

  • name (signal name) – the signal to disconnect, typically a string

  • key (Key) – the key for this signal handler, as returned by connect_signal().

This function will remove a callback from the list connected to a signal with connect_signal(). The key passed should be the value returned by connect_signal().

If the callback is not connected or already disconnected, this function will simply do nothing.

urwid.disconnect_signal(obj, name, callback, user_arg=None, weak_args=None, user_args=None)
Signals.disconnect(obj, name: Hashable, callback: Callable[..., Any], user_arg: Any = None, *, weak_args: Iterable[Any] = (), user_args: Iterable[Any] = ()) → None
Parameters:

  • obj (object) – the object to disconnect the signal from

  • name (signal name) – the signal to disconnect, typically a string

  • callback (function) – the callback function passed to connect_signal

  • user_arg – the user_arg parameter passed to connect_signal

  • weak_args – the weak_args parameter passed to connect_signal

  • user_args – the weak_args parameter passed to connect_signal

This function will remove a callback from the list connected to a signal with connect_signal(). The arguments passed should be exactly the same as those passed to connect_signal().

If the callback is not connected or already disconnected, this function will simply do nothing.

urwid.register_signal(sig_cls, signals)
Signals.register(sig_cls, signals: Container[Hashable]) → None
Parameters:

  • sig_cls (class) – the class of an object that will be sending signals

  • signals (signal names) – a list of signals that may be sent, typically each signal is represented by a string

This function must be called for a class before connecting any signal callbacks or emitting any signals from that class’ objects

urwid.emit_signal(obj, name, \*args)
Signals.emit(obj, name: Hashable, *args) → bool
Parameters:

  • obj (object) – the object sending a signal

  • name (signal name) – the signal to send, typically a string

  • args – zero or more positional arguments to pass to the signal callback functions

This function calls each of the callbacks connected to this signal with the args arguments as positional parameters.

This function returns True if any of the callbacks returned True.