Skip to main content

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

Project description

Documentation status Python version Package version Package downloads Code coverge Build status License

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

Original source hosted at GitHub.

Features

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

Installation

Simply install via pip:

pip install pymitter

The last version with Python 2 support was v0.3.2 (PyPI).

Examples

Basic usage

from pymitter import EventEmitter


ee = EventEmitter()


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


# callback usage
def handler2(arg):
    print("handler2 called with", arg)


ee.on("my_other_event", handler2)


# support for coroutine functions
@ee.on("my_third_event")
async def handler3(arg):
    print("handler3 called with", arg)


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

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

ee.emit("my_third_event", "baz")
# -> "handler3 called with baz"

Coroutines

Wrapping async functions outside an event loop will start an internal event loop and calls to emit return synchronously.

from pymitter import EventEmitter


ee = EventEmitter()


# register an async function
@ee.on("my_event")
async def handler1(arg):
    print("handler1 called with", arg)


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

Wrapping async functions inside an event loop will use the same loop and emit_async is awaitable.

from pymitter import EventEmitter


ee = EventEmitter()


async def main():
    # emit_async
    awaitable = ee.emit_async("my_event", "foo")
    # -> nothing printed yet

    await awaitable
    # -> "handler1 called with foo"

Use emit_future to not return awaitable objects but to place them at the end of the existing event loop (using asyncio.ensure_future internally).

TTL (times to listen)

from pymitter import EventEmitter


ee = EventEmitter()


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


@ee.on("my_event", ttl=2)
def handler2():
    print("handler2 called")


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

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

ee.emit("my_event")
# nothing called anymore

Wildcards

from pymitter import EventEmitter


ee = EventEmitter(wildcard=True)


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


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


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


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

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

ee.emit("my_event.*")
# -> "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. Async functions are called in a new event loop. There is no return value.

  • (async) emit_async(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. Awaitable objects returned by async functions are awaited in the outer event loop. Returns an Awaitable.

  • emit_future(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. Awaitable objects returned by async functions are placed at the end of the event loop using asyncio.ensure_future. There is no return value.

Development

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pymitter-0.5.1.tar.gz (10.0 kB view details)

Uploaded Source

Built Distribution

pymitter-0.5.1-py3-none-any.whl (9.2 kB view details)

Uploaded Python 3

File details

Details for the file pymitter-0.5.1.tar.gz.

File metadata

  • Download URL: pymitter-0.5.1.tar.gz
  • Upload date:
  • Size: 10.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.9.19

File hashes

Hashes for pymitter-0.5.1.tar.gz
Algorithm Hash digest
SHA256 6344e9728f0281672b79181ed8950dac07d3ab7169458b692f07756b87281f2d
MD5 8121c89fb10e276bc6337b27013d9828
BLAKE2b-256 e2d1d66545682f22131fd40886d864c93da1a0bb78b91440fd5217900dd2f944

See more details on using hashes here.

File details

Details for the file pymitter-0.5.1-py3-none-any.whl.

File metadata

  • Download URL: pymitter-0.5.1-py3-none-any.whl
  • Upload date:
  • Size: 9.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.9.19

File hashes

Hashes for pymitter-0.5.1-py3-none-any.whl
Algorithm Hash digest
SHA256 01ed91e143508b8ee1ba4d59ce796d6cb3efcc3e43a240f46026c1b63dcd0feb
MD5 5ee8321791b22f768f22f09be0fabaa9
BLAKE2b-256 81a65f46e806079a1fc2608d2cacb312c039c544d6eb93c718941b3b056bd2b7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page