Python helpers

hosts and patterns

When defining hostconfs you need to use the patterns and host helpers

django_hosts.defaults.patterns(prefix, *args)

The function to define the list of hosts (aka hostconfs), e.g.:

from django_hosts import patterns

host_patterns = patterns('path.to',
    (r'www', 'urls.default', 'default'),
    (r'api', 'urls.api', 'api'),
)
Parameters:
  • prefix (str) – the URLconf prefix to pass to the host object
  • *args – a list of hosts instances or an iterable thereof
class django_hosts.defaults.host(regex, urlconf, name, callback=None, prefix='', scheme=None, port=None)

The host object used in host conf together with the django_hosts.defaults.patterns() function, e.g.:

from django_hosts import patterns, host

host_patterns = patterns('path.to',
    host(r'www', 'urls.default', name='default'),
    host(r'api', 'urls.api', name='api'),
    host(r'admin', 'urls.admin', name='admin', scheme='https://'),
)
Parameters:
  • regex (str) – a regular expression to be used to match the request’s host.
  • urlconf (str) – the dotted path of a URLconf module of the host
  • callback (callable or str) – a callable or the dotted path of a callable to be used when matching has happened
  • prefix (str) – the prefix to apply to the urlconf parameter
  • scheme (str) – the scheme to prepend host names with during reversing, e.g. when using the host_url() template tag. Defaults to HOST_SCHEME.
  • port – the port to append to host names during reversing, e.g. when using the host_url() template tag. Defaults to HOST_PORT.
add_prefix(prefix='')

Adds the prefix string to a string-based urlconf.

reverse_host and reverse

If you want to reverse the hostname or the full URL or a view including the scheme, hostname and port you’ll need to use the reverse and reverse_host helper functions (or its lazy cousins).

django_hosts.resolvers.reverse(viewname, args=None, kwargs=None, prefix=None, current_app=None, host=None, host_args=None, host_kwargs=None, scheme=None, port=None)

Given the host and view name and the appropriate parameters, reverses the fully qualified URL, e.g.:

>>> from django.conf import settings
>>> settings.ROOT_HOSTCONF = 'mysite.hosts'
>>> settings.PARENT_HOST = 'example.com'
>>> from django_hosts.resolvers import reverse
>>> reverse('about')
'//www.example.com/about/'
>>> reverse('about', host='www')
'//www.example.com/about/'
>>> reverse('repo', args=('jezdez',), host='www', scheme='git', port=1337)
'git://jezdez.example.com:1337/repo/'

You can set the used port and scheme in the host object or override with the paramater named accordingly.

The host name can be left empty to automatically fall back to the default hostname as defined in the DEFAULT_HOST setting.

Parameters:
  • viewname – the name of the view
  • args – the arguments of the view
  • kwargs – the keyed arguments of the view
  • prefix – the prefix of the view urlconf
  • current_app – the current_app argument
  • scheme – the scheme to use
  • port – the port to use
  • host – the name of the host
  • host_args – the host arguments
  • host_kwargs – the host keyed arguments
Raises:

django.core.urlresolvers.NoReverseMatch – if no host or path matches

Return type:

the fully qualified URL with path

django_hosts.resolvers.reverse_host(host, args=None, kwargs=None)

Given the host name and the appropriate parameters, reverses the host, e.g.:

>>> from django.conf import settings
>>> settings.ROOT_HOSTCONF = 'mysite.hosts'
>>> settings.PARENT_HOST = 'example.com'
>>> from django_hosts.resolvers import reverse_host
>>> reverse_host('with_username', args=('jezdez',))
'jezdez.example.com'
Parameters:
  • name – the name of the host as specified in the hostconf
  • args – the host arguments to use to find a matching entry in the hostconf
  • kwargs – similar to args but key value arguments
Raises:

django.core.urlresolvers.NoReverseMatch – if no host matches

Return type:

reversed hostname

django_hosts.resolvers.reverse_host_lazy(*args, **kw)

The lazy version of the reverse_host() function to be used in class based views and other module level situations

django_hosts.resolvers.reverse_lazy(*args, **kw)

The lazy version of the reverse() function to be used in class based views and other module level situations

HostSiteManager model manager

class django_hosts.managers.HostSiteManager(field_name=None, select_related=True)

A model manager to limit objects to those associated with a site.

Parameters:
  • field_name – the name of the related field pointing at the Site model, or a series of relations using the field1__field2__field3 notation. Falls back to looking for ‘site’ and ‘sites’ fields.
  • select_related – a boolean specifying whether to use select_related() when querying the database

Define a manager instance in your model class with one of the following notations:

on_site = HostSiteManager()  # automatically looks for site and sites
on_site = HostSiteManager("author__site")
on_site = HostSiteManager("author__blog__site")
on_site = HostSiteManager("author__blog__site",
                          select_related=False)

Then query against it with one of the manager methods:

def home_page(request):
    posts = BlogPost.on_site.by_request(request).all()
    return render(request, 'home_page.html', {'posts': posts})
by_id(site_id=None)

Returns a queryset matching the given site id. If not given this falls back to the SITE_ID setting.

Parameters:site_id – the ID of the site
Return type:QuerySet
by_request(request)

Returns a queryset matching the given request’s site attribute.

Parameters:request (HttpRequest) – the current request
Return type:QuerySet
by_site(site)

Returns a queryset matching the given site.

Parameters:site (Site) – a site instance
Return type:QuerySet
get_queryset(site_id=None)

Returns a new QuerySet object. Subclasses can override this method to easily customize the behavior of the Manager.