/pymitter

Python port of the extended Node.js EventEmitter 2 approach providing namespaces, wildcards and TTL.

Primary LanguagePython

pymitter

Python port of the extended Node.js EventEmitter 2 approach of https://github.com/asyncly/EventEmitter2 providing namespaces, wildcards and TTL.

Features

  • Namespaces with wildcards
  • Times to listen (TTL)
  • Usage via decorators or callbacks
  • Lightweight implementation, good performance

Installation

pymitter is a registered PyPI module, so the installation with pip is quite easy:

pip install pymitter

Examples

Basic usage

from pymitter import EventEmitter

ee = EventEmitter()

# decorator usage
@ee.on("myevent")
def handler1(arg):
   print "handler1 called with", arg

# callback usage
def handler2(arg):
    print "handler2 called with", arg
ee.on("myotherevent", handler2)

# emit
ee.emit("myevent", "foo")
# -> "handler1 called with foo"

ee.emit("myotherevent", "bar")
# -> "handler2 called with bar"

TTL

from pymitter import EventEmitter

ee = EventEmitter()

@ee.once("myevent")
def handler1():
    print "handler1 called"

@ee.on("myevent", ttl=10)
def handler2():
    print "handler2 called"


ee.emit("myevent")
# -> "handler1 called"
# -> "handler2 called"

ee.emit("myevent")
# -> "handler2 called"

Wildcards

from pymitter import EventEmitter

ee = EventEmitter(wildcards=True)

@ee.on("myevent.foo")
def handler1():
    print "handler1 called"

@ee.on("myevent.bar")
def handler2():
    print "handler2 called"

@ee.on("myevent.*")
def hander3():
    print "handler3 called"


ee.emit("myevent.foo")
# -> "handler1 called"
# -> "handler3 called"

ee.emit("myevent.bar")
# -> "handler2 called"
# -> "handler3 called"

ee.emit("myevent.*")
# -> "handler1 called"
# -> "handler2 called"
# -> "handler3 called"

API

EventEmitter(wildcard=False, delimiter=".", new_listener=False, max_listeners=-1)

EventEmitter constructor. Note: always use kwargs for configuration. When wildcard is True, wildcards are used as shown in this example. delimiter is used to seperate namespaces within events. If new_listener is True, the "new_listener" event is emitted every time a new listener is registered. Functions listening to this event are passed (func, event=None). max_listeners defines the maximum number of listeners per event. Negative values mean infinity.

  • on(event, func=None, ttl=-1)

    Registers a function to an event. When func is None, decorator usage is assumed. ttl defines the times to listen. Negative values mean infinity. Returns the function.

  • once(event, func=None)

    Registers a function to an event with ttl = 1. When func is None, decorator usage is assumed. Returns the function.

  • on_any(func=None)

    Registers a function that is called every time an event is emitted. When func is None, decorator usage is assumed. Returns the function.

  • off(event, func=None)

    Removes a function that is registered to an event. When func is None, decorator usage is assumed. Returns the function.

  • off_any(func=None)

    Removes a function that was registered via on_any(). When func is None, decorator usage is assumed. Returns the function.

  • off_all()

    Removes all functions of all events.

  • listeners(event)

    Returns all functions that are registered to an event. Wildcards are not applied.

  • listeners_any()

    Returns all functions that were registered using on_any().

  • listeners_all()

    Returns all registered functions.

  • emit(event, *args, **kwargs)

    Emits an event. All functions of events that match event are invoked with args and kwargs in the exact order of their registeration. Wildcards might be applied.

Development

License

The MIT License (MIT)

Copyright (c) 2014 Marcel Rieger

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Authors

Marcel R. (riga)