telegraphy 0.1

Telegraphy - Real Time Events For Django.

Telegraphy
==========

Project home: <http://github.com/>...

This projects facilitates the integration of real-time features into a
Django project.

Django is not prepeared for handling real time web features. There are a
lot of technologies like asynchronous servers, message queues, advanced
key-value stores that are not trivial to integrate with Django.
Telegraphy currently abstract messages as classes. In order to send some
event to the browser, you must define an event class.

You can easily extend you models to generate server-side, asynchronous,
events that can be received (and handled) in your frontend templates, in
real time.

The Django Telegraphy App
-------------------------

Includes the following features:

> - Simple management management command to run an asynchronous-events
> server.
> - Generic model signal based *create*, *update*, *delete* events.
> - Custom events definitions.
> - Template tags and a JavaScript API for easy events management on
> the frontend.

Telegraphy
----------

Provides an asynchronous-events management server, or **Gateway** with
the following features:

> - Real Time Events
> : - Authentication
> - Subscription handling
> : - Public vs Authnticated Events
> - Subscription management (client or event based)
>
> - Persistant Subscriptions
> - Event management
> : - Class based event definition
> - Event query language
> : - Performance
> - Simplified client side subscription
> handling
> - Easy channel emulation
>
Installation
============

Just get it:

~~~~ {.sourceCode .none}
pip install telegraphy
~~~~

You will need to have pip installed on your system. On linux install the
python-pip package, on windows follow
[this](http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows).
Also, if you are on linux and not working with a virtualenv, remember to
use `sudo` for both commands (`sudo pip install telegraphy`).

Examples
========

The django\_telegraphy app allows you to easily extend your models so
that they generate events on creation, update or delete. Those events
will reach your front end in real time.

Simply install the django\_telegraphy app in your Django project. Then
run the following command in parallel to your web-server:

~~~~ {.sourceCode .none}
python manage.py run_telegraph
~~~~

Extend your models so that they automatically generate events: create an
`events.py` file next to your `models.py`

~~~~ {.sourceCode .python}
from apps.telegraphy.events import DjangoEvent
from apps.myapp.models import MyModel


class MyModelEvents(DjangoEvent):

class Meta:
model = MyModel
~~~~

And that's it! Now

You can find more [examples in the
documentation](http://simpleai.readthedocs.org/en/latest/)

More detailed documentation
===========================

You can read the docs online
[here](http://telegraphy.readthedocs.org/en/latest/). Or for offline
access, you can clone the project code repository and read them from the
`docs` folder.

Help and discussion
===================

Join us at the telegraphy [google
group](http://groups.google.com/group/telegraphy).

Authors
=======

- Many people you can find on the [contributors
section](https://github.com/machinalis/telegraphy/graphs/contributors).

\* Special acknowledgements to [Machinalis](http://www.machinalis.com/)
for the time provided to work on this project. Machinalis also works on
some other very interesting projects, like
[SimpleAI](http://simpleai.machinalis.com/),
[Quepy](http://quepy.machinalis.com/) and
[more](https://github.com/machinalis).