Справочник по полям модели

Этот раздел содержит все существующие подробности о всех параметрах поля и типах полей в Django.

См.также

If the built-in fields don’t do the trick, you can try django-localflavor (documentation), which contains assorted pieces of code that are useful for particular countries and cultures.

Также вы можете легко создать собственное поле для модели.

Примечание

Технически, эти поля определенны в django.db.models.fields, но для удобства они импортированы в django.db.models; по неписанному соглашению принято использовать from django.db import models и обращаться к полям, как models.<Foo>Field.

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

Приведенные аргументы доступны для всех полей. Все они не обязательны.

null

Field.null

При True Django сохранит пустое значение как NULL в базе данных. Значение по умолчанию – False.

Avoid using null on string-based fields such as CharField and TextField. If a string-based field has null=True, that means it has two possible values for «no data»: NULL, and the empty string. In most cases, it’s redundant to have two possible values for «no data;» the Django convention is to use the empty string, not NULL. One exception is when a CharField has both unique=True and blank=True set. In this situation, null=True is required to avoid unique constraint violations when saving multiple objects with blank values.

Для всех типов полей, вы также должны указать blank=True если вы хотите разрешить пустые значения в формах, т.к. параметр null влияет только на сохранение в базе данных (смотрите blank).

Примечание

При использовании Oracle, NULL будет использоваться для пустой строки независимо от значения этого параметра.

blank

Field.blank

При True поле может быть пустым. Значение по умолчанию – False.

Заметим что этот параметр отличается от null. null указывается для базы данных, в то время как blank – для проверки данных. При blank=True, проверка данных в форме позволит сохранять пустое значение в поле. При blank=False поле будет обязательным.

choices

Field.choices

A sequence consisting itself of iterables of exactly two items (e.g. [(A, B), (A, B) ...]) to use as choices for this field. If choices are given, they’re enforced by model validation and the default form widget will be a select box with these choices instead of the standard text field.

Первый элемент каждого кортежа – это значение, которое будет сохранено в базе данных. Второй элемент – название, которое будет отображаться для пользователей. Например:

YEAR_IN_SCHOOL_CHOICES = [
    ('FR', 'Freshman'),
    ('SO', 'Sophomore'),
    ('JR', 'Junior'),
    ('SR', 'Senior'),
    ('GR', 'Graduate'),
]

Значения лучше указать в константах внутри модели:

from django.db import models

class Student(models.Model):
    FRESHMAN = 'FR'
    SOPHOMORE = 'SO'
    JUNIOR = 'JR'
    SENIOR = 'SR'
    GRADUATE = 'GR'
    YEAR_IN_SCHOOL_CHOICES = [
        (FRESHMAN, 'Freshman'),
        (SOPHOMORE, 'Sophomore'),
        (JUNIOR, 'Junior'),
        (SENIOR, 'Senior'),
        (GRADUATE, 'Graduate'),
    ]
    year_in_school = models.CharField(
        max_length=2,
        choices=YEAR_IN_SCHOOL_CHOICES,
        default=FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {self.JUNIOR, self.SENIOR}

Though you can define a choices list outside of a model class and then refer to it, defining the choices and names for each choice inside the model class keeps all of that information with the class that uses it, and helps reference the choices (e.g, Student.SOPHOMORE will work anywhere that the Student model has been imported).

Вы можете сгруппировать значения в именованные группы:

MEDIA_CHOICES = [
    ('Audio', (
            ('vinyl', 'Vinyl'),
            ('cd', 'CD'),
        )
    ),
    ('Video', (
            ('vhs', 'VHS Tape'),
            ('dvd', 'DVD'),
        )
    ),
    ('unknown', 'Unknown'),
]

Первый элемент каждого кортежа – это название группы. Второй элемент – итератор с двух-элементными кортежами содержащими значение и отображаемое название. Сгруппированные опции могут комбинироваться с не сгруппированными (как unknown в примере выше).

Для каждой модели с полем содержащим choices, Django добавляет метод для получения названия текущего значения поля. Смотрите get_FOO_display() в документации про API для работы с базой данных.

Note that choices can be any sequence object – not necessarily a list or tuple. This lets you construct choices dynamically. But if you find yourself hacking choices to be dynamic, you’re probably better off using a proper database table with a ForeignKey. choices is meant for static data that doesn’t change much, if ever.

Примечание

A new migration is created each time the order of choices changes.

Если поле содержит blank=False, но default не определен, в поле выбора будет добавлено значение с названием "---------". Чтобы это изменить, добавьте в choices элемент с None, например, (None, 'Your String For Display'). Также можно использовать пустую строку вместо None, где это имеет смысл, например, для CharField.

Enumeration types

In addition, Django provides enumeration types that you can subclass to define choices in a concise way:

from django.utils.translation import gettext_lazy as _

class Student(models.Model):

    class YearInSchool(models.TextChoices):
        FRESHMAN = 'FR', _('Freshman')
        SOPHOMORE = 'SO', _('Sophomore')
        JUNIOR = 'JR', _('Junior')
        SENIOR = 'SR', _('Senior')
        GRADUATE = 'GR', _('Graduate')

    year_in_school = models.CharField(
        max_length=2,
        choices=YearInSchool.choices,
        default=YearInSchool.FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {YearInSchool.JUNIOR, YearInSchool.SENIOR}

These work similar to enum from Python’s standard library, but with some modifications:

  • Enum member values are a tuple of arguments to use when constructing the concrete data type. Django supports adding an extra string value to the end of this tuple to be used as the human-readable name, or label. The label can be a lazy translatable string. Thus, in most cases, the member value will be a (value, label) two-tuple. See below for an example of subclassing choices using a more complex data type. If a tuple is not provided, or the last item is not a (lazy) string, the label is automatically generated from the member name.
  • A .label property is added on values, to return the human-readable name.
  • A number of custom properties are added to the enumeration classes – .choices, .labels, .values, and .names – to make it easier to access lists of those separate parts of the enumeration. Use .choices as a suitable value to pass to choices in a field definition.
  • The use of enum.unique() is enforced to ensure that values cannot be defined multiple times. This is unlikely to be expected in choices for a field.

Note that using YearInSchool.SENIOR, YearInSchool['SENIOR'], or YearInSchool('SR') to access or lookup enum members work as expected, as do the .name and .value properties on the members.

If you don’t need to have the human-readable names translated, you can have them inferred from the member name (replacing underscores with spaces and using title-case):

>>> class Vehicle(models.TextChoices):
...     CAR = 'C'
...     TRUCK = 'T'
...     JET_SKI = 'J'
...
>>> Vehicle.JET_SKI.label
'Jet Ski'

Since the case where the enum values need to be integers is extremely common, Django provides an IntegerChoices class. For example:

class Card(models.Model):

    class Suit(models.IntegerChoices):
        DIAMOND = 1
        SPADE = 2
        HEART = 3
        CLUB = 4

    suit = models.IntegerField(choices=Suit.choices)

It is also possible to make use of the Enum Functional API with the caveat that labels are automatically generated as highlighted above:

>>> MedalType = models.TextChoices('MedalType', 'GOLD SILVER BRONZE')
>>> MedalType.choices
[('GOLD', 'Gold'), ('SILVER', 'Silver'), ('BRONZE', 'Bronze')]
>>> Place = models.IntegerChoices('Place', 'FIRST SECOND THIRD')
>>> Place.choices
[(1, 'First'), (2, 'Second'), (3, 'Third')]

If you require support for a concrete data type other than int or str, you can subclass Choices and the required concrete data type, e.g. date for use with DateField:

class MoonLandings(datetime.date, models.Choices):
    APOLLO_11 = 1969, 7, 20, 'Apollo 11 (Eagle)'
    APOLLO_12 = 1969, 11, 19, 'Apollo 12 (Intrepid)'
    APOLLO_14 = 1971, 2, 5, 'Apollo 14 (Antares)'
    APOLLO_15 = 1971, 7, 30, 'Apollo 15 (Falcon)'
    APOLLO_16 = 1972, 4, 21, 'Apollo 16 (Orion)'
    APOLLO_17 = 1972, 12, 11, 'Apollo 17 (Challenger)'

There are some additional caveats to be aware of:

  • Enumeration types do not support named groups.

  • Because an enumeration with a concrete data type requires all values to match the type, overriding the blank label cannot be achieved by creating a member with a value of None. Instead, set the __empty__ attribute on the class:

    class Answer(models.IntegerChoices):
        NO = 0, _('No')
        YES = 1, _('Yes')
    
        __empty__ = _('(Unknown)')
    
New in Django 3.0:

The TextChoices, IntegerChoices, and Choices classes were added.

db_column

Field.db_column

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

Если имя колонки это зарезервированное SQL слово, или содержит символы запрещенные в названиях переменной в Python – в частности, дефис – все нормально. Django автоматически экранирует название колонок и таблиц.

db_index

Field.db_index

При True для поля будет создан индекс в базе данных.

db_tablespace

Field.db_tablespace

Имя «tablespace» базы данных используемое для индекса поля, если поле имеет индекс. По-умолчанию используется значение настройки DEFAULT_INDEX_TABLESPACE проекта, если оно указано, иначе db_tablespace модели. Если база данных не поддерживает «tablespace» для индексов, этот параметр будет проигнорирован.

default

Field.default

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

The default can’t be a mutable object (model instance, list, set, etc.), as a reference to the same instance of that object would be used as the default value in all new model instances. Instead, wrap the desired default in a callable. For example, if you want to specify a default dict for JSONField, use a function:

def contact_default():
    return {"email": "to1@example.com"}

contact_info = JSONField("ContactInfo", default=contact_default)

lambdas can’t be used for field options like default because they can’t be serialized by migrations. See that documentation for other caveats.

Для полей типа ForeignKey, которые ссылаются на объекты модели, значением по умолчанию должно быть значение поля на которое они ссылаются (pk, если не указан to_field), а не объект модели.

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

editable

Field.editable

При False, поле не будет отображаться в админке или любой другой ModelForm для модели. Такие поля также пропускаются при валидации модели. Значение по умолчанию – True.

error_messages

Field.error_messages

error_messages позволяет переопределить сообщения ошибок возвращаемых полем. Используйте словарь с ключами соответствующими необходимым ошибкам.

Ключи ошибок такие: null, blank, invalid, invalid_choice, unique и ``unique_for_date`. Дополнительные ошибки указаны для каждого типа поля ниже.

These error messages often don’t propagate to forms. See Определение error_messages.

help_text

Field.help_text

Подсказка, отображаемая под полем в интерфейсе администратора. Это полезно для описания поля, даже если модель не используется в форме.

Заметим, что, при отображении в форме, HTML-символы не экранируются. Это позволяет использовать HTML в help_text если вам необходимо. Например:

help_text="Please use the following format: <em>YYYY-MM-DD</em>."

Alternatively you can use plain text and django.utils.html.escape() to escape any HTML special characters. Ensure that you escape any help text that may come from untrusted users to avoid a cross-site scripting attack.

primary_key

Field.primary_key

При True это поле будет первичным ключом.

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

primary_key=True подразумевает null=False и unique=True. Модель может содержать только один первичный ключ.

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

unique

Field.unique

При True значение поля должно быть уникальным.

Этот параметр учитывается при сохранении в базу данных и при проверке данных в модели. Если вы попытаетесь сохранить повторное значение в поле с unique, будет вызвана ошибка django.db.IntegrityError методом save().

This option is valid on all field types except ManyToManyField and OneToOneField.

Заметим что, при unique равном True, не нужно указывать db_index, т.к. unique создает индекс.

unique_for_date

Field.unique_for_date

Этот параметр должен быть равен названию DateField или DateTimeField поля, для которого значение должно быть уникальным.

Например, если модель имеет поле title с unique_for_date="pub_date", тогда Django позволит сохранять записи только с уникальной комбинацией title и pub_date.

Если указать этот параметр для DateTimeField, только дата значения будет учитываться. Но при USE_TZ равном True, проверка будет выполнена в текущем часовом поясе во время сохранения объекта.

Проверка выполняется методом Model.validate_unique() во время валидации модели, не на уровне базы данных. Если unique_for_date содержит поля, которые не входят в ModelForm (например, поле было указанно в exclude или содержит editable=False), Model.validate_unique() не будет выполнять эту валидацию.

unique_for_month

Field.unique_for_month

Аналогично unique_for_date, но значение будет уникально для месяца.

unique_for_year

Field.unique_for_year

Аналогично unique_for_date и unique_for_month.

verbose_name

Field.verbose_name

Отображаемое имя поля. Если параметр не указан, Django самостоятельно создаст его используя имя атрибута поля, заменяя подчеркивание на пробелы. Смотрите раздел про отображаемые имена полей.

validators

Field.validators

Список проверок(«валидаторов») выполняемых для этого поля. Смотрите раздел о «валидаторах» для подробной информации.

Регистрация и загрузка операторов для фильтрации

Field предоставляет API для регистрации своих операторов фильтрации. Этот API позволяет добавить свои варианты фильтрации по полю.

Типы полей

AutoField

class AutoField(**options)

Автоинкрементное поле IntegerField. Используется для хранения ID. Скорее всего вам не придется использовать это поле, первичный ключ будет автоматически добавлен к модели. Смотрите Первичный ключ по умолчанию.

BigAutoField

class BigAutoField(**options)

A 64-bit integer, much like an AutoField except that it is guaranteed to fit numbers from 1 to 9223372036854775807.

BigIntegerField

class BigIntegerField(**options)

A 64-bit integer, much like an IntegerField except that it is guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The default form widget for this field is a TextInput.

BinaryField

class BinaryField(max_length=None, **options)

A field to store raw binary data. It can be assigned bytes, bytearray, or memoryview.

By default, BinaryField sets editable to False, in which case it can’t be included in a ModelForm.

BinaryField has one extra optional argument:

BinaryField.max_length

The maximum length (in characters) of the field. The maximum length is enforced in Django’s validation using MaxLengthValidator.

Злоупотребление BinaryField

Помните, хранение файлов в базе данных в 99% случаях - это плохой подход. Это поле не замена статическим файлам.

BooleanField

class BooleanField(**options)

Поле хранящее значение true/false.

The default form widget for this field is CheckboxInput, or NullBooleanSelect if null=True.

Значение по умолчанию для BooleanField None, если Field.default не указан.

CharField

class CharField(max_length=None, **options)

Строковое поле для хранения коротких или длинных строк.

Для большого количества текстовой информации используйте TextField.

Виджет по умолчанию для этого поля TextInput.

CharField принимает один дополнительный аргумент:

CharField.max_length

The maximum length (in characters) of the field. The max_length is enforced at the database level and in Django’s validation using MaxLengthValidator.

Примечание

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

DateField

class DateField(auto_now=False, auto_now_add=False, **options)

Дата, представленная в виде объекта datetime.date Python. Принимает несколько дополнительных параметров:

DateField.auto_now

Значение поля будет автоматически установлено в текущую дату при каждом сохранении объекта. Полезно для хранения времени последнего изменения. Заметим, что текущее время будет использовано всегда; это не просто значение по умолчанию, которое вы можете переопределить.

The field is only automatically updated when calling Model.save(). The field isn’t updated when making updates to other fields in other ways such as QuerySet.update(), though you can specify a custom value for the field in an update like that.

DateField.auto_now_add

Значение поля будет автоматически установлено в текущую дату при создании(первом сохранении) объекта. Полезно для хранения времени создания. Заметим, что текущее время будет использовано всегда; это не просто значение по-умолчанию, которое вы можете переопределить. По этому, даже если вы укажите значение для этого поля, оно будет проигнорировано. Если вы хотите изменять значения этого поля, используйте следующее вместо auto_now_add=True:

В форме поле будет представлено как :class:`~django.forms.TextInput с JavaScript календарем, и кнопкой «Сегодня». Содержит дополнительную ошибку invalid_date.

Опции auto_now_add, auto_now и default взаимоисключающие. Использование их вместе вызовет ошибку.

Примечание

При использовании auto_now или auto_now_add со значением True будут установлены параметры editable=False и blank=True.

Примечание

The auto_now and auto_now_add options will always use the date in the default timezone at the moment of creation or update. If you need something different, you may want to consider using your own callable default or overriding save() instead of using auto_now or auto_now_add; or using a DateTimeField instead of a DateField and deciding how to handle the conversion from datetime to date at display time.

DateTimeField

class DateTimeField(auto_now=False, auto_now_add=False, **options)

Дата и время, представленные объектом datetime.datetime Python. Принимает аналогичные параметры что и DateField.

Виджет по умолчанию в форме для этого поля - TextInput. Интерфейс администратора использует два виджета TextInput и JavaScript.

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options)

A fixed-precision decimal number, represented in Python by a Decimal instance. It validates the input using DecimalValidator.

Has two required arguments:

DecimalField.max_digits

Максимальное количество цифр в числе. Заметим, что это число должно быть больше или равно decimal_places.

DecimalField.decimal_places

Количество знаков после запятой.

Например, для хранения числа до 999 с двумя знаками после запятой, используйте:

models.DecimalField(..., max_digits=5, decimal_places=2)

Для хранения числа до миллиарда и 10 знаков после запятой:

models.DecimalField(..., max_digits=19, decimal_places=10)

Виджет по умолчанию в форме для этого поля - NumberInput, если localize равен False, иначе TextInput.

Примечание

For more information about the differences between the FloatField and DecimalField classes, please see FloatField vs. DecimalField. You should also be aware of SQLite limitations of decimal fields.

DurationField

class DurationField(**options)

Поля для хранения периодов времени - используется объект Python timedelta. Для PostgreSQL используется тип interval, а в Oracle – INTERVAL DAY(9) TO SECOND(6). Иначе используется bigint, в котором хранится количество микросекунд.

Примечание

Арифметика над DurationField работает в большинстве случаев. Однако, для всех баз данных, кроме PostgreSQL, арифметическое сравнение DurationField и DateTimeField работает не как ожидается.

EmailField

class EmailField(max_length=254, **options)

A CharField that checks that the value is a valid email address using EmailValidator.

FileField

class FileField(upload_to=None, max_length=100, **options)

Поле для загрузки файла.

Примечание

The primary_key argument isn’t supported and will raise an error if used.

Также принимается два дополнительных параметра:

FileField.upload_to

Этот атрибут позволяет указать каталог и название файла при его сохранении. Его можно использовать двумя способами. В обоих случаях значение будет передано в метод Storage.save().

If you specify a string value or a Path, it may contain strftime() formatting, which will be replaced by the date/time of the file upload (so that uploaded files don’t fill up the given directory). For example:

class MyModel(models.Model):
    # file will be uploaded to MEDIA_ROOT/uploads
    upload = models.FileField(upload_to='uploads/')
    # or...
    # file will be saved to MEDIA_ROOT/uploads/2015/01/30
    upload = models.FileField(upload_to='uploads/%Y/%m/%d/')

Если вы используйте бэкенд по умолчанию FileSystemStorage, значение будет добавлено к MEDIA_ROOT, чтобы сформировать путь в файловой системе для сохранения файла. Если вы используете другой бэкенд, обратитесь к его документации, чтобы узнать как он обрабатывает upload_to.

upload_to также принимается вызываемый объект, такой как функция, который будет вызван для получения пути к загруженному файлу, включая имя файла. Вызываемый объект должен принимать два обязательных аргумента, и возвращать путь в стиле Unix (с прямыми слэшами), который будет передан в систему хранения файлов(storage). Два аргумента это:

Аргумент Описание
instance

Экземпляр модели, для которой определено поле FileField. Точнее, это объект, для которого сохраняется текущий файл.

В большинстве случаев объект еще не будет сохранен в базу данных, и при использовании AutoField, первичный ключ объекта может быть пустым.

filename Оригинальное имя файла. Вы можете его учитывать, или проигнорировать при определении окончательного пути к файлу.

Например:

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return 'user_{0}/{1}'.format(instance.user.id, filename)

class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)
Changed in Django 3.0:

Support for pathlib.Path was added.

FileField.storage

Объект «storage», который отвечает за хранение и получение файлов. Смотрите Управление файлами для подробной информации.

Виджет форма для этого поля - ClearableFileInput.

Использование FileField или ImageField (смотрите ниже) требует некоторых дополнительных действий:

  1. В файле настроек необходимо определить MEDIA_ROOT, как полный путь к каталогу, куда Django должен сохранять файлы. (Для повышения производительности файлы не хранятся в базе данных.) Определить MEDIA_URL, который является URL-ом к этому каталогу и используется для создания URL-а к файлу. Убедитесь, что пользователь, от которого работает сервер, имеет права записи в этот каталог.
  2. Добавьте FileField или ImageField к модели, определите upload_to, чтобы указать Django в каком подкаталоге в MEDIA_ROOT должны быть сохранены файлы.
  3. Все, что будет сохранено в базе данных, это путь к файлу (относительно MEDIA_ROOT). Скорее всего вы будете использовать url предоставленную Django. Например, если ImageField назван mug_shot, вы можете получить URL к файлу в шаблоне используя {{ object.mug_shot.url }}.

Например, MEDIA_ROOT равен '/home/media', и upload_to равен 'photos/%Y/%m/%d'. '%Y/%m/%d' часть параметра upload_to это форматирование strftime(); '%Y' – год из 4-х цифр, '%m' – номер месяца из 2-х цифр и '%d' – число месяца из 2-х цифр. Если вы загрузили файл 15 января 2007, он будет сохранен в каталоге /home/media/photos/2007/01/15.

Если вам нужны название файла или его размер, используйте атрибуты name и size соответственно; больше информации о доступных методах и атрибутах вы найдете в справке о File и разделе документации Управление файлами.

Примечание

Процесс сохранения файла – часть процесса сохранения объекта, таким образом имя файла, сохраненного на диске, не будет доступно, пока объект не будет сохранен.

Чтобы получить URL к загруженному файлу, используйте атрибут url. При этом будет вызван метод url() класса Storage.

Заметим, что при загрузке файлов, вы должны обращать внимание, куда вы загружаете файлы и какие типы файлов загружаются, чтобы предотвратить возможные уязвимости в защите системы. Проверяйте все загружаемые файлы. Например, если вы разрешите загрузить файл без проверки в каталог, который обрабатывается сервером, кто-нибудь сможет загрузить CGI или PHP скрипт и выполнить его, посетив его URL на вашем сайте. Не допускайте это.

Также заметим что это относится и к HTML файлам, так как они могу быть выполнены в браузере(хоть и не на сервере), и нести угрозу XSS или CSRF атаки.

По-умолчанию, экземпляр FileField создается как колонка varchar в базе данных. Как и с другими полями, вы можете изменить максимальную длину, используя аргумент max_length.

FileField and FieldFile

class FieldFile

When you access a FileField on a model, you are given an instance of FieldFile as a proxy for accessing the underlying file.

The API of FieldFile mirrors that of File, with one key difference: The object wrapped by the class is not necessarily a wrapper around Python’s built-in file object. Instead, it is a wrapper around the result of the Storage.open() method, which may be a File object, or it may be a custom storage’s implementation of the File API.

In addition to the API inherited from File such as read() and write(), FieldFile includes several methods that can be used to interact with the underlying file:

Предупреждение

Two methods of this class, save() and delete(), default to saving the model object of the associated FieldFile in the database.

FieldFile.name

The name of the file including the relative path from the root of the Storage of the associated FileField.

FieldFile.size

The result of the underlying Storage.size() method.

FieldFile.url

read-only свойство для получения URL вызовом метода url() класса Storage.

FieldFile.open(mode='rb')

Opens or reopens the file associated with this instance in the specified mode. Unlike the standard Python open() method, it doesn’t return a file descriptor.

Since the underlying file is opened implicitly when accessing it, it may be unnecessary to call this method except to reset the pointer to the underlying file or to change the mode.

FieldFile.close()

Работает так же как и метод file.close() в Python и закрывает файл связанный с объектом.

FieldFile.save(name, content, save=True)

Этот метод принимает имя файла и содержимое и передает его в экземпляр класса «storage» этого поля, потом добавляет файл в модель. Если вы хотите самостоятельно добавить содержимое файла в поле FileField вашей модели, метод save() то, что вам нужно.

Принимает два аргумента: name – название файла, и content – содержимое файла. Дополнительный аргумент save указывает сохранять ли объект после изменения поля. По-умолчанию True.

Заметим, что аргумент content должен быть экземпляром django.core.files.File, а не встроенный объект файла в Python. Вы можете создать объект File из существующего объекта файла Python:

from django.core.files import File
# Open an existing file using Python's built-in open()
f = open('/path/to/hello.world')
myfile = File(f)

Или же создать из строки с содержимым файла:

from django.core.files.base import ContentFile
myfile = ContentFile("hello world")

Подробности в Управление файлами.

FieldFile.delete(save=True)

Удаляет файл связанный с объектом и очищает все атрибуты поля. Заметка: этот метод закрывает файл, если он был открыт во время вызова delete().

Дополнительный аргумент save указывает сохранять ли модель после удаления файла. По-умолчанию True.

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

FilePathField

class FilePathField(path=None, match=None, recursive=False, max_length=100, **options)

Поле CharField значение которого ограничено именем файла из определенного каталога. Принимает три дополнительных аргумента, первый из них обязателен:

FilePathField.path

Обязательно. Абсолютный путь к каталогу, из которого FilePathField принимает значение. Например: "/home/images".

path may also be a callable, such as a function to dynamically set the path at runtime. Example:

import os
from django.conf import settings
from django.db import models

def images_path():
    return os.path.join(settings.LOCAL_FILE_DIR, 'images')

class MyModel(models.Model):
    file = models.FilePathField(path=images_path)
Changed in Django 3.0:

path can now be a callable.

FilePathField.match

Необязательный. Регулярное выражение как строка, которое FilePathField использует как фильтр названий. Регулярное выражение применяется к названию файла, а не к полному пути. Например: "foo.*\.txt$", соответствует foo23.txt но отфильтрует bar.txt или foo23.gif.

FilePathField.recursive

Необязательный. Принимает True или False. По-умолчанию False. Определяет, должны ли быть включены подкаталоги path.

FilePathField.allow_files

Необязательный. Принимает True или False. По-умолчанию True. Определяет, должны ли быть включены указанные подкаталоги. Этот параметр или allow_folders должен быть True.

FilePathField.allow_folders

Необязательный. Принимает True или False. По-умолчанию False. Определяет, должны ли быть включены указанные подкаталоги. Этот параметр или allow_files должен быть True.

Конечно же можно использовать все аргумента вместе.

Следует помнить, что match применяется к имени файла, а не абсолютному пути. Таким образом:

FilePathField(path="/home/images", match="foo.*", recursive=True)

…распознает /home/images/foo.png, но не /home/images/foo/bar.png, т.к. match применяется к имени файла (foo.png и bar.png).

По-умолчанию, экземпляр FilePathField создается как колонка varchar в базе данных с максимальной длинной по умолчанию 100 символов. Как и с другими полями, вы можете изменить максимальную длину, используя аргумент max_length.

FloatField

class FloatField(**options)

Число с плавающей точкой представленное объектом float.

Виджет по умолчанию в форме для этого поля - NumberInput, если localize равен False, иначе TextInput.

FloatField или DecimalField

FloatField иногда путают с DecimalField. Хоть оба и представляют вещественные числа, они делают это по разному. FloatField использует тип float в Python, в то время как DecimalField использует тип Decimal. Подробности смотрите в документации Python модуля decimal.

ImageField

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)

Наследует все атрибуты и методы поля FileField, но также проверяет является ли загруженный файл изображением.

В дополнение к атрибутам поля FileField ImageField содержит также height и width.

Для определения этих аргументов ImageField принимает дополнительные аргументы:

ImageField.height_field

Имя поля, которому автоматически будет присвоено значение высоты изображения при каждом сохранении объекта.

ImageField.width_field

Имя поля, которому автоматически будет присвоено значение ширины изображения при каждом сохранении объекта.

Требуется библиотека Pillow.

По-умолчанию, экземпляр ImageField создается как колонка varchar в базе данных. Как и с другими полями вы можете изменить максимальную длину используя аргумент max_length.

Виджет форма для этого поля - ClearableFileInput.

IntegerField

class IntegerField(**options)

An integer. Values from -2147483648 to 2147483647 are safe in all databases supported by Django.

It uses MinValueValidator and MaxValueValidator to validate the input based on the values that the default database supports.

Виджет по умолчанию в форме для этого поля - NumberInput, если localize равен False, иначе TextInput.

GenericIPAddressField

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)

Адрес IPv4 или IPv6 в виде строки (например, 192.0.2.30 или 2a02:42fe::4). Форма использует виджет TextInput.

Преобразование адреса IPv6 происходит в соответствии с RFC 4291#section-2.2 раздел 2.2, включая рекомендации по форматированию IPv4 в параграфа 3 этого раздела, таких как ::ffff:192.0.2.0. Например, 2001:0::0:01 будет преобразован 2001::1, а ::ffff:0a0a:0a0a в ::ffff:10.10.10.10. Все символы будут преобразованы в нижний регистр.

GenericIPAddressField.protocol

Определяет формат IP адреса. Принимает значение 'both' (по умолчанию), 'IPv4' или 'IPv6'. Значение не чувствительно регистру.

GenericIPAddressField.unpack_ipv4

Преобразует адрес IPv4. Если эта опция установлена, адрес ::ffff::192.0.2.1 будет преобразован в 192.0.2.1. По-умолчанию отключена. Может быть использовано, если protocol установлен в 'both'.

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

NullBooleanField

class NullBooleanField(**options)

Like BooleanField with null=True. Use that instead of this field as it’s likely to be deprecated in a future version of Django.

PositiveIntegerField

class PositiveIntegerField(**options)

Как и поле IntegerField, но значение должно быть больше или равно нулю (0). Можно использовать значение от 0 до 2147483647. Значение 0 принимается для обратной совместимости.

PositiveSmallIntegerField

class PositiveSmallIntegerField(**options)

Как и поле PositiveIntegerField, но принимает значения в определенном диапазоне(зависит от типа базы данных). Для баз данных поддерживаемых Django можно использовать значения от 0 до 32767.

SlugField

class SlugField(max_length=50, **options)

Slug – газетный термин. «Slug» – это короткое название-метка, которое содержит только буквы, числа, подчеркивание или дефис. В основном используются в URL.

Как и для CharField, можно указать max_length (упомянутые особенности работы с различными типами баз данных актуальны). Если max_length не указан, Django будет использовать значение 50.

Устанавливает Field.db_index в True, если аргумент явно не указан.

Обычно значение SlugField создается на основе какого-то другого значения(например, название статьи). Это может работать автоматически в интерфейсе администрации благодаря параметру prepopulated_fields.

It uses validate_slug or validate_unicode_slug for validation.

SlugField.allow_unicode

При True поле может принимать Unicode символы кроме ASCII. Значение по умолчанию – False.

SmallAutoField

class SmallAutoField(**options)
New in Django 3.0.

Like an AutoField, but only allows values under a certain (database-dependent) limit. Values from 1 to 32767 are safe in all databases supported by Django.

SmallIntegerField

class SmallIntegerField(**options)

Как и поле IntegerField, но принимает значения в определенном диапазоне(зависит от типа базы данных). Для баз данных поддерживаемых Django можно использовать значения от -32768 до 32767.

TextField

class TextField(**options)

Большое текстовое поле. Форма использует виджет Textarea.

Если указать атрибут max_length, это повлияет на поле, создаваемое виджетом Textarea. Но не учитывается на уровне модели или базы данных. Для этого используйте CharField.

TimeField

class TimeField(auto_now=False, auto_now_add=False, **options)

Время, представленное объектом datetime.time Python. Принимает те же аргументы, что и DateField.

Форма использует виджет TextInput. Интерфейс администратора также использует немного JavaScript.

URLField

class URLField(max_length=200, **options)

A CharField for a URL, validated by URLValidator.

Виджет по умолчанию для этого поля TextInput.

Как подкласс CharField URLField принимает необязательный аргумент max_length. Если вы не укажите max_length, будет использовано значение – 200.

UUIDField

class UUIDField(**options)

Поля для сохранения UUID. Использует класс Python UUID. Для PostgreSQL используется тип uuid, иначе char(32).

UUID является хорошей альтернативой AutoField с primary_key. База данных не сгенерирует UUID за вас, по этому следует использовать default:

import uuid
from django.db import models

class MyUUIDModel(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    # other fields

Обратите внимание, указана функция (без скобок) в default, а не объект UUID.

Lookups on PostgreSQL

Using iexact, contains, icontains, startswith, istartswith, endswith, or iendswith lookups on PostgreSQL don’t work for values without hyphens, because PostgreSQL stores them in a hyphenated uuid datatype type.

Поля отношений

Django предоставляет набор полей для определения связей между моделями.

ForeignKey

class ForeignKey(to, on_delete, **options)

A many-to-one relationship. Requires two positional arguments: the class to which the model is related and the on_delete option.

Для создания рекурсивной связи – объект со связью многое-к-одному на себя – используйте models.ForeignKey('self', on_delete=models.CASCADE).

Если вам необходимо добавить связь на модель, которая еще не определена, вы можете использовать имя модели вместо класса:

from django.db import models

class Car(models.Model):
    manufacturer = models.ForeignKey(
        'Manufacturer',
        on_delete=models.CASCADE,
    )
    # ...

class Manufacturer(models.Model):
    # ...
    pass

Relationships defined this way on abstract models are resolved when the model is subclassed as a concrete model and are not relative to the abstract model’s app_label:

products/models.py
from django.db import models

class AbstractCar(models.Model):
    manufacturer = models.ForeignKey('Manufacturer', on_delete=models.CASCADE)

    class Meta:
        abstract = True
production/models.py
from django.db import models
from products.models import AbstractCar

class Manufacturer(models.Model):
    pass

class Car(AbstractCar):
    pass

# Car.manufacturer will point to `production.Manufacturer` here.

Для связи на модель из другого приложения используйте название модели и приложения. Например, если модель Manufacturer находится в приложении production, используйте:

class Car(models.Model):
    manufacturer = models.ForeignKey(
        'production.Manufacturer',
        on_delete=models.CASCADE,
    )

This sort of reference, called a lazy relationship, can be useful when resolving circular import dependencies between two applications.

В базе данных автоматом создается индекс для ForeignKey. Можно указать для db_index False, чтобы отключить такое поведение. Это может пригодиться, если внешний ключ используется для согласованности данных, а не объединения(join) в запросах, или вы хотите самостоятельно создать альтернативный индекс или индекс на несколько колонок.

Представление в базе данных

За кулисами, Django добавляет "_id" к названию поля для создания названия колонки. В примере выше, таблица для модели Car будет содержать колонку manufacturer_id. (Такое поведение можно изменить, указав аргумент db_column) Хотя, ваш код никогда не должен использовать названий колонок, если только вы не используете чистый SQL. Вы всегда будете использовать названия полей модели.

Параметры

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

ForeignKey.on_delete

Когда объект, на который ссылается ForeignKey, удаляется, Django эмулирует поведение SQL правил, указанных в аргументе on_delete. Например, если ваше поле ForeignKey может содержать NULL и вы хотите, чтобы оно устанавливалось в NULL после удаления связанного объекта:

user = models.ForeignKey(
    User,
    models.SET_NULL,
    blank=True,
    null=True,
)

on_delete doesn’t create a SQL constraint in the database. Support for database-level cascade options may be implemented later.

Возможные значения для on_delete находятся в django.db.models:

  • CASCADE

    Каскадное удаление. Django эмулирует поведение SQL правила ON DELETE CASCADE и так же удаляет объекты, связанные через ForeignKey.

    Model.delete() isn’t called on related models, but the pre_delete and post_delete signals are sent for all deleted objects.

  • PROTECT

    Препятствует удалению связанного объекта вызывая исключение django.db.models.ProtectedError`(подкласс :exc:`django.db.IntegrityError).

  • SET_NULL

    Устанавливает ForeignKey в NULL; возможно только если null равен True.

  • SET_DEFAULT

    Устанавливает ForeignKey в значение по умолчанию; значение по-умолчанию должно быть указано для ForeignKey.

  • SET()

    Устанавливает ForeignKey в значение указанное в SET(). Если указан выполняемый объект, результат его выполнения. Вызываемый объект можно использовать, чтобы избежать запросов во время импорта models.py:

    from django.conf import settings
    from django.contrib.auth import get_user_model
    from django.db import models
    
    def get_sentinel_user():
        return get_user_model().objects.get_or_create(username='deleted')[0]
    
    class MyModel(models.Model):
        user = models.ForeignKey(
            settings.AUTH_USER_MODEL,
            on_delete=models.SET(get_sentinel_user),
        )
    
  • DO_NOTHING

    Ничего не делать. Если используемый тип базы данных следит за целостностью связей, будет вызвано исключение IntegrityError, за исключением, когда вы самостоятельно добавите SQL правило ON DELETE для поля таблицы.

ForeignKey.limit_choices_to

Ограничивает доступные значения для поля при создании ModelForm или в админке (по умолчанию можно выбрать любой объект связанной модели). Можно передать словарь, объект Q или функцию, которая возвращает словарь или объект Q.

Например:

staff_member = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    limit_choices_to={'is_staff': True},
)

указывает полю ModelForm показывать только объекты Users, которые соответствуют is_staff=True. Может быть полезно в админке.

Указание функции может быть полезно, если используется объект Python datetime для фильтрации. Например:

def limit_pub_date_choices():
    return {'pub_date__lte': datetime.date.utcnow()}

limit_choices_to = limit_pub_date_choices

Вместо словаря можете использовать объект Q или функцию, которая возвращает такой объект, для создания сложных запросов. Однако, если limit_choices_to объект Q, он будет использован в интерфейсе администратора, только если поле не находится в raw_id_fields класса ModelAdmin для этой модели.

Примечание

Если используется функция для limit_choices_to, она будет вызываться при каждом создании формы. Также она может быть вызвана при валидации модели, например, командой или админкой. Админка может вызывать эту функцию несколько раз при проверке данных.

ForeignKey.related_name

Название, используемое для обратной связи от связанной модели. Также значение по умолчанию для related_query_name (название обратной связи используемое при фильтрации результата запроса). Ищите подробности и примеры в разделе о связанных объектах. Заметим, что вы должны определить этот параметр для поля в абстрактной модели; при этом можно использовать некоторые дополнительные возможности.

Если вы не хотите, чтобы Django создавал обратную связь, установите related_name в '+' или добавьте в конце '+'. Например, такой код создаст связь, но не добавит обратную связь в модель User:

user = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    related_name='+',
)
ForeignKey.related_query_name

The name to use for the reverse filter name from the target model. It defaults to the value of related_name or default_related_name if set, otherwise it defaults to the name of the model:

# Declare the ForeignKey with related_query_name
class Tag(models.Model):
    article = models.ForeignKey(
        Article,
        on_delete=models.CASCADE,
        related_name="tags",
        related_query_name="tag",
    )
    name = models.CharField(max_length=255)

# That's now the name of the reverse filter
Article.objects.filter(tag__name="important")

Like related_name, related_query_name supports app label and class interpolation via some special syntax.

ForeignKey.to_field

The field on the related object that the relation is to. By default, Django uses the primary key of the related object. If you reference a different field, that field must have unique=True.

ForeignKey.db_constraint

Указывает создавать ли «constraint» для внешнего ключа в базе данных. По умолчанию True и в большинстве случает это то, что вам нужно. Указав False вы рискуете целостностью данных. Некоторые ситуации, когда вам может быть это необходимо:

  • Вам досталась в наследство нецелостная база данных
  • Вы используете шардинг базы данных.

При False, если связанный объект не существует, при обращении к нему будет вызвано исключение DoesNotExist.

ForeignKey.swappable

Управляет поведением миграций, если ForeignKey ссылается на подменяемую(swappable) модель. При True - значение по умолчанию - если ForeignKey ссылается на модель, указанную через settings.AUTH_USER_MODEL (или другую настройку, определяющую какую модель использовать), связь в миграции будет использовать настройку, а не саму модель.

Вам может понадобится значение False только, если связь должна указывать на какую-то конкретную модель, игнорируя настройку - например, если это модель профиля пользователя для какой-то конкретной модели пользователя и не будет работать с любой моделью из настройки.

Setting it to False does not mean you can reference a swappable model even if it is swapped out - False means that the migrations made with this ForeignKey will always reference the exact model you specify (so it will fail hard if the user tries to run with a User model you don’t support, for example).

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

ManyToManyField

class ManyToManyField(to, **options)

Связь многие-ко-многим. Принимает позиционный аргумент: класс связанной модели. Работает так же как и ForeignKey, включая рекурсивную и ленивую связь.

Связанные объекты могут быть добавлены, удалены или созданы с помощью RelatedManager.

Представление в базе данных

Behind the scenes, Django creates an intermediary join table to represent the many-to-many relationship. By default, this table name is generated using the name of the many-to-many field and the name of the table for the model that contains it. Since some databases don’t support table names above a certain length, these table names will be automatically truncated and a uniqueness hash will be used, e.g. author_books_9cdf. You can manually provide the name of the join table using the db_table option.

Параметры

ManyToManyField принимает дополнительные аргументы – все не обязательны – которые определяют как должна работать связь.

ManyToManyField.related_name

Аналогично ForeignKey.related_name.

ManyToManyField.related_query_name

Аналогично ForeignKey.related_query_name.

ManyToManyField.limit_choices_to

Аналогично ForeignKey.limit_choices_to.

limit_choices_to``не работает для ``ManyToManyField переопределенной через through промежуточной моделью.

ManyToManyField.symmetrical

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

from django.db import models

class Person(models.Model):
    friends = models.ManyToManyField("self")

Загружая эту модель Django определяет, что она содержит ManyToManyField указывающее на себя, и не добавляет атрибут person_set классу модели Person. Вместо этого подразумевается, что :class:`ManyToManyField`симметрично – то есть, если я твой друг, то и ты мне друг.

Если вам не нужна симметричность для связи многое-ко-многим к self, установите symmetrical в False. Это заставит Django добавить дескриптор для обратной связи, позволяя ManyToManyField быть не симметричным.

Changed in Django 3.0:

Specifying symmetrical=True for recursive many-to-many relationships using an intermediary model was allowed.

ManyToManyField.through

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

Обычно используют для хранения дополнительных данных.

Примечание

Recursive relationships using an intermediary model and defined as symmetrical (that is, with symmetrical=True, which is the default) can’t determine the reverse accessors names, as they would be the same. You need to set a related_name to at least one of them. If you’d prefer Django not to create a backwards relation, set related_name to '+'.

Если вы не указали through модель, вы все равно может обратиться к неявно промежуточной модели, которая была автоматически создана. Она содержит три поля, связывающие модели.

Если связанные модели разные, создаются следующие поля:

  • id: первичный ключ для связи.
  • <containing_model>_id: id модели, которая содержит поле ManyToManyField.
  • <other_model>_id: id модели, на которую ссылается ManyToManyField.

Если ManyToManyField ссылается на одну и ту же модель, будут созданы поля:

  • id: первичный ключ для связи.
  • from_<model>_id: id объекта основной модели (исходный объект).
  • to_<model>_id: id объекта, на который указывает связь (целевой объект).

Этот класс может использоваться для получения связей.

ManyToManyField.through_fields

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

from django.db import models

class Person(models.Model):
    name = models.CharField(max_length=50)

class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(
        Person,
        through='Membership',
        through_fields=('group', 'person'),
    )

class Membership(models.Model):
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    inviter = models.ForeignKey(
        Person,
        on_delete=models.CASCADE,
        related_name="membership_invites",
    )
    invite_reason = models.CharField(max_length=64)

Membership содержит два внешних ключа на Person (person и inviter). В таком случае Django не знает какой ключ использовать для создания связи. В таком случае необходимо явно указать Django, какой внешний ключ правильный, используя параметр through_fields, как в примере выше.

through_fields принимает двух-элементный кортеж ('field1', 'field2'), где field1 – название внешнего ключа, который ссылается на модель, которая содержит ManyToManyField (в нашем примере group), а field2 – внешний ключ, который ссылается на целевую модель (в нашем примере person).

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

ManyToManyField.db_table

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

ManyToManyField.db_constraint

Указывает создавать ли «constraint» для внешних ключей в промежуточной таблице в базе данных. По умолчанию True и в большинстве случает это то, что вам нужно. Указав False вы рискуете целостностью данных. Некоторые ситуации, когда вам может быть это необходимо:

  • Вам досталась в наследство нецелостная база данных
  • Вы используете шардинг базы данных.

Нельзя указать db_constraint и through одновременно.

ManyToManyField.swappable

Управляет поведением миграций, если ManyToManyField ссылается на подменяемую(swappable) модель. При True - значение по умолчанию - если ManyToManyField ссылается на модель, указанную через settings.AUTH_USER_MODEL (или другую настройку, определяющую какую модель использовать), связь в миграции будет использовать настройку, а не саму модель.

Вам может понадобится значение False только, если связь должна указывать на какую-то конкретную модель, игнорируя настройку - например, если это модель профиля пользователя для какой-то конкретной модели пользователя и не будет работать с любой моделью из настройки.

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

ManyToManyField не поддерживает validators.

null не влияет на работу поля т.к. нет способа сделать связь обязательной на уровне базы данных.

OneToOneField

class OneToOneField(to, on_delete, parent_link=False, **options)

Связь один-к-одному. Работает так же, как и ForeignKey с unique=True, но «обратная» связь возвращает один объект.

В основном применяется как первичный ключ модели, которая «расширяет» другую модель. Например, Multi-table наследование работает через неявное добавление связи один-к-одному от дочерней модели к родительской.

Принимает обязательный позиционный аргумент: класс связанной модели. Работает так же как и ForeignKey, включая рекурсивную и «ленивую» связь.

If you do not specify the related_name argument for the OneToOneField, Django will use the lowercase name of the current model as default value.

В примере ниже:

from django.conf import settings
from django.db import models

class MySpecialUser(models.Model):
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
    )
    supervisor = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='supervisor_of',
    )

модель User будет содержать следующие атрибуты:

>>> user = User.objects.get(pk=1)
>>> hasattr(user, 'myspecialuser')
True
>>> hasattr(user, 'supervisor_of')
True

При получении связанного объекта через обратную связь, если такой объект не существует, будет вызвано исключение DoesNotExist. Например, если пользователь не имеет соответствующего экземпляра в MySpecialUser:

>>> user.supervisor_of
Traceback (most recent call last):
    ...
DoesNotExist: User matching query does not exist.

Также OneToOneField принимает все дополнительные параметры принимаемые ForeignKey, и еще один дополнительный:

При True и связанной модели, которая наследуется от другой модели, определяет, что должна сохраняться связь на родительскую модель, а не поле OneToOneField дочерней модели, которое используется для организации наследования моделей.

Смотрите примеров использования OneToOneField в Связь один к одному.

Справочник по полям модели

class Field

Field is an abstract class that represents a database table column. Django uses fields to create the database table (db_type()), to map Python types to database (get_prep_value()) and vice-versa (from_db_value()).

Таким образом поле является фундаментальной частью различных API Django, в частности, models и querysets.

В модели экземпляр поля добавляется как атрибут класса и представляет определенное поле таблицы, смотрите Модели. Оно содержит атрибуты, такие как null и unique, и методы, которые Django используется для преобразования значения поля в значение в базе данных.

Field – дочерний класс RegisterLookupMixin, что позволяет регистрировать Transform и Lookup, чтобы использовать в QuerySet (например, field_name__exact="foo"). Все встроенные фильтры зарегистрированы по умолчанию.

Все встроенные поля Django, например CharField, наследуются от Field. Если вы хотите создать свое поле, можно унаследоваться от любого встроенного поля, или от Field. Подробности смотрите в Создание собственных полей для модели.

description

Читабельное описание поля, например, для приложения django.contrib.admindocs.

Может использовать форматирование:

description = _("String (up to %(max_length)s)")

Аргументы будут подставляется из значений __dict__ поля.

descriptor_class
New in Django 3.0.

A class implementing the descriptor protocol that is instantiated and assigned to the model instance attribute. The constructor must accept a single argument, the Field instance. Overriding this class attribute allows for customizing the get and set behavior.

To map a Field to a database-specific type, Django exposes several methods:

get_internal_type()

Возвращает текстовое название типа поля для использования в бэкендах баз данных. По умолчанию возвращает название класса.

Смотрите Эмуляция встроенных полей, как использовать в собственных полях модели.

db_type(connection)

Возвращает тип поля в базе данных Field, учитывая connection.

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

rel_db_type(connection)

Returns the database column data type for fields such as ForeignKey and OneToOneField that point to the Field, taking into account the connection.

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

Существует три основных ситуации, когда Django используется преобразование типа поля:

  • при запросе как базе данных (значение Python -> значение бэкенда базы данных)
  • при загрузке данных из базы данных (значение бэкенда базы данных -> значение Python)
  • при сохранении в базу данных (значение Python -> значение бэкенда базы данных)

При запросе используются методы get_db_prep_value() и get_prep_value():

get_prep_value(value)

value – значение атрибута поля модели. Метод должен вернуть значение, которое можно использовать как параметр в запросе.

Смотрите Преобразование объектов Python в значения в запросе.

get_db_prep_value(value, connection, prepared=False)

Преобразует value в значение для бэкенда базы данных. По умолчанию возвращает value, если prepared=True, иначе – результат get_prep_value().

Смотрите Преобразование значения из запроса в значение базы данных.

При загрузке данных используется from_db_value():

from_db_value(value, expression, connection)

Преобразует значение из базы данных в объект Python. Метод обратный get_prep_value().

Для большинства встроенных полей этот метод не используется т.к. бэкенд базы данных возвращает уже правильный объект Python, или же бэкенд сам выполняет необходимые преобразования.

Смотрите Преобразование значений базы данных в объекты Python.

Примечание

Для повышения производительности поля, которые не используют from_db_value, не содержат пустую реализацию этого метода (все поля Django). По этому нет необходимости вызывать super в вашем методе.

При сохранении используются методы pre_save() и get_db_prep_save():

get_db_prep_save(value, connection)

Аналогичен get_db_prep_value(), но используется при сохранении значения в базу данных. По умолчанию возвращает результат get_db_prep_value().

pre_save(model_instance, add)

Метод вызывается перед get_db_prep_save(), чтобы подготовить значение перед сохранением (например, при DateField.auto_now).

model_instance – объект модели, к которому принадлежит поле, add – указывает сохраняется ли объект первый раз в базу данных.

Должен вернуть значение соответствующего этому полю атрибута model_instance. Название атрибута можно получить из self.attname (устанавливается Field).

Смотрите Обработка данных перед сохранением.

Поля часто принимает значения разных типов из сериализатора, или формы

to_python(value)

Преобразует значение в правильный объект Python. Выполняет действия обратные value_to_string(), и вызывается в clean().

Смотрите Преобразование значений базы данных в объекты Python.

Кроме сохранения в базу данных, поле также должно знать как сериализовать свое значение:

value_from_object(obj)

Returns the field’s value for the given model instance.

This method is often used by value_to_string().

value_to_string(obj)

Преобразует obj в строку. Используется при сериализации значения поля.

Смотрите Преобразование значения поля для сериалайзера.

При использовании django.forms.ModelForm Field должно указать, какое поле формы необходимо использовать для его представления в форме:

formfield(form_class=None, choices_form_class=None, **kwargs)

Возвращает django.forms.Field поля модели для ModelForm.

By default, if both form_class and choices_form_class are None, it uses CharField. If the field has choices and choices_form_class isn’t specified, it uses TypedChoiceField.

Смотрите Определение поля формы для поля модели.

deconstruct()

Возвращает 4-х элементный кортеж с информацией, как воссоздать поле:

  1. Название поля в модели.
  2. Путь для импорта класса поля (например, "django.db.models.IntegerField"). Должен возвращаться максимально переносимый между платформами и версиями вариант.
  3. Список позиционных аргументов.
  4. Словарь именованных аргументов.

Этот метод должен быть добавлен полям, созданным до 1.7, для использования Миграции.

Атрибуты поля

Каждый экземпляр Field содержит атрибуты, определяющие поведение поля. Используйте эти атрибуты вместо проверки isinstance, если вам необходимо написать код, который зависит от поведения поля. Эти атрибуты можно использовать совместно с Model._meta API, чтобы проверять поля конкретного типа. Собственные поля модели должны определять эти атрибуты.

Атрибуты поля

Field.auto_created

Флаг, который указывает было ли поле создано автоматически, например OneToOneField при наследовании моделей.

Field.concrete

Флаг, который указывает представлено ли поле колонкой в таблице в базе данных.

Field.hidden

Флаг, который указывает, что поле скрыто и используется для работы другого не скрытого поля (например, поля content_type и object_id используются для работы GenericForeignKey). Флаг hidden используется, чтобы выделить публичные поля модели из всех полей.

Примечание

Options.get_fields() не возвращает скрытые поля. Передайте include_hidden=True, чтобы получить все поля.

Field.is_relation

Флаг, который указывает, ссылается ли поле на другие модели (например, ForeignKey, ManyToManyField, OneToOneField, и т.д.).

Field.model

Содержит модель, в которой это поле определено. Если поле определено в родительском классе, model будет ссылаться на этот класс, а не класс экземпляра модели.

Атрибуты связывающих полей

Атрибуты, определяющие связь поля. Эти атрибуты присутствуют во всех полях, однако, только для связывающих полей(Field.is_relation=True) они содержат булевы значения(а не None).

Field.many_to_many

Флаг, который содержит True, если поле содержит связь многие-ко-многим, иначе False. Единственное поле Django, которое содержит True – это ManyToManyField.

Field.many_to_one

Флаг, который содержит True, если поле содержит связь многие-к-одному, такие как ForeignKey, иначе False.

Field.one_to_many

Флаг, который содержит True, если поле содержит связь один-ко-многим, такие как GenericRelation или обратная связь ForeignKey, иначе False.

Field.one_to_one

Флаг, который содержит True, если поле содержит связь один-к-одному, такие как OneToOneField, иначе False.

Field.related_model

Points to the model the field relates to. For example, Author in ForeignKey(Author, on_delete=models.CASCADE). The related_model for a GenericForeignKey is always None.