Справочник по API запросов

API регистрации

Django использует RegisterLookupMixin, чтобы предоставить классу интерфейс для регистрации запросов к себе или его экземплярам. Два основных примера — Field, базовый класс всех полей модели, и Transform, базовый класс всех преобразований Django.

class lookups.RegisterLookupMixin

Mixin, реализующий API запросов для класса.

classmethod register_lookup(lookup, lookup_name=None)

Регистрирует новый запрос в классе или экземпляре класса. Например:

DateField.register_lookup(YearExact)
User._meta.get_field("date_joined").register_lookup(MonthExact)

зарегистрирует запрос YearExact для DateField и запрос MonthExact для User.date_joined (можно использовать API доступа к полям для получения одного экземпляра поля). Он переопределяет запрос, который уже существует с тем же именем. Запросы, зарегистрированные в экземплярах полей, имеют приоритет над запросами, зарегистрированными в классах. lookup_name будет использоваться для этого запроса, если предоставлено, в противном случае будет использоваться lookup.lookup_name.

get_lookup(lookup_name)

Возвращает Lookup с именем lookup_name, зарегистрированным в классе или экземпляре класса в зависимости от вызова. Реализация по умолчанию рекурсивно проверяет все родительские классы и проверяет, есть ли в каком-либо из них зарегистрированный запрос с именем lookup_name, возвращая первый результат совпадения. Запросы экземпляра переопределяют любые запросы класса с тем же lookup_name.

get_lookups()

Возвращает словарь, в котором каждое имя запроса сопоставлено классу Lookup.

get_transform(transform_name)

Возвращает Transform с именем transform_name, зарегистрированным в классе или экземпляре класса. Реализация по умолчанию рекурсивно проверяет все родительские классы, чтобы проверить, есть ли в каком-либо из них зарегистрированное преобразование с именем transform_name, возвращая первый результат совпадения.

Чтобы класс был запросом, он должен следовать API выражений запроса. Lookup и Transform естественным образом следуют этому API.

API выражений запроса

API выражений запроса — это общий набор методов, которые определяют классы, чтобы быть применимыми в выражениях запроса для перевода самих себя в выражения SQL. Прямые ссылки на поля, агрегаты и Transform — примеры, которые следуют этому API. Говорят, что класс следует API выражений запроса, когда он реализует следующие методы:

as_sql(compiler, connection)

Генерирует фрагмент SQL для выражения. Возвращает кортеж (sql, params), где sql — строка SQL, а params — список или кортеж параметров запроса. compiler — объект SQLCompiler, у которого есть метод compile(), который может использоваться для компиляции других выражений. connection — соединение, используемое для выполнения запроса.

Вызов expression.as_sql() обычно неверен — вместо этого следует использовать compiler.compile(expression). Метод compiler.compile() позаботится о вызове специфичных для поставщика методов выражения.

В этом методе могут быть определены пользовательские ключевые аргументы, если существует вероятность, что методам as_vendorname() или подклассам потребуется предоставить данные для переопределения генерации строки SQL. См. Func.as_sql() для примера использования.

as_vendorname(compiler, connection)

Действует как метод as_sql(). При компиляции выражения compiler.compile() Django сначала попытается вызвать as_vendorname(), где vendorname — имя поставщика базы данных, используемой для выполнения запроса. vendorname — одно из значений postgresql, oracle, sqlite или mysql для встроенных баз данных Django.

get_lookup(lookup_name)

Должен вернуть запрос с именем lookup_name. Например, возвращая self.output_field.get_lookup(lookup_name).

get_transform(transform_name)

Должен вернуть преобразование с именем transform_name. Например, возвращая self.output_field.get_transform(transform_name).

output_field

Определяет тип класса, возвращаемого методом get_lookup(). Он должен быть экземпляром Field.

Transform

class Transform [source]

Transform — это универсальный класс для реализации преобразований полей. Яркий пример — __year, который преобразует DateField в IntegerField.

Нотация для использования Transform в выражении запроса — <expression>__<transformation> (например, date__year).

Этот класс следует API выражений запроса, что подразумевает возможность использования <expression>__<transform1>__<transform2>. Это специализированное выражение Func(), которое принимает только один аргумент. Также может использоваться в правой части фильтра или напрямую как аннотация.

bilateral

Булево значение, указывающее, должно ли это преобразование применяться к lhs и rhs. Двусторонние преобразования будут применяться к rhs в том же порядке, что и в выражении запроса. По умолчанию он установлен в False. Пример использования см. в Как написать пользовательские запросы.

lhs [source]

Левая часть — то, что преобразуется. Оно должно следовать API выражений запроса.

lookup_name

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

output_field

Определяет класс, который выводит это преобразование. Он должен быть экземпляром Field. По умолчанию — такой же, как и у lhs.output_field.

Lookup справка

class Lookup [source]

Класс Lookup — это общий класс для реализации поиска. Поиск — это выражение запроса с левой частью, lhs; правой частью, rhs; и lookup_name, который используется для получения булевого сравнения между lhs и rhs, например, lhs in rhs или lhs > rhs.

Основной способ использования поиска в выражении — это <lhs>__<lookup_name>=<rhs>. Поиск также может использоваться напрямую в QuerySet фильтрах:

Book.objects.filter(LessThan(F("word_count"), 7500))

…или аннотациях:

Book.objects.annotate(is_short_story=LessThan(F("word_count"), 7500))

lhs

Левая часть — то, что ищется. Объект обычно следует API выражений запроса. Также может быть простым значением.

rhs

Правая часть — то, с чем lhs сравнивается. Это может быть простое значение или нечто, что компилируется в SQL, обычно объект F() или QuerySet.

lookup_name

Имя этого поиска, используемое для его идентификации при парсинге выражений запроса. Оно не может содержать строку "__".

prepare_rhs

По умолчанию True. Когда rhs — простое значение, prepare_rhs определяет, следует ли его подготовить для использования в качестве параметра в запросе. Для этого вызывается lhs.output_field.get_prep_value(), если оно определено, или rhs оборачивается в Value() в противном случае.

process_lhs(compiler, connection, lhs=None) [source]

Возвращает кортеж (lhs_string, lhs_params), как возвращает compiler.compile(lhs). Этот метод может быть переопределён для настройки обработки lhs.

compiler — это объект SQLCompiler, который используется как compiler.compile(lhs) для компиляции lhs. connection может использоваться для компиляции поставщика SQL. Если lhs не None, используйте его в качестве обработанной lhs вместо self.lhs.

process_rhs(compiler, connection) [source]

Ведёт себя аналогично process_lhs(), для правой части.