django-hosts
============
.. image:: https://img.shields.io/pypi/v/django-hosts.svg
:target: https://pypi.python.org/pypi/django-hosts
.. image:: https://img.shields.io/pypi/pyversions/django-hosts.svg
:target: https://pypi.org/project/django-hosts/
.. image:: https://img.shields.io/pypi/djversions/django-hosts.svg
:target: https://pypi.org/project/django-hosts/
.. image:: https://github.com/jazzband/django-hosts/workflows/Test/badge.svg
:target: https://github.com/jazzband/django-hosts/actions
.. image:: https://codecov.io/gh/jazzband/django-hosts/branch/master/graph/badge.svg
:target: https://codecov.io/gh/jazzband/django-hosts
.. image:: https://readthedocs.org/projects/django-hosts/badge/?version=latest&style=flat
:target: https://django-hosts.readthedocs.io/en/latest/
.. image:: https://jazzband.co/static/img/badge.svg
:target: https://jazzband.co/
This Django app routes requests for specific hosts to different URL schemes
defined in modules called "hostconfs".
For example, if you own ``example.com`` but want to serve specific content
at ``api.example.com`` and ``beta.example.com``, add the following to a
``hosts.py`` file:
.. code-block:: python
from django_hosts import patterns, host
host_patterns = patterns('path.to',
host(r'api', 'api.urls', name='api'),
host(r'beta', 'beta.urls', name='beta'),
)
This causes requests to ``{api,beta}.example.com`` to be routed to their
corresponding URLconf. You can use your ``urls.py`` as a template for these
hostconfs.
Patterns are evaluated in order. If no pattern matches, the request is
processed in the usual way, ie. using the standard ``ROOT_URLCONF``.
The patterns on the left-hand side are regular expressions. For example,
the following ``ROOT_HOSTCONF`` setting will route ``foo.example.com``
and ``bar.example.com`` to the same URLconf.
.. code-block:: python
from django_hosts import patterns, host
host_patterns = patterns('',
host(r'(foo|bar)', 'path.to.urls', name='foo-or-bar'),
)
.. note:
Remember:
* Patterns are matched against the extreme left of the requested host
* It is implied that all patterns end either with a literal full stop
(ie. ".") or an end of line metacharacter.
* As with all regular expressions, various metacharacters need quoting.
Installation
------------
First, install the app with your favorite package manager, e.g.:
.. code-block:: shell
pip install django-hosts
Alternatively, use the `repository on Github`_.
You can find the full docs here: `django-hosts.rtfd.org`_
Then configure your Django site to use the app:
#. Add ``'django_hosts'`` to your ``INSTALLED_APPS`` setting.
#. Add ``'django_hosts.middleware.HostsRequestMiddleware'`` to the
**beginning** of your ``MIDDLEWARE`` setting.
#. Add ``'django_hosts.middleware.HostsResponseMiddleware'`` to the **end** of
your ``MIDDLEWARE`` setting.
#. Create a new module containing your default host patterns,
e.g. in the ``hosts.py`` file next to your ``urls.py``.
#. Set the ``ROOT_HOSTCONF`` setting to the dotted Python
import path of the module containing your host patterns, e.g.:
.. code-block:: python
ROOT_HOSTCONF = 'mysite.hosts'
#. Set the ``DEFAULT_HOST`` setting to the **name** of the host pattern you
want to refer to as the default pattern. It'll be used if no other
pattern matches or you don't give a name to the ``host_url`` template
tag.
.. _`repository on Github`: https://github.com/jazzband/django-hosts
.. _`django-hosts.rtfd.org`: https://django-hosts.readthedocs.io/