Все поля Модели

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

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

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

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

Заметка

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

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

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

null

Field.null

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

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

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

Заметка

При использовании серверной части базы данных Oracle значение 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'параметр в этом примере).

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

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

Заметка

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

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

Типы перечисления

Кроме того, 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, но с некоторыми изменениями:

  • Значения членов перечисления - это кортеж аргументов, используемых при построении конкретного типа данных. Django поддерживает добавление дополнительного строкового значения в конец этого кортежа для использования в качестве удобочитаемого имени или label. labelМожет быть ленивым переводимые строки. Таким образом, в большинстве случаев значение члена будет двухкортежным. См. Ниже пример выбора подкласса с использованием более сложного типа данных. Если кортеж не указан, или последний элемент не является (ленивые) строка, то это автоматически генерируется из имени элемента.(value, label)label
  • .labelСвойство добавляется на значения, чтобы вернуть имя удобочитаемый.
  • Ряд пользовательских свойств добавляется к классам счетных - .choices, .labels, .values, и .names- чтобы сделать его проще списки доступа этих отдельных частей перечисления. Используйте .choices в качестве подходящего значения для перехода choicesв определение поля.
  • Использование enum.unique()принудительно, чтобы гарантировать, что значения не могут быть определены несколько раз. Этого вряд ли можно ожидать при выборе поля.

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

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

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

Также можно использовать Enum Functional API с оговоркой, что метки создаются автоматически, как указано выше:

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

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

Для таких полей, как 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. Дополнительные ключи сообщений об ошибках указаны для каждого поля в разделе Типы полей ниже.

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

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модели поднимет a 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.

Обратите внимание, что если вы установите для этого параметра значение a 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-битное целое число, очень похожее на an, AutoFieldза исключением того, что оно гарантированно соответствует числам от 1до 9223372036854775807.

BigIntegerField

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

64-битное целое число, очень похожее на an, 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

Максимальная длина (в символах) поля. 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в Trueпричинит поле , чтобы иметь editable=Falseи blank=True множество.

Заметка

Параметры auto_nowи auto_now_addвсегда будут использовать дату в часовом поясе по умолчанию в момент создания или обновления. Если вам нужно что-то другое, вы можете рассмотреть возможность использования собственного вызываемого значения по умолчанию или переопределения save()вместо использования auto_nowили auto_now_add; или используя DateTimeField вместо a DateFieldи решая, как обрабатывать преобразование из datetime в date во время отображения.

DateTimeField

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

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

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

DecimalField

classDecimalField ( max_digits = None , decimal_places = None , ** options )

Десятичное число с фиксированной точностью, представленное в 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 против DecimalField . Вы также должны знать об ограничениях SQLite для десятичных полей.

DurationField

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

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

Заметка

Арифметика с DurationFieldработает в большинстве случаев. Однако во всех базах данных, кроме PostgreSQL, сравнение значения a 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()методу.

Если вы укажете строковое значение или a 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, вы можете получить абсолютный путь к вашему изображению в шаблоне с помощью .{{ object.mug_shot.url }}

Например, скажем, ваш MEDIA_ROOTустановлен на '/home/media', и upload_toустановлен на 'photos/%Y/%m/%d'. '%Y/%m/%d' Часть upload_toIS 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объектом, или это может быть реализация FileAPI пользовательского хранилища .

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

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

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

FieldFile.name

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

FieldFile.path

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

FieldFile.size

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

FieldFile.url

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

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

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

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

FieldFile.close()

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

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

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

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

Обратите внимание, что contentаргумент должен быть экземпляром django.core.files.File, а не встроенным файловым объектом Python. Вы можете создать a 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)

Или вы можете построить его из строки 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 )

A, 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. По умолчанию 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

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

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

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

FloatField vs. DecimalField

FloatFieldКласс иногда смешивается с DecimalFieldклассом. Хотя оба они представляют собой действительные числа, они представляют эти числа по-разному. FloatFieldиспользует float тип Python внутри, а DecimalFieldиспользует Decimalтип Python . Для получения информации о разнице между ними см. Документацию 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 следует 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

Ограничивает допустимые входные данные указанным протоколом. Допустимые значения: '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 данные представлены в собственном формате 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который на самом деле был строкой, которая случайно оказалась в том же формате, который был выбран для datetimes.

По умолчанию 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 ( ** варианты )

Подобно a 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 , ** варианты )

A CharFieldдля URL, подтвержденного URLValidator.

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

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

UUIDField

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

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

Универсальные уникальные идентификаторы - хорошая альтернатива AutoFieldfor 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аргументом. Например, если у вас есть объект, допускающий значение NULL, 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

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

Вызываемая форма может быть полезна, например, при использовании вместе с datetimeмодулем Python для ограничения выбора диапазоном дат. Например:

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

limit_choices_to = limit_pub_date_choices

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

Заметка

Если вызываемый объект используется для 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_9cdf. Вы можете вручную указать имя объединенной таблицы, используя 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

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

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 таблицы "многие-ко-многим" включают такое ограничение.

Заметка

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

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

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

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

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

  • id: первичный ключ отношения.
  • from_<model>_id: idэкземпляр, который указывает на модель (т.е. исходный экземпляр).
  • to_<model>_id: 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принимает 2-кортеж , где - это имя внешнего ключа для модели, для которой определено ( в данном случае), и имя внешнего ключа для целевой модели ( в данном случае).('field1', 'field2')field1ManyToManyFieldgroupfield2person

Если у вас есть более одного внешнего ключа в модели-посреднике для любой (или даже обеих) моделей, участвующих в отношении «многие ко многим», вы должны указать 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 , ** параметры )

Отношения один на один. Концептуально это похоже на ForeignKeywith 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, в частности, modelsи querysets.

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

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

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

description

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

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

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

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

descriptor_class
Новое в Django 3.0.

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

Чтобы сопоставить a 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()если есть False.

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

При загрузке данных 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в строку. Используется для сериализации значения поля.

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

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

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 .

Copyright ©2020 All rights reserved