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.
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.
TBD.
TBD.
XML-RPC based. TBC.
TBD.
TBD.
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.
TBC.