Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

Download
ActivePython
INSTALL>
pypm install django-websocket

How to install django-websocket

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install django-websocket
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
0.3.0 Available View build log
Windows (64-bit)
0.3.0 Available View build log
Mac OS X (10.5+)
0.3.0 Available View build log
Linux (32-bit)
0.3.0 Available View build log
Linux (64-bit)
0.3.0 Available View build log
 
License
BSD
Dependencies
Lastest release
version 0.3.0 on Jan 5th, 2011

The django-websocket module provides an implementation of the WebSocket Protocol for django. It handles all the low-level details like establishing the connection through sending handshake reply, parsing messages from the browser etc...

It integrates well into django since it provides easy hooks to receive WebSocket requests either for single views through decorators or for the whole site through a custom middleware.

Usage

You can use the accept_websocket decorator if you want to handle websocket connections just for a single view - it will route standard HTTP requests to the view as well. Use require_websocket to only allow WebSocket connections but reject normal HTTP requests.

You can use a middleware if you want to have WebSockets available for all URLs in your application. Add django_websocket.middleware.WebSocketMiddleware to your MIDDLEWARE_CLASSES setting. This will still reject websockets for normal views. You have to set the accept_websocket attribute on a view to allow websockets.

To allow websockets for every single view, set the WEBSOCKET_ACCEPT_ALL setting to True.

The request objects passed to a view, decorated with accept_websocket or require_websocket will have the following attributes/methods attached. These attributes are always available if you use the middleware.

request.is_websocket()

Returns either True if the request has a valid websocket or False if its a normal HTTP request. Use this method in views that can accept both types of requests to distinguish between them.

request.websocket

After a websocket is established, the request will have a websocket attribute which provides a simple API to communicate with the client. This attribute will be None if request.is_websocket() returns False.

It has the following public methods:

WebSocket.wait()

This will return exactly one message sent by the client. It will not return before a message is received or the conection is closed by the client. In this case the method will return None.

WebSocket.read()

The read method will return either a new message if available or None if no new message was received from the client. It is a non-blocking alternative to the wait() method.

WebSocket.count_messages()

Returns the number of queued messages.

WebSocket.has_messages()

Returns True if new messages are available, else False.

WebSocket.send(message)

This will send a single message to the client.

WebSocket.__iter__()

You can use the websocket as iterator. It will yield every new message sent by the client and stop iteration after the client has closed the connection.

Error handling

The library will return a Http 400 error (Bad Request) if the client requests a WebSocket connection, but the request is malformed or not supported by django-websocket.

Examples

Receive one message from the client, send that message back to the client and close the connection (by returning from the view):

System Message: WARNING/2 (<string>, line 100)

Literal block expected; none found.

from django_websocket import require_websocket

@require_websocket def echo_once(request): message = request.websocket.wait() request.websocket.send(message)

Send websocket messages from the client as lowercase and provide same functionallity for normal GET requests:

System Message: WARNING/2 (<string>, line 110)

Literal block expected; none found.

from django.http import HttpResponse from django_websocket import accept_websocket

def modify_message(message): return message.lower()

@accept_websocket def lower_case(request): if not request.is_websocket(): message = request.GET['message'] message = modify_message(message) return HttpResponse(message) else: for message in request.websocket: message = modify_message(message) request.websocket.send(message)

Disclaimer (what you should know when using django-websocket)

Using in development

Django doesn't support a multithreaded development server yet. It is still not possible to open two concurrent requests. This makes working with WebSockets a bit tedious - since WebSockets will require an open request by their nature.

This has the implication that you won't be able to have more than one WebSocket open at a time when using django's runserver command. It's also not possible to fire an AJAX request while a WebSocket is in use etc.

django-websocket ships with a custom runserver command that works around these limitations. Add django_websocket to your INSTALLED_APPS settings to install it. Use your development server like you did before and provide the --multithreaded option to enable multithreaded behaviour:

System Message: WARNING/2 (<string>, line 146)

Literal block expected; none found.

python manage.py runserver --multithreaded

Using in production

Be aware that django-websocket is just a toy for its author to play around with at the moment. It is not recommended to use in production without knowing what you do. There are no real tests made in the wild yet.

But this doesn't mean that the project won't grow up in the future. There will be fixes to reported bugs and feature request are welcome to improve the API.

Please write me an email or contact me somewhere else if you have experience with django-websocket in a real project or even in a production environment.

Contribute

Every contribution in any form is welcome. Ask questions, report bugs, request new features, make rants or tell me any other critique you may have.

One of the biggest contributions you can make is giving me a quick Thank you if you like this library or if it has saved you a bunch of time.

But if you want to get your hands dirty:

Authors

Credits

Some low-level code for WebSocket implementation is borrowed from the eventlet library.

Changelog

Release 0.3.0
  • Added multithreaded development server.
Release 0.2.0
  • Changed name of attribute WebSocket.websocket_closed to

System Message: WARNING/2 (<string>, line 205)

Bullet list ends without a blank line; unexpected unindent.

WebSocket.closed. - Changed behaviour of WebSocket.close() method. Doesn't close system socket - it's still needed by django! - You can run tests now with python setup.py test. - Refactoring WebSocket class. - Adding WebSocket.read() which returns None if no new messages are available instead of blocking like WebSocket.wait(). - Adding example project to play around with. - Adding WebSocket.has_messages(). You can use it to check if new messages are ready to be processed. - Adding WebSocket.count_messages(). - Removing BaseWebSocketMiddleware - is replaced by WebSocketMiddleware. Don't need for a base middleware anymore. We can integrate everything in one now.

Release 0.1.1
  • Fixed a bug in BaseWebSocketMiddleware that caused an exception in

System Message: WARNING/2 (<string>, line 224)

Bullet list ends without a blank line; unexpected unindent.

process_response if setup_websocket failed. Thanks to cedric salaun for the report.

Release 0.1.0
  • Initial release

Subscribe to package updates

Last updated Jan 5th, 2011

Download Stats

Last month:1

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.