mirror of
https://github.com/django/daphne.git
synced 2025-11-04 01:27:33 +03:00
e24bc17bbf
* Added as_route documentation * Added documentation for client * Improve tests for binding * Changes for client docs * Fix docs indentations at client part * Added missed imports * Small fixes and refs * Fix typos * Fix errors and typos.
83 lines
3.2 KiB
ReStructuredText
83 lines
3.2 KiB
ReStructuredText
Routing
|
|
=======
|
|
|
|
Routing in Channels is done using a system similar to that in core Django;
|
|
a list of possible routes is provided, and Channels goes through all routes
|
|
until a match is found, and then runs the resulting consumer.
|
|
|
|
The difference comes, however, in the fact that Channels has to route based
|
|
on more than just URL; channel name is the main thing routed on, and URL
|
|
path is one of many other optional things you can route on, depending on
|
|
the protocol (for example, imagine email consumers - they would route on
|
|
domain or recipient address instead).
|
|
|
|
The routing Channels takes is just a list of *routing objects* - the three
|
|
built in ones are ``route``, ``route_class`` and ``include``, but any object
|
|
that implements the routing interface will work:
|
|
|
|
* A method called ``match``, taking a single ``message`` as an argument and
|
|
returning ``None`` for no match or a tuple of ``(consumer, kwargs)`` if matched.
|
|
|
|
* A method called ``channel_names``, which returns a set of channel names that
|
|
will match, which is fed to the channel layer to listen on them.
|
|
|
|
The three default routing objects are:
|
|
|
|
* ``route``: Takes a channel name, a consumer function, and optional filter
|
|
keyword arguments.
|
|
|
|
* ``route_class``: Takes a class-based consumer, and optional filter
|
|
keyword arguments. Channel names are taken from the consumer's
|
|
``channel_names()`` method.
|
|
|
|
* ``include``: Takes either a list or string import path to a routing list,
|
|
and optional filter keyword arguments.
|
|
|
|
.. _filters:
|
|
|
|
Filters
|
|
-------
|
|
|
|
Filtering is how you limit matches based on, for example, URLs; you use regular
|
|
expressions, like so::
|
|
|
|
route("websocket.connect", consumers.ws_connect, path=r"^/chat/$")
|
|
|
|
.. note::
|
|
Unlike Django's URL routing, which strips the first slash of a URL for
|
|
neatness, Channels includes the first slash, as the routing system is
|
|
generic and not designed just for URLs.
|
|
|
|
You can have multiple filters::
|
|
|
|
route("email.receive", comment_response, to_address=r".*@example.com$", subject="^reply")
|
|
|
|
Multiple filters are always combined with logical AND; that is, you need to
|
|
match every filter to have the consumer called.
|
|
|
|
Filters can capture keyword arguments to be passed to your function or your class based consumer methods as a ``kwarg``::
|
|
|
|
route("websocket.connect", connect_blog, path=r'^/liveblog/(?P<slug>[^/]+)/stream/$')
|
|
|
|
You can also specify filters on an ``include``::
|
|
|
|
include("blog_includes", path=r'^/liveblog')
|
|
|
|
When you specify filters on ``include``, the matched portion of the attribute
|
|
is removed for matches inside the include; for example, this arrangement
|
|
matches URLs like ``/liveblog/stream/``, because the outside ``include``
|
|
strips off the ``/liveblog`` part it matches before passing it inside::
|
|
|
|
inner_routes = [
|
|
route("websocket.connect", connect_blog, path=r'^/stream/'),
|
|
]
|
|
|
|
routing = [
|
|
include(inner_routes, path=r'^/liveblog')
|
|
]
|
|
|
|
You can also include named capture groups in the filters on an include and
|
|
they'll be passed to the consumer just like those on ``route``; note, though,
|
|
that if the keyword argument names from the ``include`` and the ``route``
|
|
clash, the values from ``route`` will take precedence.
|