Using signals¶

bzz uses the blinker library for signals. Using them is very simple:

import tornado.web
from mongoengine import *
import bzz
from bzz.signals import post_create_instance

server = None

# just create your own documents
class User(Document):
   __collection__ = "GettingStartedUser"
   name = StringField()

def create_user():
   # let's create a new user by posting it's data
   # we ignore the callback and response from http client
   # because we only need the signal in this example.
   http_client.fetch(
      'http://localhost:8889/user/',
      method='POST',
      body='name=Bernardo%20Heynemann'
   )

def handle_post_instance_created(sender, instance, handler):
   # just making sure we got the actual user
   try:
       assert instance.name == 'Bernardo Heynemann'
   finally:
       io_loop.stop()

# just connect the signal to the event handler
post_create_instance.connect(handle_post_instance_created)

# get routes for our model
routes = bzz.ModelHive.routes_for('mongoengine', User)

# Make sure our test is clean
User.objects.delete()

# create the server and run it
application = tornado.web.Application(routes)
server = HTTPServer(application, io_loop=io_loop)
server.listen(8889)
io_loop.add_timeout(1, create_user)
io_loop.start()

Available Signals¶

pre_get_instance¶

This signal is sent before an instance is retrieved (GET with a PK).

If a list would be returned the pre_get_list signal should be used instead.

Please note that since this signal is sent before getting the instance, the instance is not available yet.

Arguments:

sender - The model that assigned the signal
arguments - URL arguments that will be used to get the instance.
handler - The tornado handler that will be used to get the instance of your model.

Example handler:

def handle_pre_get_instance(sender, arguments, handler):
    if handler.application.config.SEND_TO_URL:
        # sends something somewhere
        pass

post_get_instance¶

This signal is sent after an instance is retrieved (GET with a PK).

If a list would be returned the post_get_list signal should be used instead.

Arguments:

sender - The model that assigned the signal
instance - The instance of your model that was retrieved.
handler - The tornado handler that was used to get the instance of your model.

Example handler:

def handle_post_get_instance(sender, instance, handler):
    # do something with instance

pre_get_list¶

This signal is sent before a list of instances is retrieved (GET without a PK).

If an instance would be returned the pre_get_instance signal should be used instead.

Please note that since this signal is sent before getting the list, the list is not available yet.

Arguments:

sender - The model that assigned the signal
arguments - URL arguments that will be used to get the instance.
handler - The tornado handler that will be used to get the instance of your model.

Example handler:

def handle_pre_get_list(sender, arguments, handler):
    if handler.application.config.SEND_TO_URL:
        # sends something somewhere
        pass

post_get_list¶

This signal is sent after a list of instances is retrieved (GET without a PK).

If an instane would be returned the post_get_instance signal should be used instead.

Arguments:

sender - The model that assigned the signal
items - The list of instances of your model that was retrieved.
handler - The tornado handler that was used to get the instance of your model.

Example handler:

def handle_post_get_list(sender, items, handler):
    # do something with the list of items

pre_create_instance¶

This signal is sent before a new instance is created (POST).

Please note that since this signal is sent before creating the instance, the instance is not available yet.

Arguments:

sender - The model that assigned the signal
arguments - URL arguments that will be used to create the instance.
handler - The tornado handler that will be used to create the new instance of your model.

Example handler:

def handle_before_instance_created(sender, arguments, handler):
    if handler.application.config.SEND_TO_URL:
        # sends something somewhere
        pass

post_create_instance¶

This signal is sent after a new instance is created (POST).

Arguments:

sender - The model that assigned the signal
instance - The instance that was created.
handler - The tornado handler that created the new instance of your model.

Example handler:

def handle_post_instance_created(sender, instance, handler):
    if handler.application.config.SEND_TO_URL:
        # sends something somewhere
        pass

    # do something else with instance

pre_update_instance¶

This signal is sent before an instance is updated (PUT).

Please note that since this signal is sent before updating the instance, the instance is not available yet.

Arguments:

sender - The model that assigned the signal
arguments - URL arguments that will be used to update the instance.
handler - The tornado handler that will be used to update the instance of your model.

Example handler:

def handle_before_instance_updated(sender, arguments, handler):
     # if something is wrong, raise error

post_update_instance¶

This signal is sent after an instance is updated (PUT).

Arguments:

sender - The model that assigned the signal
instance - The instance that was updated.
updated_fields - The fields that were updated in the instance with the old and new values.
handler - The tornado handler that updated the instance of your model.

The updated_fields format is like:

{
    'field': {
        'from': 1,
        'to': 2
    },
    'field2': {
        'from': 'a',
        'to': 'b'
    }
}

Example handler:

def handle_post_instance_updated(sender, instance, updated_fields, handler):
    # do something else with instance and/or updated_fields

pre_delete_instance¶

This signal is sent before an instance is deleted (DELETE).

Please note that since this signal is sent before deleting the instance, the instance is not available yet.

Arguments:

sender - The model that assigned the signal
arguments - URL arguments that will be used to delete the instance.
handler - The tornado handler that will be used to delete the instance of your model.

Example handler:

def handle_before_instance_deleted(sender, arguments, handler):
    # do something with arguments

post_delete_instance¶

This signal is sent after a new instance is deleted (DELETE).

Arguments:

sender - The model that assigned the signal
instance - The instance that was created.
handler - The tornado handler that created the new instance of your model.

WARNING: The instance returned on this signal has already been removed. How each ORM handles this is peculiar to the given ORM.

Example handler:

def handle_post_instance_deleted(sender, instance, handler):
    # do something else with instance
    # just remember the instance has already been deleted!

pre_get_user_details¶

In order to add more items in the authenticated user data (retrieved by /me route), you can use the pre_get_user_details:

signals.pre_get_user_details = None¶

Arguments:

provider_name: Used as sender and can be used to filter what signals to listen to.

user_data: A dict similar to:

{
    id: "1234567890abcdef",
    email: "...@holmes.com",
    name: "Sherlock Holmes",
    provider: "google"
}

handler: The tornado handler that will be used to update the user data

Example handler:

@signals.pre_get_user_details.connect
def handle_pre_get_user_details(self, provider_name, user_data, handler):
    # add user details under user_data, such as:
    # user_data['username'] = 'holmes'