django-subdomains 1.2.2

Subdomain tools for the Django framework, including subdomain-based URL routing.

# 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`.