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
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 thefield1__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 requestReturn type: QuerySet
- field_name – the name of the related field pointing at the