Фреймворк «sites»

Django поставляется с необязательным фреймворком «sites». Он предназначен для сопоставления объектов и функциональности с конкретными веб-сайтами и хранит доменные имена и описательные имена ваших сайтов, работающих на Django.

Используйте его, если одна установка Django обслуживает более одного сайта и вам необходимо каким-то образом различать эти сайты.

Фреймворк «sites» в основном основан на этой модели:

class models.Site

Модель для хранения атрибутов domain и name веб-сайта.

domain: Полное доменное имя, связанное с веб-сайтом. Например, www.example.com.

name: Описательное имя веб-сайта.

Настройка SITE_ID указывает идентификатор базы данных объекта Site, связанного с этим файлом настроек. Если настройка опущена, функция get_current_site() попытается получить текущий сайт, сравнив domain с именем хоста из метода request.get_host().

Как вы будете использовать это, зависит от вас, но Django автоматически использует его несколькими способами, следуя определённым соглашениям.

Пример использования

Зачем использовать sites? Лучше всего это объяснить на примерах.

Связывание контента с несколькими сайтами

Сайты LJWorld.com и Lawrence.com управляются одной новостной организацией — газетой Lawrence Journal-World в Лоуренсе, Канзас. LJWorld.com был нацелен на новости, а Lawrence.com — на местные развлечения. Но иногда редакторы хотели опубликовать статью на обоих сайтах.

Примитивный способ решения проблемы заключался бы в том, чтобы потребовать от авторов публикаций публиковать одну и ту же историю дважды: один раз для LJWorld.com и снова для Lawrence.com. Но это неэффективно для авторов, и избыточно хранить несколько копий одной и той же истории в базе данных.

Лучшее решение избавляется от дублирования контента: оба сайта используют одну и ту же базу данных статей, а статья связана с одним или несколькими сайтами. В терминологии модели Django это представлено с помощью ManyToManyField в модели Article:

from django.contrib.sites.models import Site
from django.db import models

class Article(models.Model):
    headline = models.CharField(max_length=200)
    # ...
    sites = models.ManyToManyField(Site)

Это позволяет сделать несколько полезных вещей:

Это позволяет авторам редактировать весь контент — на обоих сайтах — в одном интерфейсе (админ-панель Django).
Это означает, что одну и ту же историю не нужно публиковать дважды в базе данных; она хранится в базе данных в единственном экземпляре.
Это позволяет разработчикам использовать один и тот же код представления Django для обоих сайтов. Код представления, отображающий определённую историю, проверяет, находится ли запрошенная история на текущем сайте. Он выглядит примерно так:
```
from django.contrib.sites.shortcuts import get_current_site

def article_detail(request, article_id):
    try:
        a = Article.objects.get(id=article_id, sites__id=get_current_site(request).id)
    except Article.DoesNotExist:
        raise Http404("Article does not exist on this site")
    # ...
```

Связывание контента с одним сайтом

Аналогично, вы можете связать модель с моделью Site в отношении «многие-к-одному», используя ForeignKey.

Например, если статья допускается только на одном сайте, вы бы использовали модель такого типа:

from django.contrib.sites.models import Site
from django.db import models

class Article(models.Model):
    headline = models.CharField(max_length=200)
    # ...
    site = models.ForeignKey(Site, on_delete=models.CASCADE)

Это имеет те же преимущества, что и в предыдущем разделе.

Интеграция с текущим сайтом из представлений

Вы можете использовать фреймворк «sites» в своих представлениях Django, чтобы выполнять определённые действия в зависимости от сайта, на котором вызывается представление. Например:

from django.conf import settings

def my_view(request):
    if settings.SITE_ID == 3:
        # Do something.
        pass
    else:
        # Do something else.
        pass

Конечно, жёстко кодировать идентификаторы сайтов таким образом не очень хорошо. Такой способ лучше всего подходит для быстрых исправлений. Более чистый способ достижения того же результата — проверка домена текущего сайта:

from django.contrib.sites.shortcuts import get_current_site

def my_view(request):
    current_site = get_current_site(request)
    if current_site.domain == 'foo.com':
        # Do something
        pass
    else:
        # Do something else.
        pass

Это также обеспечивает проверку, установлен ли фреймворк sites, и возвращает экземпляр RequestSite, если он не установлен.

Если у вас нет доступа к объекту запроса, вы можете использовать метод get_current() менеджера модели Site. Тогда вам нужно убедиться, что в файле настроек присутствует настройка SITE_ID. Этот пример эквивалентен предыдущему:

from django.contrib.sites.models import Site

def my_function_without_request():
    current_site = Site.objects.get_current()
    if current_site.domain == 'foo.com':
        # Do something
        pass
    else:
        # Do something else.
        pass

Получение текущего домена для отображения

LJWorld.com и Lawrence.com оба имеют функциональность оповещений по электронной почте, которая позволяет читателям получать уведомления, когда появляются новости. Это довольно просто: читатель регистрируется на веб-форме и сразу же получает электронное письмо со следующим сообщением: «Спасибо за подписку».

Реализовывать код обработки регистрации дважды было бы неэффективно и избыточно, поэтому сайты используют один и тот же код в фоновом режиме. Но сообщение «спасибо за подписку» должно быть разным для каждого сайта. Используя объекты Site, мы можем абстрагировать сообщение «спасибо» для использования значений имени текущего сайта name и домена domain.

Вот пример того, как выглядит представление обработки формы:

from django.contrib.sites.shortcuts import get_current_site
from django.core.mail import send_mail

def register_for_newsletter(request):
    # Check form values, etc., and subscribe the user.
    # ...

    current_site = get_current_site(request)
    send_mail(
        'Thanks for subscribing to %s alerts' % current_site.name,
        'Thanks for your subscription. We appreciate it.\n\n-The %s team.' % (
            current_site.name,
        ),
        'editor@%s' % current_site.domain,
        [user.email],
    )

    # ...

На Lawrence.com в этом электронном письме тема будет «Спасибо за подписку на уведомления lawrence.com». На LJWorld.com тема будет «Спасибо за подписку на уведомления LJWorld.com». То же самое относится и к телу электронного письма.

Обратите внимание, что ещё более гибкий (но более ресурсоёмкий) способ сделать это — использовать систему шаблонов Django. Если у Lawrence.com и LJWorld.com есть разные каталоги шаблонов (DIRS), вы могли бы использовать систему шаблонов так:

from django.core.mail import send_mail
from django.template import loader

def register_for_newsletter(request):
    # Check form values, etc., and subscribe the user.
    # ...

    subject = loader.get_template('alerts/subject.txt').render({})
    message = loader.get_template('alerts/message.txt').render({})
    send_mail(subject, message, 'editor@ljworld.com', [user.email])

    # ...

В этом случае вам нужно будет создать subject.txt и message.txt файлы шаблонов как для каталога шаблонов LJWorld.com, так и для Lawrence.com. Это даёт вам больше гибкости, но также усложняет процесс.

Рекомендуется по возможности использовать объекты Site, чтобы избежать ненужной сложности и избыточности.

Получение текущего домена для полных URL-адресов

Соглашение Django по умолчанию по получению URL-адреса объекта без доменного имени очень удобно, но в некоторых случаях вам может потребоваться отобразить полный URL-адрес — с http:// и доменным именем — для объекта. Для этого можно использовать фреймворк sites. Пример:

>>> from django.contrib.sites.models import Site
>>> obj = MyModel.objects.get(id=3)
>>> obj.get_absolute_url()
'/mymodel/objects/3/'
>>> Site.objects.get_current().domain
'example.com'
>>> 'https://%s%s' % (Site.objects.get_current().domain, obj.get_absolute_url())
'https://example.com/mymodel/objects/3/'

Включение фреймворка sites

Чтобы включить фреймворк sites, выполните следующие действия:

Добавьте 'django.contrib.sites' в настройку INSTALLED_APPS.
Определите настройку SITE_ID:
```
SITE_ID = 1
```
Запустите migrate.

django.contrib.sites регистрирует обработчик сигнала post_migrate, который создаёт сайт по умолчанию с именем example.com и доменным именем example.com. Этот сайт также будет создан после того, как Django создаст тестовую базу данных. Чтобы установить правильное имя и домен для вашего проекта, используйте миграцию данных.

Для обслуживания разных сайтов в рабочей среде вам следует создать отдельный файл настроек для каждого SITE_ID (возможно, импортируя их из общего файла настроек, чтобы избежать дублирования общих настроек), а затем указать соответствующий DJANGO_SETTINGS_MODULE для каждого сайта.

Кеширование объекта текущего `Site`

Поскольку текущий сайт хранится в базе данных, каждый вызов Site.objects.get_current() может привести к запросу к базе данных. Но Django немного умнее: при первом запросе текущий сайт кэшируется, а все последующие вызовы возвращают кэшированные данные вместо обращения к базе данных.

Если по какой-либо причине вам нужно выполнить запрос к базе данных, вы можете сказать Django очистить кэш, используя Site.objects.clear_cache():

# First call; current site fetched from database.
current_site = Site.objects.get_current()
# ...

# Second call; current site fetched from cache.
current_site = Site.objects.get_current()
# ...

# Force a database query for the third call.
Site.objects.clear_cache()
current_site = Site.objects.get_current()

Менеджер `CurrentSiteManager`

class managers.CurrentSiteManager

Если Site играет ключевую роль в вашем приложении, рассмотрите использование полезного CurrentSiteManager в вашей модели(ях). Это менеджер модели менеджер, который автоматически фильтрует запросы, включая только объекты, связанные с текущим Site.

Обязательная настройка SITE_ID

CurrentSiteManager доступен только при определённой настройке SITE_ID в ваших настройках.

Используйте CurrentSiteManager, добавив его явно в вашу модель. Например:

from django.contrib.sites.models import Site
from django.contrib.sites.managers import CurrentSiteManager
from django.db import models

class Photo(models.Model):
    photo = models.FileField(upload_to='photos')
    photographer_name = models.CharField(max_length=100)
    pub_date = models.DateField()
    site = models.ForeignKey(Site, on_delete=models.CASCADE)
    objects = models.Manager()
    on_site = CurrentSiteManager()

С этой моделью, Photo.objects.all() вернёт все Photo объекты в базе данных, но Photo.on_site.all() вернёт только Photo объекты, связанные с текущим сайтом, в соответствии с настройкой SITE_ID.

Другими словами, эти два утверждения эквивалентны:

Photo.objects.filter(site=settings.SITE_ID)
Photo.on_site.all()

Как CurrentSiteManager узнал, какое поле Photo было Site? По умолчанию, CurrentSiteManager ищет поле ForeignKey с именем site или поле ManyToManyField с именем sites для фильтрации. Если вы используете поле с другим именем, отличным от site или sites для идентификации объектов Site, к которым связан ваш объект, то вам необходимо явно передать имя пользовательского поля в качестве параметра к CurrentSiteManager в вашей модели. Следующая модель, у которой есть поле, названное publish_on, демонстрирует это:

from django.contrib.sites.models import Site
from django.contrib.sites.managers import CurrentSiteManager
from django.db import models

class Photo(models.Model):
    photo = models.FileField(upload_to='photos')
    photographer_name = models.CharField(max_length=100)
    pub_date = models.DateField()
    publish_on = models.ForeignKey(Site, on_delete=models.CASCADE)
    objects = models.Manager()
    on_site = CurrentSiteManager('publish_on')

Если вы попытаетесь использовать CurrentSiteManager и передадите имя поля, которого не существует, Django выведет ValueError.

Наконец, обратите внимание, что, скорее всего, вам понадобится обычный (не специфичный для сайта) Manager в вашей модели, даже если вы используете CurrentSiteManager. Как объясняется в документации менеджеров, если вы создаёте менеджер вручную, Django не создаст автоматический objects = models.Manager() менеджер за вас. Также обратите внимание, что определённые части Django – в частности, сайт администрирования Django и общие представления – используют менеджер, который определён первым в модели, поэтому если вы хотите, чтобы ваш сайт администрирования имел доступ ко всем объектам (а не только к объектам, специфичным для сайта), поместите objects = models.Manager() в вашу модель перед определением CurrentSiteManager.

Средства промежуточного ПО сайта

Если вы часто используете этот шаблон:

from django.contrib.sites.models import Site

def my_view(request):
    site = Site.objects.get_current()
    ...

Чтобы избежать повторений, добавьте django.contrib.sites.middleware.CurrentSiteMiddleware в MIDDLEWARE. Средства промежуточного ПО устанавливают атрибут site на каждом объекте запроса, так что вы можете использовать request.site для получения текущего сайта.

Как Django использует фреймворк сайтов

Хотя использование фреймворка сайтов не обязательно, его настоятельно рекомендуется, так как Django использует его в нескольких местах. Даже если ваша установка Django обслуживает только один сайт, вы должны потратить две секунды на создание объекта сайта с вашим domain и name, и указать его ID в настройке SITE_ID.

Вот как Django использует фреймворк сайтов:

В redirects framework, каждый объект перенаправления связан с определённым сайтом. При поиске перенаправления Django учитывает текущий сайт.
В flatpages framework, каждый плоский документ связан с определённым сайтом. При создании плоского документа вы указываете его Site, и FlatpageFallbackMiddleware проверяет текущий сайт при получении плоских документов для отображения.
В syndication framework, шаблоны для title и description автоматически имеют доступ к переменной {{ site }}, которая является объектом Site, представляющим текущий сайт. Также, обработчик для предоставления URL-адресов элементов будет использовать domain из текущего объекта Site, если вы не укажете полный домен.
В authentication framework, django.contrib.auth.views.LoginView передаёт имя текущего Site в шаблон как {{ site_name }}.
Краткое представление (django.contrib.contenttypes.views.shortcut) использует домен текущего объекта Site при вычислении URL-адреса объекта.
В фреймворке администрирования ссылка «Просмотреть на сайте» использует текущий Site для определения домена сайта, на который будет перенаправление.

`RequestSite` объекты

Некоторые приложения django.contrib используют фреймворк сайтов, но спроектированы так, что не требуют установки фреймворка сайтов в вашей базе данных. (Некоторые пользователи не хотят или просто не могут установить дополнительную таблицу базы данных, необходимую для фреймворка сайтов.) Для таких случаев фреймворк предоставляет класс django.contrib.sites.requests.RequestSite, который может использоваться в качестве резервного варианта, когда фреймворк сайтов на базе базы данных недоступен.

class requests.RequestSite

Класс, который разделяет основной интерфейс Site (т.е. у него есть атрибуты domain и name), но получает данные из объекта Django HttpRequest, а не из базы данных.

__init__(request): Устанавливает атрибуты name и domain в значение get_host().

Объект RequestSite имеет интерфейс, похожий на обычный объект Site, за исключением того, что его метод __init__() принимает объект HttpRequest. Он может определить domain и name сайта, анализируя домен запроса. У него есть методы save() и delete() для соответствия интерфейсу Site, но эти методы генерируют исключение NotImplementedError.

`get_current_site` ярлык

Наконец, чтобы избежать повторяющегося кода обратного вызова, фреймворк предоставляет функцию django.contrib.sites.shortcuts.get_current_site().

shortcuts.get_current_site(request)

Функция, проверяющая установку django.contrib.sites и возвращающая либо текущий объект Site, либо объект RequestSite на основе запроса. Она ищет текущий сайт, используя request.get_host(), если параметр SITE_ID не определён.

Метод request.get_host() может возвращать как домен, так и порт, если в заголовке Host явно указан порт, например, example.com:80. В таких случаях, если поиск по домену не удался из-за того, что домен не соответствует записи в базе данных, порт удаляется, и поиск повторяется только с именем домена. Это не относится к RequestSite, который всегда использует исходный хост.

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/3.0/ref/contrib/sites/

Фреймворк «sites»

Пример использования

Связывание контента с несколькими сайтами

Связывание контента с одним сайтом

Интеграция с текущим сайтом из представлений

Получение текущего домена для отображения

Получение текущего домена для полных URL-адресов

Включение фреймворка sites

Кеширование объекта текущего Site

Менеджер CurrentSiteManager

Средства промежуточного ПО сайта

Как Django использует фреймворк сайтов

RequestSite объекты

get_current_site ярлык

Кеширование объекта текущего `Site`

Менеджер `CurrentSiteManager`

`RequestSite` объекты

`get_current_site` ярлык