API de référence des expressions de rechercheLien vers cette rubrique#

API d’inscriptionLien vers cette rubrique#

Django utilise RegisterLookupMixin pour donner à une classe l’interface pour inscrire des recherches avec elle-même. Les deux exemples majeurs sont Field, la classe de base de tous les champs de modèles, et Transform, la classe de base de toutes les transformations de Django.

class lookups.RegisterLookupMixinLien vers cette définition#

Une classe mixin qui implémente l’API de recherche pour une classe.

classmethod register_lookup(lookup, lookup_name=None)Lien vers cette définition#

Inscrit une nouvelle recherche pour cette classe. Par exemple, DateField.register_lookup(YearExact) inscrit la recherche YearExact pour le champ DateField. Elle remplace une recherche de même nom qui existe déjà. Si présent, lookup_name sera utilisé pour cette recherche, sinon ce sera lookup.lookup_name.

get_lookup(lookup_name)Lien vers cette définition#

Renvoie la recherche Lookup nommée lookup_name inscrite dans la classe. L’implémentation par défaut cherche récursivement dans toutes les classes parentes et vérifie si l’une d’elles possède une recherche inscrite sous le nom lookup_name, et renvoie la première qu’elle rencontre.

get_lookups()Lien vers cette définition#

Renvoie un dictionnaire faisant correspondre chaque nom de requête inscrit dans la classe avec sa classe Lookup.

get_transform(transform_name)Lien vers cette définition#

Renvoie une transformation Transform nommée transform_name. L’implémentation par défaut cherche récursivement dans toutes les classes parentes et vérifie si l’une d’elles possède une transformation inscrite sous le nom transform_name, et renvoie la première qu’elle rencontre.

Pour qu’une classe soit considérée comme une recherche, elle doit suivre l”API d’expression de recherche. Lookup et Transform suivent naturellement cette API.

L’API d’expression de rechercheLien vers cette rubrique#

L’API d’expression de recherche est un ensemble commun de méthodes que les classes définissent afin de pouvoir être utilisées dans les expressions de recherche avec la capacité de se traduire en expressions SQL. Les références directes aux champs, les agrégations et les expressions Transform sont des exemples qui respectent cette API. On dit d’une classe qu’elle respecte l’API d’expression de recherche lorsqu’elle implémente les méthodes suivantes :

as_sql(compiler, connection)Lien vers cette définition#

Génère le fragment SQL de l’expression. Renvoie un tuple (sql, params), où sql est la chaîne SQL et params est la liste ou le tuple des paramètres de requête. compiler est un objet SQLCompiler comportant une méthode compile() pouvant être utilisée pour compiler d’autres expressions. connection est la connexion utilisée pour exécuter la requête.

Il n’est normalement pas correct d’appeler expression.as_sql(), c’est plutôt compiler.compile(expression) qui doit être utilisé. La méthode compiler.compile() se charge d’appeler les méthodes spécifiques au fournisseur de base de données pour l’expression donnée.

Des paramètres nommés personnalisés peuvent être définis pour cette méthode s’il est probable que des méthodes as_nomfournisseur() ou des sous-classes pourraient vouloir fournir des données pour surcharger la génération de la chaîne SQL. Voir Func.as_sql() pour un exemple d’utilisation.

as_vendorname(compiler, connection)Lien vers cette définition#

Fonctionne comme la méthode as_sql(). Lorsqu’une expression est compilée avec compiler.compile(), Django essaie d’abord d’appeler as_nomfournisseur() où nomfournisseur correspond au nom du fournisseur de la base de données utilisée pour exécuter la requête. Pour les moteurs fournis avec Django, nomfournisseur peut correspondre à postgresql, oracle, sqlite ou mysql.

get_lookup(lookup_name)Lien vers cette définition#

Doit renvoyer la recherche nommée lookup_name. Par exemple, en renvoyant self.output_field.get_lookup(lookup_name).

get_transform(transform_name)Lien vers cette définition#

Doit renvoyer la transformation nommée transform_name. Par exemple, en renvoyant self.output_field.get_transform(transform_name).

output_fieldLien vers cette définition#

Définit le type de classe renvoyée par la méthode get_lookup(). Il doit s’agir d’une instance Field.

Référence de TransformLien vers cette rubrique#

class TransformLien vers cette définition#

Transform est une classe générique pour implémenter des transformations de champs. Un exemple typique est __year (année) qui transforme un champ DateField en champ IntegerField.

La notation utilisée pour placer Transform dans une expression de recherche est <expression>__<transformation> (par ex. date__year).

Cette classe respecte l”API d’expression de recherche, ce qui signifie que vous pouvez utiliser <expression>__<transform1>__<transform2>. Il s’agit d’une expression Func() spécialisée qui n’accepte qu’un seul paramètre. Elle peut également être utilisée dans la partie droite d’un filtre ou directement sous forme d’annotation.

bilateralLien vers cette définition#

Une valeur booléenne indiquant si cette transformation doit s’appliquer aux deux parties lhs et rhs. Les transformations bilatérales seront appliquées à rhs dans leur ordre d’apparition dans l’expression de requête. Par défaut, cet attribut vaut False. Pour des exemples d’utilisation, voir Expressions de recherche personnalisées.

lhsLien vers cette définition#

La partie gauche de l’expression, ce qui est transformé. Elle doit respecter l”API d’expression de recherche.

lookup_nameLien vers cette définition#

Le nom de la transformation, utilisé pour l’identifier lors de l’analyse des expressions de recherche. Il ne peut pas contenir la chaîne "__".

output_fieldLien vers cette définition#

Définit la classe que cette transformation produit. Il doit s’agir d’une instance de Field. Par défaut, c’est la même classe que lhs.output_field.

Référence de LookupLien vers cette rubrique#

class LookupLien vers cette définition#

Lookup est une classe générique pour implémenter des recherches. Une recherche est une expression de requête avec un côté gauche lhs, un côté droit rhs et un nom lookup_name utilisé pour produire une comparaison booléenne entre lhs et rhs telle que lhs in rhs ou lhs > rhs.

La notation utilisée pour placer une recherche Lookup dans une expression de recherche est <cote_gauche>__<nom_recherche>=<cote_droit>.

Cette classe se comporte comme une expression de recherche, mais comme elle possède =<rhs> dans sa construction, les recherches doivent toujours être en fin d’expression de recherche.

lhsLien vers cette définition#

Le côté gauche, le contenu recherché. L’objet doit respecter l”API d’expression de recherche.

rhsLien vers cette définition#

Le côté droit, ce qui est comparé avec lhs. Il peut s’agir d’une valeur brute ou de quelque chose qui se compile en SQL, typiquement un objet F() ou un QuerySet.

lookup_nameLien vers cette définition#

Le nom de la recherche, utilisé pour l’identifier lors de l’analyse des expressions de recherche. Il ne peut pas contenir la chaîne "__".

process_lhs(compiler, connection, lhs=None)Lien vers cette définition#

Renvoie un tuple (lhs_string, lhs_params), tel que renvoyé par compiler.compile(lhs). Cette méthode peut être surchargée pour affiner le traitement de lhs.

compiler est un objet SQLCompiler destiné à la compilation de lhs, comme avec compiler.compile(lhs). Le paramètre connection peut être utilisé pour compiler du SQL selon un fournisseur particulier. Si lhs n’est pas None, ce paramètre est employé comme lhs à la place de self.lhs.

process_rhs(compiler, connection)Lien vers cette définition#

Se comporte de la même manière que process_lhs(), mais pour le côté droit.