Metadata-Version: 2.1
Name: aioevt
Version: 2.2.0
Summary: UNKNOWN
Home-page: https://github.com/GoodiesHQ/aioevt
Author: Austin Archer
Author-email: aarcher@protonmail.com
License: UNKNOWN
Description: # Aioevt
        #### Simplified Asyncio-Friendly Event Management
        
        
        ### Problem
        Asyncio offers a lot of utilities that provide thread-safe execution of coroutines and synchronous functions. However, there isn't any one "unified" way of emitting/catching events accross threads, and synchronization primitives are not themselves thread-safe. This can lead to unexpected behavior when trying to synchronize multiple event loops on multiple threads.
        
        ### Solution
        `aioevt` - After creating the manager, you can emit or await 'global' events in a thread-safe way. Callbacks can registered from any thread and target any event loop. This allows you to very easily share objects and quickly emit information without fussing with thread safety.
        
        ## Documentation
        
        
        ### Evt and EvtData
        
        The core objects used throughout `aioevt` are the `Evt` and `EvtData` dataclassess.
         - `Evt` represents an event itself and is comprised of a `name` (identifier), `func` (callback), `loop` (for execution), and `recurring` (automatic re-scheduling)
         - `EvtData` consists only of `args` and `kwargs` which are splatted into callbacks as needed
        
        ### Create a manager    
        
        Create an `aioevt` manager which uses the default event loop.
        
            mgr = aioevt.Manager()
        
        ### Register an event
        
        Register a global event to be triggered from a provided event loop when a named event is emitted. This can be done in two ways: both through the `mgr.register` method, or the `mgr.on` decorator. An event can have multiple callbacks, and each callback will be invoked with the same parameters on each emit. **Note:** The return value of the event callback is not retrievable. If you'd like to handle a value from inside a callback, simply emit a different event and wait for it in the desired location.
        
            mgr.register(
                name="MyEvent",         # Name by which the event will be referenced
                func=my_func,           # Synchronous or Asynchronous function
                loop=my_event_loop,     # Provide a target loop in which to execute the function, Default: None (get running)
                recurring=True,         # Determines if the event should be re-registered after the first emit, Default: True
            )
        
        and
        
            @mgr.on(name="Add", loop=my_event_loop, recurring=True)
            def my_callback(num1, num2, num3, num4):
                # e.g. run hard calculations within a ProcessPoolExecutor
                total = num1 + num2 + num3 + num4
                mgr.emit("Calculated", args=(total,))
            
            mgr.emit_after(0.1, "Add", args=(1, 2, 3, 4))
            data = await mgr.wait("Calculated")
            assert data.args[0] == 10
        
        #### Emitting an event
        Emit a signal with arbitrary positional and/or keyword parameters. This can be done with `mgr.emit` or `mgr.emit_after` which is identical except that it accepts an additional `delay` argument as its first parameter.
        
        
            mgr.emit(
                name="MyEvent",         # Name of the event to emit
                args=(1, 2, 3),         # Tuple of args used to emit
                kwargs={"num4": 4},     # Dict of kwargs used to emit     
            )
        
        #### Waiting for an event
        Using `mgr.wait`, you can asynchronously wait until an event is fired. This is commonly used just to wait for a certain status, but will also return an `EvtData` object which contains the `args` and `kwargs` values that were passed into the call to `mgr.emit`
        
            data = await mgr.wait(
                name="MyEvent",         # Name of the event to wait for
                timeout=None,           # Timeout in seconds, Default: None
            )
        
            print(data.args)            # mgr.emit(..., args=...)
            print(data.kwargs)          # mgr.emit(..., kwargs=...)
        
        #### Unregistering an event
        
        Recurring events can be unregistered manually both by name and by function value. **Note** that unregistering by name is significantly faster and more efficient, so use that when possible.
        
            mgr.unregister(name="MyEventName")
            mgr.unregister(func=my_callback_func)
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
