fata1ex Nov 10 2009 at 23:39

Перевод Django Documentation: Models. Part 1

8 min

19K

Доброго времени суток!

Данный топик представляет собой первую часть перевода документации Django, а именно раздела о моделях. Сразу хочу сказать, что я не являюсь профессиональным переводчиком и изначально делал перевод для себя. Все замечания и вопросы просьба писать в комментариях или посылать по хабрапочте. Надеюсь, информация окажется полезной для вас.

_Модели
___Небольшой пример
___Использование моделей
___Поля
_____Типы полей
_____Параметры полей
_____Автоматические первичные ключи
_____Подробные имена полей

Перевод Django Documentation: Models. Part 2
Перевод Django Documentation: Models. Part 3
Перевод Django Documentation: Models. Part 4 (Last)

Данный документ относится к Django's SVN релизу, который может значительно отличаться от предыдущих. Старая документация (для Django 1.0) доступна здесь

Модели

Модель является единственным и окончательным источником сведений о ваших данных. Она описывает поведение данных, которые вы храните, и содержит их основные поля. Как правило, каждая модель является представлением одной из таблиц базы данных.

Основные сведения:

Каждая модель — это класс, являющийся подклассом django.db.models.Model.
Каждый атрибут модели представляет отдельное поле базы данных.
С помощью моделей Django фактически предоставляет вам автоматически-генерируемый API доступа к базе данных (см. создание запросов).

Дополнением к данному документу является официальное хранилище примеров использования моделей (Так же вы можете найти эти примеры в дистрибутиве Django в директории tests/modeltests).

Небольшой пример

В данном примере определяется класс Person, содержащий поля first_name и last_name:

Copy Source | Copy HTML from django.db import models class Person(models.Model): first_name = models.CharField(max_length=30) last_name = models.CharField(max_length=30) 

first_name и last_name являются полями нашей модели. Каждое поле определяет атрибут класса, а каждый атрибут в свою очередь представляет собой колонку базы данных.

Вышеприведенный класс Person создаст таблицу базу данных примерно такого вида:

Copy Source | Copy HTML CREATE TABLE myapp_person ( "id" serial NOT NULL PRIMARY KEY, "first_name" varchar(30) NOT NULL, "last_name" varchar(30) NOT NULL ); 

Некоторые технические замечания:

Имя таблицы, myapp_person, автоматически получено из метаданных нашей модели, однакобыть задан оно может быть переопределено (см. имена таблиц).
Поле id добавлено автоматически, но вы можете изменить это поведение.
В нашем примере используется синтаксис SQL, отвечающий PostgreSQL, однако, стоит отметить, что Django использует SQL с учетом базы данных, указанной в вашем файле настроек.

Использование моделей

Как только вы определили ваши модели, вы должны сообщить Django, что собираетесь использовать их. Делается это с помощью изменения вашего файла настроек, а именно редактирования INSTALLED_APPS, в который нужно добавить имя вашего модуля, содержащего models.py.

Например, если модели вашего приложения находятся в модуле mysite.myapp.models (данная структура создается после выполнения сценария manage.py startapp), нужная нам часть INSTALLED_APPS должна выглядеть так:

Copy Source | Copy HTML INSTALLED_APPS = ( #... 'mysite.myapp', #... ) 

После редактирования INSTALLED_APPS не забудьте запустить сценарий syncdb.

Поля

Наиболее важной и едиhttp://docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.__unicode__
нственно необходимой частью любой модели является список полей базы данных, которые она определяет. Поля задаются атрибутами класса.

Например:http://docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.__unicode__

Copy Source | Copy HTML class Musician(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) instrument = models.CharField(max_length=100) class Album(models.Model): artist = models.ForeignKey(Musician) name = models.CharField(max_length=100) release_date = models.DateField() num_stars = models.IntegerField() 

Типы полей

Каждое поле вашей модели должно быть экземпляром соответствующего класса Field. Django использует типы класса Field для определения нескольких вещей:

Тип колонки базы данных (например, INTEGER, VARCHAR).
Виджет для использования интерфейса администратора в Django, если вы хотите его использовать (например, input type=«text»>).
Минимальные требования к проверке, используемой в интерфейсе администраhttp://docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.__unicode__тора Django и автоматически-генерируемых формах.

Django поставляется с десятками встроенных типов; вы можете посмотреть полный список в справке по полям моделей. Так же вы можете создавать собственные типы полей.

Параметры полей

Каждое поле имеет определенный набор характерных аргументов, документированных в справке по полям моделей. Например, CharField (и его подклассы) требует аргумент max_length, который определяет размер поля базы данных VARCHAR, используемый для хранения ваших данных.
docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.__unicode__
Существует также набор общих аргументов, которые доступны для всех типов полей. Все они являются необязательными. Полное описание предоставлено в справке, однако небольшой обзор наиболее часто-используемых мы приведем здесь:

null

Если значение аргумента True, Django будет сохранять пустые значения в базе данных как NULL. По умолчанию False.

blank

Если значение аргумента True, то поле может быть пустым. По умолчанию False.

Заметим, что blank отличается null. Аргумент null относится только к базам данных, а blank в свою очередь отвечает за проверку ввода. Если поле имеет аргумент blank со значением TRUE, то проверка в docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.Field.defaultинтерфейсе администратора Django будет допускать ввод пустого значения. Если же значение атрибута — False, поле будетhttp://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.Field.default обязательным для заполнения.

choices

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

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

<docs.djangoproject.com/en/dev/ref/models/instances/#django.db.models.Model.__unicode__ a href="http://s-c.me/3744/s">Copy Source | Copy HTML YEAR_IN_SCHOOL_CHOICES = ( (u'FR', u'Freshman'), (u'SO', u'Sophomore'), (u'JR', u'Junior'), (u'SR', u'Senior'), (u'GR', u'Graduate'), ) 

Первым элементом в каждом кортеже является значение, которое будет занесено в базу данных, второе будет отображено в интерфейсе администратора или в ModelChoiceField. При использовании экземпляра объекта модели, вывод значений choices для поля может быть осуществлен с помощью метода get_FOO_display. Например:

Copy Source | Copy HTML from django.db import models class Person(models.Model): GENDER_CHOICES = ( (u'M', u'Male'), (u'F', u'Female'), ) name = models.CharField(max_length=60) gender = models.CharField(max_length=2, choices=GENDER_CHOICES) 

Copy Source | Copy HTML >>> p = Person(name="Fred Flinstone", gender="M") >>> p.save() >>> p.gender u'M' >>> p.get_gender_display() u'Male' 

default

Значение данного аргумента является значением поля по умолчанию или вызываемый объект (в этом случае вызываемый объект будет вызываться каждый раз при создании нового объекта).

help_text

Значение данного аргумента — текст (дополнительная «помощь»), который будет отображаться в интерфейсе администратора в форме объектов после данного поля. Это полезно для документирования, если ваш объект не имеет формы администратора.

primary_key

Если значение аргумента True, поле будет являться первичным ключом для модели.

Если вы не определите primary_key=True ни для одной из полей вашей модели, Django автоматически добавит IntegerField, чтобы модель имела первичный ключ, поэтому вы можете устанавливать значение primary_key=True для какого-либо поля, только если хотите переопределить стандартное поведение при создании первичного ключа.

unique

Если значение аргумента True, поле должно быть уникальным во всей таблице базы данных.

Напомним, выше приведено лишь краткое описание часто-используемых аргументов полей. Более детально изучить их вы можете здесь.

Автоматические первичные ключи

По умолчанию Django добавляет каждой модели такое поле:

Copy Source | Copy HTML id = models.AutoField(primary_key=True) 

Это автоинкрементный первичный ключ.

Если вы хотите создать свой первичный ключ, просто определите атрибут primary_key=True в одном из ваших полей. Если Django увидит, что вы однозначно задали Field.primary_key, то колонка id добавлена не будет.

Каждая модель должна иметь одно и только одно поле с primary_key=True.

Подробные имена полей

Каждый тип поля, кроме ForeignKey, ManyToManyField и OneToOneField, содержит необязательный первый аргумент — подробное имя (verbose name). Если этот аргумент не задан, Django автоматически создаст его, используя имена атрибутов поля, преобразовывая нижние подчеркивания в пробелы.

В данном примере, подробное имя будет «Person's first name»:

Copy Source | Copy HTML first_name = models.CharField("Person's first name", max_length=30) 

В данном примере, подробное имя будет «first name»:

Copy Source | Copy HTML first_name = models.CharField(max_length=30) 

ForeignKey, ManyToManyField и OneToOneField требуют, чтобы первым аргументом была модель, поэтому с ними используется аргумент verbose_name:

Copy Source | Copy HTML poll = models.ForeignKey(Poll, verbose_name="the related poll") sites = models.ManyToManyField(Site, verbose_name="list of sites") place = models.OneToOneField(Place, verbose_name="related place") 

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

Вот и все :) to be continued

Перевод Django Documentation: Models. Part 2
Перевод Django Documentation: Models. Part 3
Перевод Django Documentation: Models. Part 4 (Last)

Tags:

Hubs:

Django