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:
For installation notes, refer to the Installation instructions.
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 manage.py run_telegraph
For more info about this process, go to the Gateway section.
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 events.py file in your app’s directory (next to the models.py and urls.py).
For every model you want to generate events, create a sub-class of telegraphy.contrib.django_telegraphy.events.BaseEventModel:
from models import MyModel from telegraphy.contrib.django_telegraphy.events import BaseEventModel class MyEventsModel(BaseEventModel): model = MyModel
Register the event:
event = MyEventsModel() event.register()
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 urls.py file:
from django.conf.urls import patterns ... from telegraphy.contrib.django_telegraphy import events events.autodiscover() 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.
telegraphy.contrib.django_telegraphy.events.BaseEventModel. The class’ allowed attributes are:
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.
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.
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.
XML-RPC based. TBC.
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.