Référence des champs de modèle¶
Ce document contient toutes les références d’API de Field
, y compris les détails que Django met à disposition concernant les options de champs et les types de champs.
Voir aussi
Si les champs intégrés ne font pas l’affaire, vous pouvez essayer django-localflavor (documentation) qui contient des bouts de code utiles pour un pays ou une culture particulière.
Il est aussi possible d’écrire facilement son propre champ de modèle personnalisé.
Note
Techniquement, ces modèles sont définis dans django.db.models.fields
, mais par commodité ils sont importés dans django.db.models
; la convention standard est d’utiliser from django.db import models
et de se référer aux champs avec models.<Foo>Field
.
Options des champs¶
Les paramètres suivants sont disponibles pour tous les types de champs. Tous sont facultatifs.
null
¶
-
Field.
null
¶
Si la valeur est True
, Django stocke les valeurs vides avec NULL
dans la base de données. La valeur par défaut est False
.
Évitez d’utiliser null
pour des champs textuels comme CharField
ou TextField
. Un champ textuel avec null=True
implique qu’il y a deux valeurs possibles signifiant « pas de données » : NULL` et la chaîne vide. Dans la plupart des cas, il est redondant d’avoir deux valeurs possibles indiquant qu’il n’y a pas de données. La convention dans Django est d’utiliser la chaîne vide, pas NULL
. Une exception est lorsqu’un champ CharField
possède à la fois unique=True
et blank=True
. Dans ce cas, null=True
est nécessaire pour éviter des violations de contrainte unique quand plusieurs objets avec des valeurs vierges sont enregistrées.
Pour les champs textuels comme pour les champs non textuels, il est aussi nécessaire de définir blank=True
si vous voulez autoriser les valeurs vides dans les formulaires, puisque le paramètre null
ne se rapporte qu’au stockage dans la base de données (voir blank
).
Note
Lors de l’utilisation du moteur de base de données Oracle, c’est toujours la valeur NULL
qui est stockée pour signifier que la chaîne est vide, quelle que soit la valeur de cet attribut.
blank
¶
-
Field.
blank
¶
Si la valeur est True
, le champ peut être vide. La valeur par défaut est False
.
Notez que c’est différent de null
. null
est purement lié à la base de données, alors que blank
est lié à la validation. Quand un champ possède blank=True
, la validation de formulaire permet la saisie de valeurs vides. Quand un champ possède blank=False
, le champ doit être obligatoirement rempli.
choices
¶
-
Field.
choices
¶
Un objet dictionnaire ou itérable dans le format détaillé ci-dessous représentant les choix possibles pour ce champ. Si des choix sont fournis, ils sont contrôlés par la validation des modèles et le composant de formulaire par défaut sera une liste déroulante contenant ces choix au lieu de la boîte de saisie de texte standard.
S un dictionnaire est donné, l’élément clé est la valeur réelle à définir pour le modèle, et le second élément est la valeur visible par l’utilisateur. Par exemple :
YEAR_IN_SCHOOL_CHOICES = {
"FR": "Freshman",
"SO": "Sophomore",
"JR": "Junior",
"SR": "Senior",
"GR": "Graduate",
}
Il est aussi possible de transmettre une séquence composée elle-même d’itérables de tuples binaires (par ex. [(A1, B1), (A2, B2) ...]
) représentant les choix possibles pour ce champ. Le premier élément de chaque tuple est la valeur réelle à définir pour le modèle et le second élément est la valeur visible par l’utilisateur. Par exemple :
YEAR_IN_SCHOOL_CHOICES = [
("FR", "Freshman"),
("SO", "Sophomore"),
("JR", "Junior"),
("SR", "Senior"),
("GR", "Graduate"),
]
choices
peut aussi être défini comme un exécutable qui n’attend aucun argument et renvoie l’un des formats décrits ci-dessus. Par exemple :
def get_currencies():
return {i: i for i in settings.CURRENCIES}
class Expense(models.Model):
amount = models.DecimalField(max_digits=10, decimal_places=2)
currency = models.CharField(max_length=3, choices=get_currencies)
La transmission d’un exécutable à choices
peut être particulièrement indiqué lorsque par exemple les choix sont :
- le résultat d’opérations intensives en entrées/sorties (qui pourrait être éventuellement mis en cache), tel que l’interrogation d’une base de données (interne ou externe) ou l’accès à des choix provenant d’un fichier statique ;
- une liste globalement stable mais pouvant varier de temps à autre ou de projet en projet. On trouve par exemple dans cette catégorie des applications tierces fournissant un inventaire de valeurs bien connues, telles que des monnaies, des pays, des langues, des fuseaux horaires, etc.
La prise en charge de dictionnaires et d’objets exécutables a été ajoutée.
Il est généralement conseillé de définir les choix à l’intérieur de la classe d’un modèle et de définir des constantes judicieusement nommées pour chaque valeur :
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}
Bien qu’il soit possible de définir une liste de choix en dehors de la classe d’un modèle, puis de s’y référer, le fait de définir les choix et leurs étiquettes à l’intérieur de la classe du modèle permet de conserver toutes ces informations avec la classe qui les exploite ainsi que de faciliter la référence à ces choix (par exemple, Student.SOPHOMORE
fonctionnera partout où le modèle Student
a été importé).
Vous pouvez aussi arranger les choix possibles dans des groupes nommés qui pourront être utilisés à des fins d’organisation :
MEDIA_CHOICES = {
"Audio": {
"vinyl": "Vinyl",
"cd": "CD",
},
"Video": {
"vhs": "VHS Tape",
"dvd": "DVD",
},
"unknown": "Unknown",
}
La clé du dictionnaire est le nom utilisé pour le groupe et la valeur contient les choix à l’intérieur du groupe, consistant en valeur de champ et nom lisible par les humains pour chaque option. Les options groupées peuvent être combinées à des options non groupées dans un seul dictionnaire (comme l’option "unknown"
dans cet exemple).
Il est aussi possible d’utiliser une séquence, par ex. une liste de tuples binaires :
MEDIA_CHOICES = [
(
"Audio",
(
("vinyl", "Vinyl"),
("cd", "CD"),
),
),
(
"Video",
(
("vhs", "VHS Tape"),
("dvd", "DVD"),
),
),
("unknown", "Unknown"),
]
Notez que ces choix peuvent être constitués par n’importe quelle séquence, et pas nécessairement par une liste ou un tuple. Ceci vous permet de construire dynamiquement la liste des choix. Mais si vous commencer à bidouiller l’attribut choices
pour qu’il soit dynamique, il est probable qu’il soit plus judicieux d’utiliser une vraie table de base de données contenant une ForeignKey
. choices
est conçu pour les données statiques qui ne changent pas souvent, voire jamais.
Note
Une nouvelle migration est produite chaque fois que l’ordre des choix choices
change.
Pour chaque champ de modèle ayant l’option choices
, Django normalise les choix à une liste de tuples binaires et ajoute une méthode pour obtenir l’étiquette à afficher selon la valeur actuelle du champ. Voir get_FOO_display()
dans la documentation de l’API de base de données.
À l’exception des cas où blank=False
est défini pour le champ avec un contenu default
, une étiquette contenant "---------"
sera ajoutée à la liste de sélection. Pour surcharger ce comportement, ajoutez un tuple à choices
contenant None
. Par exemple, (None, 'Votre chaîne à afficher')
. Il est aussi possible d’utiliser une chaîne vide au lieu de None
lorsque c’est raisonnable, comme pour un champ CharField
.
Types énumératifs¶
De plus, Django fournit des types énumératifs dont vous pouvez hériter pour définir des choix de manière concise :
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,
default=YearInSchool.FRESHMAN,
)
def is_upperclass(self):
return self.year_in_school in {
self.YearInSchool.JUNIOR,
self.YearInSchool.SENIOR,
}
Ils fonctionnent de la même manière que le type enum
de la bibliothèque Python standard, mais avec quelques modifications :
Les valeurs des membres Enum sont des tuples de paramètres à utiliser lors de la construction du type de données concret. Django prend en charge l’ajout d’une chaîne supplémentaire à la fin du tuple pour servir de nom humainement lisible, dit
label
. Celabel
peut être une chaîne traduisible différée. Ainsi dans la plupart des cas, la valeur d’un membre sera un tuple binaire(valeur, étiquette)
. Voir ci-dessous pour un exemple de sous-classe de choix utilisant un type de données plus complexe. Si la valeur fournie n’est pas un tuple ou que le dernier élément n’est pas une chaîne (possiblement différée), la partielabel
est automatiquement générée à partir du nom du membre.Une propriété
.label
est ajoutée aux valeurs, pour renvoyer le nom humainement lisible.Un certain nombre de propriétés personnalisées sont ajoutées aux classes énumératives –
.choices
,.labels
,.values
, and.names
– pour faciliter l’accès aux listes des ces parties séparées de l’énumération.Avertissement
Ces noms de propriétés ne peuvent pas être employés comme noms de membres car cela occasionnerait un conflit.
L’utilisation de
enum.unique()
est forcé pour être sûr qu’une même valeur ne puisse pas être définie plusieurs fois. C’est peu probable pour une définition de choix d’un champ.
Notez que l’utilisation de YearInSchool.SENIOR
, YearInSchool['SENIOR']
, ou YearInSchool('SR')
pour accéder ou rechercher des membres d’une énumération fonctionne comme espéré, tout comme les propriétés .name
et .value
des membres.
Si vous n’avez pas besoin d’avoir des noms humainement lisibles et traduisibles, vous pouvez laisser faire la classe qui s’occupera de déduire le label
à partir du nom du membre (remplaçant les soulignements par des espaces et en mettant en majuscules les premières lettres de chaque mot) :
>>> class Vehicle(models.TextChoices):
... CAR = "C"
... TRUCK = "T"
... JET_SKI = "J"
...
>>> Vehicle.JET_SKI.label
'Jet Ski'
Comme le cas où les valeurs énumératives sont des nombres entiers est extrêmement courant, Django fournit une classe IntegerChoices
. Par exemple
class Card(models.Model):
class Suit(models.IntegerChoices):
DIAMOND = 1
SPADE = 2
HEART = 3
CLUB = 4
suit = models.IntegerField(choices=Suit)
Il est aussi possible de faire usage de l”API fonctionnelle des Enum avec la restriction que les étiquettes label
sont automatiquement générées comme expliqué précédemment :
>>> 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')]
Si vous avez besoin de prendre en charge un type de données concret autre que int
ou str
, vous pouvez hériter de Choices
et du type de données souhaité, comme par exemple utiliser date
pour un champ 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)"
Il y a quelques restrictions dont il faut tenir compte :
Les types énumératifs ne prennent pas en charge les groupes nommés.
Comme une énumération avec type de données concret exige que toutes les valeurs correspondent au type, le remplacement de l’étiquette vierge ne peut pas se faire en créant un membre avec une valeur
None
. Il faut plutôt définir l’attribut__empty__
de la classeclass Answer(models.IntegerChoices): NO = 0, _("No") YES = 1, _("Yes") __empty__ = _("(Unknown)")
La prise en charge de la transmission directe de types énumération dans choices
a été ajoutée.
db_column
¶
-
Field.
db_column
¶
Le nom de la colonne à utiliser pour ce champ dans la base de données. Si cet attribut est absent, Django utilise le nom du champ.
Si le nom de la colonne dans la base de données est un mot réservé en SQL ou s’il contient des caractères non autorisés dans le nom d’une variable Python (notamment, le trait d’union), ce n’est pas un souci. Django met entre guillemets les noms de table et de colonne de manière transparente.
db_comment
¶
-
Field.
db_comment
¶
Le commentaire sur la colonne de base de données à utiliser pour ce champ. C’est utile pour documenter les champs pour ceux qui ont un accès direct à la base de données et qui ne lisent pas forcément votre code Django. Par exemple
pub_date = models.DateTimeField(
db_comment="Date and time when the article was published",
)
db_default
¶
-
Field.
db_default
¶
La valeur par défaut générée en base de données pour ce champ. Il peut s’agir d’une valeur littérale ou d’une fonction de base de données, telle que Now
:
created = models.DateTimeField(db_default=Now())
Des expressions plus complexes peuvent être utilisées, tant qu’elles sont composées de valeurs littérales et de fonctions de bases de données :
month_due = models.DateField(
db_default=TruncMonth(
Now() + timedelta(days=90),
output_field=models.DateField(),
)
)
Les valeurs par défaut de bases de données ne peuvent pas se référer à d’autres champs ou modèles. Par exemple, ceci n’est pas valide :
end = models.IntegerField(db_default=F("start") + 50)
Si db_default
et Field.default
sont tous deux définis, default
aura la priorité lors de la création d’instance à partir de code Python. db_default
sera tout de même défini au niveau de la base de données et sera utilisé dans les cas d’insertion effectuée en dehors de l’ORM Django ou lors d’ajout de nouveaux champs dans une migration.
db_tablespace
¶
-
Field.
db_tablespace
¶
Le nom de l’espace de tables de base de données à utiliser pour l’index de ce
champ, si ce champ est indexé. La valeur par défaut est le réglage DEFAULT_INDEX_TABLESPACE
du projet, s’il est défini, ou l’attribut db_tablespace
du modèle, s’il existe. Si le moteur de base
de données ne prend pas en charge les espaces de tables, cette option est ignorée.
default
¶
-
Field.
default
¶
La valeur par défaut du champ. Cela peut être une valeur ou un objet exécutable. Dans ce dernier cas, l’objet est appelé lors de chaque création d’un nouvel objet.
La valeur par défaut ne peut pas être un objet mutant (instance de modèle, list
, set
, etc.), car toutes les nouvelles instances du modèle utiliseraient une référence vers la même instance de cet objet. Au lieu de cela, imbriquez la valeur par défaut souhaitée dans un exécutable. Par exemple, si vous vouliez indiquer un dict
par défaut pour un champ JSONField
, utilisez une fonction :
def contact_default():
return {"email": "to1@example.com"}
contact_info = JSONField("ContactInfo", default=contact_default)
Les fonctions lambda
ne peuvent pas être utilisées comme options de champs tels que default
car elles ne peuvent pas être sérialisées par les migrations. Consultez cette dernière documentation pour d’autres mises en garde.
Pour les champs comme ForeignKey
qui correspondent à des instances de modèles, les valeurs par défaut devraient être la valeur du champ qu’ils représentent (pk
sauf si to_field
est défini) et non pas des instances de modèles.
La valeur par défaut est utilisée lorsque de nouvelles instances de modèle sont créées et qu’aucune valeur n’est fournie pour le champ. Lorsque le champ est une clé primaire, la valeur par défaut est aussi utilisée si le champ est défini à None
.
La valeur par défaut peut aussi être utilisée au niveau de la base de données avec Field.db_default
.
editable
¶
-
Field.
editable
¶
Si False
, le champ ne sera pas affiché dans l’administration de Django, ni dans d’éventuels formulaires basés sur ModelForm
. Il sera aussi omis dans la phase de validation de modèle. La valeur par défaut est True
.
error_messages
¶
-
Field.
error_messages
¶
Le paramètre error_messages
permet de redéfinir les messages par défaut que le champ renvoie. Passez un dictionnaire dont les clés correspondent aux messages d’erreur que vous voulez redéfinir.
Les clés des messages d’erreur comprennent null
, blank
, invalid
, invalid_choice
, unique
et unique_for_date
. D’autres clés de messages d’erreur sont définies pour chaque champ de la section types de champs ci-dessous.
Ces messages d’erreur ne se propagent souvent pas aux formulaires. Voir Considérations sur les messages d’erreur des modèles.
help_text
¶
-
Field.
help_text
¶
Texte d’aide supplémentaire à afficher avec le composant de formulaire. Utile pour la documentation même si le champ n’est pas utilisé dans un formulaire.
Notez que le HTML contenu dans cette valeur n’est pas échappé dans les formulaires générés automatiquement. Cela vous permet d’inclure du HTML dans help_text
si vous le souhaitez. Par
exemple :
help_text = "Please use the following format: <em>YYYY-MM-DD</em>."
Accessoirement, vous pouvez utiliser du texte brut et django.utils.html.escape()
pour échapper n’importe quel caractère spécial HTML. Assurez-vous d’échapper tout texte d’aide qui proviendrait d’utilisateurs non fiables afin d’éviter des attaques de script inter-site.
primary_key
¶
-
Field.
primary_key
¶
Si la valeur est True
, ce champ représentera la clé primaire du modèle.
Si vous n’indiquez aucun paramètre primary_key=True
dans les champs d’un modèle, Django ajoute automatiquement un champ pour constituer une clé primaire ; il n’est donc pas nécessaire de définir le paramètre primary_key=True
pour un champ sauf si vous souhaitez modifier le comportement par défaut de clé primaire automatique. Le type des champs clé primaire auto-générés peut être défini par application dans AppConfig.default_auto_field
ou globalement dans le réglage DEFAULT_AUTO_FIELD
. Pour en savoir plus, consultez Champs clé primaire automatiques.
primary_key=True
implique null=False
et unique=True
. Une seule clé primaire est autorisée par objet.
Le champ de clé primaire est en lecture seule. Si vous modifiez la valeur de la clé primaire d’un objet existant et que vous l’enregistrez, un nouvel objet est créé en parallèle à l’ancien.
Le champ de clé primaire est défini à None
lors de la suppression
d’un objet.
unique
¶
-
Field.
unique
¶
Si la valeur est True
, ce champ doit être unique dans toute la table.
Cet attribut est appliqué au niveau de la base de données ainsi que dans la validation des modèles. Si vous essayez d’enregistrer une instance d’un modèle avec une valeur d’un champ unique
dupliquée, une exception django.db.IntegrityError
sera levée par la méthode save()
du modèle.
Cette option est valide pour tous les types de champs, sauf pour ManyToManyField
et OneToOneField
.
Notez que lorsque unique
vaut True
, il n’est pas nécessaire de définir db_index
, car unique
implique qu’un index sera créé.
unique_for_date
¶
-
Field.
unique_for_date
¶
Indiquez le nom d’un champ de type DateField
ou DateTimeField
comme valeur pour cette option, pour rendre obligatoire l’unicité de la valeur de ce champ en fonction de la valeur du champ date
indiqué.
Par exemple, si vous avez un champ title
qui a unique_for_date="pub_date"
, Django n’autorise pas la saisie de deux enregistrements avec le même title
et la même pub_date
.
Notez que si cet attribut est défini avec un objet DateTimeField
, seule la partie date du champ est prise en compte. De plus, lorsque USE_TZ
vaut True
, le contrôle est effectué dans le fuseau horaire en cours au moment où l’objet est enregistré.
Cette contrainte est appliquée par Model.validate_unique()
pendant la validation des modèles, et non pas au niveau de la base de données. Si une contrainte unique_for_date
implique des champs qui ne font pas partie d’un formulaire ModelForm
(par exemple si l’un des champs figure dans exclude
ou que son attribut editable
vaut False
), Model.validate_unique()
passe outre la validation de la contrainte concernée.
unique_for_month
¶
-
Field.
unique_for_month
¶
Comme unique_for_date
, mais requiert que le champ soit unique en rapport au mois du champ date.
unique_for_year
¶
-
Field.
unique_for_year
¶
Comme unique_for_date
et unique_for_month
, mais avec l’année du champ date.
verbose_name
¶
-
Field.
verbose_name
¶
Un nom humainement compréhensible pour le champ. Si cet attribut n’est pas renseigné, Django le crée automatiquement en utilisant le nom d’attribut du champ, en convertissant les soulignements en espaces. Voir noms de champs verbeux.
validators
¶
-
Field.
validators
¶
Une liste de validateurs à exécuter pour ce champ. Consultez la documentation des validateurs pour plus d’informations.
Types de champs¶
AutoField
¶
-
class
AutoField
(**options)¶
Un champ IntegerField
qui incrémente automatiquement sa valeur par rapport aux identifiants disponibles. Vous n’avez habituellement pas besoin d’utiliser ce champ directement ; un champ clé primaire est automatiquement ajouté au modèle s’il n’est pas explicitement défini. Voir Champs clé primaire automatiques.
BigAutoField
¶
-
class
BigAutoField
(**options)¶
Un entier 64 bits, ressemblant à un AutoField
sauf qu’il garantit la couverture des nombres de 1
à 9223372036854775807
.
BigIntegerField
¶
-
class
BigIntegerField
(**options)¶
Un entier 64 bits, ressemblant à un IntegerField
sauf qu’il garantit la couverture des nombres de -9223372036854775808
à 9223372036854775807
. Le composant de formulaire par défaut de ce champ est un NumberInput
.
BinaryField
¶
-
class
BinaryField
(max_length=None, **options)¶
Un champ pour stocker des données binaires brutes. Il peut recevoir des données de type bytes
, bytearray
ou memoryview
.
Par défaut, BinaryField
définit editable
à False
, auquel cas il ne peut être inclus dans un formulaire ModelForm
.
-
BinaryField.
max_length
¶ Facultatif. La taille maximale (en octets) du champ. Cette longueur maximale est contrôlée par la validation de Django en utilisant
MaxLengthValidator
.
Usage abusif de BinaryField
Bien qu’il puisse être tentant de vouloir stocker des fichiers dans la base de données, il s’agit d’une mauvaise idée dans 99 % des cas. Ce champ n’est pas une solution de remplacement d’une bonne gestion des fichiers statiques.
BooleanField
¶
-
class
BooleanField
(**options)¶
Un champ vrai/faux.
Le composant de formulaire par défaut de ce champ est un CheckboxInput
, ou NullBooleanSelect
si null=True
.
La valeur par défaut de BooleanField
est None
lorsque Field.default
n’est pas défini.
CharField
¶
-
class
CharField
(max_length=None, **options)¶
Un champ pour les chaînes de caractères, courtes ou longues.
Pour une grande quantité de texte, utilisez TextField
.
Le composant de formulaire par défaut de ce champ est un TextInput
.
CharField
offre les paramètres supplémentaires suivants :
-
CharField.
max_length
¶ La longueur maximale du champ (en caractères). La longueur
max_length
est garantie au niveau de la base de données et dans la validation de Django grâce àMaxLengthValidator
. Ce paramètre est obligatoire pour tous les moteurs de base de données inclus dans Django à l’exception de PostgreSQL qui prend en charge les colonnesVARCHAR
illimitées.Note
Si vous écrivez une application qui doit être portable sur plusieurs moteurs de base de données, il faut savoir qu’il y a des restrictions à propos de
max_length
pour certains de ces moteurs. Référez-vous aux notes sur les moteurs de base de données pour plus de détails.Changed in Django 4.2:La prise en charge des colonnes
VARCHAR
illimitées a été ajoutée pour PostgreSQL.
-
CharField.
db_collation
¶ Facultatif. Le nom de collation de base de données pour le champ.
Note
Les noms de collation ne sont pas standardisés. De fait, ils ne sont pas portables entre les différents moteurs de base de données.
Oracle
Oracle ne prend en charge les collations que lorsque le paramètre d’initialisation de base de données
MAX_STRING_SIZE
est défini àEXTENDED
.
DateField
¶
-
class
DateField
(auto_now=False, auto_now_add=False, **options)¶
Une date, représentée en Python par une instance de datetime.date
. Accepte quelques paramètres supplémentaires et facultatifs :
-
DateField.
auto_now
¶ Assigne automatiquement la valeur du champ à la date du jour lors de chaque enregistrement de l’objet. Utile pour les horodatages de « dernière modification ». Notez que c’est toujours la date actuelle qui est utilisée ; il ne s’agit pas seulement d’une valeur par défaut que l’on peut surcharger.
La mise à jour automatique de ce champ ne se produit que lors de l’appel à
Model.save()
. Le champ n’est pas mis à jour lors de mises à jour d’autres champs par d’autres façons comme par exempleQuerySet.update()
, bien qu’il soit possible de spécifier explicitement une valeur pour ce champ lors d’une telle mise à jour.
-
DateField.
auto_now_add
¶ Assigne automatiquement la valeur du champ à la date du jour lors du premier enregistrement de l’objet. Utile pour les horodatages de date de création. Notez que c’est toujours la date actuelle qui est utilisée ; il ne s’agit pas seulement d’une valeur par défaut que l’on peut surcharger. Ainsi, même si vous définissez une valeur pour ce champ lors de la création de l’objet, il sera ignoré. Si vous voulez pouvoir modifier ce champ, utilisez ce qui suit au lieu de définir
auto_now_add=True
:- Pour un champ
DateField
:default=date.today
- dedatetime.date.today()
- Pour un champ
DateTimeField
:default=timezone.now
- dedjango.utils.timezone.now()
- Pour un champ
Le composant de formulaire par défaut de ce champ est un DateInput
. L’interface d’administration ajoute un calendrier JavaScript ainsi qu’un raccourci pour « Aujourd’hui ». Contient une clé supplémentaire de message d’erreur invalid_date
.
Les options auto_now_add
, auto_now
et default
sont mutuellement exclusives. Toute combinaison de ces options produira une erreur.
Note
Avec l’implémentation actuelle, si auto_now
ou auto_now_add
sont activés, les paramètres de champ suivants sont définis automatiquement : editable=False
et blank=True
.
Note
Les options auto_now
et auto_now_add
utilisent toujours la date dans le fuseau horaire par défaut au moment de la création ou de la mise à jour. Si vos besoins sont différents, vous pouvez envisager d’utiliser votre propre fonction de valeur par défaut ou de surcharger save()
au lieu de faire appel à auto_now
ou auto_now_add
. Ou encore d’utiliser un champ DateTimeField
au lieu d’un champ DateField
et de décider de la manière de gérer la conversion d’une heure/date vers une date au moment de son affichage.
DateTimeField
¶
-
class
DateTimeField
(auto_now=False, auto_now_add=False, **options)¶
Une date et une heure, représentées en Python par une instance de datetime.datetime
. Ce champ accepte les mêmes paramètres supplémentaires que le champ DateField
.
Le composant de formulaire par défaut de ce champ est un DateTimeInput
. L’interface d’administration utilise deux composants TextInput
séparés avec des raccourcis JavaScript.
DecimalField
¶
-
class
DecimalField
(max_digits=None, decimal_places=None, **options)¶
Un nombre décimal de taille fixe, représenté en Python par une instance de Decimal
. Les saisies sont validées en utilisant DecimalValidator
.
Il requiert les paramètres obligatoires suivants :
-
DecimalField.
max_digits
¶ Le nombre maximum de chiffres autorisés dans le nombre. Notez que ce nombre doit être plus grand ou égal à
decimal_places
.
-
DecimalField.
decimal_places
¶ Le nombre de décimales à stocker avec le nombre.
Par exemple, pour enregistrer un nombre jusqu’à 999.99
avec une précision de 2 chiffres après la virgule, vous devriez utiliser :
models.DecimalField(..., max_digits=5, decimal_places=2)
Et pour enregistrer un nombre jusqu’à un milliard environ avec une précision de 10 chiffres après la virgule :
models.DecimalField(..., max_digits=19, decimal_places=10)
Le composant de formulaire par défaut de ce champ est un NumberInput
lorsque localize
vaut False
, ou TextInput
dans le cas contraire.
Note
Pour plus d’informations sur les différences entre les classes FloatField
et DecimalField
, consultez FloatField vs. DecimalField. IL est aussi important d’être conscient des limites de SQLite à propos des champs décimaux.
DurationField
¶
-
class
DurationField
(**options)¶
Un champ pour stocker des périodes de temps, représentées en Python par des objets timedelta
. Avec PostgreSQL, le type de données utilisé est un interval
et avec Oracle, le type de données est INTERVAL DAY(9) TO SECOND(6)
. Sinon, c’est un grand nombre entier bigint
de microsecondes qui est utilisé.
Note
L’arithmétique des champs DurationField
fonctionne la plupart du temps. Cependant, pour toutes les bases de données autres que PostgreSQL, la comparaison de valeurs d’un champ DurationField
avec l’arithmétique des instances DateTimeField
ne fonctionne pas comme on pourrait l’espérer.
EmailField
¶
-
class
EmailField
(max_length=254, **options)¶
Un champ CharField
qui vérifie que sa valeur est une adresse électronique valide en utilisant EmailValidator
.
FileField
¶
-
class
FileField
(upload_to='', storage=None, max_length=100, **options)¶
Un champ de fichier à téléverser.
Note
Le paramètre primary_key
n’est pas pris en charge et génère une erreur s’il est utilisé.
Il offre les paramètres facultatifs suivants :
-
FileField.
upload_to
¶ Cet attribut permet de définir le répertoire de téléversement et le nom de fichier. Il peut être défini de deux manières. Dans les deux cas, la valeur est transmise à la méthode
Storage.save()
.Si vous indiquez une valeur textuelle ou un chemin
Path
, la valeur peut contenir des chaînes de formatstrftime()
qui seront remplacées par la date/heure du fichier téléversé (permettant ainsi de ne pas remplir exagérément le répertoire indiqué). Par exemple :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/")
Si vous utilisez le stockage par défaut
FileSystemStorage
, la valeur textuelle sera ajoutée au cheminMEDIA_ROOT
pour déterminer l’emplacement du système de fichiers local où les fichiers téléversés seront stockés. Si vous utilisez un autre stockage, vérifiez la documentation de ce dernier pour savoir comment il traiteupload_to
.upload_to
peut aussi être un objet exécutable, comme une fonction. Il sera appelé pour obtenir le chemin de téléversement, incluant le nom du fichier. Cet objet exécutable doit accepter deux paramètres et renvoyer un chemin de type Unix (avec des barres obliques) qui sera transmis au système de stockage. Les deux paramètres sont :Paramètre Description instance
Une instance du modèle où le champ
FileField
est défini. Plus spécifiquement, il s’agit de l’instance à laquelle le fichier actuel est joint.Dans la plupart des cas, cet objet n’aura pas encore été enregistré dans la base de données, donc en cas d’utilisation du champ
AutoField
par défaut, il pourrait bien ne pas avoir encore de valeur pour le champ de sa clé primaire.filename
Le nom donné originellement au fichier. Sa prise en compte dans la détermination du chemin d’accès final n’est pas obligatoire. Par exemple :
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)
-
FileField.
storage
¶ Un objet de stockage ou un objet exécutable qui renvoie un objet de stockage. Celui-ci prend en charge l’enregistrement et la récupération des fichiers. Consultez Gestion des fichiers pour plus de détails sur la manière de fournir un tel objet.
Le composant de formulaire par défaut de ce champ est un ClearableFileInput
.
L’utilisation d’un FileField
ou d’un ImageField
(voir ci-après) dans une classe de modèle se fait en quelques étapes :
- Dans votre fichier de réglages, vous devez indiquer dans
MEDIA_ROOT
le chemin d’accès absolu vers un répertoire où Django peut enregistrer les fichiers téléversés (pour des raisons de performance, ces fichiers ne sont pas stockés en base de données). Indiquez dansMEDIA_URL
l’URL publique de base correspondant à ce répertoire. Assurez-vous que ce répertoire soit accessible en écriture par l’utilisateur du serveur web. - Ajoutez le champ
FileField
ouImageField
à votre modèle, en définissant l’optionupload_to
pour indiquer dans quel sous-répertoire deMEDIA_ROOT
les fichiers doivent être téléversés. - Tout ce qui sera stocké dans la base de données est le chemin d’accès au fichier (relatif à
MEDIA_ROOT
). Il est très commode et courant d’utiliser l’attributurl
offert par Django. Par exemple, considérant unImageField
nommémug_shot
, vous pouvez obtenir l’URL absolue de cette image dans un gabarit avec{{ object.mug_shot.url }}
.
Par exemple, supposons que MEDIA_ROOT
contient '/home/media'
et que la valeur de upload_to
est 'photos/%Y/%m/%d'
. La partie '%Y/%m/%d'
de upload_to
est du formatage strftime()
; '%Y'
correspond à l’année sur quatre chiffres, '%m'
correspond au mois sur deux chiffres et '%d'
correspond au jour sur deux chiffres. Si vous téléversez un fichier le 15 janvier 2007, il sera enregistré dans le répertoire /home/media/photos/2007/01/15
.
Si vous souhaitez obtenir le nom du fichier téléversé ou sa taille, vous pouvez utiliser ses attributs
name
et size
respectivement. Pour plus d’informations sur les attributs et méthodes disponibles, consultez la référence de la classe File
et le guide thématique Gestion des fichiers.
Note
Le fichier est enregistré durant la phase d’enregistrement du modèle dans la base de données, il n’est donc pas possible de se baser sur le nom de fichier réel sur le disque tant que le modèle lui-même n’a pas été enregistré.
L’URL relative du fichier téléversé peut être obtenue en utilisant l’attribut url
. En interne, c’est la méthode url()
de la classe Storage
sous-jacente qui est appelée.
Notez que chaque fois que vous avez affaire à des fichiers téléversés, vous devriez faire très attention à l’endroit où vous les enregistrez ainsi qu’à leur type, pour éviter toute faille de sécurité. Vérifiez tous les fichiers téléversés, ainsi vous serez sûr que ces fichiers sont bien ce qu’ils doivent être. Par exemple, si vous laissez quelqu’un téléverser aveuglément des fichiers sans les valider à destination d’un répertoire se trouvant sous la racine des documents de votre serveur web, cette personne pourrait envoyer un script CGI ou PHP et le faire exécuter en visitant son URL sur votre site. Ne permettez pas cela.
Notez également que même l’envoi d’un fichier HTML peut poser des problèmes de sécurité équivalents aux attaques XSS ou CSRF, car ces fichiers peuvent être interprétés par un navigateur (même si le serveur n’est pas impliqué dans ce cas).
Les instances de FileField
sont créées en tant que colonnes varchar
dans la base de données avec une longueur par défaut maximale de 100 caractères. Comme pour d’autres champs, vous pouvez modifier la taille maximale en utilisant le paramètre max_length
.
FileField
et FieldFile
¶
-
class
FieldFile
¶
Lorsque vous accédez à un FileField
d’un modèle, vous recevez une instance de FieldFile
comme substitut d’accès au fichier sous-jacent.
L’API de FieldFile
reflète celle de File
, avec une différence clé : l’objet adapté par la classe n’est pas forcément une adaptation de l’objet fichier natif de Python. C’est au contraire une adaptation du résultat de la méthode Storage.open()
, qui peut être un objet File
ou une implémentation d’un stockage personnalisé de l’API de File
.
En plus de l’API héritée de File
, comme read()
et write()
, FieldFile
comprend plusieurs méthodes pouvant être utilisées pour interagir avec le fichier sous-jacent :
Avertissement
Deux méthodes de cette classe, save()
et delete()
enregistrent par défaut l’objet modèle du FieldFile
associé dans la base de données.
-
FieldFile.
name
¶
Le nom du fichier contenant le chemin relatif depuis la racine de Storage
du champ FileField
associé.
-
FieldFile.
path
¶
Une propriété en lecture seule pour accéder au chemin du fichier sur le système de fichiers local en appelant la méthode path()
de la classe Storage
sous-jacente.
-
FieldFile.
size
¶
Le résultat de la méthode sous-jacente Storage.size()
.
-
FieldFile.
url
¶
Une propriété en lecture seule pour accéder à l’URL relative du fichier, au travers de l’appel à la méthode url()
de la classe Storage
sous-jacente.
-
FieldFile.
open
(mode='rb')¶
Ouvre ou réouvre le fichier associé à cette instance dans le mode
spécifié. Au contraire de la méthode Python standard open()
, elle ne renvoie pas de descripteur de fichier.
Comme le fichier sous-jacent est ouvert implicitement lors de son accès, il peut être inutile d’appeler cette méthode, sauf si l’on veut réinitialiser le pointeur du fichier sous-jacent ou que l’on veut changer le mode
.
-
FieldFile.
close
()¶
Même comportement que la méthode file.close()
standard de Python et ferme le fichier associé à l’instance actuelle.
-
FieldFile.
save
(name, content, save=True)¶
Cette méthode accepte un nom de fichier et le contenu du fichier, les transmet à la classe de stockage du champ puis associe le fichier ainsi stocké avec le champ du modèle. Si vous souhaitez attribuer manuellement des données de fichier avec des instances FileField
d’un modèle, la méthode save()
est utilisée pour rendre persistantes ces données de fichier.
Requiert deux paramètres obligatoires : name
correspondant au nom du fichier et content
qui représente un objet contenant le contenu du fichier. Le paramètre facultatif save
indique si l’instance de modèle doit être enregistrée après la modification du fichier associé à ce champ. Sa valeur par défaut est True
.
Notez que le paramètre content
doit être une instance de django.core.files.File
, et non pas de l’objet file
de Python. Vous pouvez construire une instance de File
à partir d’un objet Python file
existant comme ceci :
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)
Ou il est aussi possible de le construire à partir d’une chaîne de caractères Python comme ceci :
from django.core.files.base import ContentFile
myfile = ContentFile("hello world")
Pour plus d’informations, voir Gestion des fichiers.
-
FieldFile.
delete
(save=True)¶
Supprime le fichier associé à cette instance et efface tous les attributs du champ. Remarque : cette méthode ferme le fichier s’il se trouve être ouvert lorsque delete()
est appelée.
Le paramètre facultatif save
indique si l’instance de modèle doit être enregistrée après la suppression du fichier associé à ce champ. Sa valeur par défaut est True
.
Notez que lorsqu’un modèle est supprimé, les fichiers liés ne sont pas supprimés. Si vous devez effacer les fichiers orphelins, c’est à vous de le faire (par exemple avec une commande de gestion personnalisée lancée manuellement ou programmée de manière périodique par un outil tel que cron).
FilePathField
¶
-
class
FilePathField
(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options)¶
Un CharField
dont les choix sont limités aux noms de fichiers dans un répertoire déterminé du système de fichiers. Il possède quelques paramètres particuliers, dont le premier est obligatoire :
-
FilePathField.
path
¶ Obligatoire. Le chemin d’accès absolu vers le répertoire dont le contenu fournit la source des choix du
FilePathField
. Exemple :"/home/images"
.path
peut aussi être un exécutable, comme une fonction pour définir le chemin dynamiquement au moment de l’exécution. Exempleimport 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)
-
FilePathField.
match
¶ Facultatif. Une expression régulière sous forme de chaîne de caractères qui sera utilisée par
FilePathField
pour filtrer les noms de fichier. Notez que cette expression régulière sera appliquée au nom de fichier seul, et non pas à son chemin d’accès absolu. Exemple :"foo.*\.txt$"
correspond au fichierfoo23.txt
, mais pas àbar.txt
ni àfoo23.png
.
-
FilePathField.
recursive
¶ Facultatif. Vaut
True
ouFalse
(valeur par défaut). Indique si tous les sous-répertoires depath
doivent être inclus.
-
FilePathField.
allow_files
¶ Facultatif. Vaut
True
(valeur par défaut) ouFalse
. Indique si les fichiers de l’emplacement spécifié doivent être inclus. Il faut que l’une des deux valeurs, ce champ ouallow_folders
, soitTrue
.
-
FilePathField.
allow_folders
¶ Facultatif. Vaut
True
ouFalse
(valeur par défaut). Indique si tous les répertoires à l’intérieur de l’emplacement spécifié doivent être inclus. Il faut que l’une des deux valeurs, ce champ ouallow_files
, soitTrue
.
Le piège potentiel est que match
s’applique au nom du fichier uniquement, et non pas au chemin d’accès absolu. Donc, dans cet exemple :
FilePathField(path="/home/images", match="foo.*", recursive=True)
… correspondra à /home/images/foo.png
mais pas à /home/images/foo/bar.png
car match
s’applique uniquement au nom du fichier (foo.png
et bar.png
).
Les instances de FilePathField
sont créées en tant que colonnes varchar
dans la base de données avec une longueur par défaut maximale de 100 caractères. Comme pour d’autres champs, vous pouvez modifier la taille maximale en utilisant le paramètre max_length
.
FloatField
¶
-
class
FloatField
(**options)¶
Un nombre flottant représenté en Python par une instance de float
.
Le composant de formulaire par défaut de ce champ est un NumberInput
lorsque localize
vaut False
, ou TextInput
dans le cas contraire.
FloatField
vs. DecimalField
La classe FloatField
est parfois confondue avec la classe DecimalField
. Même si elles représentent les deux des nombres réels, elles les stockent de manière différente. FloatField
utilise en interne le type Python float
alors que DecimalField
utilise le type Python Decimal
. Pour plus d’informations sur la différence entre ces deux types, consultez la documentation Python du module decimal
.
GeneratedField
¶
-
class
GeneratedField
(expression, output_field, db_persist=None, **kwargs)¶
Un champ qui est toujours calculé en fonction d’autres champs du même modèle. Ce champ est géré et mis à jour par la base de données elle-même. Il utilise la syntaxe SQL GENERATED ALWAYS
.
Il existe deux sortes de colonnes auto-générées : persistantes et virtuelles. Une colonne auto-générée persistante est calculée au moment de son écriture (insertion/mise à jour) et occupe de l’espace comme si c’était une colonne normale. Une colonne auto-générée virtuelle n’occupe pas d’espace disque et est calculée au moment de sa lecture. Ainsi, une colonne auto-générée virtuelle est pareille à une vue, alors qu’un colonne auto-générée persistante est pareille à une vue matérialisée.
-
GeneratedField.
expression
¶ Une
Expression
utilisée par la base de données pour définir automatiquement la valeur du champ chaque fois que le modèle est modifié.Les expressions doivent être déterministes et se limiter à référencer des champs du même modèle (dans la même table de base de données). Les champs auto-générés ne peuvent pas faire référence à d’autres champs auto-générés. Les moteurs de base de données peuvent imposer des restrictions supplémentaires.
-
GeneratedField.
output_field
¶ Une instance de champ de modèle pour définir le type de données du champ.
-
GeneratedField.
db_persist
¶ Détermine si la colonne de base de données doit être stockée comme une colonne réelle. Si
False
, la colonne se comporte comme une colonne virtuelle et n’occupe aucun espace de stockage de base de données.PostgreSQL ne prend en charge que les colonnes persistantes. Oracle ne prend en charge que les colonnes virtuelles.
Actualisation des données
Comme la base de données recalcule toujours la valeur, l’objet doit être rechargé pour accéder à la nouvelle valeur après avoir appelé save()
, en utilisant par exemple refresh_from_db()
.
Limites des bases de données
Il y a de nombreuses restrictions spécifiques aux diverses bases de données pour les champs auto-générés que Django ne contrôle pas, ce qui peut générer des erreurs au niveau de la base de données. Par exemple, PostgreSQL exige des fonctions et opérateurs référencés dans une colonne générée qu’ils soient marqués comme IMMUTABLE
.
Vous devriez toujours vérifier que expression
est prise en charge pour votre base de données. Consultez les documentations MariaDB, MySQL, Oracle, PostgreSQL ou SQLite.
GenericIPAddressField
¶
-
class
GenericIPAddressField
(protocol='both', unpack_ipv4=False, **options)¶
Une adresse IPv4 ou IPv6 au format textuel (par ex. 192.0.2.30
ou 2a02:42fe::4
). Le composant de formulaire par défaut de ce champ est un TextInput
.
La normalisation d’adresse IPv6 respecte la section 2.2 de la RFC 4291#section-2.2, y compris l’utilisation du format IPv4 suggéré dans le 3e paragraphe de cette section, comme ::ffff:192.0.2.0
. Par exemple, 2001:0::0:01
sera normalisé en 2001::1
et ::ffff:0a0a:0a0a
en ::ffff:10.10.10.10
. Tous les caractères sont convertis en minuscules.
-
GenericIPAddressField.
protocol
¶ Limite la validité des saisies au protocole indiqué. Les valeurs possibles sont
'both'
(les deux protocoles acceptés, valeur par défaut),'IPv4'
ou'IPv6'
.
-
GenericIPAddressField.
unpack_ipv4
¶ Décode les adresses IPv4 mappées comme
::ffff:192.0.2.1
. Si cette option est activée, cette adresse serait décodée en192.0.2.1
. L’option est désactivée par défaut. Utilisable uniquement quandprotocol
est défini à'both'
.
Si vous autorisez les valeurs vierges, vous devez aussi autoriser les valeurs nulles, car les valeurs vierges sont stockées par une valeur nulle.
ImageField
¶
-
class
ImageField
(upload_to=None, height_field=None, width_field=None, max_length=100, **options)¶
Hérite de tous les attributs et méthodes de FileField
, mais valide également que l’objet téléversé est une image valide.
En complément des attributs spéciaux disponibles pour FileField
, un champ ImageField
possède aussi les attributs height
et width
.
Pour faciliter l’interrogation de ces attributs, ImageField
possède les paramètres facultatifs suivants :
-
ImageField.
height_field
¶ Le nom d’un champ du modèle qui sera automatiquement renseigné avec la hauteur de l’image à chaque enregistrement de l’instance du modèle.
-
ImageField.
width_field
¶ Le nom d’un champ du modèle qui sera automatiquement renseigné avec la largeur de l’image à chaque enregistrement de l’instance du modèle.
Nécessite la bibliothèque Pillow.
Les instances de ImageField
sont créées en tant que colonnes varchar
dans la base de données avec une longueur par défaut maximale de 100 caractères. Comme pour d’autres champs, vous pouvez modifier la taille maximale en utilisant le paramètre max_length
.
Le composant de formulaire par défaut de ce champ est un ClearableFileInput
.
IntegerField
¶
-
class
IntegerField
(**options)¶
Un nombre entier. Les valeurs de -2147483648
à 2147483647
sont acceptées par toutes les base de données prises en charge par Django.
Il utilise MinValueValidator
et MaxValueValidator
pour contrôler les saisies en fonction des valeurs admises par la base de données par défaut.
Le composant de formulaire par défaut de ce champ est un NumberInput
lorsque localize
vaut False
, ou TextInput
dans le cas contraire.
JSONField
¶
-
class
JSONField
(encoder=None, decoder=None, **options)¶
Un champ pour stocker des données JSON encodées. En Python, les données sont représentées dans leur format natif correspondant : dictionnaires, listes, chaînes, nombres, booléens et None
.
JSONField
est pris en charge avec MariaDB, MySQL, Oracle, PostgreSQL et SQLite (avec l’extension JSON1 activée).
-
JSONField.
encoder
¶ Une sous-classe facultative de py:class:json.JSONEncoder pour sérialiser les types de données non prises en charge par le sérialiseur JSON standard (par ex.
datetime.datetime
ouUUID
). Par exemple, vous pouvez utiliser la classeDjangoJSONEncoder
.Contient
json.JSONEncoder
par défaut.
-
JSONField.
decoder
¶ Une sous-classe facultative de
json.JSONDecoder
pour désérialiser la valeur obtenue de la base de données. La valeur sera dans le format choisi par le codeur personnalisé (une chaîne la plupart du temps). La désérialisation pourrait devoir tenir compte de l’incertitude liée au type de la valeur d’entrée. Par exemple, vous courez le risque de renvoyer un objetdatetime
qui était en fait une chaîne qui était fortuitement au même format que celui choisi pour les objetsdatetime
.Contient
json.JSONDecoder
par défaut.
Pour interroger les champs JSONField
dans la base de données, voir Interrogation de JSONField.
Valeur par défaut
Si vous donnez une valeur default
à ce champ, assurez-vous que ce soit un objet exécutable tel que dict
ou une fonction qui renvoie à chaque fois un nouvel objet. L’utilisation d’un objet mutable tel que default={}
ou defauilt=[]
n’est pas correct car cela crée une valeur par défaut mutable qui est alors partagée entre toutes les instances.
Indexation
Index
et Field.db_index
créent tous deux un index B-tree, qui n’est pas particulièrement utile lorsqu’on interroge un champ JSONField
. Avec PostgreSQL uniquement, il est possible d’utiliser un index GinIndex
qui est mieux adapté.
Utilisateurs de PostgreSQL
PostgreSQL dispose de deux types de données natifs basés sur JSON : json
et jsonb
. La principale différence entre eux est la façon dont ils sont stockés et comment ils peuvent être interrogés. Le champ json
de PostgreSQL est stocké comme la représentation textuelle d’origine du JSON et doit être décodé à la volée lorsqu’on l’interroge sur la base de clés. Le champ jsonb
est stocké en fonction de la structure réelle du JSON qui permet l’indexation. En contre-partie, l’écriture du champ jsonb
est légèrement plus coûteuse. JSONField
utilise le type jsonb
.
PositiveBigIntegerField
¶
-
class
PositiveBigIntegerField
(**options)¶
Comme un PositiveIntegerField
, mais n’autorise que des valeurs plus petites qu’un certain plafond (dépendant du moteur de base de données). Toutes les valeurs de 0
à 9223372036854775807
sont acceptées par toutes les bases de données prises en charge officiellement par Django.
PositiveIntegerField
¶
-
class
PositiveIntegerField
(**options)¶
Comme un champ IntegerField
, mais doit être un entier positif ou zéro (0
). Les valeurs de 0
à 2147483647
sont acceptées par toutes les base de données prises en charge par Django. La valeur 0
est acceptée pour des raisons de rétrocompatibilité.
PositiveSmallIntegerField
¶
-
class
PositiveSmallIntegerField
(**options)¶
Comme un PositiveIntegerField
, mais n’autorise que des valeurs plus petites qu’un certain plafond (dépendant du moteur de base de données). Toutes les valeurs de 0
à 32767
sont acceptées par toutes les bases de données prises en charge officiellement par Django.
SlugField
¶
-
class
SlugField
(max_length=50, **options)¶
Slug est un terme anglophone de journalisme. Un slug est une brève étiquette d’un contenu, composée uniquement de lettres, de chiffres, de soulignements ou de tirets. Ils sont généralement utilisés dans les URL.
Comme pour le champ CharField
, vous pouvez indiquer le paramètre max_length
(lisez les notes à propos de la portabilité entre bases de données de max_length
). Si max_length
n’est pas précisé, Django utilise la valeur 50 par défaut.
L’option Field.db_index
est implicitement égale à True
.
Il est souvent pratique de pouvoir automatiquement renseigner un SlugField en se basant sur la valeur d’un autre attribut. Vous pouvez le faire dans l’interface d’administration en utilisant prepopulated_fields
.
Il utilise validate_slug
ou validate_unicode_slug
pour la validation.
-
SlugField.
allow_unicode
¶ Si la valeur est
True
, le champ accepte des lettres Unicode en plus des lettres ASCII de base. La valeur par défaut estFalse
.
SmallAutoField
¶
-
class
SmallAutoField
(**options)¶
Comme un AutoField
, mais n’autorise que des valeurs plus petites qu’un certain plafond (dépendant du moteur de base de données). Toutes les valeurs de 1
jusqu’à 32767
sont acceptées par toutes les bases de données prises en charge officiellement par Django.
SmallIntegerField
¶
-
class
SmallIntegerField
(**options)¶
Comme un IntegerField
, mais n’autorise que des valeurs plus petites qu’un certain plafond (dépendant du moteur de base de données). Toutes les valeurs de -32768
jusqu’à 32767
sont acceptées par toutes les bases de données prises en charge officiellement par Django.
TextField
¶
-
class
TextField
(**options)¶
Un champ de texte long. Le composant de formulaire par défaut de ce champ est un Textarea
.
Si vous indiquez un attribut max_length
, celui-ci se répercute sur le composant Textarea
du champ de formulaire généré automatiquement. Cependant, la limite n’est pas imposée au niveau du modèle, ni de la base de données. Pour cela, utilisez plutôt un champ CharField
.
-
TextField.
db_collation
¶ Facultatif. Le nom de collation de base de données pour le champ.
Note
Les noms de collation ne sont pas standardisés. De fait, ils ne sont pas portables entre les différents moteurs de base de données.
Oracle
Oracle ne prend pas en charge les collations pour les champs
TextField
.
TimeField
¶
-
class
TimeField
(auto_now=False, auto_now_add=False, **options)¶
Une heure, représentée en Python par une instance de datetime.time
. Ce champ accepte les mêmes options d’auto-complétion qu’un champ DateField
.
Le composant de formulaire par défaut de ce champ est un TimeInput
. L’interface d’administration ajoute des raccourcis JavaScript.
URLField
¶
-
class
URLField
(max_length=200, **options)¶
Un champ CharField
pour les URL, validé par URLValidator
.
Le composant de formulaire par défaut de ce champ est un URLInput
.
Comme pour les autres sous-classes de CharField
, URLField
accepte le paramètre facultatif max_length
. Si vous ne renseignez pas la valeur de max_length
, elle prend la valeur 200 par défaut.
UUIDField
¶
-
class
UUIDField
(**options)¶
Un champ pour stocker des identifiants universels uniques (UUID). Utilise la classe Python UUID
. Avec PostgreSQL et MariaDB 10.7+, le type de données uuid
est employé, sinon c’est un type char(32)
.
Les identifiants universels uniques sont une bonne alternative aux champs AutoField
pour les clés primaires primary_key
. La base de données ne produit pas de UUID à votre place, c’est pourquoi il est recommandé d’utiliser 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
Notez que nous passons bien un objet exécutable (sans les parenthèses) à default
, et non pas une instance de UUID
.
Expressions de requête avec PostgreSQL et MariaDB 10.7+
L’utilisation des expressions de requête iexact
, contains
, icontains
, startswith
, istartswith
, endswith
ou iendswith
avec PostgreSQL ne fonctionne pas pour les valeurs sans tirets, car PostgreSQL et MariaDB 10.7+ stockent ces valeurs dans un type de base de données uuid
avec tirets.
Référence d’API des champs¶
-
class
Field
¶ Field
est une classe abstraite qui représente une colonne de table de base de données. Django utilise des champs pour créer une table de base de données (db_type()
), pour faire correspondre des types Python à une base de données (get_prep_value()
) et inversement (from_db_value()
).Un champ est donc une pièce essentielle dans différentes API de Django, notamment pour les
modèles
et lesjeux de requête
.Dans les modèles, un champ est instancié comme attribut de classe et représente une colonne de table de base de données, voir Modèles. Il possède des attributs comme
null
etunique
, ainsi que des méthodes que Django utilise pour faire correspondre la valeur du champ à des valeurs spécifiques à la base de données.Un champ
Field
est une sous-classe deRegisterLookupMixin
, ce qui fait qu’à la foisTransform
etLookup
peuvent y être inscrits pour être exploités dans les requêtesQuerySet
(par ex.nom_champ__exact="foo"
). Toutes les expressions de requête intégrées sont inscrites par défaut.Tous les types de champs fournis par Django, tels que
CharField
, sont des implémentations dérivées deField
. Si vous avez besoin d’un nouveau type de champ, vous pouvez soit hériter d’un des champs de Django ou écrire une classeField
à partir de zéro. Dans tous les cas, consultez Écriture de champs de modèles personnalisés.-
description
¶ Une description verbeuse du champ, par exemple pour l’application
django.contrib.admindocs
.La description peut prendre la forme :
description = _("String (up to %(max_length)s)")
où les paramètres sont interpolés à partir du
__dict__
du champ.
-
descriptor_class
¶ Une classe implémentant le protocole de descripteur qui est instanciée et attribuée à l’attribut d’instance de modèle. Le constructeur doit accepter un seul paramètre, l’instance d’un champ. La surcharge de cet attribut de classe permet de personnaliser les comportements
get
etset
.
Pour faire correspondre un champ
Field
à un type particulier d’une base de données, Django expose plusieurs méthodes :-
get_internal_type
()¶ Renvoie une chaîne nommant ce champ à l’usage du moteur de base de données spécifique. Par défaut, c’est le nom de la classe qui est renvoyé.
Voir Émulation de types de champs intégrés pour son utilisation dans des types de champs personnalisés.
-
db_type
(connection)¶ Renvoie le type de donnée de la colonne de la base de données de la classe
Field
, prenant en compte l’objetconnection
.Voir Types de base de données personnalisés pour son utilisation dans des types de champs personnalisés.
-
rel_db_type
(connection)¶ Renvoie le type de donnée de la colonne de la base de données, tel que
ForeignKey
etOneToOneField
qui pointent versField
, prenant en compte l’objetconnection
.Voir Types de base de données personnalisés pour son utilisation dans des types de champs personnalisés.
Il existe trois situations principales où Django a besoin de faire interagir le moteur de base de données et les champs :
- lorsqu’il interroge la base de données (valeur Python -> valeur pour le moteur de base de données)
- lorsqu’il charge des données à partir de la base de données (valeur du moteur de base de données -> valeur Python)
- lorsqu’il enregistre vers la base de données (valeur Python -> valeur pour le moteur de base de données)
Lors d’une interrogation,
get_db_prep_value()
etget_prep_value()
sont utilisés :-
get_prep_value
(value)¶ value
est la valeur actuelle de l’attribut de modèle, et la méthode doit renvoyer les données dans un format préparé spécialement pour être utilisé comme paramètre de la requête.Voir Conversion d’objets Python en valeurs de requête pour son utilisation.
-
get_db_prep_value
(value, connection, prepared=False)¶ Convertit
value
vers une valeur spécifique au moteur de base de données. Par défaut, il renvoievalue
siprepared=True
etget_prep_value()
sinon.Voir Conversion de valeurs de requête en valeurs de base de données pour son utilisation.
Lors du chargement de données,
from_db_value()
est utilisé :-
from_db_value
(value, expression, connection)¶ Convertit la valeur renvoyée par la base de données en un objet Python. C’est l’inverse de
get_prep_value()
.Cette méthode n’est pas utilisée pour la plupart des champs intégrés, car le moteur de base de données renvoie déjà le bon type Python, ou le moteur se charge lui-même de la conversion.
expression
est la même chose queself
.Voir Conversion de valeurs en objets Python pour son utilisation.
Note
Pour des raisons de performance,
from_db_value
n’est pas implémentée comme opération blanche pour les champs qui n’en ont pas besoin (tous les champs Django). Par conséquent, vous ne pouvez pas appelersuper
dans votre définition.
Lors de l’enregistrement,
pre_save()
etget_db_prep_save()
sont utilisés :-
get_db_prep_save
(value, connection)¶ Comme pour
get_db_prep_value()
, mais appelé lorsque la valeur du champ doit être enregistrée dans la base de données. Renvoie par défautget_db_prep_value()
.
-
pre_save
(model_instance, add)¶ Méthode appelée avant
get_db_prep_save()
pour préparer la valeur avant d’être enregistrée (par ex. pourDateField.auto_now
).model_instance
est l’instance à laquelle appartient ce champ etadd
indique si l’instance est enregistrée dans la base de données pour la première fois.Cette méthode doit renvoyer la valeur de l’attribut correspondant de
model_instance
pour ce champ. Le nom d’attribut est dansself.attname
(défini parField
).Voir Pré-traitement des valeurs avant enregistrement pour son utilisation.
Les champs reçoivent souvent leur valeur dans un type différent, que ce soit par la sérialisation ou par les formulaires.
-
to_python
(value)¶ Convertit la valeur dans le bon objet Python. Elle opère à l’inverse de
value_to_string()
et est également appelée dansclean()
.Voir Conversion de valeurs en objets Python pour son utilisation.
En plus de l’enregistrement dans la base de données, le champ doit aussi savoir comment sérialiser sa valeur :
-
value_from_object
(obj)¶ Renvoie la valeur du champ pour l’instance de modèle donnée.
Cette méthode est souvent utilisée par
value_to_string()
.
-
value_to_string
(obj)¶ Convertit
obj
en une chaîne. Utilisé pour sérialiser la valeur du champ.Voir Conversion des données de champs pour la sérialisation pour son utilisation.
Lors de l’utilisation de
formulaires de modèles
, le champField
doit savoir quel champ de formulaire doit le représenter en appelant :-
formfield
(form_class=None, choices_form_class=None, **kwargs)¶ Renvoie le champ de formulaire
django.forms.Field
utilisé par défaut pour ce champ dans un formulaireModelForm
.Par défaut, si
form_class
etchoices_form_class
valent les deuxNone
, c’est un champCharField
qui sera renvoyé. Si le champ possède l’attributchoices
et quechoices_form_class
n’est pas renseigné, ce sera un champTypedChoiceField
.Voir Sélection du champ de formulaire pour un champ de modèle pour son utilisation.
-
deconstruct
()¶ Renvoie un tuple à 4 éléments avec suffisamment d’informations pour recréer le champ :
- Le nom du champ dans le modèle.
- Le chemin d’importation du champ (par ex.
"django.db.models.IntegerField"
). Il est recommandé d’indiquer la version la plus portable, donc moins le chemin est spécifique, mieux c’est. - Une liste de paramètres positionnels.
- Un dictionnaire de paramètres nommés.
Cette méthode doit être ajoutée aux champs créés avant la version 1.7 afin de pouvoir migrer leurs données en utilisant les Migrations.
-
Inscription et obtention d’expressions de recherche¶
Field
implémente l’API d’inscription d’expressions de recherche. Cette API peut être utilisée pour personnaliser les recherches possibles pour une classe de champ et ses instances, et la manière d’obtenir ces recherches depuis un champ.
La prise en charge de l’inscription d’expressions de recherche sur les instances de Field
a été ajoutée.
Référence d’attributs des champs¶
Chaque instance Field
contient plusieurs attributs qui permettent d’inspecter son comportement. Utilisez ces attributs plutôt que de vous baser sur des contrôles de type isinstance
lorsque vous avez besoin d’écrire du code qui dépend de la fonctionnalité d’un champ. Ces attributs peuvent être utilisée conjointement avec l’API Model._meta pour préciser une recherche de types de champs spécifiques. Les champs de modèles personnalisés devraient implémenter ces drapeaux.
Attributs pour les champs¶
-
Field.
auto_created
¶ Drapeau booléen indiquant si le champ a été créé automatiquement, comme pour le champ
OneToOneField
utilisé dans un contexte d’héritage de modèles.
-
Field.
concrete
¶ Drapeau booléen indiquant si le champ est associé à une colonne de base de données.
Drapeau booléen indiquant si un champ est masqué et qu’il ne devrait pas être renvoyé par
Options.get_fields()
par défaut. Un exemple est le champ inverse d’une cléForeignKey
dont l’attributrelated_name
commence par'+'
.
-
Field.
is_relation
¶ Drapeau booléen indiquant si un champ contient des références à un ou plusieurs autres modèles pour sa fonctionnalité (par ex.
ForeignKey
,ManyToManyField
,OneToOneField
, etc.).
-
Field.
model
¶ Renvoie le modèle dans lequel le champ est défini. Si un champ est défini dans la classe parent d’un modèle,
model
désigne alors la classe parente, et non pas la classe de l’instance.
Attributs pour les champs de relation¶
Ces attributs sont utilisés pour interroger la cardinalité et d’autres détails d’une relation. Ces attributs sont présents sur tous les champs ; cependant, ils n’ont des valeurs booléennes (plutôt que None
) que si le champ est de type relationnel (Field.is_relation=True
).
-
Field.
many_to_many
¶ Drapeau booléen qui vaut
True
si le champ est une relation plusieurs-à-plusieurs ;False
sinon. Le seul champ inclus dans Django pour lequel cet attribut vautTrue
estManyToManyField
.
-
Field.
many_to_one
¶ Drapeau booléen qui vaut
True
si le champ est une relation plusieurs-à-un, comme pour un champForeignKey
;False
sinon.
-
Field.
one_to_many
¶ Drapeau booléen qui vaut
True
si le champ est une relation un-à-plusieurs, comme pourGenericRelation
ou la contrepartie d’une cléForeignKey
;False
sinon.
-
Field.
one_to_one
¶ Drapeau booléen qui vaut
True
si le champ est une relation un-à-un, comme pour un champOneToOneField
;False
sinon.
Pointe vers le modèle en lien avec le champ. Par exemple,
Author
dansForeignKey(Author, on_delete=models.CASCADE)
. Lerelated_model
d’une cléGenericForeignKey
vaut toujoursNone
.