Ссылка на поле модели

Этот документ содержит все ссылки на API Field , включая детали, которые Django предоставляет в отношении опций и типов полей .

Смотрите также

Если встроенные поля не помогают , вы можете попробовать django-localflavor ( документация ), которая содержит фрагменты кода, полезные для конкретной страны или культуры.

Также можно легко написать собственное настраиваемое поле шаблона .

Заметка

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

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

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

null

Field.null

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

Избегайте использования null для текстовых полей, таких как CharField или TextField . Текстовое поле с null=True подразумевает, что есть два возможных значения, означающих «нет данных»: NULL и пустая строка. В большинстве случаев наличие двух возможных значений, указывающих на отсутствие данных, является избыточным. В Django принято использовать пустую строку, а не NULL . Исключение составляют случаи, когда в поле CharField есть и unique=True и blank=True . В этом случае null=True необходимо избегать нарушений уникальных ограничений при сохранении нескольких объектов с пустыми значениями.

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

Заметка

При использовании Oracle Database Engine всегда NULL сохраняется значение, указывающее, что строка пуста, независимо от значения этого атрибута.

blank

Field.blank

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

Обратите внимание, что это отличается от null . null относится исключительно к базе данных, а blank относится к валидации. Когда поле есть blank=True , проверка формы позволяет вводить пустые значения. Если в поле есть blank=False , поле необходимо заполнить.

choices

Field.choices

Сама последовательность состоит из итерируемых бинарных кортежей (например ) , представляющих возможные варианты для этой области. Если варианты предоставлены, они контролируются проверкой шаблона, и компонент формы по умолчанию будет представлять собой раскрывающийся список, содержащий эти варианты, а не стандартное текстовое поле ввода.[(A, B), (A, B) ...]

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

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}

Хотя можно определить список вариантов вне класса модели и затем ссылаться на него, определение вариантов и их меток внутри класса модели сохраняет вся эта информация с классом, который ею управляет, а также упрощение ссылки на эти варианты (например, будет Student.SOPHOMORE работать везде, где Student была импортирована модель ).

Вы также можете расположить возможные варианты выбора в именованных группах, которые можно использовать в организационных целях:

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

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

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

Обратите внимание, что эти варианты могут быть любой последовательностью, не обязательно списком или кортежем. Это позволяет вам динамически создавать список вариантов. Но если вы начнете настраивать атрибут так, choices чтобы он был динамическим, скорее всего, имеет смысл использовать настоящую таблицу базы данных, которая его содержит ForeignKey . choices предназначен для статических данных, которые не часто меняются, если вообще когда-либо.

Заметка

Новая миграция производится каждый раз при изменении порядка выбора choices .

За исключением случаев, когда blank=False определено для поля с содержимым default , содержащая метка "---------" будет добавлена ​​в список выбора. Чтобы переопределить это поведение, добавьте кортеж в choices контейнер None . Например, . Также можно использовать пустую строку вместо того, когда это разумно, например, для поля .(None, 'Votre chaîne à afficher') None CharField

Перечислительные типы

Кроме того, Django предоставляет перечислительные типы, которые вы можете наследовать для краткого определения вариантов:

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 {
            self.YearInSchool.JUNIOR,
            self.YearInSchool.SENIOR,
        }

Они работают так же, как и enum стандартные библиотеки Python, но с некоторыми изменениями:

  • Значения членов Enum представляют собой кортежи параметров, которые используются при построении конкретного типа данных. «Django поддерживает добавление дополнительной строки в конце кортежа, чтобы она служила понятным для человека именем», - говорит он label . Это label может быть отложенная переводимая строка. Таким образом, в большинстве случаев значение члена будет двоичным кортежем . См. Ниже пример подкласса выбора, использующего более сложный тип данных. Если предоставленное значение не является кортежем или последний элемент не является строкой (возможно, отложенной), часть - это ref: автоматически сгенерированный <field-choices-enum-auto-label> из имени члена ,(valeur, label) label
  • .label К значениям добавляется свойство , чтобы вернуть удобочитаемое имя.
  • Ряд пользовательских свойств добавляется в перечисленных классы - .choices , .labels , .values , и .names - для облегчения доступа к спискам отдельных частей перечисления. Используйте значение .choices для передачи в качестве параметра choices в определении поля.
  • Использование enum.unique() обязано быть уверенным, что одно и то же значение не может быть определено более одного раза. Это маловероятно при выборе определения поля.

Следует отметить , что использование YearInSchool.SENIOR , YearInSchool['SENIOR'] или YearInSchool('SR') для доступа или поиска членов перечисления произведений , как хотелось бы , как свойства .name и .value членов.

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

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

Поскольку случай, когда перечисляемые значения являются целыми числами, чрезвычайно распространен, Django предоставляет класс IntegerChoices . например

class Card(models.Model):

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

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

Также можно использовать функциональный API Enum с ограничением, что метки label создаются автоматически, как объяснялось ранее.

>>> 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')]

Если вам нужно поддерживать конкретный тип данных, отличный от int или str , вы можете наследовать от Choices желаемого типа данных, например, используя date для поля 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)'

Следует учитывать несколько ограничений:

  • Перечислимые типы не поддерживают именованные группы .

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

    class Answer(models.IntegerChoices):
        NO = 0, _('No')
        YES = 1, _('Yes')
    
        __empty__ = _('(Unknown)')
    
Новое в Django 3.0:

Классы TextChoices , IntegerChoices и Choices были добавлены.

db_column

Field.db_column

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

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

db_index

Field.db_index

Итак True , для этого поля будет создан индекс базы данных.

db_tablespace

Field.db_tablespace

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

default

Field.default

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

По умолчанию не может быть изменяемым объектом (модель экземпляр list , и set т.д.), в качестве ссылки на объекте Самого экземпляр , который будет использоваться в качестве значения по умолчанию во всех новых экземплярах модели. Вместо этого оберните желаемое значение по умолчанию в вызываемый. Например, если вы хотите указать значение dict по умолчанию для JSONField , используйте функцию:

def contact_default():
    return {"email": "[email protected]"}

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

Функции lambda нельзя использовать в качестве параметров поля, например, default потому что они не могут быть сериализованы посредством миграции . См. Эту последнюю документацию для других предостережений.

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

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

editable

Field.editable

Да False , поле не будет отображаться ни в администрировании Django, ни в каких-либо формах на основе ModelForm . Это также будет опущено на этапе проверки модели . По умолчанию это True .

error_messages

Field.error_messages

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

Основные сообщения об ошибках включают в себя null , blank , invalid , invalid_choice , unique и unique_for_date . Дополнительные ключи сообщений об ошибках определены для каждого поля в разделе Типы полей ниже.

Эти сообщения об ошибках часто не передаются в формы. См. Замечания по сообщениям об ошибках модели .

help_text

Field.help_text

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

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

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

Кстати, вы можете использовать обычный текст и django.utils.html.escape() экранировать любой специальный символ HTML. Обязательно избегайте текста справки от ненадежных пользователей, чтобы избежать атак с использованием межсайтовых сценариев.

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() шаблона вызовет исключение .

Эта опция действительна для всех типов элементов управления, кроме ManyToManyField и 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

классAutoField ( ** варианты )

Поле IntegerField , значение которого автоматически увеличивается по сравнению с доступными идентификаторами. Обычно вам не нужно использовать это поле напрямую; поле первичного ключа автоматически добавляется в модель, если оно не определено явно. См. Автоматические поля первичного ключа .

BigAutoField

классBigAutoField ( ** варианты )

64-битное целое число, похожее на единицу, AutoField за исключением того, что оно гарантирует охват чисел от 1 до 9223372036854775807 .

BigIntegerField

классBigIntegerField ( ** варианты )

64-битное целое число, похожее на единицу, IntegerField за исключением того, что оно гарантирует охват чисел от -9223372036854775808 до 9223372036854775807 . Компонент формы по умолчанию для этого поля - NumberInput .

BinaryField

classBinaryField ( max_length = None , ** варианты )

Поле для хранения необработанных двоичных данных. Он может получать данные типа bytes , bytearray или memoryview .

По умолчанию BinaryField устанавливается editable значение False , и в этом случае его нельзя включить в форму ModelForm .

BinaryField имеет дополнительный необязательный параметр:

BinaryField.max_length

Максимальный размер (в символах) поля. Эта максимальная длина контролируется проверкой Django с помощью MaxLengthValidator .

Неправильное использование BinaryField

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

BooleanField

классBooleanField ( ** варианты )

Поле истина / ложь.

Компонент формы по умолчанию для этого поля - один CheckboxInput или NullBooleanSelect около того null=True .

Значение по умолчанию BooleanField - None когда Field.default не определено.

CharField

classCharField ( max_length = None , ** варианты )

Поле для символьных строк, коротких или длинных.

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

Компонент формы по умолчанию для этого поля - TextInput .

CharField имеет дополнительный обязательный параметр:

CharField.max_length

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

Заметка

Если вы пишете приложение, которое необходимо переносить между несколькими ядрами баз данных, имейте в виду, что max_length для некоторых из этих механизмов существуют ограничения . Дополнительные сведения см. В Примечаниях к ядру СУБД .

DateField

classDateField ( auto_now = False , auto_now_add = False , ** параметры )

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

DateField.auto_now

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

Автоматическое обновление этого поля происходит только при звонке Model.save() . Поле не обновляется при обновлении других полей другими способами, например QuerySet.update() , например , хотя можно явно указать значение для этого поля во время такого обновления.

DateField.auto_now_add

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

Компонент формы по умолчанию для этого поля - DateInput . Интерфейс администрирования добавляет календарь JavaScript, а также ярлык «Сегодня». Содержит дополнительный ключ сообщения об ошибке invalid_date .

Варианты auto_now_add , auto_now и default взаимно исключают друг друга. Любая комбинация этих опций приведет к ошибке.

Заметка

В текущей реализации, если включены auto_now или auto_now_add , автоматически устанавливаются следующие параметры поля: editable=False и blank=True .

Заметка

Параметры auto_now и auto_now_add всегда используют дату в часовом поясе по умолчанию при создании или обновлении. Если у вас другие потребности, вы можете рассмотреть возможность использования собственной функции по умолчанию или функции переопределения save() вместо использования auto_now или auto_now_add . Или использовать поле DateTimeField вместо поля DateField и решить, как обрабатывать преобразование времени / даты в дату, когда она отображается.

DateTimeField

classDateTimeField ( auto_now = False , auto_now_add = False , ** параметры )

Дата и время, представленные в Python экземпляром datetime.datetime . Это поле принимает те же дополнительные параметры, что и поле DateField .

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

DecimalField

classDecimalField ( max_digits = None , decimal_places = None , ** параметры )

Десятичное число фиксированного размера, представленное в Python экземпляром Decimal . Записи проверяются с помощью DecimalValidator .

Для этого требуются два обязательных параметра :

DecimalField.max_digits

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

DecimalField.decimal_places

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

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

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

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

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

Компонент формы по умолчанию для этого поля - NumberInput когда localize есть False , или TextInput наоборот.

Заметка

Для получения более подробной информации о различиях между FloatField и классами DecimalField , см FloatField vs. DecimalField . Также важно знать ограничения SQLite в отношении десятичных полей.

DurationField

классDurationField ( ** варианты )

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

Заметка

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

EmailField

classEmailField ( max_length = 254 , ** варианты )

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

FileField

classFileField ( upload_to = None , max_length = 100 , ** options )

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

Заметка

Параметр primary_key не поддерживается и при использовании генерирует ошибку.

Имеет два необязательных параметра:

FileField.upload_to

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

Если вы укажете текстовое значение или путь Path , значение может содержать строки формата, strftime() которые будут заменены датой / временем загруженного файла (что позволит избежать переполнения указанного каталога). Например :

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 (с косой чертой), который будет передан в систему хранения. Вот два параметра:

настройка Описание
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)
Изменено в Django 3.0:

pathlib.Path Добавлена поддержка путей типов .

FileField.storage

Объект хранения или вызываемый объект, который возвращает объект хранения. Это управляет хранением и поиском ваших файлов. См. Раздел Управление файлами для получения подробной информации о том, как предоставить этот объект.

Изменено в Django 3.1:

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

Компонент формы по умолчанию для этого поля - ClearableFileInput .

Использование одного FileField или одного ImageField (см. Ниже) в классе модели включает несколько шагов:

  1. В вашем файле настроек вы должны указать MEDIA_ROOT абсолютный путь к каталогу, в котором Django будет сохранять загруженные файлы (из соображений производительности эти файлы не хранятся в базе данных). Укажите в MEDIA_URL базовом общедоступном URL-адресе, соответствующем этому каталогу. Убедитесь, что этот каталог доступен для записи пользователю веб-сервера.
  2. Добавьте поле FileField или ImageField в свой шаблон, установив параметр, upload_to указывающий, в какой подкаталог 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' соответствует четырехзначному году, '%m' соответствует двузначному месяцу и '%d' соответствует двузначному дню. Если вы загрузите файл 15 января 2007 г., он будет сохранен в каталоге /home/media/photos/2007/01/15 .

Если вы хотите получить имя загруженного файла или его размер, вы можете использовать его атрибуты name и size соответственно. Дополнительные сведения о доступных атрибутах и ​​методах см. В справочнике по классам File и в руководстве по теме « Управление файлами» .

Заметка

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

Относительный URL-адрес загруженного файла можно получить с помощью атрибута url . Внутри вызывается метод базового url() класса Storage .

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

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

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

FileField и FieldFile

класс FieldFile

Когда вы FileField получаете доступ к одному из шаблонов, вы получаете экземпляр FieldFile в качестве суррогата для доступа к базовому файлу.

API-интерфейс FieldFile отражает API-интерфейс File , с одним ключевым отличием: объект, адаптированный классом, не обязательно является адаптацией собственного файлового объекта Python . Скорее, это адаптация результата метода Storage.open() , который может быть объектом File или реализацией настраиваемого хранилища API File .

В дополнение к API, унаследованному от File , like read() и write() , FieldFile включает несколько методов, которые можно использовать для взаимодействия с базовым файлом:

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

Два метода этого класса save() и delete() по умолчанию сохраняют объект модели FieldFile ассоциированного пользователя в базе данных.

FieldFile.name

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

FieldFile.size

Результат базового метода Storage.size() .

FieldFile.url

Свойство только для чтения для доступа к относительному URL-адресу файла через вызов метода базового url() класса Storage .

FieldFile.open( режим = 'rb' )

Открывает или повторно открывает файл, связанный с этим экземпляром, в mode указанном. В отличие от стандартного метода Python open() , он не возвращает дескриптор файла.

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

FieldFile.close()

То же поведение, что и file.close() стандартный метод Python, и закройте файл, связанный с текущим экземпляром.

FieldFile.save( имя , содержание , сохранить = Истина )

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

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

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

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)

Или также можно построить его из строки Python следующим образом:

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

Для получения дополнительной информации см. Управление файлами .

FieldFile.delete( сохранить = True )

Удаляет файл, связанный с этим экземпляром, и очищает все атрибуты поля. ПРИМЕЧАНИЕ. Этот метод закрывает файл, если обнаруживается, что он открыт при delete() вызове.

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

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

FilePathField

classFilePathField ( path = '' , match = None , recursive = False , allow_files = True , allow_folders = False , max_length = 100 , ** options )

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

FilePathField.path

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

path также может быть исполняемым файлом, например функцией для динамической установки пути во время выполнения. пример

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)
Изменено в Django 3.0:

path теперь может быть исполняемым объектом.

FilePathField.match

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

FilePathField.recursive

По желанию. Есть True или False (по умолчанию). Указывает, path должны ли быть включены все подкаталоги .

FilePathField.allow_files

По желанию. Есть True (по умолчанию) или False . Указывает, должны ли быть включены файлы в указанном месте. Одно из двух значений, это поле или allow_folders , должно быть True .

FilePathField.allow_folders

По желанию. Есть True или 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

классFloatField ( ** варианты )

Число с плавающей запятой, представленное в Python экземпляром float .

Компонент формы по умолчанию для этого поля - NumberInput когда localize есть False , или TextInput наоборот.

FloatField против DecimalField

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

ImageField

classImageField ( upload_to = None , height_field = None , width_field = None , max_length = 100 , ** параметры )

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

Помимо специальных атрибутов, доступных для FileField , поле ImageField также имеет атрибуты height и width .

Чтобы упростить запрос этих атрибутов, ImageField есть два дополнительных необязательных атрибута:

ImageField.height_field

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

ImageField.width_field

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

Требуется библиотека подушек .

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

Компонент формы по умолчанию для этого поля - ClearableFileInput .

IntegerField

классIntegerField ( ** варианты )

Целое число. Значения от -2147483648 до 2147483647 принимаются всеми базами данных, поддерживаемыми Django.

Он использует MinValueValidator и MaxValueValidator для управления записями в соответствии со значениями, разрешенными базой данных по умолчанию.

Компонент формы по умолчанию для этого поля - NumberInput когда localize есть False , или TextInput наоборот.

GenericIPAddressField

classGenericIPAddressField ( протокол = 'both' , unpack_ipv4 = False , ** параметры )

Адрес IPv4 или IPv6 в текстовом формате (например, 192.0.2.30 или 2a02:42fe::4 ). Компонент формы по умолчанию для этого поля - TextInput .

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

GenericIPAddressField.protocol

Ограничивает действительность записей указанным протоколом. Возможные значения: 'both' (оба принятых протокола, значение по умолчанию) 'IPv4' или 'IPv6' .

GenericIPAddressField.unpack_ipv4

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

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

JSONField

классJSONField ( кодировщик = Нет , декодер = Нет , ** параметры )
Новое в Django 3.1.

Поле для хранения закодированных данных JSON. В Python данные представлены в соответствующем собственном формате: словари, списки, строки, числа, логические значения и None .

JSONField поддерживается в MariaDB 10.2.7+, MySQL 5.7.8+, Oracle, PostgreSQL и SQLite 3.9.0+ (с включенным расширением JSON1 ).

JSONField.encoder

Необязательный json.JSONEncoder подкласс для сериализации типов данных, не поддерживаемых стандартным сериализатором JSON (например, datetime.datetime или UUID ). Например, вы можете использовать DjangoJSONEncoder класс.

По умолчанию json.JSONEncoder .

JSONField.decoder

Необязательный json.JSONDecoder подкласс для десериализации значения, полученного из базы данных. Значение будет в формате, выбранном пользовательским кодировщиком (чаще всего это строка). При десериализации может потребоваться учет того факта, что вы не можете быть уверены в типе ввода. Например, вы рискуете вернуть a, datetime который на самом деле был строкой, которая случайно оказалась в том же формате, который был выбран для datetime s.

По умолчанию json.JSONDecoder .

Если вы указываете полю a default , убедитесь, что это неизменяемый объект, например a str , или вызываемый объект, который каждый раз возвращает новый изменяемый объект, например dict или функцию. Предоставление изменяемого объекта по умолчанию, такого как один объект default={} или default=[] разделяет его между всеми экземплярами модели.

Чтобы запросить JSONField базу данных, см. Запрос JSONField .

индексирование

Index и Field.db_index оба создают индекс B-дерева, который не особенно полезен при запросах JSONField . Только на PostgreSQL вы можете использовать GinIndex то, что лучше подходит.

Пользователи PostgreSQL

PostgreSQL имеет два собственных типа данных на основе JSON: json и jsonb . Основное различие между ними заключается в том, как они хранятся и как их можно запрашивать. Поле json PostgreSQL хранится как исходное текстовое представление JSON и должно быть декодировано на лету при запросе на основе ключей. Поле jsonb хранится в соответствии с фактической структурой JSON, которая позволяет индексировать. Зато написание поля jsonb немного дороже. JSONField использует тип jsonb .

Пользователи Oracle

Oracle Database не поддерживает хранение скалярных значений JSON. Поддерживаются только объекты и массивы JSON (представленные в Python с помощью dict и list ).

NullBooleanField

классNullBooleanField ( ** варианты )

Вроде BooleanField с null=True .

Не рекомендуется с версии 3.1: NullBooleanField устарел в пользу BooleanField(null=True) .

PositiveBigIntegerField

классPositiveBigIntegerField ( ** варианты )
Новое в Django 3.1.

Подобно a PositiveIntegerField , но допускает значения только в определенной (зависящей от базы данных) точке. Значения от 0 до 9223372036854775807 безопасны во всех базах данных, поддерживаемых Django.

PositiveIntegerField

классPositiveIntegerField ( ** варианты )

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

PositiveSmallIntegerField

классPositiveSmallIntegerField ( ** варианты )

Как и один PositiveIntegerField , но допускает только значения меньше определенного предела (в зависимости от движка базы данных). Все значения от 0 до 32767 принимаются всеми базами данных, официально поддерживаемыми Django.

SlugField

classSlugField ( max_length = 50 , ** варианты )

Слаг - англоязычный термин, обозначающий журналистику. Слаг - это короткий тег содержимого, состоящий только из букв, цифр, знаков подчеркивания или тире. Обычно они используются в URL-адресах.

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

Параметр Field.db_index неявно равен True .

Часто бывает полезно иметь возможность автоматически заполнять SlugField на основе значения другого атрибута. Сделать это можно в интерфейсе администрирования с помощью prepopulated_fields .

Он использует validate_slug или validate_unicode_slug для проверки.

SlugField.allow_unicode

Если значение равно True , поле принимает буквы Юникода в дополнение к основным буквам ASCII. По умолчанию это False .

SmallAutoField

классSmallAutoField ( ** варианты )
Новое в Django 3.0.

Как и один AutoField , но допускает только значения меньше определенного предела (в зависимости от движка базы данных). Все значения 1 до 32767 принимаются всеми базами данных, официально поддерживаемыми Django.

SmallIntegerField

классSmallIntegerField ( ** варианты )

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

TextField

классTextField ( ** варианты )

Длинное текстовое поле. Компонент формы по умолчанию для этого поля - Textarea .

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

TimeField

classTimeField ( auto_now = False , auto_now_add = False , ** параметры )

Час, представленный в Python экземпляром datetime.time . Это поле принимает те же параметры автозаполнения, что и поле DateField .

Компонент формы по умолчанию для этого поля - TimeInput . Интерфейс администрирования добавляет ярлыки JavaScript.

URLField

classURLField ( max_length = 200 , ** варианты )

Поле CharField для URL-адресов, проверенных пользователем URLValidator .

Компонент формы по умолчанию для этого поля - URLInput .

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

UUIDField

классUUIDField ( ** варианты )

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

Универсальные уникальные идентификаторы - хорошая альтернатива полям 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 .

Выражения запросов с PostgreSQL

Использование выражений запросов iexact , contains , icontains , startswith , istartswith , endswith или iendswith PostgreSQL не работает для значений без дефисов , потому что PostgreSQL хранит эти значения в базе данных типа UUID с черточками.

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

Django также определяет набор полей, представляющих отношения.

ForeignKey

classForeignKey ( to , on_delete , ** параметры )

Отношения "многие к одному". Требуется два параметра: класс, к которому привязана модель, и параметр on_delete .

Чтобы создать рекурсивную связь (объект с отношением многие-к-одному к самому себе), используйте .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

Отношения, определенные таким образом для абстрактных моделей , разрешаются, когда модель наследуется конкретной моделью и не связаны с атрибутом 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,
    )

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

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

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

В фоновом режиме Django добавляет "_id" к имени поля для создания имен столбцов базы данных. В предыдущем примере таблица базы данных для модели Car будет иметь один столбец manufacturer_id (вы можете явно изменить это, установив db_column ). Однако ваш код никогда не должен иметь дело непосредственно с именами столбцов базы данных, если вы сами не пишете собственный SQL. Вы всегда будете использовать имена полей объектов в своих моделях.

Параметры

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

ForeignKey.on_delete

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

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

on_delete не создает ограничения SQL в базе данных. Поддержка каскадных опций на уровне базы данных может быть реализована позже .

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

  • CASCADE

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

    Model.delete() не вызывается для связанных моделей, pre_delete а post_delete отправляется для всех удаленных объектов.

  • PROTECT

    Предотвращает удаление указанного объекта, вызывая исключение ProtectedError , подкласс django.db.IntegrityError .

  • RESTRICT
    Новое в Django 3.1.

    Предотвратить удаление указанного объекта, подняв RestrictedError (подкласс django.db.IntegrityError ). В отличие от этого PROTECT , удаление указанного объекта разрешено, если он также ссылается на другой объект, который удаляется в той же операции, но через CASCADE связь.

    Рассмотрим этот набор моделей:

    class Artist(models.Model):
        name = models.CharField(max_length=10)
    
    class Album(models.Model):
        artist = models.ForeignKey(Artist, on_delete=models.CASCADE)
    
    class Song(models.Model):
        artist = models.ForeignKey(Artist, on_delete=models.CASCADE)
        album = models.ForeignKey(Album, on_delete=models.RESTRICT)
    

    Artist может быть удален, даже если это подразумевает удаление объекта, на Album который ссылается a Song , поскольку Song также ссылается на Artist себя через каскадные отношения. Например:

    >>> artist_one = Artist.objects.create(name='artist one')
    >>> artist_two = Artist.objects.create(name='artist two')
    >>> album_one = Album.objects.create(artist=artist_one)
    >>> album_two = Album.objects.create(artist=artist_two)
    >>> song_one = Song.objects.create(artist=artist_one, album=album_one)
    >>> song_two = Song.objects.create(artist=artist_one, album=album_two)
    >>> album_one.delete()
    # Raises RestrictedError.
    >>> artist_two.delete()
    # Raises RestrictedError.
    >>> artist_one.delete()
    (4, {'Song': 2, 'Album': 1, 'Artist': 1})
    
  • SET_NULL

    Поместите нулевое значение в ForeignKey  ; это возможно, только если параметр 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

    Ничего не делать. Если компонент Database Engine обеспечивает ссылочную целостность, это создает исключение, 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 . Это может быть полезно при администрировании Django.

Форма «исполняемый объект» может быть полезна, например, при использовании с модулем Python datetime для ограничения возможных вариантов выбора в соответствии с временными интервалами. Например :

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

limit_choices_to = limit_pub_date_choices

Если limit_choices_to равно или возвращает один , что полезно для сложных запросов , это повлияет только на варианты, доступные в интерфейсе администратора, если поле не находится в свойстве формы шаблона.objet 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

Имя для использования в качестве имени обратного фильтра из целевой модели. Значение по умолчанию такое же, как related_name или, default_related_name если установлено одно из них, в противном случае это название модели:

# 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")

Например related_name , related_query_name поддерживает метки приложений и интерполяцию классов с помощью специального синтаксиса .

ForeignKey.to_field

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

ForeignKey.db_constraint

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

  • У вас уже есть недействительные данные.
  • Вы разбиваете свою базу данных.

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

ForeignKey.swappable

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

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

Установка для этого свойства значения False не означает, что вы можете ссылаться на переключаемый шаблон, даже если он был заменен, это False означает, что миграции, выполненные с этим ключом ForeignKey , всегда будут ссылаться на точный шаблон, который вы установили (если пользователь пытается для запуска модели с пользовательской моделью, для которой она не предназначена, все пойдет не так).

В случае сомнений оставьте для этого свойства значение по умолчанию True .

ManyToManyField

классManyToManyField ( к , ** варианты )

Отношения "многие ко многим". Требуется позиционный параметр: класс, к которому привязана модель, который работает точно так же, как и для ForeignKey , включая рекурсивные и ленивые отношения .

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

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

За кулисами Django создает промежуточную таблицу соединений для представления отношения «многие ко многим». По умолчанию имя этой таблицы создается с использованием имени поля «многие ко многим» и имени таблицы в ее модели. Поскольку некоторые базы данных не поддерживают имена таблиц сверх определенного размера, эти имена таблиц будут автоматически усечены, и, например, будет использоваться уникальный хэш author_books_9cdf4 . Вы можете вручную присвоить имя объединенной таблице, используя опцию db_table .

Параметры

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

Используется только в определении самого ManyToManyField себя. Рассмотрим следующую модель:

from django.db import models

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

Когда Django выполняет итерацию по этой модели, он обнаруживает, что модель имеет один ManyToManyField на себе, и поэтому не добавляет никаких атрибутов person_set к классу Person . Он считает поле ManyToManyField симметричным, то есть: если я твой друг, ты тоже мой друг.

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

Изменено в Django 3.0:

Указание symmetrical=True для многих ко многим рекурсивных отношений через промежуточный шаблон теперь разрешено.

ManyToManyField.through

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

Чаще всего этот параметр используется, когда вы хотите связать дополнительные данные с отношением «многие ко многим» .

Заметка

Если вы не хотите, чтобы между одними и теми же экземплярами было несколько ассоциаций, добавьте ограничение, UniqueConstraint включая поля привязки ( from и to ). Таблицы "многие ко многим", автоматически создаваемые Django, содержат такое ограничение.

Заметка

Рекурсивные отношения, использующие промежуточный шаблон и определенные как симметричные (то есть с symmetrical=True , что по умолчанию), не могут определять обратные имена средств доступа, потому что они будут одинаковыми. Вы должны определить имя related_name хотя бы для одного из них. Если вы предпочитаете, чтобы Django не создавал обратной связи, установите related_name значение '+' .

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

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

  • id : первичный ключ отношения.
  • <modèle_conteneur>_id : поле id модели, которое объявляет поле ManyToManyField .
  • <autre_modèle>_id : поле id модели, на которое указывает элемент управления ManyToManyField .

Если поле ManyToManyField имеет ту же модель, что и цель и источник, создаются следующие поля:

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

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

Model.m2mfield.through.objects.all()
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 принимает двоичный кортеж , где - имя внешнего ключа модели, которая определяет отношение (в данном случае group`), и имя внешнего ключа целевой модели ( в данном случае).('champ1', 'champ2') champ1 ManyToManyField champ2 person

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

ManyToManyField.db_table

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

ManyToManyField.db_constraint

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

  • У вас уже есть недействительные данные.
  • Вы разбиваете свою базу данных.

Неправильно передавать оба параметра db_constraint и through .

ManyToManyField.swappable

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

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

В случае сомнений оставьте для этого свойства значение по умолчанию True .

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

null не имеет никакого эффекта, так как невозможно требовать отношения на уровне базы данных.

OneToOneField

classOneToOneField ( to , on_delete , parent_link = False , ** параметры )

Индивидуальные отношения. Концептуально это похоже на поле ForeignKey с атрибутом unique=True , но «обратная» сторона отношения напрямую возвращает единственный объект.

Это очень полезно в качестве первичного ключа модели, которая каким-то образом «расширяет» другую модель; например, наследование нескольких таблиц реализуется путем добавления неявного однозначного отношения от дочерней модели к родительской.

Позиционный параметр обязателен: класс, с которым связана модель. Это работает точно так же, как и для ForeignKey , включая все параметры, касающиеся рекурсивных и отложенных отношений .

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

В следующем примере:

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

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

>>> user.supervisor_of
Traceback (most recent call last):
    ...
RelatedObjectDoesNotExist: User has no supervisor_of.

Кроме того, OneToOneField принимает все дополнительные параметры, принятые пользователем ForeignKey , плюс один дополнительный параметр:

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

См. Примеры использования поля в разделе « Отношения один-к-одному»OneToOneField .

Справочник по Field API

класс Field

Field - абстрактный класс, представляющий столбец таблицы базы данных. Django использует поля для создания таблицы базы данных ( db_type() ), для сопоставления типов Python с базой данных ( get_prep_value() ) и наоборот ( from_db_value() ).

Таким образом, поле является важной частью различных API Django, особенно для modèles и .jeux de requête

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

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

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

description

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

Описание может иметь вид:

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

где параметры интерполируются из __dict__ поля.

descriptor_class
Новое в Django 3.0.

Класс, реализующий протокол дескриптора, который создается и назначается атрибуту экземпляра шаблона. Конструктор должен принимать единственный параметр, экземпляр поля. Перегрузка этого атрибута класса позволяет настраивать поведение get и set .

Чтобы сопоставить поле Field с конкретным типом базы данных, Django предоставляет несколько методов:

get_internal_type()

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

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

db_type( подключение )

Возвращает тип данных столбца базы данных классов Field с учетом объекта connection .

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

rel_db_type( подключение )

Возвращает тип данных столбца базы данных, например, ForeignKey и OneToOneField который указывает Field , с учетом объекта connection .

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

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

  • когда он запрашивает базу данных (значение Python -> значение для механизма базы данных)
  • когда он загружает данные из базы данных (значение ядра базы данных -> значение Python)
  • при сохранении в базу данных (значение Python -> значение для механизма базы данных)

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

get_prep_value( значение )

value - текущее значение атрибута модели, и метод должен возвращать данные в формате, специально подготовленном для использования в качестве параметра запроса.

См. Раздел « Преобразование объектов Python в значения запроса» для получения информации о его использовании.

get_db_prep_value( значение , соединение , подготовлено = Ложь )

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

См. Раздел « Преобразование значений запроса в значения базы данных» .

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

from_db_value( значение , выражение , связь )

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

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

expression такое же, как self .

См. Раздел Преобразование значений в объекты Python для использования.

Заметка

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

При регистрации, pre_save() и get_db_prep_save() используются:

get_db_prep_save( значение , связь )

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

pre_save( model_instance , добавить )

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

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

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

См. Раздел « Предварительная обработка значений перед сохранением» .

Полям часто присваиваются значения другого типа либо посредством сериализации, либо с помощью форм.

to_python( значение )

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

См. Раздел Преобразование значений в объекты Python для использования.

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

value_from_object( obj )

Возвращает значение поля для данного экземпляра модели.

Этот метод часто используется value_to_string() .

value_to_string( obj )

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

См. Раздел « Преобразование данных поля для сериализации» .

При использовании поле должно знать, какое поле формы должно его представлять, вызывая:formulaires de modèles Field

formfield( form_class = Нет , choices_form_class = Нет , ** kwargs )

Возвращает поле формы, django.forms.Field используемое по умолчанию для этого поля в форме ModelForm .

По умолчанию, если form_class и choices_form_class оба None , поле CharField будет возвращено. Если поле имеет атрибут choices и choices_form_class оставлено пустым, это будет поле TypedChoiceField .

См. Раздел Выбор поля формы для поля шаблона для его использования.

deconstruct()

Вернуть кортеж из 4 элементов с достаточной информацией для воссоздания поля:

  1. Имя поля в шаблоне.
  2. Путь импорта поля (например "django.db.models.IntegerField" ). Рекомендуется указать более переносимую версию, поэтому чем менее конкретен путь, тем лучше.
  3. Список позиционных параметров.
  4. Словарь именованных параметров.

Этот метод необходимо добавить к полям, созданным до версии 1.7, чтобы можно было перенести их данные с помощью Migrations .

Справка по атрибутам поля

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

Атрибуты для полей

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 то обозначает родительский класс, а не класс экземпляра.

Атрибуты для полей отношений

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

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

Указывает на модель, связанную с элементом управления. Например, Author в . Ключа остается в силе .ForeignKey(Author, on_delete=models.CASCADE) related_model GenericForeignKey None

Copyright ©2020 All rights reserved