Skip to content

Source

Usage

Data sources are abstractions that allow you to define the data being managed by your application independent of the GUI representation of that data. For details on the use of data sources, see the topic guide.

The base class referenced on this page, Source, isn't useful on its own. It provides an implementation of the notification API that data sources must provide, and is subclassed by:

It can also be used by custom data source implementations.

Reference

Bases: Generic[ListenerT]

A base class for data sources, providing an implementation of data notifications.

Source code in core/src/toga/sources/base.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
class Source(Generic[ListenerT]):
    """A base class for data sources, providing an implementation of data
    notifications."""

    def __init__(self) -> None:
        self._listeners: list[ListenerT] = []

    @property
    def listeners(self) -> list[ListenerT]:
        """The listeners of this data source.

        :returns: A list of objects that are listening to this data source.
        """
        return self._listeners

    def add_listener(self, listener: ListenerT) -> None:
        """Add a new listener to this data source.

        If the listener is already registered on this data source, the request to add
        is ignored.

        :param listener: The listener to add
        """
        if listener not in self._listeners:
            self._listeners.append(listener)

    def remove_listener(self, listener: ListenerT) -> None:
        """Remove a listener from this data source.

        :param listener: The listener to remove.
        """
        self._listeners.remove(listener)

    def notify(self, notification: str, **kwargs: object) -> None:
        """Notify all listeners an event has occurred.

        :param notification: The notification to emit.
        :param kwargs: The data associated with the notification.
        """
        for listener in self._listeners:
            method = getattr(listener, f"source_{notification}", None)

            # Alias for backwards compatibility:
            # March 2026: In 0.5.3 and earlier, notification methods
            # didn't start with 'source_'
            if method is None:
                method = getattr(listener, notification, None)
                if method is not None:
                    warnings.warn(
                        f"Notification handler methods on Listeners now start with "
                        f"'source_'. Change the method name to "
                        f"'source_{notification}'.",
                        DeprecationWarning,
                        stacklevel=2,
                    )

            if method:
                method(**kwargs)

listeners property

The listeners of this data source.

:returns: A list of objects that are listening to this data source.

add_listener(listener)

Add a new listener to this data source.

If the listener is already registered on this data source, the request to add is ignored.

:param listener: The listener to add

Source code in core/src/toga/sources/base.py 
 99
100
101
102
103
104
105
106
107
108
def add_listener(self, listener: ListenerT) -> None:
    """Add a new listener to this data source.

    If the listener is already registered on this data source, the request to add
    is ignored.

    :param listener: The listener to add
    """
    if listener not in self._listeners:
        self._listeners.append(listener)

notify(notification, **kwargs)

Notify all listeners an event has occurred.

:param notification: The notification to emit. :param kwargs: The data associated with the notification.

Source code in core/src/toga/sources/base.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
def notify(self, notification: str, **kwargs: object) -> None:
    """Notify all listeners an event has occurred.

    :param notification: The notification to emit.
    :param kwargs: The data associated with the notification.
    """
    for listener in self._listeners:
        method = getattr(listener, f"source_{notification}", None)

        # Alias for backwards compatibility:
        # March 2026: In 0.5.3 and earlier, notification methods
        # didn't start with 'source_'
        if method is None:
            method = getattr(listener, notification, None)
            if method is not None:
                warnings.warn(
                    f"Notification handler methods on Listeners now start with "
                    f"'source_'. Change the method name to "
                    f"'source_{notification}'.",
                    DeprecationWarning,
                    stacklevel=2,
                )

        if method:
            method(**kwargs)

remove_listener(listener)

Remove a listener from this data source.

:param listener: The listener to remove.

Source code in core/src/toga/sources/base.py 
110
111
112
113
114
115
def remove_listener(self, listener: ListenerT) -> None:
    """Remove a listener from this data source.

    :param listener: The listener to remove.
    """
    self._listeners.remove(listener)