https://github.com/miraclx/node_events
A minor rewrite of the NodeJS EventEmitter in Python
https://github.com/miraclx/node_events
event-driven event-emitter nodejs-eventemitter python-eventemitter
Last synced: about 1 month ago
JSON representation
A minor rewrite of the NodeJS EventEmitter in Python
- Host: GitHub
- URL: https://github.com/miraclx/node_events
- Owner: miraclx
- License: apache-2.0
- Created: 2019-05-22T00:41:33.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2019-07-04T22:31:32.000Z (almost 7 years ago)
- Last Synced: 2025-10-11T06:28:51.467Z (8 months ago)
- Topics: event-driven, event-emitter, nodejs-eventemitter, python-eventemitter
- Language: Python
- Size: 43 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
The `EventEmitter` class is defined and exposed publicly by the module:
``` python
from node_events import EventEmitter
```
#### EventEmitter.`addListener`(eventName, listener)
* `eventName`: <string>
* `listener`: <function>
* Returns: <[EventEmitter](#eventemitter)>
Alias for [`self.on(eventName, listener)`](#eventemitter_on)
Emits the `'addlistener:{eventName}'` event when called.
#### EventEmitter.`on`(eventName, listener)
* `eventName`: <string> The name of the event.
* `listener`: <function> The callback function.
* Returns: <[EventEmitter](#eventemitter)>
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.
Emits the `'addlistener:{eventName}'` event when called.
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
```
#### EventEmitter.`once`(eventName, listener)
* `eventName`: <string> The name of the event.
* `listener`: <function> The callback function.
* Returns: <[EventEmitter](#eventemitter)>
Adds a **one-time** `listener` function for the event named `eventName`. The next time `eventName` is triggered, this listener is removed and then invoked.
Emits the `'addlistener:{eventName}'` event when called.
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
```
#### EventEmitter.`prependListener`(eventName, listener)
* `eventName`: <string> The name of the event.
* `listener`: <function> The callback function.
* Returns: <[EventEmitter](#eventemitter)>
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.
Emits the `'addlistener:{eventName}'` event when called.
``` 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.
#### EventEmitter.`prependOnceListener`(eventName, listener)
* `eventName`: <string> The name of the event.
* `listener`: <function> The callback function.
* Returns: <[EventEmitter](#eventemitter)>
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.
Emits the `'addlistener:{eventName}'` event when called.
``` 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.
#### EventEmitter.`removeAllListeners`([eventName])
* `eventName`: <string> The name of the event.
* Returns: <[EventEmitter](#eventemitter)>
Removes all listeners, or those of the specified `eventName`.
Emits the `'rmlistener:{eventName}'` event when called.
Returns a reference to the EventEmitter, so that calls can be chained.
#### EventEmitter.`removeListener`(eventName, listener)
* `eventName`: <string>
* `listener`: <function>
* Returns: <[EventEmitter](#eventemitter)>
Removes the specified `listener` from the listener array for the event named `eventName`.
Emits the `'rmlistener:{eventName}'` event when called.
#### EventEmitter.`hasEvent`(eventName, raiseException)
* `eventName`: <string>
* `raiseException`: <boolean> (**Default**: `False`)
* Returns: <[EventEmitter](#eventemitter)>
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`.
#### EventEmitter.`hasListeners`(eventName)
* `eventName`: <string>
* `raiseException`: <boolean>
* Returns: <[EventEmitter](#eventemitter)>
Safely check that the core [EventListenerStack](#eventlistenerstack) has at least one listener.
Implements the [`EventListenerStack::hasListeners()`](#eventlistenerstack_haslisteners) inherently.
### Class: `EventListener`(listener)
* `listener`: <function>
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
```
#### EventListener.`listenerCount`(getter)
Number of times the function has been called
#### EventListener.`respond`(*data)
* `*data`: <any>
Send the `data` arguments to the encapsulated function in evaluation
#### EventListener.`verify`(fn)
* `fn`: <function>
* Returns: <boolean>
Check if `fn` matches with the encapsulated function
Useful in finding the instance amongst others by matching its core
### Class: `EventListenerStack`(eventName)
* `eventName`: <string>
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()
# Prints
# hi from test_fn
```
#### EventListenerStack.`listeners`(getter)
Return a copy of the private listeners array.
#### EventListenerStack.`listenerCount`(getter)
Return the number of listeners exist and are actively waiting for event firings
#### EventListenerStack.`respond`(*data)
* `*data`: <any>
* Returns: <boolean>
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
#### EventListenerStack.`verifyHasListener`(fn)
* `fn`: <function>
Check if the stack has the listener `fn`
#### EventListenerStack.`attachListener`(fn, index)
* `fn`: <function>
* `index`: <number>
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
#### EventListenerStack.`detachListener`(fn)
* `fn`: <function>
* Returns: <boolean>
Detach the `fn` listener from the stack if it exists returning True otherwise return False
#### EventListenerStack.`detachAllListeners`()
Detach all the listeners within the stack
#### EventListenerStack.`hasListeners`()
Check if the stack has any listeners within
#### EventListenerStack.`extractInstanceOf`(fn)
* `fn`: <function>
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
pip3 install . --user
```
## License
[Apache 2.0][license] © **Miraculous Owonubi** ([@miraclx][author-url]) <omiraculous@gmail.com>
[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