Соглашения по оформлению кода

При конструировании моделей приняты следующие соглашения по оформлению кода. Последовательность размещения атрибутов класса-модели [3]:

• названия полей;
• атрибуты менеджера модели;
• класс Meta;
• метод __unicode__;
• метод __str__;
• метод save;
• метод get_absolute_url;
• остальные методы.

Вышеперечисленные группы атрибутов должны быть отделены друг от друга пустой строкой.

Если в модели есть поле выбора (choices), оно должно быть оформлено в виде кортежа из кортежей, заглавными буквами. Должны быть расположены в начале модели [3] и названы без использования "магических чисел" [1]. Например:

class Task(models.Model):

    UNCERTAIN_STATUS = 0
    DONE_STATUS = 1
    STOP_STATUS = 2
    WAIT_STATUS = 3
    WORK_STATUS = 4
    STATUS_CHOICES = (
        (DONE_STATUS, 'done'),
        (STOP_STATUS, 'stop')
    )

    status = models.IntegerField(choices=STATUS_CHOICES,
                                 default=UNCERTAIN_STATUS)

Методы модели

Разработчик может определить в модели свои собственные методы и тем самым наделять свои объекты дополнительной функциональностью на уровне строк. Методы модели подходят для инкапсуляции всей бизнес-логики в одном месте. Например, фрагмент модели Цепочка:

class Chain(models.Model):
    """Цепочка задач."""

    # Пропущены атрибуты модели для экономии места.

    # Default manager.
    objects = PassThroughManager.for_queryset_class(ChainQuerySet)()

    def actual_status(self):
        """Определяет фактический статус цепочки."""
        if self.start_date > datetime.date.today():
            return self.WAIT_STATUS
        if self.task_set.filter(status=Task.STOP_STATUS).exists():
            return self.STOP_STATUS
        last_task = self.last_task()
        if last_task.actual_status() == Task.DONE_STATUS:
            return self.DONE_STATUS
        else:
            return self.WORK_STATUS

Согласно спроектированной архитектуре системы были разработаны следующие методы модели данных Задача:

• be_in_time определяет, успевает ли задача к дедлайну;
• actual_status определяет фактический статус задачи, основываясь на таких данных, как «статический» статус задачи (DONE, STOP), статус предыдущей задачи, порядковый номер задачи и текущая дата;
• start_date определяет дату начала работы над задачей, если это возможно;
• days_to_start определяет количество дней, оставшихся до начала работы над задачей;
• remaining_days определяет количество полных дней, оставшихся до дедлайна. Например, задача ограничена сроком [26; 29) и сейчас 27 число. До дедлайна остался один полный день (28 число), так как текущий день не учитывается;
• days_quantity_after_deadline определяет количество дней, на которые просрочена задача;
• expended_days определяет количество дней, затраченных на задачу;
• duration определяет количество дней, выделенных на выполнение задачи.

Для модели Цепочка были реализованы методы:

• actual_status определяет фактический статус цепочки, основываясь на таких данных, как дата начала работы над цепочкой, статус текущей задачи цепочки;
• deadline определяет дедлайн цепочки. Дедлайн цепочки равен дедлайну последней задачи в цепочке;
• finish_date определяет дату завершения цепочки. Дата завершения цепочки равна дате завершения последней задачи в цепочке;
• be_in_time определяет, успевает ли цепочка задач к дедлайну;
• days_to_start определяет количество дней, оставшихся до начала работы цепочки;
• remaining_days определяет количество дней, оставшихся до дедлайна цепочки. Совпадает с количеством дней, оставшихся до дедлайна последней задачи в цепочке;
• days_quantity_after_deadline определяет количество дней, на которые просрочена цепочка;
• expended_days определяет количество дней, затраченных на цепочку;
• last_task возвращает последнюю задачу из цепочки.

Менеджер модели

Менеджер модели -- это объект, с помощью которого Django выполняет запросы к БД. Каждая модель Django имеет по меньшей мере один менеджер, и разработчик может создавать свои менеджеры для организации специализированных видов доступа.

Потребность создания собственного менеджера может быть вызвана двумя причинами: необходимостью добавить менеджеру дополнительные методы или необходимостью модифицировать исходный объект QuerySet, возвращаемый менеджером [2].

Встроенный в Django менеджер моделей не позволяет строить цепочки методов, таких как actual_tasks = Task.objects.by_worker(user).actual(). Для обхода этого ограничения используется сторонняя библиотека django-model-utils, которая позволяет писать QuerySet вместо менеджера [4]. Например:

# -*- coding: utf-8 -*-
from django.db.models.query import QuerySet


class ChainQuerySet(QuerySet):

    def by_owner(self, owner):
        """Возвращает цепочки владельца."""
        return self.filter(owner=owner)

    def actual(self):
        """Возвращает актуальтуные цепочки задач."""
        return self.filter(archive=False).order_by('start_date')

Миграция схемы модели

Во время разработки Django приложений наступает момент, когда необходимо изменить схему модели данных, например, добавить новое поле. Если разработка ведется в группе, то проблема усугубляется тем, что необходимо синхронизировать модель. Эту проблему призвана решить библиотека South. Ее основными задачами является обеспечение простого, стабильного и независимого от БД слоя миграции, чтобы избавить разработчика от проблем изменения схемы.

Рассмотрим типовые примеры начала работы с South [5]. Случай, когда в базе данных нет таблиц и нет файлов миграций -- состояние проекта сразу после выполнения команда manage.py startapp myapp. Далее, вместо команды manage.py syncdb нужно создать начальную миграцию командой manage.py schemamigration myapp --initial и применить миграцию командой manage.py migrate myapp.

Следующий вариант, когда таблицы уже созданы, но нет файлов миграций. В данной ситуации необходимо выполнить команду manage.py convert_to_south myapp.

Возможна ситуация, когда таблицы уже созданы, но миграции еще не применены. Тогда необходимо выполнить manage.py migrate myapp 0001 --fake.