├── drealtime
    ├── templatetags
    │   ├── __init__.py
    │   └── drealtimetags.py
    ├── middleware.py
    └── __init__.py
├── dist
    ├── django-realtime-1.1.tar.gz
    └── django-realtime-1.1.macosx-10.5-intel.tar.gz
├── setup.py
└── README.md


/drealtime/templatetags/__init__.py:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/dist/django-realtime-1.1.tar.gz:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/anishmenon/django-realtime/HEAD/dist/django-realtime-1.1.tar.gz


--------------------------------------------------------------------------------
/dist/django-realtime-1.1.macosx-10.5-intel.tar.gz:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/anishmenon/django-realtime/HEAD/dist/django-realtime-1.1.macosx-10.5-intel.tar.gz


--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
 1 | from setuptools import setup, find_packages
 2 | 
 3 | setup(
 4 |     name='django-realtime',
 5 |     version='1.1',
 6 |     author='Anish menon',
 7 |     author_email='anish@inzane.in',
 8 |     description='an iShout.js client for Django',
 9 |     url='https://bitbucket.org/inzane/django-realtime',
10 |     license='MIT',
11 |     packages=find_packages(),
12 |     classifiers = [
13 |         'Development Status :: 3 - Alpha',
14 |         'Environment :: Web Environment',
15 |         'Intended Audience :: Developers',
16 |         'License :: OSI Approved :: MIT License',
17 |         'Operating System :: OS Independent',
18 |         'Programming Language :: Python',
19 |         'Framework :: Django'
20 |     ]
21 | )
22 | 


--------------------------------------------------------------------------------
/drealtime/templatetags/drealtimetags.py:
--------------------------------------------------------------------------------
 1 | from django.conf import settings
 2 | from django.template import Library
 3 | register = Library()
 4 | 
 5 | def _determine_base_path():
 6 |     client = getattr(settings, 'ISHOUT_CLIENT_ADDR', 'localhost:5500')
 7 |     secure = getattr(settings, 'ISHOUT_HTTPS', False)
 8 |     proto = 'http'
 9 |     if secure:
10 |         proto = 'https'
11 | 
12 |     return '%s://%s' % (proto, client)    
13 | 
14 | @register.simple_tag
15 | def ishout_socketio_path():
16 |     return '%s/%s' %(_determine_base_path(), 'socket.io/socket.io.js')
17 | 
18 | @register.simple_tag
19 | def ishout_js_path():
20 |     return '%s/%s' %(_determine_base_path(), 'client/ishout.client.js')
21 | 
22 | 
23 | @register.simple_tag
24 | def ishout_js():
25 |     """
26 |     returns the needed HTML tags for including ishout.js and its dependency
27 |     (socket.io) in the client's browser. make sure that `ISHOUT_CLIENT_ADDR`
28 |     is in the settings.py file and is reachable from the internet, as
29 |     it will be used as the domain name. if you are using ishout.js over
30 |     SSL, be sure to set `ISHOUT_HTTPS` to True.
31 |     """
32 |     path = _determine_base_path()
33 |     return """
34 |     <script type="text/javascript" src="%s/socket.io/socket.io.js"></script>
35 |     <script type="text/javascript" src="%s/client/ishout.client.js"></script>
36 |     """ % (path, path)


--------------------------------------------------------------------------------
/drealtime/middleware.py:
--------------------------------------------------------------------------------
 1 | import datetime
 2 | from django.conf import settings
 3 | from drealtime import iShoutClient
 4 | 
 5 | ishout_client = iShoutClient()
 6 | ishout_cookie_name = 'ishoutToken'
 7 | 
 8 | class iShoutCookieMiddleware(object):
 9 |     """
10 |     call the iShout.js API interface and get a token
11 |     for the currently logged-in user.
12 |     set the token received from the API as a cookie.
13 |     
14 |     Put this before `AuthenticationMiddleware`.
15 |     """
16 |     def get_token(self, request):
17 |         """
18 |         use the HTTP client to get a token from the iShout.js server,
19 |         for the currently logged in user.
20 |         """
21 |         res = ishout_client.get_token(request.user.pk)
22 |         return res
23 | 
24 |     def has_ishout_cookie(self, request):
25 |         cookie = request.COOKIES.get(ishout_cookie_name)
26 |         if cookie:
27 |             return True
28 |         return False
29 | 
30 |     def determine_path(self, request):
31 |         # Use the same path as the session cookie.
32 |         return settings.SESSION_COOKIE_PATH
33 | 
34 |     def determine_domain(self, request):
35 |         # Use the same domain as the session cookie.
36 |         return settings.SESSION_COOKIE_DOMAIN
37 | 
38 |     def set_ishout_cookie(self, request, response):
39 |         cookie_path = self.determine_path(request)
40 |         cookie_domain = self.determine_domain(request)
41 |         ishout_cookie_value = self.get_token(request)
42 |         
43 |         # calculate expiry
44 |         cookie_age = datetime.timedelta(seconds=settings.SESSION_COOKIE_AGE)
45 | 
46 |         utc_date = datetime.datetime.utcnow()
47 |         cookie_date_str = '%a, %d-%b-%Y %H:%M:%S GMT'
48 |         expires = datetime.datetime.strftime(
49 |             utc_date + cookie_age, cookie_date_str
50 |         )
51 | 
52 |         # Set the cookie. use the same path, domain and expiry
53 |         # as the cookie set for the session.
54 |         response.set_cookie(
55 |             ishout_cookie_name,
56 |             ishout_cookie_value,
57 |             max_age=settings.SESSION_COOKIE_AGE,
58 |             expires=expires,
59 |             path=cookie_path,
60 |             domain=cookie_domain
61 |         )
62 |         return response
63 | 
64 |     def process_response(self, request, response):
65 |         # We only use it for authenticated users
66 |         if not hasattr(request, 'user'):
67 |             return response
68 |             
69 |         if not request.user.is_authenticated() and \
70 |         ishout_cookie_name in request.COOKIES:
71 |             # If there is no authenticated user attached to this request,
72 |             # but the ishout.js token cookie is still present, delete it.
73 |             # This is usually called on logout.
74 |             path = self.determine_path(request)
75 |             domain = self.determine_domain(request)
76 |             response.delete_cookie(
77 |                 ishout_cookie_name, path=path, domain=domain
78 |             )
79 |             return response
80 |         
81 |         # skip unauthenticated users
82 |         if not request.user.is_authenticated():
83 |             return response
84 | 
85 |         # Check if we have the cookie already set:
86 |         if self.has_ishout_cookie(request):
87 |             return response
88 | 
89 |         # If not, set it.
90 |         self.set_ishout_cookie(request, response)
91 |         return response
92 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Django-Realtime: an iShout.js client for Django.
  2 | 
  3 | iShout.js is a node.js + socket.io server used for adding real-time notifications to your existing web application.
  4 | This project adds easy iShout.js integration for Django, thus enabling you to easily
  5 | add real-time notifications to you exiting Django applications.
  6 | 
  7 | Before installing and using the client, make sure you setup iShout.js using [this guide](https://bitbucket.org/inzane/ishout "iShout.js Installation").
  8 | 
  9 | 
 10 | ## Installation
 11 | 
 12 | * install the client either by cloning this repo, or, if using pip, by using the following command:
 13 | 
 14 |     pip install django-realtime
 15 | 
 16 | * add `drealtime` to `INSTALLED_APPS` in your settings.py file.
 17 | 
 18 | 
 19 | ## Configuration
 20 | 
 21 | * add `'drealtime.middleware.iShoutCookieMiddleware'` to your `MIDDLEWARE_CLASSES`settings. right above `SessionMiddleware`. this will take care of setting the authentication cookie.
 22 | * in your templates, add `{% load drealtimetags %}` at the top of the template. inside your `<head>` tag, add `{% ishout_js %}`. this will include the proper `<script>` tags for you. place this tag above any js files that use the ishout.js client.
 23 | * the following optional settings are availabe:
 24 |     * `ISHOUT_CLIENT_ADDR` - defaults to `'localhost:5500'`. *should probably be changed for production.*
 25 |     * `ISHOUT_API_ADDR` - defaults to `'localhost:6600'`.
 26 |     * `ISHOUT_HTTPS` - defaults to `False`. whether or not iShout.js is setup to use SSL.
 27 | 
 28 | 
 29 | ## Usage
 30 | 
 31 | Now, from a view, emit a message to a user:
 32 | 
 33 | ```python
 34 | from drealtime import iShoutClient
 35 | ishout_client = iShoutClient()
 36 | 
 37 | # This is our pseudo view code
 38 | def comment_on_blog(request):
 39 |     post = Post.objects.get(...)
 40 |     # Process stuff, handle forms, do whatever you want.
 41 |     ishout_client.emit(
 42 |         post.author.pk,
 43 |         'notifications',
 44 |         data={ 'msg' : 'You have a new comment!' }
 45 |     )
 46 |     # Some other things happening here..
 47 |     return render_to_response('blog_post.html', ctx)
 48 | ```
 49 | 
 50 | In your HTML code, add the following JS snippet, to receive this notification on the client's side:
 51 | 
 52 | ```js
 53 | // use .on() to add a listener. you can add as many listeners as you want.
 54 | ishout.on('notifications', function(data){
 55 |     alert(data.msg);
 56 | });
 57 | 
 58 | // .init() will authenticate against the ishout.js server, and open the WebSocket connection.
 59 | ishout.init();
 60 | ```
 61 | 
 62 | Your client should receive an alert with the notification. the channel name (`notifications`) and the data you send
 63 | are completley up to you, so be creative and use it wisely.
 64 | 
 65 | If you have more than one channel we want to listen on, we can also chain these calls:
 66 | 
 67 | ```js
 68 | ishout.on('notifications', function(data){
 69 |     popupNotification(data.msg);
 70 | 
 71 | }).on('alerts', function(data)}{
 72 |     alert(data.alert_msg);
 73 | 
 74 | }).on('something-else', function(data){
 75 |     $('#someDiv').html(data.htmlContent);
 76 |     
 77 | }).init();
 78 | ```
 79 | 
 80 | ## License 
 81 | 
 82 | (The MIT License)
 83 | 
 84 | Copyright (c) 2012 Anish menon anish@inzane.in;
 85 | 
 86 | Permission is hereby granted, free of charge, to any person obtaining
 87 | a copy of this software and associated documentation files (the
 88 | 'Software'), to deal in the Software without restriction, including
 89 | without limitation the rights to use, copy, modify, merge, publish,
 90 | distribute, sublicense, and/or sell copies of the Software, and to
 91 | permit persons to whom the Software is furnished to do so, subject to
 92 | the following conditions:
 93 | 
 94 | The above copyright notice and this permission notice shall be
 95 | included in all copies or substantial portions of the Software.
 96 | 
 97 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
 98 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 99 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
100 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
101 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
102 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
103 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
104 | 


--------------------------------------------------------------------------------
/drealtime/__init__.py:
--------------------------------------------------------------------------------
  1 | try:
  2 |     # Python 2
  3 |     import httplib
  4 | except ImportError:
  5 |     # Python 3
  6 |     import http.client as httplib
  7 | import socket
  8 | from django.conf import settings
  9 | try:
 10 |     from django.utils import simplejson as json
 11 | except ImportError:
 12 |     import json
 13 | 
 14 | __version__ = '0.1.6'
 15 | VERSION = map(int, __version__.split('.'))
 16 | 
 17 | class iShoutClient(object):
 18 |     """
 19 |     A really basic HTTP client to the iShout.js internal interface.
 20 |     It is intended for use with django, but could easily be adapted
 21 |     for general use (or maybe for another python web framework)
 22 |     """
 23 |     def __init__(self):
 24 |         self.base_url = getattr(settings, 'ISHOUT_API_ADDR', 'localhost:6600')
 25 | 
 26 |     def _do_request(self, method, path, *args, **kwargs):
 27 |         # A generic wrapper around httplib.
 28 |         # I initally wanted to use @kennethreitz's awesome Requests
 29 |         # (python-requests.org) but didn't want to intoduce more dependencies.
 30 |         try:
 31 |             con = httplib.HTTPConnection(self.base_url)
 32 |             con.request(method, path, *args, **kwargs)
 33 |             return con.getresponse()
 34 |         except (httplib.HTTPException, socket.error):
 35 |             return None
 36 | 
 37 |     def get_token(self, user_id):
 38 |         """
 39 |         For a given user ID, return a token. Keep in mind that this ID
 40 |         could be anything that uniquley describes a user in the system.
 41 |         A primary key from the users table is a good fit, but so is
 42 |         a session ID, as long as it is unique.
 43 |         """
 44 |         path = '/auth/token/%s' % (user_id)
 45 |         response = self._do_request('POST', path)
 46 |         if not response or response.status > 399:
 47 |             return None
 48 |         try:
 49 |             resp = json.loads(response.read())
 50 |         except ValueError:
 51 |             return None
 52 |         if resp:
 53 |             if 'token' in resp:
 54 |                 return '%s|%s' % (user_id, resp['token'])
 55 |         return None
 56 | 
 57 |     def register_group(self, user_id, group_name):
 58 |         """
 59 |         Add a user ID (read about what a user ID is under get_token())
 60 |         to a given group name. Groups are created on the fly when adding
 61 |         the first user. This group could be anything you want it to be,
 62 |         no rules here. Map a set of users to a logical name.
 63 |         """
 64 |         path = '/auth/group/%s/%s' % (group_name, user_id)
 65 |         response = self._do_request('POST', path)
 66 |         response.read()
 67 | 
 68 |     def unregister_group(self, user_id, group_name):
 69 |         """
 70 |         Remove a user from group.
 71 |         """
 72 |         path = '/auth/group/%s/%s' % (group_name, user_id)
 73 |         response = self._do_request('DELETE', path)
 74 |         response.read()
 75 | 
 76 | 
 77 |     def emit(self, user_id, channel, data):
 78 |         """
 79 |         send a message over the given channel to the specified user.
 80 |         `data` should be a regular python dict, or any other object
 81 |         that is json.dumps'able.
 82 |         """
 83 |         path = '/emit/user/%s/%s' % (user_id, channel)
 84 |         headers = {'Content-Type' : 'application/json'}
 85 |         data = json.dumps(data)
 86 |         response = self._do_request('POST', path, data, headers)
 87 |         response.read()
 88 | 
 89 |     def broadcast_group(self, group_name, channel, data):
 90 |         """
 91 |         Emitts the message over the specified channel to all members
 92 |         of the group.
 93 |         """
 94 |         path = '/emit/group/%s/%s' % (group_name, channel)
 95 |         headers = {'Content-Type' : 'application/json'}
 96 |         data = json.dumps(data)
 97 |         response = self._do_request('POST', path, data, headers)
 98 |         response.read()
 99 | 
100 |     def broadcast_room(self, channel, data):
101 |         """
102 |         Emitts the message over the specified channel to all members
103 |         of the group.
104 |         """
105 |         path = '/emit/room/%s' % (channel)
106 |         headers = {'Content-Type' : 'application/json'}
107 |         data = json.dumps(data)
108 |         response = self._do_request('POST', path, data, headers)
109 |         response.read()
110 | 
111 |     def broadcast(self, channel, data):
112 |         """
113 |         Emit the given message to all connected users.
114 |         """
115 |         path = '/emit/broadcast/%s' % (channel)
116 |         headers = {'Content-Type' : 'application/json'}
117 |         data = json.dumps(data)
118 |         response = self._do_request('POST', path, data, headers)
119 |         response.read()
120 | 
121 |     def get_room_status(self, channel):
122 |         """
123 |         Return information about the current status of a room.
124 |         (most importanly, members currently online in that room).
125 |         """
126 |         path = '/status/room/%s' % (channel)
127 |         response = self._do_request('GET', path)
128 |         data = response.read()
129 |         try:
130 |             return json.loads(data)
131 |         except ValueError:
132 |             return None
133 | 
134 | 


--------------------------------------------------------------------------------