source: listenerpy/tudelft_utilities_listener/Listener.py

from abc import ABC
from abc import abstractmethod
from typing import TypeVar, Generic, List


T = TypeVar('T')
class Listener(ABC,Generic[T]):
        '''
        Listener for changes in a {@link Listenable}.
        @param <T> type of data being notified back to the caller.
        '''
        
        @abstractmethod
        def notifyChange(self, data: T):
                '''
                a notification call that occurs when something changed. Consult the
                parent object for details about this event.
                
                <h1>NOTICE 1</h1> notifications run in the thread of the caller. The
                caller will be blocked until this callback has been completed. It is
                therfore good practice to handle callbacks quickly.
                
                <h1>NOTICE 2</h1> Notifications often cross a thread sarety boundary. For
                example when in MVC a model (typically thread safe) calls back a panel
                (not thread safe). The called side (the panel) thus must handle the
                callback in a thread safe manner, e.g. using
                {@link SwingUtilities#invokeLater(Runnable)}. We recommend to avoid
                synchronize as this will can block indefinitely (see notice 1) which
                might lead to deadlocks.
                
                <h1>NOTICE 3</h1>If the call to your notifyChange implementation
                throws an unchecked exception, it ends up in the caller's space
                where this exception can not be 
                properly handled because the caller does not know what the notifications
                are supposed to be used for. Therefore exceptions will generally 
                just be logged and ignored; the caller may also un-register your
                subscription in an attempt to avoid further problems.
                
                <h1>NOTICE 3</h1>If the call to your notifyChange implementation
                throws an unchecked exception, it ends up in the caller's space
                where this exception can not be 
                properly handled because the caller does not know what the notifications
                are supposed to be used for. Therefore exceptions will generally 
                just be logged and ignored; the caller may also un-register your
                subscription in an attempt to avoid further problems.

                @param data additional data, typically the new value associated with the
            event
                '''