node_events.py

A minor rewrite of the NodeJS EventEmitter in Python

Installing

Via PyPI:

pip install node_events

Usage

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

Class: EventEmitter

The EventEmitter class is defined and exposed publicly by the module:

from node_events import EventEmitter

EventEmitter.addListener(eventName, listener)

• eventName: <string>
• listener: <function>
• Returns: <EventEmitter>

Alias for self.on(eventName, listener)

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>

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() 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.

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>

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() 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.

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>

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.

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>

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.

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>

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>

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>

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>

Safely check that the core EventListenerStack has at least one listener. Implements the 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:

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:

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 instance encapsulating the fn listener if it exists otherwise return None

Development

Building

Feel free to clone, use in adherance to the license and perhaps send pull requests

git clone https://github.com/miraclx/node_events.py.git
cd node_events.py
# hack on code
pip3 install . --user

License

Apache 2.0 © Miraculous Owonubi (@miraclx) <omiraculous@gmail.com>