nullLien vers cette rubrique#

Field.nullLien vers cette définition#

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

blankLien vers cette rubrique#

Field.blankLien vers cette définition#

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.

choicesLien vers cette rubrique#

Field.choicesLien vers cette définition#

Une séquence composée elle-même d’itérables de tuples binaires (par ex. [(A, B), (A, B) ...]) 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.

Le premier élément de chaque tuple est la valeur réelle à définir pour le modèle. 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 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'),
]

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.

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.

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

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.choices,
        default=YearInSchool.FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {
            self.YearInSchool.JUNIOR,
            self.YearInSchool.SENIOR,
        }

>>> class Vehicle(models.TextChoices):
...     CAR = 'C'
...     TRUCK = 'T'
...     JET_SKI = 'J'
...
>>> Vehicle.JET_SKI.label
'Jet Ski'

class Card(models.Model):

    class Suit(models.IntegerChoices):
        DIAMOND = 1
        SPADE = 2
        HEART = 3
        CLUB = 4

    suit = models.IntegerField(choices=Suit.choices)

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

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

db_columnLien vers cette rubrique#

Field.db_columnLien vers cette définition#

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_indexLien vers cette rubrique#

Field.db_indexLien vers cette définition#

Si True, une index de base de données sera créé pour ce champ.

db_tablespaceLien vers cette rubrique#

Field.db_tablespaceLien vers cette définition#

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.

defaultLien vers cette rubrique#

Field.defaultLien vers cette définition#

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.

editableLien vers cette rubrique#

Field.editableLien vers cette définition#

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_messagesLien vers cette rubrique#

Field.error_messagesLien vers cette définition#

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_textLien vers cette rubrique#

Field.help_textLien vers cette définition#

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_keyLien vers cette rubrique#

Field.primary_keyLien vers cette définition#

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.

uniqueLien vers cette rubrique#

Field.uniqueLien vers cette définition#

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_dateLien vers cette rubrique#

Field.unique_for_dateLien vers cette définition#

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_monthLien vers cette rubrique#

Field.unique_for_monthLien vers cette définition#

Comme unique_for_date, mais requiert que le champ soit unique en rapport au mois du champ date.

unique_for_yearLien vers cette rubrique#

Field.unique_for_yearLien vers cette définition#

Comme unique_for_date et unique_for_month, mais avec l’année du champ date.

verbose_nameLien vers cette rubrique#

Field.verbose_nameLien vers cette définition#

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.

validatorsLien vers cette rubrique#

Field.validatorsLien vers cette définition#

Une liste de validateurs à exécuter pour ce champ. Consultez la documentation des validateurs pour plus d’informations.

AutoFieldLien vers cette rubrique#

class AutoField(**options)Lien vers cette définition#

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.

BigAutoFieldLien vers cette rubrique#

class BigAutoField(**options)Lien vers cette définition#

Un entier 64 bits, ressemblant à un AutoField sauf qu’il garantit la couverture des nombres de 1 à 9223372036854775807.

BigIntegerFieldLien vers cette rubrique#

class BigIntegerField(**options)Lien vers cette définition#

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.

BinaryFieldLien vers cette rubrique#

class BinaryField(max_length=None, **options)Lien vers cette définition#

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 possède un paramètre facultatif supplémentaire :

BinaryField.max_lengthLien vers cette définition#

La taille maximale (en octets) du champ. Cette longueur maximale est contrôlée par la validation de Django en utilisant MaxLengthValidator.

BooleanFieldLien vers cette rubrique#

class BooleanField(**options)Lien vers cette définition#

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.

CharFieldLien vers cette rubrique#

class CharField(max_length=None, **options)Lien vers cette définition#

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 deux paramètres supplémentaires :

CharField.max_lengthLien vers cette définition#

Obligatoire. La taille maximale (en caractères) du champ. Cette longueur maximale est contrôlée au niveau de la base de données ainsi que par la validation de Django en utilisant MaxLengthValidator.

CharField.db_collationLien vers cette définition#

Facultatif. Le nom de collation de base de données pour le champ.

DateFieldLien vers cette rubrique#

class DateField(auto_now=False, auto_now_add=False, **options)Lien vers cette définition#

Une date, représentée en Python par une instance de datetime.date. Accepte quelques paramètres supplémentaires et facultatifs :

DateField.auto_nowLien vers cette définition#

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 exemple QuerySet.update(), bien qu’il soit possible de spécifier explicitement une valeur pour ce champ lors d’une telle mise à jour.

DateField.auto_now_addLien vers cette définition#

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 - de datetime.date.today()

• Pour un champ DateTimeField: default=timezone.now - de django.utils.timezone.now()

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.

DateTimeFieldLien vers cette rubrique#

class DateTimeField(auto_now=False, auto_now_add=False, **options)Lien vers cette définition#

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.

DecimalFieldLien vers cette rubrique#

class DecimalField(max_digits=None, decimal_places=None, **options)Lien vers cette définition#

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 deux paramètres obligatoires :

DecimalField.max_digitsLien vers cette définition#

Le nombre maximum de chiffres autorisés dans le nombre. Notez que ce nombre doit être plus grand ou égal à decimal_places.

DecimalField.decimal_placesLien vers cette définition#

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 NumberInput lorsque localize vaut False, ou TextInput dans le cas contraire.

DurationFieldLien vers cette rubrique#

class DurationField(**options)Lien vers cette définition#

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

EmailFieldLien vers cette rubrique#

class EmailField(max_length=254, **options)Lien vers cette définition#

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

FileFieldLien vers cette rubrique#

class FileField(upload_to=None, max_length=100, **options)Lien vers cette définition#

Un champ de fichier à téléverser.

Possède deux paramètres facultatifs :

FileField.upload_toLien vers cette définition#

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 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é). Par exemple :

Code

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 chemin MEDIA_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 traite upload_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 :

Code

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.storageLien vers cette définition#

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 :

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 le champ FileField ou ImageField à votre modèle, en définissant l’option upload_to pour indiquer dans quel sous-répertoire de MEDIA_ROOT les fichiers doivent être téléversés.

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.

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.

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)

from django.core.files.base import ContentFile
myfile = ContentFile("hello world")

FilePathFieldLien vers cette rubrique#

class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options)Lien vers cette définition#

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.pathLien vers cette définition#

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

Code

import 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.matchLien vers cette définition#

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.recursiveLien vers cette définition#

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

FilePathField.allow_filesLien vers cette définition#

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_foldersLien vers cette définition#

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.

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.

FloatFieldLien vers cette rubrique#

class FloatField(**options)Lien vers cette définition#

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.

ImageFieldLien vers cette rubrique#

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)Lien vers cette définition#

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_fieldLien vers cette définition#

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_fieldLien vers cette définition#

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.

IntegerFieldLien vers cette rubrique#

class IntegerField(**options)Lien vers cette définition#

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.

GenericIPAddressFieldLien vers cette rubrique#

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)Lien vers cette définition#

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.protocolLien vers cette définition#

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_ipv4Lien vers cette définition#

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.

JSONFieldLien vers cette rubrique#

class JSONField(encoder=None, decoder=None, **options)Lien vers cette définition#

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 10.2.7+, MySQL 5.7.8+, Oracle, PostgreSQL et SQLite (avec l’extension JSON1 activée).

JSONField.encoderLien vers cette définition#

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 ou UUID). Par exemple, vous pouvez utiliser la classe DjangoJSONEncoder.

Contient json.JSONEncoder par défaut.

JSONField.decoderLien vers cette définition#

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 objet datetime qui était en fait une chaîne qui était fortuitement au même format que celui choisi pour les objets datetime.

Contient json.JSONDecoder par défaut.

Si vous donnez une valeur default à ce champ, assurez-vous que ce soit un objet immuable tel qu’une chaîne str, ou un objet exécutable qui renvoie un nouvel objet mutable à chaque appel, tel qu’un dict ou une fonction. Si vous indiquez une valeur par défaut qui est mutable comme default={} or default=[], cette valeur sera partagée entre toutes les instances du modèle.

Pour interroger les champs JSONField dans la base de données, voir Interrogation de JSONField.

NullBooleanFieldLien vers cette rubrique#

class NullBooleanField(**options)Lien vers cette définition#

Comme BooleanField avec null=True.

PositiveBigIntegerFieldLien vers cette rubrique#

class PositiveBigIntegerField(**options)Lien vers cette définition#

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.

PositiveIntegerFieldLien vers cette rubrique#

class PositiveIntegerField(**options)Lien vers cette définition#

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

PositiveSmallIntegerFieldLien vers cette rubrique#

class PositiveSmallIntegerField(**options)Lien vers cette définition#

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.

SlugFieldLien vers cette rubrique#

class SlugField(max_length=50, **options)Lien vers cette définition#

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_unicodeLien vers cette définition#

Si la valeur est True, le champ accepte des lettres Unicode en plus des lettres ASCII de base. La valeur par défaut est False.

SmallAutoFieldLien vers cette rubrique#

class SmallAutoField(**options)Lien vers cette définition#

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.

SmallIntegerFieldLien vers cette rubrique#

class SmallIntegerField(**options)Lien vers cette définition#

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.

TextFieldLien vers cette rubrique#

class TextField(**options)Lien vers cette définition#

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_collationLien vers cette définition#

Le nom de collation de base de données pour le champ.

TimeFieldLien vers cette rubrique#

class TimeField(auto_now=False, auto_now_add=False, **options)Lien vers cette définition#

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.

URLFieldLien vers cette rubrique#

class URLField(max_length=200, **options)Lien vers cette définition#

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.

UUIDFieldLien vers cette rubrique#

class UUIDField(**options)Lien vers cette définition#

Un champ pour stocker des identifiants universels uniques (UUID). Utilise la classe Python UUID. Avec PostgreSQL, 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.

ForeignKeyLien vers cette rubrique#

class ForeignKey(to, on_delete, **options)Lien vers cette définition#

Une relation plusieurs-à-un. Exige deux paramètres : la classe à laquelle le modèle est lié et l’option on_delete.

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

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',
        on_delete=models.CASCADE,
    )
    # ...

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

Les relations définies de cette façon pour des modèles abstraits sont résolues au moment où le modèle est hérité par un modèle concret et ne sont pas en lien avec l’attribut app_label du modèle abstrait :

from django.db import models

class AbstractCar(models.Model):
    manufacturer = models.ForeignKey('Manufacturer', on_delete=models.CASCADE)

    class Meta:
        abstract = True

from django.db import models
from products.models import AbstractCar

class Manufacturer(models.Model):
    pass

class Car(AbstractCar):
    pass

# Car.manufacturer will point to `production.Manufacturer` here.

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',
        on_delete=models.CASCADE,
    )

Cette méthode de référence, appelée une relation différée, 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.

ManyToManyFieldLien vers cette rubrique#

class ManyToManyField(to, **options)Lien vers cette définition#

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.

OneToOneFieldLien vers cette rubrique#

class OneToOneField(to, on_delete, parent_link=False, **options)Lien vers cette définition#

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,
        on_delete=models.CASCADE,
    )
    supervisor = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        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 RelatedObjectDoesNotExist est générée lors de l’accès à la relation inverse si aucune ligne correspondante n’existe dans la table liée. Cette exception est une sous-classe de l’exception Model.DoesNotExist du modèle cible. 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):
    ...
RelatedObjectDoesNotExist: User has no supervisor_of.

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

OneToOneField.parent_linkLien vers cette définition#

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.