Telegraphy aims to facilitate the integration of real-time features into a Django project.

Django is not yet prepared for handling real time web features. There are a lot of issues and technologies that must be taken into account that are not trivial to integrate with Django: WebSockets, asynchronous servers, message queues, advanced key-value stores, etc.

Telegraphy takes care of all that. It provides a simple, class-based way to provide your models with the capability to generate events. These will reach the client application, in near-real-time. Besides:

  • A management command to run the Gateway.
  • Automatic signals-based CUD events (Create, Update, Delete).
  • Custom events definitions.
  • Template tags for easy configuration.
  • A very simple JS API to make real-time Django apps a reality.

For installation notes, refer to the Installation instructions.

Management command: run_telegraph

django-telegraphy provides a management command to run the Gateway server. Until this functionality can be properly integrated in the existing runserver command, open a new console and run:

$ python run_telegraph

For more info about this process, go to the Gateway section.

Class based events generation

Currently, this app’s main feature is to give your models the ability to generate server-side events that will reach the clients. To do that you must:

  • Create an file in your app’s directory (next to the and

  • For every model you want to generate events, create a sub-class of

    from models import MyModel
    from import BaseEventModel
    class MyEventsModel(BaseEventModel):
        model = MyModel
  • Register the event:

    event = MyEventsModel()

    The events module provides an autodiscover method to automatically register all the events in the app. This method is typically called in the project’s file:

    from django.conf.urls import patterns
    from telegraphy.contrib.django_telegraphy import events
    urlpatterns = ...
  • Done. Every time an instance of MyModel is created, saved or deleted, an event will be generated and sent to the clients through the Gateway.

BaseEventModel The class’ allowed attributes are:

It is the only compulsory attribute. It references the target Django.db Model being extended.
fields (default = None)

A list of the target model’s field names to include in the event data. If it is None then all the Model’s fields will be included.

If the target model has a to_dict() attribute, then it is used to generate the event’s data, so the fields attribute is ignored.

If this attribute is set, then exclude is ignored.

exclude (default = None)

A list of the target model’s field names to ignore. They will not be sent in the event data, in the case that fields is None.

If the target model has a to_dict() attribute, then it is used to generate the event’s data, so the exclude attribute is ignored.

operations (default = (OP_CREATE, OP_UPDATE, OP_DELETE))

Indicates what operations in the target model’s instances will generate events:

OP_CREATE: an event will be generated each time an instance of the target model is created .

OP_UPDATE: an event will be generated each time an instance of the target model is saved (not on creation).

OP_DELETE: an event will be generated each time an instance of the target model is deleted.

If false-ish then no events will be automatically generated by this model.

name (default = None)
The name of the event. If none is provided, it is automatically generated from the app and target model’s name/ For example: myapp.MyModel.
verbose_name (default = None)
A verbose, human-friendly name for the event. If provided, it is sent in the event’s meta-data. A helper for user-interface purposes.


The events module provides an autodiscover method. It will search for all the models that are subclasses of BaseEventModel, in all the project’s installed apps. Then it instantiates and registers each one of them.





Communications with the gateway

XML-RPC based. TBC.

Generating custom events


Template tags


JavaScript API

TBC. The AutobahnJS-based API provides a Gateway representative which is responsible of:
  • connect to a running instance of a Gateway
  • subscribe to events. Free events? can we subscribe to unregistered Gateway events?
  • provide means to handle connection changes (keep the connection alive?)

Authentication shortcomings

Django uses a HTTP Only cookie called sessionid. This cookie would not be exposed to JavaScript for security issues. Since Gateway process may not run in the same context (port, ip, machine) where Django is running, we can’t rely on it for authentication.

In order to authenticate clients we must pre share (key, secret) tokens, as part of the WAMP Challenge-Response-Authentication mechanism. This tokens are created by the gateway whenever a page that uses telegraphy’s template tag is rendered. These tokens are short lived, they expire once the websocket connection has been established.


Read the Docs v: latest
On Read the Docs
Project Home

Free document hosting provided by Read the Docs.