Package: py-events
EventsA simple event system for using as a component in larger systems.Inspired byC# events.Getting StartedThis library provides a mechanism to subscribe to and publish events. The primary use case is to enable code that processes events to be separated from the code that generated or detects them.One common use case would be in implementing a statistics tracker for a game. You would not want to classes/modules responsible for managing the game logic (like a player's HP or calculating combat damage) to be polluted with dozens (or hundreds) or lines of counter incrementing logic (or even worse, user interface updates for those statistics). With this library you could simply fire an event from relevant places and let a dedicated statistics management module/component handle logging, saving, presenting and forwarding statistics about what happened.Organized properly, using events can allow for a much greater separation of concerns and simplify otherwise complex logic dramatically.InstallationActivate your virtual environment if you are using one (and you should be), then execute:python -m pip install py-eventsDefine your eventThe core of this library is theEventclass. The primary use ofEventis to subclass it to define a new type of event. Typically, a subclass ofEventonly needs to override the__init__method to set up any new attributes that you want the event to have.Define a custom eventfrompy_eventsimportEventclassCustomEvent(Event):""" My custom event. """def__init__(self,message:str):"""This event contains a message to be sent to handlers."""super().__init__()self.message=messageSet up a handlerOnce you have anEventsubclass defined, you can create asubscriberfor the event. Asubscriberis a callable that accepts the event being fired as it's only positional argument. Typically this is a plain function, but can be a class with a__call__method defined for more complex use cases.Registering yoursubscribercan be done in two ways. For simple functions you define directly in your application's source code there is theEvent.handlesmethod you can use as a decorator to register the function automatically. If you are importing the function from somewhere, or using a callable class instead, you can call theEvent.add_handlermethod to register an already constructed callable.Simple handlerimportloggingfrommy_moduleimportCustomEvent@CustomEvent.handlerdefsimple_handler(event:CustomEvent)->None:""" Log the message from my custom event. """logging.info(event.message)Class based handlerimportloggingfrommy_moduleimportCustomEventclassComplexHandler:""" Log message from custom event and keep track of number of events fired. """def__init__(self)->None:self.events_handled_count=0def__call__(self,event:CustomEvent)->None:""" Log message from event and increment events_handled counter. """logging.info(event.message)self.events_handled_count+=1# Create a constant reference that other modules could import and use to check on the counterCOMPLEX_HANDLER=ComplexHandler()CustomEvent.add_handler(COMPLEX_HANDLER)Publish your eventOnce you have asubscriberset up you can publish events from anywhere to have them sent to all of thesubscribersyou have set up. Firing an event is as simple as constructing an instance of it and calling it'sfiremethod.Useful Note: The baseEventclass is set up to be relatively stateless, so a single instance of anEventcan be fired multiple times.Fire your eventfrommy_moduleimportCustomEventCustomEvent("Hello world").fire()