Welcome to django_event’s documentation!

Django Event is notification system framework that allows you to push notifications to the browser.

Installing

First you need pip. Use your OS’s package system to install it. On ubuntu you can install it like this:

apt-get install python-pip

And it is highly recommended you to use python virtual environment. See Virtualenv docs.

After that you need to install django-event:

pip install git+https://github.com/ailove-dev/django-event

If you use Django Rest Framework and want to django-event provided REST api’s for events use following command:

pip install git+https://github.com/ailove-dev/django-event[rest_framework_api]

Contents:

django_event

django_event.management

django_event.management.commands
django_event.management.commands.deleteoldevents
class django_event.management.commands.deleteoldevents.Command[source]

Bases: django.core.management.base.NoArgsCommand

Django command to delete old events.

handle_noargs(**options)[source]
django_event.management.commands.runwebsocketserver
class django_event.management.commands.runwebsocketserver.Command(stdout=None, stderr=None, no_color=False)[source]

Bases: django.core.management.base.BaseCommand

Django command to start tornado server.

handle(*args, **options)[source]

django_event.publisher

django_event.publisher.rest_framework
django_event.publisher.rest_framework.serializers

Serializers module for django rest_framework.

class django_event.publisher.rest_framework.serializers.EventSerializer(instance=None, data=None, files=None, context=None, partial=False, many=None, allow_add_remove=False, **kwargs)[source]

Bases: rest_framework.serializers.ModelSerializer

Specifies which fields should be serialized and overrides date fields to return local time instead of server time.

class Meta[source]
model

alias of Event

exclude = ('event_request', 'task_name', 'task_id')
class django_event.publisher.rest_framework.serializers.LocalDateTimeField(input_formats=None, format=None, *args, **kwargs)[source]

Bases: rest_framework.fields.DateTimeField

Automatically converts server time into local time.

to_representation(value)[source]

Converts UTC to local time.

Parameters:value (DateTime) – UTC datetime from db.
django_event.publisher.rest_framework.urls

Urls for django.

urlpatterns = patterns(
    '',
    url(
        r'^$',
        event_list,
        name='event_list'
    ),
    url(
        r'^(?P<pk>[0-9]+)/$',
        event_detail,
        name='event_detail'
    ),
    url(
        r'^(?P<pk>[0-9]+)/cancel/$',
        cancel_event,
        name='cancel_event'
    ),
    url(
        r'^(?P<pk>[0-9]+)/retry/$',
        retry_event,
        name='retry_event'
    ),
)
django_event.publisher.rest_framework.views

Synchronous views for django to get/cancel or retry events.

class django_event.publisher.rest_framework.views.CancelEventView(**kwargs)[source]

Bases: rest_framework.views.APIView

Cancel executing event.

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>,)
class django_event.publisher.rest_framework.views.EventDetailView(**kwargs)[source]

Bases: rest_framework.views.APIView

Retrieve specific user event.

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>,)
queryset
serializer_class

alias of EventSerializer

class django_event.publisher.rest_framework.views.EventTypesView(**kwargs)[source]

Bases: rest_framework.views.APIView

Event types view.

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>,)
class django_event.publisher.rest_framework.views.RetryEventView(**kwargs)[source]

Bases: rest_framework.views.APIView

Retry not completed event.

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>,)
django_event.publisher.rest_framework.views.cancel_event(*args, **kwargs)

Cancel executing event.

django_event.publisher.rest_framework.views.event_detail(*args, **kwargs)

Retrieve specific user event.

django_event.publisher.rest_framework.views.event_list(*args, **kwargs)

List all user events.

django_event.publisher.rest_framework.views.event_types(*args, **kwargs)

Event types view.

django_event.publisher.rest_framework.views.retry_event(*args, **kwargs)

Retry not completed event.

class django_event.publisher.rest_framework.views.EventListView(**kwargs)[source]

Bases: rest_framework.generics.ListAPIView

List all user events.

filter_backends = (filters.OrderingFilter, )

Filter backend. Provides basic ordering.

get(request, *args, **kwargs)[source]

Get user events —

serializer_class

alias of EventSerializer

django_event.publisher.decorator

Core publisher client module. Basically you should use this decorator instead of manually write events into database. Decorator specifies some overridable methods if you need basic customization.

Usage examples:

Defining event task:

@event(event_type='some_type', routing_strategy='')
def some_task(event_request, event):
    argument = event_request.custom_argument
    return some_processed_data(event_request.data, event)

And call:

some_task.delay(EventRequest(django_request, custom_argument=123))

You can know more about .delay() or other methods in Celery docs.

class django_event.publisher.decorator.event(event_type='', send_mail=False, progress_throttling=0.1, routing_strategy='', task_kwargs=None, on_start=lambda _event: None, on_success=lambda _event: None, on_error=lambda _event: None)[source]

Bases: object

Main client publisher interface. Decorates function and return celery task.

Automatically start and end event after celery started/completed the task. You must pass EventRequest into decorated function. EventRequest can accept keyword arguments needed by wrapped function which are not required but django request are required by internal needs. This decorator automatically set EventRequest and Event instances as wrapped function arguments.

Wrapped func may raise specific exception EventError used to notify subscribers about failure. Basically this decorator will handle only that type of exceptions. Be sure you handle all raised exception in wrapped func otherwise it will pass outside decorator and into database as well.

__call__(func)[source]

Wraps passed function into Celery Task.

Parameters:func (callable object) – Function to be wrapped.
Returns:Celery task instance.
Return type:Celery Task
__init__(event_type='', send_mail=False, progress_throttling=0.1, routing_strategy='', task_kwargs=None, on_start=lambda _event: None, on_success=lambda _event: None, on_error=lambda _event: None)[source]
Parameters:
  • event_type (str) – Event type, using in message routing.
  • send_mail (bool) – Send email after event is done.
  • progress_throttling (float) – Describes how often event will send progress messages. See Event docs for more information about this parameter.
  • routing_strategy (str) – Routing strategy e.g. what listeners will do with messages. Empty strategy means you want to deliver notification to all subscribed clients. See Event docs for more information about this parameter.
  • task_kwargs (dict) – Celery task arguments.
  • on_start (str) – Event start callback.
  • on_success (callable object) – Event success callback.
  • on_error (callable object) – Event error callback.
complete_event()[source]

Ends event. Override this if you want to customize message.

create_event()[source]

Create event model with passing arguments. Basically you dont need to manually create event.

start_event()[source]

Starts event. Override this if you want to customize message.

django_event.publisher.exceptions

Exceptions module.

exception django_event.publisher.exceptions.EventError[source]

Bases: exceptions.Exception

Using to notify subscribed clients about event failure.

django_event.publisher.publisher
django_event.publisher.request

Event request module.

Usage examples: You can pass custom arguments into decorated function which are not required.

EventRequest(django_request, custom_argument=123)

But django request is must for event.

EventRequest(django_request)
class django_event.publisher.request._DummyRequest(data, user)[source]

Private class that emulates Django Request class.

class django_event.publisher.request._DummyUser(user_id)[source]

Private class that emulates Django User class.

class django_event.publisher.request.EventRequest(django_request, **kwargs)[source]

Bases: object

Event request class user to pass arguments to decorated events.

__getattr__(item)[source]

Magick method for dot notation for custom task arguments.

static deserialize(json_request, return_dummy=False)[source]

Deserialize JSON request and returns EventRequest instance or dict which contains Dummy classes.

Parameters:
  • json_request (str) – JSON serialized event request.
  • return_dummy (bool) – Return EventRequest or dict with dummies.
Returns:

Deserialized instance.
Return type:

EventRequest or dict
serialize()[source]

Serialize event request into JSON for database storing.

Returns:JSON serialized event request.
Return type:str
django_event.publisher.views

Synchronous views for django to get/cancel or retry events.

class django_event.publisher.views.CancelEventView(**kwargs)[source]

Bases: django_event.publisher.views.LoginRequiredMixin, django_event.publisher.views.EventDetailMixin, django.views.generic.base.View

Base cancel event view class.

cancel(pk)[source]

Returns True if event is successfully canceled False otherwise.

Parameters:pk (int) – Event id.
Returns:True if canceled else False.
Return type:bool
post(request, pk)[source]
class django_event.publisher.views.EventDetailMixin[source]

Bases: django_event.publisher.views.EventListMixin

Event view mixin class with overrided get_object() method.

get_object(pk, queryset=None)[source]

Returns user-owned event by id.

Returns:QuerySet of user-owned events.
Return type:Event
class django_event.publisher.views.EventDetailView(**kwargs)[source]

Bases: django_event.publisher.views.LoginRequiredMixin, django_event.publisher.views.EventDetailMixin, django.views.generic.detail.DetailView

Base event detail view class.

class django_event.publisher.views.EventListMixin[source]

Bases: object

Event view mixin class with overrided get_queryset() method.

get_queryset()[source]

Returns user-owned events.

Returns:QuerySet of user-owned events.
Return type:EventQuerySet
model

alias of Event

class django_event.publisher.views.EventListView(**kwargs)[source]

Bases: django_event.publisher.views.LoginRequiredMixin, django_event.publisher.views.EventListMixin, django.views.generic.list.ListView

Base event list view class.

class django_event.publisher.views.EventTypesView(**kwargs)[source]

Bases: django_event.publisher.views.LoginRequiredMixin, django.views.generic.base.View

Event types view.

get(request)[source]

Return event types.

class django_event.publisher.views.LoginRequiredMixin[source]

Bases: object

Event view mixin class with overrided dispatch() method to restrict anonymous users.

dispatch(*args, **kwargs)[source]

Override dispatch to implement auth restriction.

Parameters:request (HttpRequest) – Incoming request.
Returns:Response.
Return type:HttpResponse
class django_event.publisher.views.RetryEventView(**kwargs)[source]

Bases: django_event.publisher.views.LoginRequiredMixin, django_event.publisher.views.EventDetailMixin, django.views.generic.base.View

Base retry event view class.

post(request, pk)[source]
retry(pk)[source]

Returns new event id if it successfully retried event None otherwise.

Parameters:pk (int) – Event id.
Returns:New event id if retried else None.
Return type:int or None
django_event.publisher.views.cancel_event(request, *args, **kwargs)

Base cancel event view class.

django_event.publisher.views.event_detail(request, *args, **kwargs)

Base event detail view class.

django_event.publisher.views.event_list(request, *args, **kwargs)

Base event list view class.

django_event.publisher.views.event_types(request, *args, **kwargs)

Event types view.

django_event.publisher.views.retry_event(request, *args, **kwargs)

Base retry event view class.

django_event.publisher.urls

Urls for django.

urlpatterns = patterns(
    '',
    url(
        r'^$',
        event_list,
        name='event_list'
    ),
    url(
        r'^(?P<pk>[0-9]+)/$',
        event_detail,
        name='event_detail'
    ),
    url(
        r'^(?P<pk>[0-9]+)/cancel/$',
        cancel_event,
        name='cancel_event'
    ),
    url(
        r'^(?P<pk>[0-9]+)/retry/$',
        retry_event,
        name='retry_event'
    ),
)

django_event.rabbitmq

django_event.rabbitmq.client

django_event.subscriber

django_event.subscriber.connection

Core event server module. Provides basic websocket connection and subscribe/unsubscribe message system.

class django_event.subscriber.connection._Request[source]

Bases: object

Private class that emulates Django Request class.

class django_event.subscriber.connection.EventConnection(session)[source]

Bases: sockjs.tornado.conn.SockJSConnection

SockJS connection handler.

executor
Annotation:

= ThreadPoolExecutor(max_workers=cpu_count())

Thread pool for synchronous methods
authenticate(*args, **kwargs)[source]

Authenticates user by session key.

Parameters:request (Tornado Request) – Request given on connection open.
Returns:Authenticated user.
Return type:Django User
on_close(*args, **kwargs)[source]

Asynchronous callback. Called internally by base class on connection closed. Unsubscribes all event listeners.

on_message(*args, **kwargs)[source]

Asynchronous callback. Called internally by base class on message received. Provides message routing. Subscribes and unsubscribes on messages types.

Parameters:message (str) – JSON message received from RabbitMQ.
on_open(*args, **kwargs)[source]

Asynchronous callback. Basic authentication by session implemented. Called internally by base class on connection opened.

Parameters:request (Tornado Request) – Request given on connection open.
send(*args, **kwargs)[source]

Sends message to websocket.

Parameters:
  • message (dict) – JSON decoded message routed by on_message method.
  • binary (bool) – Flag. True if message need to be send in binary.
subscribe(*args, **kwargs)[source]

Subscribes event listeners on messages.

Parameters:message (dict) – JSON decoded message routed by on_message method.
unsubscribe(*args, **kwargs)[source]

Unsubscribes event listeners from messages.

Parameters:message (dict) – JSON decoded message routed by on_message method.
wrong_message(*args, **kwargs)[source]

Overridable method for wrong message type.

Parameters:message (dict) – JSON decoded message routed by on_message method.
django_event.subscriber.listeners

Base listener module.

class django_event.subscriber.listeners.Listener(user)[source]

Bases: object

Abstract base listener class. Listeners used by subscribers.

executor = <concurrent.futures.thread.ThreadPoolExecutor object>
classmethod get_listener(*args, **kwargs)[source]

Fabric method for listener subclasses. Imports listener by type and returns it.

Parameters:event_type (str) – Event type.
Returns:Listener module that will process certain type of messages.
Return type:Listener subclass
io_loop = <tornado.platform.epoll.EPollIOLoop object>
on_message(message)[source]

Abstract method. Specifies on message behaviour.

Parameters:message (str) – Received message.
Raise:NotImplementedError
routing_matched()[source]

Computes routing key for current user and compares with received message’s routing key.

Returns:True if routing key matched.
Return type:bool
class django_event.subscriber.listeners.SendMessageListener(user, sender)[source]

Bases: django_event.subscriber.listeners.Listener

Base listener for send message through SockJS connection.

on_message(message)[source]

Sends message if routing key matched.

Parameters:message (str) – Received message.
django_event.subscriber.subscriber

django_event.utils

Utilities event module.

django_event.utils.get_routing(user, routing_strategy)[source]

Get routing key needed by event or listener.

Parameters:
  • user (User) – User to be routed.
  • routing_strategy (str) – How it can compute routing key.
Returns:

Routing key for RabbitMQ.
Return type:

str
django_event.utils.import_var(var_path)[source]

Imports variable.

Parameters:var_path (str) – Module path in python representation.
Returns:Imported variable e.g. classes etc.
Return type:Anything you import.
Raise:ImportError if invalid module path passed into.
django_event.utils.try_import_or_runtime_error(module, message)[source]

Trying to import module. No-op if imported. Raises RuntimeError with given message otherwise.

Parameters:
  • module (str) – Module name.
  • message (str) – Error message.
Raise:

RuntimeError if module doesn’t exist.

django_event.settings

Available django-event settings:

from django.conf import settings


event_settings = settings.DJANGO_EVENT


BACKEND = event_settings.get('BACKEND', 'rabbitmq')
BACKEND_OPTIONS = event_settings.get('BACKEND_OPTIONS', {})

TORNADO_OPTIONS = event_settings.get('TORNADO_OPTIONS', {})

LISTENERS = event_settings.get('LISTENERS', {})

STORE_DAYS = event_settings.get('STORE_DAYS', 7)

EVENT_MODEL = event_settings.get('EVENT_MODEL', 'django_event.Event')

AVAILABLE_TYPES = [key for key in LISTENERS.iterkeys()]

django_event.publisher.models

Core event model module.

You must handle old events by yourself using cron or celery worker.

class django_event.models.AbstractBaseEvent(*args, **kwargs)[source]

Bases: django.db.models.base.Model

An abstract base class implementing a fully featured Event model. Majority of model methods have custom_message parameter in case if you don’t like/need default message protocol. Most of the methods are for private need i.e. all on_* methods. Be sure to not use these methods directly.

class Meta[source]
abstract = False
verbose_name = <django.utils.functional.__proxy__ object>
verbose_name_plural = <django.utils.functional.__proxy__ object>
AbstractBaseEvent.cancel(custom_message=None)[source]

Cancel executing event. If custom message passed it will send it instead of default message.

Parameters:custom_message (JSON serializable object.) – Custom message.
AbstractBaseEvent.complete(result, status=True, custom_message=None, callback=<function <lambda>>, errback=<function <lambda>>)[source]

Complete event and save state into database. It will always call passed callback.

Parameters:
  • result (JSON serializable object.) – Task result.
  • status (bool) – Describes task result status e.g. task raised exception will set False status.
  • custom_message (JSON serializable object.) – Custom message.
  • callback (callable object) – Callback after event ended with success.
  • errback (callable object) – Callback after event ended with error.
classmethod AbstractBaseEvent.create(progress_throttling=0.1, routing_strategy=u'', *args, **kwargs)[source]

Fabric method for event creature. Use this as main event creature source.

Parameters:
  • progress_throttling (float) – Describes how often event will send progress messages when user increments progress via increment_progress() method. Event will not send any progress messages with out user actions on increment_progress(). If you don’t need progress you may not specify this parameter and not use increment_progress() method.
  • routing_strategy (str) – Routing strategy e.g. what listeners will do with messages. Empty strategy means you want to deliver notification to all subscribed clients.
  • args – Model init args
  • kwargs – Model init kwargs
Returns:

Created and configured event.
Return type:

Event
classmethod AbstractBaseEvent.delete_old()[source]

Deletes old events.

AbstractBaseEvent.failure

Shortcut for event status.

Returns:True if event failed else False.
Return type:bool
AbstractBaseEvent.get_next_by_created_at(*moreargs, **morekwargs)
AbstractBaseEvent.get_previous_by_created_at(*moreargs, **morekwargs)
AbstractBaseEvent.increment_progress(progress_delta, custom_message=None)[source]

Increments event progress with out saving to database. If custom message passed it will send it instead of default message.

Parameters:
  • progress_delta (float) – Progress delta.
  • custom_message (JSON serializable object.) – Custom message.
AbstractBaseEvent.may_be_canceled

Shortcut for event state.

Returns:Check if event may be canceled.
Return type:bool
AbstractBaseEvent.may_be_retried

Shortcut for event state.

Returns:Check if event may be retried.
Return type:bool
AbstractBaseEvent.on_cancel(custom_message)[source]

Cancel callback. Sends message to subscribed clients.

Parameters:custom_message (JSON serializable object.) – Custom message.
AbstractBaseEvent.on_complete(custom_message, callback, errback)[source]

Complete callback. Dispatch between success and error status.

Parameters:
  • custom_message (JSON serializable object.) – Custom message.
  • callback (callable object) – Callback after event ended with success.
  • errback (callable object) – Callback after event ended with error.
AbstractBaseEvent.on_error(custom_message, errback)[source]

Error callback. Sends message to subscribed clients.

Parameters:
  • custom_message (JSON serializable object.) – Custom message
  • errback (callable object) – Errback after event ended with error.
AbstractBaseEvent.on_progress_change(custom_message)[source]

Progress change callback. Sends message to subscribed clients.

Parameters:custom_message (JSON serializable object.) – Custom message.
AbstractBaseEvent.on_retry(custom_message)[source]

Cancel callback. Sends message to subscribed clients.

Parameters:custom_message (JSON serializable object.) – Custom message.
AbstractBaseEvent.on_start(custom_message)[source]

Start callback. Sends message to subscribed clients. If custom message passed it will send it instead of default message.

Parameters:custom_message (JSON serializable object.) – Custom message.
AbstractBaseEvent.on_success(custom_message, callback)[source]

Success callback. Sends message to subscribed clients.

Parameters:
  • custom_message (JSON serializable object.) – Custom message
  • callback (callable object) – Callback after event ended with success.
AbstractBaseEvent.retry(custom_message=None, request=None, **kwargs)[source]

Retry not completed event. If custom message passed it will send it instead of default message.

Parameters:custom_message (JSON serializable object.) – Custom message.
AbstractBaseEvent.send_email()[source]

Sends email to user after event is done.

TODO: implement email sending.

AbstractBaseEvent.send_message(message, content_type, broadcast=False, callback=<function <lambda>>)[source]

Send custom message to subscribed clients and execute passed callback.

Parameters:
  • message (str) – Message.
  • content_type (str) – Message content type.
  • broadcast (bool) – True if you need broadcast.
  • callback (callable object) – Callback after message send.
AbstractBaseEvent.start(custom_message=None, callback=<function <lambda>>)[source]

Start event and save state into database. It will always call passed callback.

Parameters:
  • custom_message (JSON serializable object.) – Overrides default message.
  • callback (callable object) – Callback after event started
AbstractBaseEvent.success

Shortcut for event status.

Returns:True if event succeed else False.
Return type:bool
AbstractBaseEvent.try_custom(message)[source]

Custom message helper method. Publish message if present and return True, False otherwise.

Parameters:message (JSON serializable object.) – Custom message.
AbstractBaseEvent.user
AbstractBaseEvent.view()[source]

Mark instance as viewed.

class django_event.models.EventQuerySet(model=None, query=None, using=None, hints=None)[source]

Bases: django.db.models.query.QuerySet

Event query set and manager. Defines some useful shortcuts.

completed()[source]

Completed events.

Returns:Completed events.
Return type:EventQuerySet
failed()[source]

Failed events.

Returns:Failed events.
Return type:EventQuerySet
mark_viewed()[source]

Mark completed events as viewed.

not_completed()[source]

Not completed events.

Returns:Not completed events.
Return type:EventQuerySet
not_viewed()[source]

Not viewed events.

Returns:Not viewed events.
Return type:EventQuerySet
old()[source]

Old events.

Returns:Old events.
Return type:EventQuerySet
successful()[source]

Successful events.

Returns:Successful events.
Return type:EventQuerySet
viewed()[source]

Viewed events.

Returns:Viewed events.
Return type:EventQuerySet
django_event.models.get_event_model()[source]

Helper for getting event swappable model.

Returns:Event model
class django_event.models.Event(*args, **kwargs)[source]

Default event model.

complete(result, status=True, custom_message=None, callback=lambda event: None, errback=lambda event: None)

Complete event and save state into database. It will always call passed callback.

Parameters:
  • result (JSON serializable object.) – Task result.
  • status (bool) – Describes task result status e.g. task raised exception will set False status.
  • custom_message (JSON serializable object.) – Custom message.
  • callback (callable object) – Callback after event ended with success.
  • errback (callable object) – Callback after event ended with error.
send_message(message, content_type, broadcast=False, callback=lambda event: None)

Send custom message to subscribed clients and execute passed callback.

Parameters:
  • message (str) – Message.
  • content_type (str) – Message content type.
  • broadcast (bool) – True if you need broadcast.
  • callback (callable object) – Callback after message send.
start(custom_message=None, callback=lambda event: None)

Start event and save state into database. It will always call passed callback.

Parameters:
  • custom_message (JSON serializable object.) – Overrides default message.
  • callback (callable object) – Callback after event started

Indices and tables