Metadata-Version: 2.1
Name: node_events
Version: 0.6.1
Summary: A minor rewrite of the NodeJS EventEmitter in Python
Home-page: https://github.com/miraclx/node_events.py
Author: Miraculous Owonubi
Author-email: omiraculous@gmail.com
License: Apache-2.0
Description: # node_events.py
        
        > A minor rewrite of the NodeJS EventEmitter in Python
        
        [![PyPI Version][pypi-image]][pypi-url]
        ![License][license-image]
        ![Python Version][version-image]
        
        ## Installing
        
        Via [PyPI][pypi-url]:
        
        ``` bash
        pip install node_events
        ```
        
        ## Usage
        
        ``` python
        from node_events import EventEmitter
        
        myEmitter = EventEmitter()
        
        
        def fn():
            print("An event occurred")
        
        
        myEmitter.on('event', fn)
        myEmitter.emit('event')
        
        # Prints
        #   An event occurred
        
        ```
        
        ## API
        
        ### <a id="eventemitter"></a> Class: `EventEmitter`
        
        The `EventEmitter` class is defined and exposed publicly by the module:
        ``` python
        from node_events import EventEmitter
        ```
        
        #### EventEmitter.`addListener`(eventName, listener)
        
        * `eventName`: &lt;string&gt;
        * `listener`: &lt;function&gt;
        * Returns: &lt;[EventEmitter](#eventemitter)&gt;
        
        Alias for [`self.on(eventName, listener)`](#eventemitter_on)
        
        #### <a id="eventemitter_on"></a> EventEmitter.`on`(eventName, listener)
        
        * `eventName`: &lt;string&gt; The name of the event.
        * `listener`: &lt;function&gt; The callback function.
        * Returns: &lt;[EventEmitter](#eventemitter)&gt;
        
        Appends the `listener` to the listeners array for the event named `eventName`. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.
        By default, event listeners are invoked in the order they are added. The [`emitter.prependListener()`](#eventemitter_prependlistener) method can be used as an alternative to add the event listener to the beginning of the listeners array.
        
        Returns a reference to the `EventEmitter`, so that calls can be chained.
        
        ``` python
        emitter = EventEmitter()
        
        def appendListener():
          print('a')
        
        def prependListener():
          print('b')
        
        emitter.on('test', appendListener)
        emitter.prependListener('test', appendListener)
        
        emitter.emit('test')
        
        # Prints
        #   b
        #   a
        ```
        
        #### <a id="eventemitter_once"></a> EventEmitter.`once`(eventName, listener)
        
        * `eventName`: &lt;string&gt; The name of the event.
        * `listener`: &lt;function&gt; The callback function.
        * Returns: &lt;[EventEmitter](#eventemitter)&gt;
        
        Adds a **one-time** `listener` function for the event named `eventName`. The next time `eventName` is triggered, this listener is removed and then invoked.
        By default, event listeners are invoked in the order they are added. The [`emitter.prependOnceListener()`](#eventemitter_prependoncelistener) method can be used as an alternative to add the event listener to the beginning of the listeners array.
        
        Returns a reference to the `EventEmitter`, so that calls can be chained.
        
        ``` python
        emitter = EventEmitter()
        
        def appendListener():
          print('a')
        
        def prependListener():
          print('b')
        
        emitter.once('test', appendListener)
        emitter.prependOnceListener('test', appendListener)
        
        emitter.emit('test')
        
        # Prints
        #   b
        #   a
        ```
        
        #### <a id="eventemitter_prependlistener"></a> EventEmitter.`prependListener`(eventName, listener)
        
        * `eventName`: &lt;string&gt; The name of the event.
        * `listener`: &lt;function&gt; The callback function.
        * Returns: &lt;[EventEmitter](#eventemitter)&gt;
        
        Adds the `listener` function to the beginning of the listeners array for the event named `eventName`. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.
        
        ``` python
        emitter = EventEmitter()
        
        def newConnection():
          print('someone connected!')
        
        emitter.prependListener('connection', newConnection)
        emitter.emit('connection')
        ```
        
        Returns a reference to the `EventEmitter`, so that calls can be chained.
        
        #### <a id="eventemitter_prependoncelistener"></a> EventEmitter.`prependOnceListener`(eventName, listener)
        
        * `eventName`: &lt;string&gt; The name of the event.
        * `listener`: &lt;function&gt; The callback function.
        * Returns: &lt;[EventEmitter](#eventemitter)&gt;
        
        Adds a **one-time** `listener` function for the event named `eventName` to the beginning of the listeners array. The next time `eventName` is triggered, this listener is removed, and then invoked.
        
        ``` python
        emitter = EventEmitter()
        
        def newConnection():
          print('someone connected!')
        
        emitter.prependOnceListener('connection', newConnection)
        emitter.emit('connection')
        ```
        
        Returns a reference to the `EventEmitter`, so that calls can be chained.
        
        #### <a id="eventemitter_removealllisteners"></a> EventEmitter.`removeAllListeners`([eventName])
        
        * `eventName`: &lt;string&gt; The name of the event.
        * Returns: &lt;[EventEmitter](#eventemitter)&gt;
        
        Removes all listeners, or those of the specified `eventName`.
        
        Returns a reference to the EventEmitter, so that calls can be chained.
        
        #### <a id="eventemitter_removelistener"></a> EventEmitter.`removeListener`(eventName, listener)
        
        * `eventName`: &lt;string&gt;
        * `listener`: &lt;function&gt;
        * Returns: &lt;[EventEmitter](#eventemitter)&gt;
        
        Removes the specified `listener` from the listener array for the event named `eventName`.
        
        #### <a id="eventemitter_hasevent"></a> EventEmitter.`hasEvent`(eventName, raiseException)
        
        * `eventName`: &lt;string&gt;
        * `raiseException`: &lt;boolean&gt; (**Default**: `False`)
        * Returns: &lt;[EventEmitter](#eventemitter)&gt;
        
        Check if the event emitter has within itself an event named `eventName`, return a boolean for the operation.
        if `raiseException` is True, raise an exception if the result of the check evaluates to `False`.
        
        #### <a id="eventemitter_haslisteners"></a> EventEmitter.`hasListeners`(eventName)
        
        * `eventName`: &lt;string&gt;
        * `raiseException`: &lt;boolean&gt;
        * Returns: &lt;[EventEmitter](#eventemitter)&gt;
        
        Safely check that the core [EventListenerStack](#eventlistenerstack) has at least one listener.
        Implements the [`EventListenerStack::hasListeners()`](#eventlistenerstack_haslisteners) inherently.
        
        ### <a id="eventlistener"></a> Class: `EventListener`(listener)
        
        * `listener`: &lt;function&gt;
        
        This class wraps the `listener` function with useful, sandboxed manipulative features
        
        The `EventListener` class is defined and exposed publicly by the module:
        ``` python
        from node_events import EventListener
        
        def fn():
          print("test_fn")
        
        EventListener(fn).respond()
        
        # Prints
        #   test_fn
        ```
        
        #### <a id="eventlistener_listenercount"></a> EventListener.`listenerCount`<sub>(getter)</sub>
        
        Number of times the function has been called
        
        #### <a id="eventlistener_respond"></a> EventListener.`respond`(*data)
        
        * `*data`: &lt;any&gt;
        
        Send the `data` arguments to the encapsulated function in evaluation
        
        #### <a id="eventlistener_verify"></a> EventListener.`verify`(fn)
        
        * `fn`: &lt;function&gt;
        * Returns: &lt;boolean&gt;
        
        Check if `fn` matches with the encapsulated function
        Useful in finding the instance amongst others by matching its core
        
        ### <a id="eventlistenerstack"></a> Class: `EventListenerStack`(eventName)
        
        * `eventName`: &lt;string&gt;
        
        Stacking layer of listeners for an event defined named `eventName`
        Serves as an interfacing remote for series of grouped listeners
        
        The `EventListenerStack` class is defined and exposed publicly by the module:
        ``` python
        from node_events import EventListenerStack
        
        def test_fn():
          print("hi from test_fn")
        
        stack = EventListenerStack("event_name")
        stack.attachListener(test_fn, 0)
        stack.respond()
        
        # Print
        #   hi from test_fn
        ```
        
        #### <a id="eventlistenerstack_listeners"></a> EventListenerStack.`listeners`<sub>(getter)</sub>
        
        Return a copy of the private listeners array. (recommended if iterations skips some indexes in [`self.rawListeners`](#eventlistenerstack_rawlisteners))
        
        #### <a id="eventlistenerstack_listenercount"></a> EventListenerStack.`listenerCount`<sub>(getter)</sub>
        
        Return the number of listeners exist and are actively waiting for event firings
        
        #### <a id="eventlistenerstack_respond"></a> EventListenerStack.`respond`(*data)
        
        * `*data`: &lt;any&gt;
        * Returns: &lt;boolean&gt;
        
        Send the `data` arguments to all the listeners within the stack in the order of which they appear
        Returns True if the stack has any active listeners who read the data else False
        
        #### <a id="eventlistenerstack_verifyhaslistener"></a> EventListenerStack.`verifyHasListener`(fn)
        
        * `fn`: &lt;function&gt;
        
        Check if the stack has the listener `fn`
        
        #### <a id="eventlistenerstack_attachlistener"></a> EventListenerStack.`attachListener`(fn, index)
        
        * `fn`: &lt;function&gt;
        * `index`: &lt;number&gt;
        
        Attach the `fn` listener to the event stack.
        The `index` parameter determines the index at which to place the function in the stack array
        Note, function calls are based on orderly calls from the stack array
        
        #### <a id="eventlistenerstack_detachlistener"></a> EventListenerStack.`detachListener`(fn)
        
        * `fn`: &lt;function&gt;
        * Returns: &lt;boolean&gt;
        
        Detach the `fn` listener from the stack if it exists returning True otherwise return False
        
        #### <a id="eventlistenerstack_detachalllisteners"></a> EventListenerStack.`detachAllListeners`()
        
        Detach all the listeners within the stack
        
        #### <a id="eventlistenerstack_haslisteners"></a> EventListenerStack.`hasListeners`()
        
        Check if the stack has any listeners within
        
        #### <a id="eventlistenerstack_extractinstanceof"></a> EventListenerStack.`extractInstanceOf`(fn)
        
        * `fn`: &lt;function&gt;
        
        Extract the [`EventListener`](#eventlistener) instance encapsulating the `fn` listener if it exists otherwise return `None`
        
        ## Development
        
        ### Building
        
        Feel free to clone, use in adherance to the [license](#license) and perhaps send pull requests
        
        ``` bash
        git clone https://github.com/miraclx/node_events.py.git
        cd node_events.py
        # hack on code
        python3 setup.py bdist_wheel
        pip3 install dist/*.whl --user
        ```
        
        ## License
        
        [Apache 2.0][license] © **Miraculous Owonubi** ([@miraclx][author-url]) &lt;omiraculous@gmail.com&gt;
        
        [license]:  LICENSE 'Apache 2.0 License'
        [author-url]: https://github.com/miraclx
        
        [pypi-url]: https://pypi.org/project/node-events
        [pypi-image]: https://img.shields.io/pypi/v/node-events.svg?color=red&label=node-events&style=popout-square
        [license-image]: https://img.shields.io/pypi/l/node-events.svg?color=green&label=License&style=popout-square
        [version-image]: https://img.shields.io/pypi/pyversions/node-events.svg?color=blue&label=PythonVersion&style=popout-square
        
Platform: UNKNOWN
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Description-Content-Type: text/markdown
