Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Extremus-io/djwebsockets
https://github.com/Extremus-io/djwebsockets
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/Extremus-io/djwebsockets
- Owner: Extremus-io
- License: mit
- Created: 2015-09-14T00:04:11.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2019-08-09T06:38:33.000Z (about 5 years ago)
- Last Synced: 2024-07-24T22:23:27.037Z (about 2 months ago)
- Language: Python
- Homepage: https://extremus-io.github.io/djwebsockets
- Size: 3.23 MB
- Stars: 21
- Watchers: 4
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- starred-awesome - djwebsockets - (Python)
README
# djwebsockets
The library adds websocket support to django. It gives event driven websocket control for simple and straight forward programming.
The idea is to create a separate websocket server when an instance of django wsgi application instance is produced. and kill it as soon as the instance dies.
#### Change-log:
> v0.9.3
> > Replaced the sending mechanism with queues and fixed some bugs where socket closes before sending all pending messages.
> V0.9
> > for some reason, multiple namespaces were not working and so namespace was reverted from regex to exact matching
> > you can now add base websocket url using `WEBSOCKET_BASE_URI` setting in django's `settings.py`.
> > *Breaking Changes*
> > all the websocket classes you want to use have to inherit `djwebsockets.websocket.BaseWSClass`.
> v0.8.1
> > Added mixin support
> > Added ability to run django request middleware on websocket requests through a mixin (see demo chatroom example)
> > Now works on any WSGI application or desktop application.
> > Added a demo chatroom example.
##### Note:
> requires python 3.4 to work
### Installation:
- run `pip install djwebsockets`.
- add ```djwebsockets``` to ```settings.INSTALLED_APPS```
- add ```WEBSOCKET_HOST``` and ```WEBSOCKET_PORT``` to settings.py
- in wsgi.py file, replace line
```python
from django.core.wsgi import get_wsgi_application
```
with
```python
from djwebsockets.wsgi import get_wsgi_application
```
###Usage:
* in any app's ```models.py``` add
```python
from djwebsockets.decorator import Namespace
from djwebsockets.websocket import BaseWSClass
```
* create a websocket handler with a namespace
```python
@Namespace("/example/")
class ExamplerHandler(BaseWSClass):
@classmethod
def on_connect(cls, websocket, path):
...
@classmethod
def on_message(cls, websocket, message):
...
@classmethod
def on_close(cls, websocket):
...
```
* `Namespace` has to match the exact path of any websocket connecting.
### Mixins:
- mixins essentially process all or some of the events before actual handler, allowing to tweak the data or block the event call.
- creating mixin is a lot similar to creating the handler itself.
```python
class ExampleMixin(BaseMixin):
@classmethod
def on_connect(cls, websocket, path):
...
@classmethod
def on_message(cls, websocket, message):
...
@classmethod
def on_close(cls, websocket):
...
```
- The mixin has to extend `djwebsockets.mixins.BaseMixin` class
- To use this mixin in your app, extend your handler with this mixin
```python
@Namespace("/example/")
class ExamplerHandler(ExampleMixin, BaseWSClass):
@classmethod
def on_connect(cls, websocket, path):
...
@classmethod
def on_message(cls, websocket, message):
...
@classmethod
def on_close(cls, websocket):
...
```
- You can also add multiple mixins. They will be executed from right to left.
```python
@Namespace("/example/")
class ExamplerHandler(ExampleMixin1 ,ExampleMixin2, ExampleMixin3, BaseWSClass):
@classmethod
def on_connect(cls, websocket, path):
...
@classmethod
def on_message(cls, websocket, message):
...
@classmethod
def on_close(cls, websocket):
...
```
### \*\*Experimental\*\* django middleware support:
- Django middleware can be used to authentication, sessions etc. (```websocket.user``` and ```websocket.session```)
- To activate django middleware, extend your websocket handler with `djwebsockets.mixins.wsgi.WSGIMixin`.
- add middle you want to run just like django.
```python
WEBSOCKET_MIDDLEWARE = [
'django.contrib.sessions.middleware.SessionMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.auth.middleware.SessionAuthenticationMiddleware',
]
```
> For general Auth, session the above three or their equivalents will be sufficient.