django-telegraphy

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 manage.py 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 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.

BaseEventModel

telegraphy.contrib.django_telegraphy.events.BaseEventModel. The class’ allowed attributes are:

model
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.

Autodiscover

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.

Events

TBD.

Authorization

TBD.

Communications with the gateway

XML-RPC based. TBC.

Generating custom events

TBD.

Template tags

TBD.

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.

TBC.

Read the Docs v: latest
Versions
latest
develop
Downloads
PDF
HTML
Epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.