Skip to main content

The Blinker Herald includes helpers to easily emit signals using Blinker. Decorate a function or method with @blinker_herald.emit() and pre and post signals will automatically be emitted to connected handlers.

Project description

===============================
Blinker Herald
===============================

.. image:: https://img.shields.io/pypi/v/blinker_herald.svg
:target: https://pypi-hypernode.com/pypi/blinker_herald

.. image:: https://img.shields.io/travis/rochacbruno/blinker_herald.svg
:target: https://travis-ci.org/SatelliteQE/blinker_herald

.. image:: https://readthedocs.org/projects/blinker_herald/badge/?version=latest
:target: https://readthedocs.org/projects/blinker_herald/?badge=latest
:alt: Documentation Status

.. image:: https://coveralls.io/repos/github/SatelliteQE/blinker_herald/badge.svg?branch=master
:target: https://coveralls.io/github/SatelliteQE/blinker_herald?branch=master
:alt: Coverage

.. image:: docs/The_Herald.jpg
:scale: 50 %

The Blinker Herald includes helpers to easily emit signals using the excelent
`blinker`_ library.

Decorate a function or method with :code:`@blinker_herald.emit()`
and **pre** and **post** signals will be automatically emitted to
all connected handlers.

* Free software: ISC license
* Documentation: https://blinker_herald.readthedocs.org.

Features
--------

* All the features provided by `blinker`_
* `+` an easy decorator :code:`@emit()` to magically emit signals when your functions are called and before it returns a result.
* A :code:`signals` namespace proxy to discover the signals in your project
* Customizable for your needs


Usage
-----
Let's say you have a class and wants to emit a signal for a specific method::

from blinker_herald import emit

class SomeClass(object):

@emit()
def do_something(self, arg1):
# here is were magically the 'pre' signal will be sent
return 'something done'
# here is were magically the 'post' signal will be sent


using :code:`@emit` decorator makes blinker_herald to emit a signal for that method
and now you can connect handlers to capture that signals

You can capture **pre** signal to manipulate the object::

SomeClass.do_something.pre.connect
def handle_pre(sender, signal_emitter, **kwargs):
signal_emitter.foo = 'bar'
signal_emitter.do_another_thing()

And you can also capture the **post** signal to log the results::

SomeClass.do_something.post.connect
def handle_post(sender, signal_emitter, result, **kwargs):
logger.info("The method {0} returned {1}".format(sender, result))


You can also use the namespace proxy :code:`blinker_herald.signals` to connect
handlers to signals, the signal name is the prefix **pre** or **post**
followed by **_** and the method name::

from blinker_herald import signals

@signals.pre_do_something.connect
def handle_pre(sender, signal_emitter, **kwargs):
...


If you have a lot of subclasses emitting signals with the same name and you
need to capture only specific signals, you can specify that you want to listen
to only one type of sender::

from blinker_herald import emit, signals, SENDER_CLASS
class BaseModel(object):
...
@emit(sender=SENDER_CLASS)
def create(self, **kwargs):
new_instance = my_project.new(self, **kwargs)
return new_instance

class One(BaseModel):
pass

class Two(BaseModel):
pass

.. note::
By default the sender is always the instance but you can use :code:`SENDER_CLASS`
to force the sender to be the **class** another options are **SENDER_CLASS_NAME**,
**SENDER_MODULE**, **SENDER_NAME** and you can also pass a string, an object
or a lambda receiving the **sender** instance e.g: :code:`@emit(sender=lambda self: self.get_sender())`

Using :code:`SENDER_CLASS` you can now connect to specific signal::

from blinker_herald import signals

@signals.post_create.connect_via(One)
def handle_post_only_for_one(sender, signal_emitter, result, **kwargs):
# sender is the class One (cls)
# signal the instance of the class One (self)
# result is the return of the method create

The above will handle the :code:`create` method signal for the class **One** but not for the class **Two**


You can also be more specific about the signal you want to connect using the
**__** double underscore to provide method name::

from blinker_herald import signals

@signals.module_name__ClassName__post_method_name.connect
def handle_post(sender, signal_emitter, result, **kwargs):
...

The above will connect to the **post** signal emitted by :code:`module_name.ClassName.method_name`

.. note::
You don't have to use the pattern above if your project do not have a lot of
method name collisions, using only the method name will be just fine for most cases.



Credits
-------

This software was first created by SatelliteQE team to provide signals to
Robottelo and Nailgun

.. _blinker: http://pypi.python.org/pypi/blinker


=======
History
=======

0.1.0 (2016-05-28)
------------------

* First release on PyPI.

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

blinker_herald-0.2.0.tar.gz (42.1 kB view details)

Uploaded Source

Built Distribution

blinker_herald-0.2.0-py2.py3-none-any.whl (8.3 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file blinker_herald-0.2.0.tar.gz.

File metadata

File hashes

Hashes for blinker_herald-0.2.0.tar.gz
Algorithm Hash digest
SHA256 b1fd320aa594a5f0cd4cd2e07db97cdbbea00197fdcd38161c873864315351cd
MD5 bbe974b9fe5b5a381dcbb1ae63fc35fd
BLAKE2b-256 98fec3ef82a7d78ddcecff0cbae06433f0c0fd164910d5308af7594370ebfd11

See more details on using hashes here.

Provenance

File details

Details for the file blinker_herald-0.2.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for blinker_herald-0.2.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 2558c404a1ea0f62b99a167d0d8794bbc45fcd3b1e8d8bdfcab1dd1d2b1809f9
MD5 11265eb654375e7a76f8ef322b22e757
BLAKE2b-256 c501ec44660f2a35b3e280e2d8334fff6396657feaa2e59f9675604be586bf96

See more details on using hashes here.

Provenance

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