diff --git a/docs/concepts.rst b/docs/concepts.rst index a4b865b..3364d7b 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -21,6 +21,8 @@ view is called. Let's look at what *channels* are first. +.. _what-are-channels: + What is a channel? ------------------ diff --git a/docs/deploying.rst b/docs/deploying.rst index 73b0308..036b467 100644 --- a/docs/deploying.rst +++ b/docs/deploying.rst @@ -118,7 +118,7 @@ first, make sure your project has an ``asgi.py`` file that looks like this channel_layer = get_channel_layer() -Then, you can run Daphne and supply the channel layer as the argument: +Then, you can run Daphne and supply the channel layer as the argument:: daphne my_project.asgi:channel_layer @@ -152,3 +152,26 @@ customise requests is run on the consumers. You can even use different Python versions for the interface servers and the workers; the ASGI protocol that channel layers communicate over is designed to be very portable and network-transparent. + + +.. _wsgi-to-asgi: + +Running ASGI under WSGI +----------------------- + +ASGI is a relatively new specification, and so it's backwards compatible with +WSGI servers with an adapter layer. You won't get WebSocket support this way - +WSGI doesn't support WebSockets - but you can run a separate ASGI server to +handle WebSockets if you want. + +The ``wsgiref`` package contains the adapter; all you need to do is put this +in your Django project's ``wsgi.py`` to declare a new WSGI application object +that backs onto ASGI underneath:: + + import os + from asgiref.wsgi import WsgiToAsgiAdapter + from channels.asgi import get_channel_layer + + os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_test.settings") + channel_layer = get_channel_layer() + application = WsgiToAsgiAdapter(channel_layer) diff --git a/docs/getting-started.rst b/docs/getting-started.rst index f3279a1..833b549 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -127,6 +127,8 @@ Now, that's taken care of adding and removing WebSocket send channels for the we're not going to store a history of messages or anything and just replay any message sent in to all connected clients. Here's all the code:: +.. _websocket-example: + # In consumers.py from channels import Group diff --git a/docs/index.rst b/docs/index.rst index c77d205..881089d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,8 @@ data model underlying Channels and how they're used inside Django. Then, read :doc:`getting-started` to see how to get up and running with WebSockets with only 30 lines of code. +If you want a quick overview, start with :doc:`inshort`. + You can find the Channels repository `on GitHub `_. Contents: @@ -22,6 +24,7 @@ Contents: .. toctree:: :maxdepth: 2 + inshort concepts installation getting-started diff --git a/docs/inshort.rst b/docs/inshort.rst new file mode 100644 index 0000000..b4657a6 --- /dev/null +++ b/docs/inshort.rst @@ -0,0 +1,90 @@ +In Short +======== + + +What is Channels? +----------------- + +Channels extends Django to add :ref:`a new layer ` +that allows two important features: + +* WebSocket handling, in a way very :ref:`similar to normal views ` +* Background tasks, running in the same servers as the rest of Django + + +How? +---- + +It separates Django into two process types: + +* One that handles HTTP and WebSockets +* One that runs views, websocket handlers and background tasks (*consumers*) + +They communicate via a protocol called :doc:`ASGI `, which is similar +to WSGI but runs over a network and allows for more protocol types. + +Channels does not introduce asyncio, gevent, or any other async code to +your Django code; all of your business logic runs synchronously in a worker +process or thread. + + +I have to change how I run Django? +---------------------------------- + +No, all the new stuff is entirely optional. If you want it, however, you'll +change from running Django under a WSGI server, to running: + +* An ASGI server, like `Daphne ` +* Django worker servers, using ``manage.py runworker`` +* Something to route ASGI requests over, like Redis or a database. + + +What else does Channels give me? +-------------------------------- + +Other features include: + +* Easy HTTP long-poll support for thousands of clients at once +* Full session and auth support for WebSockets +* Automatic user login for WebSockets based on site cookies +* Built-in primitives for mass triggering of events (chat, live blogs, etc.) +* Zero-downtime deployment with browsers paused while new workers spin up +* Optional low-level HTTP control on a per-URL basis +* Extendability to other protocols or event sources (e.g. WebRTC, raw UDP, SMS) + + +Does it scale? +-------------- + +Yes, you can run any number of *protocol servers* (ones that serve HTTP +and WebSockets) and *worker servers* (ones that run your Django code) to +fit your use case. + +The ASGI spec allows a number of different *channel layers* to be plugged in +between these two components, with difference performance characteristics, and +it's designed to allow both easy sharding as well as the ability to run +separate clusters with their own protocol and worker servers. + + +Do I need to worry about making all my code async-friendly? +----------------------------------------------------------- + +No, all your code runs synchronously without any sockets or event loops to +block. You can use async code within a Django view or channel consumer if you +like - for example, to fetch lots of URLs in parallel - but it doesn't +affect the overall deployed site. + + +What version of Django does it work with? +----------------------------------------- + +You can install Channels as a library for Django 1.8 and 1.9, and it (should be) +part of Django 1.10. It has a few extra dependencies, but these will all +be installed if you use `pip`. + + +What do I read next? +-------------------- + +Start off by reading about the :doc:`concepts underlying Channels `, +and then move on to read our example-laden :doc:`Getting Started guide `.