Options Meta
des modèles¶
Ce document explique toutes les options de métadonnées qu’il est possible d’attribuer aux modèles dans leur classe Meta
interne.
Options Meta
disponibles¶
abstract
¶
-
Options.
abstract
¶ Si
abstract = True
, ce modèle sera une classe de base abstraite.
app_label
¶
-
Options.
app_label
¶ Si un modèle est défini en dehors d’une application dans
INSTALLED_APPS
, il doit déclarer à quelle application il appartient :app_label = 'myapp'
Si vous souhaitez représenter un modèle avec le format
étiquette_app.nom_objet
ouétiquette_app.nom_modèle
, vous pouvez respectivement utilisermodel._meta.label
oumodel._meta.label_lower
.
base_manager_name
¶
-
Options.
base_manager_name
¶ - New in Django 1.10.
Le nom du gestionnaire à utiliser pour l’attribut
_base_manager
du modèle.
db_table
¶
-
Options.
db_table
¶ Le nom de la table de base de données à utiliser pour le modèle :
db_table = 'music_album'
Noms de tables¶
Pour vous faire gagner du temps, Django dérive automatiquement le nom de la table de base de données du nom de la classe de modèle et de l’application dans laquelle elle se trouve. Un nom de table de base de données d’un modèle est construit en adjoignant le « label » d’application du modèle (le nom utilisé lors de la commande manage.py startapp
) au nom de classe du modèle, combinés par un soulignement.
Par exemple, pour une application bibliotheque
(qui serait créée avec manage.py startapp bibliotheque
) et un modèle défini par class Livre
, le nom de la table de base de données serait bibliotheque_livre
.
Pour surcharger le nom de la table de base de données, utilisez l’attribut db_table
de la classe Meta
.
Si votre nom de table de base de données est un mot SQL réservé ou s’il contient des caractères non autorisés dans des noms de variables Python (en particulier le trait d’union), il n’y a pas de souci à se faire. Django place entre guillemets les noms de colonnes et de tables en arrière-plan.
Noms de tables en minuscules pour MySQL
Il est fortement conseillé d’écrire les noms de tables en minuscules lors de leur surcharge avec db_table
, particulièrement lorsqu’on utilise le moteur MySQL. Voir les notes pour MySQL pour plus de détails.
Noms de tables entre guillemets pour Oracle
Afin de respecter la limite de 30 caractères qu’Oracle impose aux noms de tables et pour suivre les conventions habituelles des bases de données Oracle, Django peut raccourcir les noms de tables et les transformer en majuscules. Pour empêcher ces transformations, écrivez des valeurs entre guillemets dans db_table
:
db_table = '"name_left_in_lowercase"'
Il est aussi possible d’utiliser de tels noms entre guillemets avec les autres moteurs de base de données pris en charge par Django ; cependant, contrairement à Oracle, les guillemets n’ont pas d’effet. Voir les notes sur Oracle pour plus de détails.
db_tablespace
¶
-
Options.
db_tablespace
¶ Le nom de l”espace de tables de base de données à utiliser pour ce modèle. La valeur par défaut est le réglage
DEFAULT_TABLESPACE
du projet, s’il est défini. Si le moteur ne prend pas en charge les espaces de tables, cette option est ignorée.
default_manager_name
¶
-
Options.
default_manager_name
¶ - New in Django 1.10.
Le nom du gestionnaire à utiliser pour l’attribut
_default_manager
du modèle.
get_latest_by
¶
-
Options.
get_latest_by
¶ Le nom d’un champ de tri pour le modèle, typiquement un champ
DateField
,DateTimeField
ouIntegerField
. Cette option définit le champ par défaut à utiliser dans les méthodeslatest()
etearliest()
du gestionnaire (Manager
) du modèle.Exemple :
get_latest_by = "order_date"
Voir la documentation de
latest()
pour plus de détails.
managed
¶
-
Options.
managed
¶ La valeur par défaut est
True
, signifiant que Django crée les tables de base de données adéquates dansmigrate
ou dans le cadre des migrations et les efface dans le contexte de la commande d’administrationflush
. C’est-à-dire que Django pilote le cycle de vie des tables de la base de données.Si la valeur est
False
, aucune opération de création ou de suppression de table de base de données n’est effectuée pour ce modèle. Utile si le modèle représente une table existante ou un vue de base de données qui a été créée par un autre moyen. C’est l”unique différence lorsquemanaged=False
. Tous les autres aspects de la gestion des modèles sont traités comme pour un modèle normal. Cela inclut :L’ajout automatique d’un champ de clé primaire au modèle si aucun n’est déclaré. Pour enlever toute confusion possible aux lecteurs de votre code, il est recommandé d’indiquer toutes les colonnes de la table de base de données que vous modélisez en utilisant des modèles non pilotés.
Si un modèle avec
managed=False
contient un champManyToManyField
qui pointe vers un autre modèle non piloté, la table intermédiaire de la relation plusieurs-à-plusieurs ne sera pas non plus créée. Cependant, la table intermédiaire entre un modèle piloté et un modèle non piloté sera bel et bien créée.Si vous aimeriez changer ce comportement par défaut, créez explicitement le modèle de la table intermédiaire (avec l’option
managed
appropriée) et utilisez l’attributManyToManyField.through
pour que la relation utilise le modèle ainsi créé.
En ce qui concerne les tests impliquant des modèles avec
managed=False
, c’est à vous de vous assurer que les tables correctes soient créées dans le cadre de la mise en place des tests.Si vous êtes intéressé à modifier le comportement Python d’une classe de modèle, vous pourriez utiliser
managed=False
et créer une copie d’un modèle existant. Cependant, il existe une meilleure approche pour ce genre de situation : Modèles mandataires.
order_with_respect_to
¶
-
Options.
order_with_respect_to
¶ Rend cet objet « triable » en fonction du champ donné, presque toujours un champ
ForeignKey
. Cela peut être utilisé pour permettre à des objets liés d’être triés en fonction d’un objet parent. Par exemple, si un objetAnswer
(réponse) est lié à un objetQuestion
et qu’une question possède plus d’une réponse et que l’ordre des réponses est signifiant, voici comment cela serait défini :from django.db import models class Question(models.Model): text = models.TextField() # ... class Answer(models.Model): question = models.ForeignKey(Question, on_delete=models.CASCADE) # ... class Meta: order_with_respect_to = 'question'
Lorsque
order_with_respect_to
est défini, deux méthodes complémentaires sont fournies pour récupérer et définir l’ordre des objets liés :get_RELATED_order()
etset_RELATED_order()
, oùRELATED
est le nom du modèle en minuscules. Par exemple, en supposant qu’un objetQuestion
possède plusieurs objetsAnswer
liés, la liste renvoyée contient les clés primaires des objetsAnswer
liés :>>> question = Question.objects.get(id=1) >>> question.get_answer_order() [1, 2, 3]
L’ordre des objets liés
Answer
d’un objetQuestion
peut être défini en passant une liste de clés primaires d’objetsAnswer
:>>> question.set_answer_order([3, 1, 2])
Les objets liés reçoivent aussi deux méthodes,
get_next_in_order()
etget_previous_in_order()
, qui peuvent être utilisées pour accéder à ces objets dans l’ordre correct. En supposant que les objetsAnswer
sont triés parid
:>>> answer = Answer.objects.get(id=2) >>> answer.get_next_in_order() <Answer: 3> >>> answer.get_previous_in_order() <Answer: 1>
order_with_respect_to
définit implicitement l’option ordering
.
En interne, order_with_respect_to
ajoute un champ (colonne de base de données) supplémentaire nommé _order
et définit l’option ordering
du modèle avec ce champ. Par conséquent, order_with_respect_to
et ordering
ne peuvent pas être utilisés conjointement, et l’ordre de tri ajouté par order_with_respect_to
s’applique chaque fois que vous obtenez une liste d’objets pour ce modèle.
Modification de order_with_respect_to
Comme order_with_respect_to
ajoute une colonne de base de données supplémentaire, il vous revient donc de créer et d’appliquer les migrations appropriées si vous ajoutez ou modifiez order_with_respect_to
après la création initiale opérée par migrate
.
ordering
¶
-
Options.
ordering
¶ Le tri par défaut des objets, lors de l’obtention de listes d’objets :
ordering = ['-order_date']
Il s’agit d’un tuple ou d’une liste de chaînes. Chaque chaîne correspond à un nom de champ, facultativement préfixée par « - » indiquant un tri descendant. Les champs sans préfixe « - » sont triés dans l’ordre ascendant. Indiquez la chaîne « ? » pour trier de façon aléatoire.
Par exemple, pour trier sur un champ
pub_date
dans l’ordre ascendant, indiquez :ordering = ['pub_date']
Pour trier par
pub_date
dans l’ordre descendant, indiquez :ordering = ['-pub_date']
Pour trier par
pub_date
dans l’ordre descendant, puis parauthor
dans l’ordre ascendant, indiquez :ordering = ['-pub_date', 'author']
Le tri par défaut affecte également les requêtes d’agrégation.
Avertissement
Le tri n’est pas une opération anodine. Chaque champ ajouté dans les critères de tri implique un coût au niveau de la base de données. Chaque clé étrangère ajoutée inclut aussi implicitement tous ses champs de tri par défaut.
Si une requête ne possède pas d’ordre de tri, les résultats sont renvoyés de la base de données dans un ordre non défini. Un ordre particulier ne peut être garanti que si l’ordre se base sur un ou des champs qui identifient chaque objet du résultat de manière unique. Par exemple, si un champ nom
n’est pas unique, le tri par ce champ ne garantit pas que les objets de même nom apparaissent toujours dans le même ordre.
permissions
¶
-
Options.
permissions
¶ Permissions supplémentaires à intégrer dans la table des permissions lors de la création de cet objet. Les permissions d’ajout, de suppression et de modification sont automatiquement créées pour tous les modèles. Cet exemple ajoute une permission supplémentaire,
can_deliver_pizzas
:permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
Il s’agit d’une liste ou d’un tuple de tuples binaires dans le format
(code_permission, nom_verbeux_permission)
.
default_permissions
¶
-
Options.
default_permissions
¶ Contient
('add', 'change', 'delete')
par défaut. Vous pouvez ajuster cette liste, par exemple en définissant une liste vide si votre application n’a besoin d’aucune permission par défaut. Les permissions doivent être définies pour le modèle avant que celui-ci ne soit créé parmigrate
afin d’éviter la création de permissions non utilisées.
proxy
¶
-
Options.
proxy
¶ Si
proxy = True
, un modèle qui hérite d’un autre modèle sera considéré comme un modèle mandataire.
required_db_features
¶
-
Options.
required_db_features
¶ Liste de fonctionnalités de base de données que la connexion en cours devrait avoir pour que le modèle soit considéré pendant la phase de migration. Par exemple, si cette liste contient
['gis_enabled']
, le modèle ne sera synchronisé qu’avec les bases de données possédant des fonctionnalités SIG. Ceci est également utile pour omettre certains modèles lors de tests avec plusieurs moteurs de base de données différents. Évitez les relations avec ces modèles qui sont créés conditionnellement car l’ORM ne sait pas comment traiter ces cas.
required_db_vendor
¶
-
Options.
required_db_vendor
¶ Nom d’un fournisseur de base de données pour lequel ce modèle est spécifique. Les noms des fournisseurs intégrés actuels sont :
sqlite
,postgresql
,mysql
etoracle
. Si cet attribut n’est pas vide et que le fournisseur de la connexion actuelle ne correspond pas, le modèle n’est pas synchronisé.
select_on_save
¶
-
Options.
select_on_save
¶ Détermine si Django utilise l’algorithme
django.db.models.Model.save()
d’avant la version 1.6. L’ancien algorithme utiliseSELECT
pour savoir s’il y a une ligne existant à mettre à jour. Le nouvel algorithme essaie directement unUPDATE
. Dans de rares cas, la mise à jour parUPDATE
d’une ligne existante n’est pas visible par Django. Un des exemples est le déclencheurON UPDATE
de PostgreSQL qui renvoieNULL
. Dans de telles situations, le nouvel algorithme effectue finalement unINSERT
même quand une ligne existe déjà dans la base de données.Il n’y a habituellement pas besoin de définir cet attribut. La valeur par défaut est
False
.Voir
django.db.models.Model.save()
pour plus de détails sur l’ancien et le nouvel algorithme d’enregistrement.
indexes
¶
-
Options.
indexes
¶ - New in Django 1.11.
Une liste des index que vous souhaitez définir pour le modèle :
from django.db import models class Customer(models.Model): first_name = models.CharField(max_length=100) last_name = models.CharField(max_length=100) class Meta: indexes = [ models.Index(fields=['last_name', 'first_name']), models.Index(fields=['first_name'], name='first_name_idx'), ]
unique_together
¶
-
Options.
unique_together
¶ Noms de champs qui forment ensemble des index uniques :
unique_together = (("driver", "restaurant"),)
Il s’agit d’un tuple de tuples dont les valeurs combinées doivent être uniques. Utilisé dans l’administration de Django et appliqué au niveau base de données (c’est-à-dire que les commandes
UNIQUE
appropriées sont inclues dans les commandesCREATE TABLE
).Par commodité,
unique_together
peut être formé d’un seul tuple lorsqu’un seul groupe de champs est défini :unique_together = ("driver", "restaurant")
Il n’est pas possible d’inclure un champ
ManyToManyField
dansunique_together
(il n’est même pas évident de savoir ce que ça signifierait). Si vous avez besoin de valider de l’unicité au niveau d’un champManyToManyField
, essayez d’utiliser un signal ou un modèlethrough
explicite.L’exception
ValidationError
générée durant la validation du modèle lorsque la contrainte est violée possède le code d’erreurunique_together
.
index_together
¶
-
Options.
index_together
¶ Noms de champs qui forment ensemble des index :
index_together = [ ["pub_date", "deadline"], ]
Cette liste de champs formera un index combiné (c’est-à-dire que la commande
CREATE INDEX
appropriée sera produite).Par commodité,
index_together
peut être formé d’une seule liste lorsqu’un seul groupe de champs est défini :index_together = ["pub_date", "deadline"]
verbose_name
¶
-
Options.
verbose_name
¶ Un nom verbeux pour l’objet, au singulier :
verbose_name = "pizza"
Si cette option est absente, Django manipule le nom de la classe :
CamelCase
devientcamel case
.
verbose_name_plural
¶
-
Options.
verbose_name_plural
¶ Le nom verbeux pluriel pour l’objet :
verbose_name_plural = "stories"
Si cette option est absente, Django utilise
verbose_name
et y ajoute un « s ».