Subdomain tools for the Django framework, including subdomain-based URL routing.
Project description
# django-subdomains
## Installation
This application is available via the
[Python Package Index](http://pypi.python.org/pypi/django-subdomains) and can
be installed with any Python package manager, such as `pip` or `easy_install`
by running:
pip install django-subdomains
or
easy_install django-subdomains
It is highly recommended to use package version numbers to ensure API
consistency.
To install the latest version from the repository source, clone the repository
and then run `make install` in the repository directory.
## Configuring Django Settings
1. Add `subdomains.middleware.SubdomainURLRoutingMiddleware` to your
`MIDDLEWARE_CLASSES` in your Django settings file.
2. Set up your `SUBDOMAIN_URLCONFS` dictionary in your Django settings file.
(See the example below.)
3. Make sure that you've set up your `SITE_ID` in your Django settings file,
and that the `domain` attribute corresponds to the proper domain name.
4. ???
5. Profit!
## Example Configuration
# This is the URL that will be loaded for any subdomain that is not listed
# in SUBDOMAIN_URLCONFS. If you're going use wildcard subdomains, this will
# correspond to the wildcarded subdomain.
# For example, 'accountname.mysite.com' will load the ROOT_URLCONF, since
# it is not defined in SUBDOMAIN_URLCONFS.
ROOT_URLCONF = 'myproject.urls.account'
SUBDOMAIN_URLCONFS = {
# The format for these is 'subdomain': 'urlconf'
None: 'myproject.urls.frontend',
'www': 'myproject.urls.frontend',
'api': 'myproject.urls.api',
}
## Usage Notes
The subdomain is also added to the request, so you can change view logic,
depending on it's value, like so:
def user_profile(request):
try:
# Retrieve the user account associated with the current subdomain.
user = User.objects.get(username=request.subdomain)
except User.DoesNotExist:
# No user matches the current subdomain, so return a generic 404.
raise Http404
### Adding Functionality
You can also subclass `SubdomainURLRoutingMiddleware` if you'd like, to
associate requests with user accounts based on subdomain, etc.
## Settings
### `USE_SUBDOMAIN_EXCEPTION`
Default: `False`
If `USE_SUBDOMAIN_EXCEPTION` is set to `True`, an
`subdomains.exceptions.IncorrectSiteException` will be raised if the domain
name does not match the `django.contrib.sites.models.Site` instance specified
by your `SITE_ID`. This setting defaults to `False`, and will instead throw a
warning that will not prevent your application from continuing if the `Site`
is incorrect.
### `REMOVE_WWW_FROM_DOMAIN`
Default: `False`
If `REMOVE_WWW_FROM_DOMAIN` is set to `True`, the `domain` attribute of the
`Site` model will have the `www.` portion stripped before processing. This
allows for "www.example.com" to be used in the `Site`'s `domain` attribute,
without subdomains being resolved to "___.www.example.com".
## Contributing
Before submitting a patch, please make sure to run the test suite, as well as
pyflakes and PEP8 checks. These can be ran from the repository with the command
`make check test`.
## Installation
This application is available via the
[Python Package Index](http://pypi.python.org/pypi/django-subdomains) and can
be installed with any Python package manager, such as `pip` or `easy_install`
by running:
pip install django-subdomains
or
easy_install django-subdomains
It is highly recommended to use package version numbers to ensure API
consistency.
To install the latest version from the repository source, clone the repository
and then run `make install` in the repository directory.
## Configuring Django Settings
1. Add `subdomains.middleware.SubdomainURLRoutingMiddleware` to your
`MIDDLEWARE_CLASSES` in your Django settings file.
2. Set up your `SUBDOMAIN_URLCONFS` dictionary in your Django settings file.
(See the example below.)
3. Make sure that you've set up your `SITE_ID` in your Django settings file,
and that the `domain` attribute corresponds to the proper domain name.
4. ???
5. Profit!
## Example Configuration
# This is the URL that will be loaded for any subdomain that is not listed
# in SUBDOMAIN_URLCONFS. If you're going use wildcard subdomains, this will
# correspond to the wildcarded subdomain.
# For example, 'accountname.mysite.com' will load the ROOT_URLCONF, since
# it is not defined in SUBDOMAIN_URLCONFS.
ROOT_URLCONF = 'myproject.urls.account'
SUBDOMAIN_URLCONFS = {
# The format for these is 'subdomain': 'urlconf'
None: 'myproject.urls.frontend',
'www': 'myproject.urls.frontend',
'api': 'myproject.urls.api',
}
## Usage Notes
The subdomain is also added to the request, so you can change view logic,
depending on it's value, like so:
def user_profile(request):
try:
# Retrieve the user account associated with the current subdomain.
user = User.objects.get(username=request.subdomain)
except User.DoesNotExist:
# No user matches the current subdomain, so return a generic 404.
raise Http404
### Adding Functionality
You can also subclass `SubdomainURLRoutingMiddleware` if you'd like, to
associate requests with user accounts based on subdomain, etc.
## Settings
### `USE_SUBDOMAIN_EXCEPTION`
Default: `False`
If `USE_SUBDOMAIN_EXCEPTION` is set to `True`, an
`subdomains.exceptions.IncorrectSiteException` will be raised if the domain
name does not match the `django.contrib.sites.models.Site` instance specified
by your `SITE_ID`. This setting defaults to `False`, and will instead throw a
warning that will not prevent your application from continuing if the `Site`
is incorrect.
### `REMOVE_WWW_FROM_DOMAIN`
Default: `False`
If `REMOVE_WWW_FROM_DOMAIN` is set to `True`, the `domain` attribute of the
`Site` model will have the `www.` portion stripped before processing. This
allows for "www.example.com" to be used in the `Site`'s `domain` attribute,
without subdomains being resolved to "___.www.example.com".
## Contributing
Before submitting a patch, please make sure to run the test suite, as well as
pyflakes and PEP8 checks. These can be ran from the repository with the command
`make check test`.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.