Référence des champs de modèle

Ce document contient tous les détails que Django met à disposition concernant les options des champs et les types de champs.

Voir aussi

Si les champs intégrés ne font pas l’affaire, vous pouvez essayer localflavor 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, car les valeurs de chaîne vide sont toujours stockées avec la chaîne vide, pas comme NULL. 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.

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:attr:~Field.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.

Si vous souhaitez accepter des valeurs null avec BooleanField, utilisez plutôt NullBooleanField.

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 itérable (par exemple une liste ou un tuple) composé lui-même d’itérables de tuples binaires (par ex. [(A, B), (A, B) ...]) représentant les choix possibles pour ce champ. Si ce paramètre est présent, 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.

Le premier élément de chaque tuple est la valeur réelle à enregistrer. 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'),
)

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'
    YEAR_IN_SCHOOL_CHOICES = (
        (FRESHMAN, 'Freshman'),
        (SOPHOMORE, 'Sophomore'),
        (JUNIOR, 'Junior'),
        (SENIOR, 'Senior'),
    )
    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'),
)

Le premier élément de chaque tuple est le nom utilisé pour le groupe. Le second élément est un objet itérable de tuples binaires contenant la valeur et l’étiquette à afficher pour cette option. Les options groupées peuvent être combinées à des options non groupées dans une seule liste (comme l’option unknown dans cet exemple).

Pour chaque champ de modèle ayant l’option choices, Django 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.

Enfin, notez que ces choix peuvent être constitués par n’importe quel objet itérable, 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.

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_index

Field.db_index

Si True, django-admin.py sqlindexes génère une instruction CREATE INDEX pour ce champ.

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, liste, 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 aviez un champ JSONField personnalisé et que vous vouliez lui fournir un dictionnaire comme valeur par défaut, utilisez une fonction lambda, comme ceci :

contact_info = JSONField("ContactInfo", default=lambda:{"email": "to1@example.com"})

editable

Field.editable

If False, the field will not be displayed in the admin or any other ModelForm. They are also skipped during model validation. Default is 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 et unique. D’autres clés de messages d’erreur sont définies pour chaque champ de la section types de champs ci-dessous.

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>."

Alternatively you can use plain text and django.utils.html.escape() to escape any HTML special characters. Ensure that you escape any help text that may come from untrusted users to avoid a cross-site scripting attack.

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 AutoField 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. 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.

The primary key field is read-only. If you change the value of the primary key on an existing object and then save it, a new object will be created alongside the old one.

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, OneToOneField et FileField.

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.

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 TextInput.

BinaryField

class BinaryField([**options])
New in Django 1.6.

Un champ pour stocker des données binaires brutes. Il ne peut recevoir que des octets (bytes). Il faut savoir que ce champ possède des fonctionnalités restreintes. Par exemple, il n’est pas possible de filtrer un jeu de requête par une valeur BinaryField.

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.

Si vous devez accepter les valeurs null, utilisez plutôt NullBooleanField.

Changed in Django 1.6:

La valeur par défaut de BooleanField est dorénavant None au lieu de False 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 a un paramètre obligatoire supplémentaire :

CharField.max_length

La taille maximale (en caractères) du champ. Cette taille est définie au niveau de la base de données et appliquée lors de la validation par Django.

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.

Utilisateurs de MySQL

Si vous utilisez ce champ avec MySQLdb 1.2.2 et la collation utf8_bin (ce qui n’est pas le cas par défaut), il y a quelques problèmes dont il faut être conscient. Référez-vous aux notes sur la base de données MySQL pour plus de détails.

CommaSeparatedIntegerField

class CommaSeparatedIntegerField(max_length=None[, **options])

Un champ d’entiers séparés par une virgule. Comme pour le champ CharField, le paramètre attr:~CharField.max_length est obligatoire ; la remarque au sujet de la portabilité entre les moteurs de base de données doit elle aussi être prise en compte.

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.

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.

Le composant de formulaire par défaut de ce champ est un TextInput. 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.

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.

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 TextInput. 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. Il requiert deux paramètres obligatoires :

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 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 TextInput.

Note

Pour plus d’informations sur les différences entre les classes FloatField et DecimalField, consultez FloatField vs. DecimalField.

EmailField

class EmailField([max_length=75, **options])

Un champ CharField qui vérifie que sa valeur est une adresse électronique valide.

Non conformité aux RFC

La valeur par défaut de max_length à 75 caractères n’est pas capable de gérer toutes les adresses électroniques se conformant au standard RFC3696/5321. Pour pouvoir stocker toutes les adresses électroniques potentiellement valides, il faut définir max_length à 254 caractères. La valeur par défaut de 75 caractères existe pour des raisons historiques. Cette valeur par défaut n’a pas été modifiée afin de conserver la rétrocompatibilité avec les utilisations existantes de EmailField.

FileField

class FileField(upload_to=None[, max_length=100, **options])

Un champ de fichier à téléverser.

Note

Les paramètres primary_key et unique ne sont pas pris en charge et génèrent une exception TypeError s’ils sont utilisés.

Requiert un paramètre obligatoire :

FileField.upload_to

Un chemin d’accès local qui sera ajouté au réglage MEDIA_ROOT pour déterminer la valeur de l’attribut url.

Ce chemin peut contenir des chaînes de format strftime() 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é).

Cet attribut peut aussi être un objet exécutable, comme une fonction, qui 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 passés 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.

Ce champ accepte aussi un paramètre facultatif :

FileField.storage

Facultatif. Un objet de stockage, qui 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 :

  1. Dans votre fichier de réglages, vous devez indiquer dans MEDIA_ROOT le chemin d’accès absolu vers un répertoire où Django enregistrera les fichiers téléversés (pour des raisons de performance, ces fichiers ne sont pas stockés en base de données). Indiquez dans MEDIA_URL l’URL publique de base correspondant à ce répertoire. Assurez vous que ce répertoire est accessible en écriture par l’utilisateur du serveur Web.

  2. Ajoutez un FileField ou un ImageField à votre modèle, en prenant soin de définir l’option upload_to indiquant à Django le sous-répertoire de MEDIA_ROOT dans lequel il doit enregistrer les fichiers.

  3. 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’attribut url offert par Django. Par exemple, considérant un ImageField 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).

FileField instances are created in your database as varchar columns with a default max length of 100 characters. As with other fields, you can change the maximum length using the max_length argument.

FileField et FieldFile

class FieldFile[source]

When you access a FileField on a model, you are given an instance of FieldFile as a proxy for accessing the underlying file. In addition to the functionality inherited from django.core.files.File, this class has several attributes and methods that can be used to interact with file data:

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')[source]

Même comportement que la méthode open() standard de Python et ouvre le fichier associé à l’instance actuelle dans le mode indiqué par mode.

FieldFile.close()[source]

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)[source]

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.

Takes two required arguments: name which is the name of the file, and content which is an object containing the file’s contents. The optional save argument controls whether or not the model instance is saved after the file associated with this field has been altered. Defaults to 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('/tmp/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)[source]

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.

The optional save argument controls whether or not the model instance is saved after the file associated with this field has been deleted. Defaults to 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=None[, match=None, recursive=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 trois paramètres spéciaux, 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".

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 fichier foo23.txt, mais pas à bar.txt ni à foo23.png.

FilePathField.recursive

Facultatif. Vaut True ou False (valeur par défaut). Indique si tous les sous-répertoires de path doivent être inclus.

FilePathField.allow_files
New in Django 1.5.

Facultatif. Vaut True (valeur par défaut) ou False. Indique si les fichiers de l’emplacement spécifié doivent être inclus. Il faut que l’une des deux valeurs, ce champ ou allow_folders, soit True.

FilePathField.allow_folders
New in Django 1.5.

Facultatif. Vaut True ou False (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 ou allow_files, soit True.

Ces paramètre peuvent bien sûr être utilisés conjointement.

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

FilePathField instances are created in your database as varchar columns with a default max length of 100 characters. As with other fields, you can change the maximum length using the max_length argument.

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 TextInput.

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.

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 deux attributs facultatifs supplémentaires :

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.

ImageField instances are created in your database as varchar columns with a default max length of 100 characters. As with other fields, you can change the maximum length using the max_length argument.

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. Le composant de formulaire par défaut de ce champ est TextInput.

IPAddressField

class IPAddressField([**options])

Une adresse IP au format textuel (par ex. « 192.0.2.30 »). Le composant de formulaire par défaut de ce champ est un TextInput.

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, 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 en 192.0.2.1. L’option est désactivée par défaut. Utilisable uniquement quand protocol 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.

NullBooleanField

class NullBooleanField([**options])

Comme un champ BooleanField, mais autorise la valeur NULL comme choix possible. Préférez ce champ à un BooleanField avec l’option null=True. Le composant de formulaire par défaut de ce champ est un NullBooleanSelect.

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.

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.

Utilisateurs de MySQL

Si vous utilisez ce champ avec MySQLdb 1.2.1p2 et la collation utf8_bin (ce qui n’est pas le cas par défaut), il y a quelques problèmes dont il faut être conscient. Référez-vous aux notes sur la base de données MySQL pour plus de détails.

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 TextInput. L’interface d’administration ajoute des raccourcis JavaScript.

URLField

class URLField([max_length=200, **options])

Un champ CharField pour les URL.

Le composant de formulaire par défaut de ce champ est un TextInput.

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.

New in Django 1.5:

La valeur actuelle du champ est affichée avec un lien cliquable au-dessus de la zone de saisie.

Champs pour les relations

Django définit aussi un ensemble de champs représentant les relations.

ForeignKey

class ForeignKey(othermodel[, **options])

Une relation plusieurs-à-un. Exige un paramètre positionnel : la classe à laquelle le modèle est lié.

Pour créer une relation récursive (un objet avec une relation plusieurs-à-un vers lui-même), utilisez models.ForeignKey('self').

Si vous avez besoin de créer une relation vers un modèle qui n’a pas encore été défini, vous pouvez utiliser le nom de ce modèle, à la place de l’objet modèle lui-même :

from django.db import models

class Car(models.Model):
    manufacturer = models.ForeignKey('Manufacturer')
    # ...

class Manufacturer(models.Model):
    # ...
    pass

Pour faire référence à un modèle d’une autre application, vous pouvez explicitement indiquer un modèle avec le chemin vers son application. Par exemple, si le modèle Manufacturer précédent est défini dans une autre application appelée production, il faudrait utiliser :

class Car(models.Model):
    manufacturer = models.ForeignKey('production.Manufacturer')

Cette méthode de référence peut être utile pour la résolution des dépendances d’importation circulaires entre deux applications.

Un index de base de données est automatiquement créé pour les champs ForeignKey. Vous pouvez le désactiver en définissant db_index à False. Il est parfois souhaitable d’éviter la création inutile d’un index si la clé étrangère est créée par cohérence plutôt que pour les jointures ou si vous allez créer un autre index tel qu’un index partiel ou un index sur plusieurs colonnes.

Représentation en base de données

En arrière-plan, Django ajoute "_id" au nom du champ pour créer ses noms de colonnes de base de données. Dans l’exemple précédent, la table de base de données pour le modèle Car aura une colonne manufacturer_id (vous pouvez changer ceci explicitement en définissant db_column). Cependant, votre code ne devrait jamais avoir affaire directement aux noms des colonnes de base de données, à moins d’écrire soi-même du SQL personnalisé. Vous utiliserez toujours les noms des champs des objets de vos modèles.

Paramètres

Le champ ForeignKey accepte un ensemble supplémentaire de paramètres (tous facultatifs) qui définissent les détails du fonctionnement de la relation.

ForeignKey.limit_choices_to

Un dictionnaire de paramètres et de valeurs de recherche (voir Création de requêtes) qui limite les choix disponibles dans l’interface d’administration ou les ModelForm de cet objet. Par exemple :

staff_member = models.ForeignKey(User, limit_choices_to={'is_staff': True})

fait que le champ correspondant du formulaire ModelForm ne comporte que les utilisateurs ayant is_staff=True.

À la place d’un dictionnaire, ce paramètre peut être un objet de type Q pour des requêtes plus complexes. Cependant, si limit_choices_to est un objet Q, il n’a d’effet sur les choix disponibles dans l’interface d’administration que si le champ ne figure pas dans la propriété raw_id_fields``du ``ModelAdmin du modèle.

ForeignKey.related_name

Le nom à utiliser pour la relation inverse depuis l’objet lié vers celui-ci. Il s’agit aussi de la valeur par défaut de related_query_name (le nom à utiliser comme nom de filtre inverse à partir du modèle cible). Voir la documentation des objets liés pour une explication complète et des exemples. Notez que vous devez définir cette valeur quand vous définissez une relation pour un modèle abstrait ; et quand vous le faites, une syntaxe particulière est autorisée.

Si vous préférez que Django ne crée pas de relation inverse, définissez related_name à '+' ou terminez ce nom avec '+'. Par exemple, ceci assure que le modèle User n’aura pas de relation inverse à ce modèle :

user = models.ForeignKey(User, related_name='+')
ForeignKey.related_query_name
New in Django 1.6.

Le nom à utiliser comme nom de filtre inverse à partir du modèle cible. La valeur par défaut est identique à related_name si celui-ci est défini, sinon elle correspond au nom du modèle :

# Declare the ForeignKey with related_query_name
class Tag(models.Model):
    article = models.ForeignKey(Article, related_name="tags", related_query_name="tag")
    name = models.CharField(max_length=255)

# That's now the name of the reverse filter
Article.objects.filter(tag__name="important")
ForeignKey.to_field

Le champ sur lequel se fait la relation d’objet. Par défaut, Django utilise la clé primaire de l’objet lié.

ForeignKey.db_constraint
New in Django 1.6.

Contrôle si une contrainte doit être créée en base de données pour cette clé étrangère. La valeur par défaut est True, et c’est généralement le bon choix. En définissant la valeur False, l’impact sur l’intégrité des données peut être très négatif. Ceci dit, certains scénarios peuvent justifier ce réglage :

  • Vous possédez déjà des données qui ne sont pas valides.

  • Vous partitionnez votre base de données.

Lorsque ce paramètre est défini à False, l’accès à un objet lié qui n’existe pas génère son exception DoesNotExist.

ForeignKey.on_delete

Lorsqu’un objet référencé par une ForeignKey est supprimé, Django simule par défaut le comportement d’une contrainte SQL ON DELETE CASCADE et supprime aussi l’objet contenant la clé ForeignKey. Ce comportement peut être personnalisé en indiquant le paramètre on_delete. Par exemple, si le champ ForeignKey peut contenir la valeur null et que vous vouliez qu’il prenne cette valeur lorsque l’objet référencé est supprimé :

user = models.ForeignKey(User, blank=True, null=True, on_delete=models.SET_NULL)

Les valeurs possibles de on_delete sont énumérées dans django.db.models:

  • CASCADE

    Supprime en cascade ; c’est la valeur par défaut.

  • PROTECT

    Empêche la suppression de l’objet référencé en levant une exception ProtectedError, une sous-classe de django.db.IntegrityError.

  • SET_NULL

    Place la valeur nulle dans ForeignKey ; ce n’est possible que si le paramètre null vaut True.

  • SET_DEFAULT

    Définit la valeur de ForeignKey à sa valeur par défaut ; il faut évidemment qu’une valeur par défaut existe pour le champ ForeignKey.

  • SET()

    Définit la valeur de ForeignKey à celle qui est transmise à SET(), ou, si un objet exécutable est transmis, au résultat de l’appel à cet objet. Dans la plupart des cas, il sera nécessaire de transmettre un objet exécutable pour éviter de devoir lancer des requêtes au moment de l’importation du fichier models.py :

    from django.conf import settings
    from django.contrib.auth import get_user_model
    from django.db import models
    
    def get_sentinel_user():
        return get_user_model().objects.get_or_create(username='deleted')[0]
    
    class MyModel(models.Model):
        user = models.ForeignKey(settings.AUTH_USER_MODEL,
                                 on_delete=models.SET(get_sentinel_user))
    
  • DO_NOTHING

    Ne rien faire. Si le moteur de base de données assure l’intégrité référentielle, ceci génère une exception IntegrityError sauf si vous ajoutez manuellement une contrainte SQL ON DELETE au champ de base de données (peut-être en utilisant du SQL initial).

ManyToManyField

class ManyToManyField(othermodel[, **options])

Une relation plusieurs-à-plusieurs. Exige un paramètre positionnel : la classe à laquelle le modèle est lié, qui fonctionne exactement de la même manière que pour ForeignKey, y compris les relations récursives et différées.

Les objets liés peuvent être ajoutés, supprimés ou créés avec le gestionnaire RelatedManager du champ.

Représentation en base de données

En arrière-plan, Django crée une table de jointure intermédiaire pour représenter la relation plusieurs-à-plusieurs. Par défault, le nom de cette table est généré en utilisant le nom du champ plusieurs-à-plusieurs et le nom de la table de son modèle. Étant donné que certaines bases de données ne gèrent pas des noms de tables au-delà d’une certaine taille, ce nom de table sera automatiquement tronqué à 64 caractères et un hachage unique sera utilisé. Cela signifie que vous pourriez voir des noms de table comme author_books_9cdf4; ceci est tout à fait normal. Vous pouvez manuellement attribuer un nom à la table de jointure en utilisant l’option db_table.

Paramètres

ManyToManyField accepte un ensemble de paramètres supplémentaires, tous facultatifs, qui contrôlent le fonctionnement de la relation.

ManyToManyField.related_name

Comme pour ForeignKey.related_name.

Si vous avez plus d’un champ ManyToManyField pointant vers le même modèle et que vous souhaitez supprimer les relations inverses, définissez chaque related_name à une valeur unique se terminant par '+':

users = models.ManyToManyField(User, related_name='u+')
referents = models.ManyToManyField(User, related_name='ref+')
ManyToManyField.related_query_name
New in Django 1.6.

Comme pour

ManyToManyField.limit_choices_to

Comme pour ForeignKey.limit_choices_to.

limit_choices_to n’a aucun effet sur un ManyToManyField avec une table intermédiaire personnalisée définie avec le paramètre through.

ManyToManyField.symmetrical

Utilisé uniquement dans la définition d’un ManyToManyField sur lui-même. Considérons le modèle suivant :

from django.db import models

class Person(models.Model):
    friends = models.ManyToManyField("self")

Quand Django parcourt ce modèle, il constate que le modèle a un ManyToManyField sur lui-même, et par conséquence, il n’ajoute pas d’attribut person_set à la classe Person. Il considère que le champ ManyToManyField est symétrique, c’est-à-dire : si je suis votre ami, vous êtes vous aussi mon ami.

Si vous ne voulez pas de symétrie dans une relation plusieurs-à-plusieurs avec self, définissez le paramètre symmetrical à False. Cela forcera Django à ajouter un descripteur pour la relation inverse, autorisant la relation ManyToManyField à ne pas être symétrique.

ManyToManyField.through

Django génère automatiquement une table pour gérer les relations plusieurs-à-plusieurs. Cependant, si vous désirez spécifier manuellement la table intermédiaire, vous pouvez utiliser l’option through pour indiquer le modèle Django qui représente cette table intermédiaire.

L’usage le plus fréquent de cette option est lorsque vous souhaitez associer des données supplémentaires à une relation plusieurs-à-plusieurs.

Si vous ne spécifiez pas de modèle intermédiaire through de façon explicite, il est tout de même possible d’utiliser une classe de modèle through implicite pour directement accéder à la table créée pour stocker les associations. Elle comporte trois champs :

  • id: la clé primaire de la relation.

  • <modèle_conteneur>_id: le champ id du modèle qui déclare le champ ManyToManyField.

  • <autre_modèle>_id: le champ id du modèle vers lequel pointe le champ ManyToManyField.

Cette classe peut être utilisée pour interroger des lignes associées à une instance de modèle donnée, tout comme pour un modèle normal.

ManyToManyField.db_table

Le nom de la table à créer pour enregistrer les données de la relation plusieurs-à-plusieurs. Si ce paramètre n’est pas renseigné, Django génère un nom par défaut basé sur le nom de la table du modèle définissant la relation et le nom du champ lui-même.

ManyToManyField.db_constraint
New in Django 1.6.

Contrôle si des contraintes doivent être créées en base de données pour les clés étrangères de la table intermédiaire. La valeur par défaut est True, et c’est généralement le bon choix. En définissant la valeur False, l’impact sur l’intégrité des données peut être très négatif. Ceci dit, certains scénarios peuvent justifier ce réglage :

  • Vous possédez déjà des données qui ne sont pas valides.

  • Vous partitionnez votre base de données.

Il est faux de passer à la fois les paramètres db_constraint et through.

OneToOneField

class OneToOneField(othermodel[, parent_link=False, **options])

Une relation un-à-un. Conceptuellement, ceci est similaire à un champ ForeignKey avec l’attribut unique=True, mais le côté « inverse » de la relation renvoie directement un objet unique.

Ceci est très utile comme clé primaire d’un modèle qui « étend » un autre modèle d’une certaine manière ; par exemple, l’Héritage multi-table est implémenté en ajoutant une relation un-à-un implicite depuis le modèle fils vers le modèle parent.

Un paramètre positionnel est obligatoire : la classe à laquelle le modèle est lié. Ceci fonctionne exactement de la même manière que pour ForeignKey, y compris toutes les options concernant les relations récursives et différées.

Si vous ne renseignez pas le paramètre related_name du champ OneToOneField, Django utilise le nom du modèle actuel en minuscules comme valeur par défaut.

Avec l’exemple suivant :

from django.conf import settings
from django.db import models

class MySpecialUser(models.Model):
    user = models.OneToOneField(settings.AUTH_USER_MODEL)
    supervisor = models.OneToOneField(settings.AUTH_USER_MODEL, related_name='supervisor_of')

le modèle User résultant possédera les attributs suivants :

>>> user = User.objects.get(pk=1)
>>> hasattr(user, 'myspecialuser')
True
>>> hasattr(user, 'supervisor_of')
True

Une exception DoesNotExist est générée lors de l’accès à la relation inverse si aucune ligne correspondante n’existe dans la table liée. Par exemple, si un utilisateur ne possède par de superviseur dans une instance de modèle MySpecialUser:

>>> user.supervisor_of
Traceback (most recent call last):
    ...
DoesNotExist: User matching query does not exist.

De plus, OneToOneField accepte tous les paramètres supplémentaires acceptés par ForeignKey, plus un paramètre supplémentaire :

Si ce paramètre vaut True et qu’il est utilisé dans un modèle qui hérite d’un autre modèle (concret), cela indique que ce champ devrait être utilisé comme lien vers la classe parente, à la place d’un OneToOneField supplémentaire qui devrait normalement être implicitement créé par l’héritage.

Voir Relations un-à-un pour des exemples d’utilisation du champ OneToOneField.