Package: eventsystem
Convenient Event SystemCreate, subscribe and fire events with one line of code. Unlike alternative packages this one provides static typed predefined events with documented signature of event handlers.Both ordinary and async event handlers are supported. Both ordinary and async events are supported. Any of ordinary, async and awaited async event triggering is supported.Usage examplesBriefly, you need to perform two steps:decide between two options: group events in class derived fromEventDispatcheror just define functions,then decorate each event with@event.Let's see how to use the library in more details. Imagine we write some user interface stuff for our super-duper program.Single event exampleStep 1: define click event.@eventdefclick(x:int,y:int)->None:"""Occures when user clicks on our interface.:param x: mouse horizontal position relative to top left corner.:param y: mouse vertical position relative to top left corner."""...# no implementation requiredStep 2: subscribe click event.@clickdefon_click(x:int,y:int)->None:"""Process mouse click."""print(f'You have clicked at ({x};{y}).')Step 3: fire click event.click.trigger(12,34)# You have clicked at (12; 34).Events group exampleStep 1: define mouse events group.classMouse(EventDispatcher):@eventdefclick(x:int,y:int)->None:"""Occures when user clicks on our interface.:param x: mouse horizontal position relative to top left corner.:param y: mouse vertical position relative to top left corner."""...# no implementation required@eventdefmove(x:int,y:int)->None:"""Occures when user moves cursor over our interface.:param x: mouse horizontal position relative to top left corner.:param y: mouse vertical position relative to top left corner."""...Step 2: subscribe click event.mouse=Mouse()@mouse.clickdefon_click(x:int,y:int)->None:"""Process mouse click."""print(f'You have clicked at ({x};{y}).')Step 3: fire click event.mouse.click.trigger(12,34)# You have clicked at (12; 34).How to create events?Event are created by usingeventdecorator. It can be used with or without parameters.The event can have arbitrary body that is not actually called. Main feature is to defined event signature hence during subscribingdeveloper can see help message and type hints with intended event handler signature.Single event bound to default event emitterThe simplest case is to just create an event. So default event emitter is used to manage this event.@eventdefclick(x:int,y:int)->None:"""Occures when user clicks on our interface.:param x: mouse horizontal position relative to top left corner.:param y: mouse vertical position relative to top left corner."""...Single event bound to custom event emitterOtherwise, you can specify different event emitter passing as argument.my_event_emitter=EventEmitter()@event(my_event_emitter)defclick(x:int,y:int)->None:"""Occures when user clicks on our interface.:param x: mouse horizontal position relative to top left corner.:param y: mouse vertical position relative to top left corner."""...Events group bound to dedicated event emitterMoreover, you can combine events in group by using classes. There are two different approaches: using default event emitter or dedicate one per each class.Creating dedicated event emitter per each event group is recommended.Considering the preferred approach you can group event in class derived fromEventDispatcher. This ensures creation of new event emitter per each class instance.Notice that usingeventdecorator stays the same way as for non-class functions.classMouse(EventDispatcher):@eventdefclick(x:int,y:int)->None:"""Occures when user clicks on our interface.:param x: mouse horizontal position relative to top left corner.:param y: mouse vertical position relative to top left corner."""...# no implementation required@event(my_event_emitter)# given event emitter is prior to Mouse onedefmove(x:int,y:int)->None:"""Occures when user moves cursor over our interface.:param x: mouse horizontal position relative to top left corner.:param y: mouse vertical position relative to top left corner."""...Then you can instantiateMouseclass and access dedicated event emitter for e.g. further low-level tuning.mouse=Mouse()mouse.emitter.max_listeners=2# allows up to two handlersWhen usingeventdecorator onEventDispatchersubclass method with specified event emitter it takes priority over the one dedicated per class instance.Events group bound to default event emitterIn case you do not want to create dedicated event emitter per class instance (not recommended) you can just omit deriving fromEventDispatcher.In following code default event emitter is used for all events in group.classMouse:@eventdefclick(x:int,y:int)->None:"""Occures when user clicks on our interface.:param x: mouse horizontal position relative to top left corner.:param y: mouse vertical position relative to top left corner."""...# no implementation required@event(my_event_emitter)# given event emitter is prior to default onedefmove(x:int,y:int)->None:"""Occures when user moves cursor over our interface.:param x: mouse horizontal position relative to top left corner.:param y: mouse vertical position relative to top left corner."""...How to subscribe events?Event is subscribed by decorating handler.Handler can be any ordinary or async function (callable).Decorator also can be used with or without parameters.Notice, when using event your IDE can show help message and type hints of intended handler signature.Unlimited event handlerThe simplest case is to just decorate handler with event. So handler will be called when event triggers.@clickdefon_click(x:int,y:int)->None:"""Process mouse click."""print(f'You have clicked at ({x};{y}).')There is no difference between usage of single events or ones from event groups.Hence, according toMouseclass example the above code can be rewritten in:@mouse.clickdefon_click(x:int,y:int)->None:"""Process mouse click."""print(f'You have clicked at ({x};{y}).')Event handler with executions limitOtherwise, you can specify number of times to handle event. When event fires more times, no further calls will be made to the handler.@click(2)defon_click(x:int,y:int)->None:"""Process mouse click two first times."""print(f'You have clicked at ({x};{y}).')In above caseon_clickwill be called only for the first two times.How to fire events?To fire, emit, trigger event you can use.trigger(...)method where should pass exactly the same arguments that are defined in event signature.Notice, when using event your IDE can show help message and type hints of intended arguments.Basically, to trigger an event you can just calltriggermethod. Each active handler will be called with given arguments. You can use any set of arguments, including positional, universal, named, packed and even named packed.click.trigger(12,34)Alternatively consideringMouseclass example:mouse.click.trigger(12,34)Triggering events from async loopWhen event is triggered from async loop the method returns loop task of handlers dispatching. One can optionally await it to pause current async thread until dispatching will be done.Consider example above running within asyncio loop:asyncdefmain():click.trigger(12,34)# Schedule handlers execution and go to the next line without waiting....awaitclick.trigger(12,34)# Wait until all handlers process before next line execution....asyncio.run(main())It is worth nothing that some IDEs, linters or static type checkers can warn about not awaited triggering. This is not a problem and depends only on demanded triggering behaviour.Referenceeventsystem.event(...)Event descriptor decorator. Can be used on functions or class methods. Can be used with or without parameters.When used with single parameteremitter:EventEmitterbinds given event emitter to decorated event.When used without parameters (brackets): if method belongs toEventDispatcherderived class instance then uses its event emitter, else uses default emitter.eventsystem.EventDispatcher(emitter: EventEmitter | None = None)Base class to provide event group. Events are described as methods. Each event should have signature ofEventHandlerand decorated with@event.Constructor parameters:emitter- event emitter to use. If not given creates a new one.Fields:emitter- event emitter bound to dispatcher subclass instance.eventsystem.EventEvent interface. Intended to be used as decorator or parametrized decorator for handlers.Should not be instantiated directly.Fields:name- read only property of event nameMethods:get_emitter() → EventEmitter | None- get bound event emitter. In most cases, event will have event emitter bound. But in rare cases it can beNonewhen no handler descriptor has been decorated yet.trigger(...) → asyncio.Task| None- fire the event. All arguments are passed to each handler. Signature must match handler descriptor. If event is triggered being in asyncio loop the method returns corresponding Task which can be optionally awaited to pause until all handlers are processed.eventsystem.emitterDefault event emitter.eventsystem.dispatcherDefault event dispatcher bound to default event emitter.eventsystem.EventHandlerBase event and event handler signature (type annotations). Signature of handler must copy signature of event.What event emitter is?This library us build on top ofpymitter.EventEmitter- is a basic building block of that library which actually dispatches events, manages priority, limitations and queues.UsingEventEmitterdirectly you can unsubscribe handlers, get all active handlers or limit them. For detailed tuning read pymitter documentation.