--- title: "Référence des champs de modèle" version: 6.1 locale: fr source: https://docs.djangoproject.com/fr/6.1/ref/models/fields/ canonical: https://djangodocs.dev/fr/6.1/ref/models/fields/ --- # Référence des champs de modèle Ce document contient toutes les références d’API de [`Field`](#django.db.models.Field), y compris les détails que Django met à disposition concernant les [options de champs](#field-types) et les [types de champs](#field-types). > **Note** > > Les champs sont définis dans [`django.db.models.fields`](#module-django.db.models.fields), mais par commodité ils sont importés dans [`django.db.models`](/fr/6.1/topics/db/models/#module-django.db.models). La convention standard est d’utiliser `from django.db import models` et de se référer aux champs avec `models.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`](#django.db.models.Field.null) pour des champs textuels comme [`CharField`](#django.db.models.CharField) ou [`TextField`](#django.db.models.TextField). La convention Django est d’utiliser une chaîne vide, au lieu de la valeur `NULL`, pour indiquer qu’un champ de type texte ne contient pas de données. Si un champ textuel possède `null=False`, il est toujours possible d’y enregistrer une chaîne vide pour indiquer « pas de données ». 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. Une exception est lorsqu’un champ [`CharField`](#django.db.models.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`](#django.db.models.Field.null) ne se rapporte qu’au stockage dans la base de données (voir [`blank`](#django.db.models.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. ### `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`](#django.db.models.Field.null). [`null`](#django.db.models.Field.null) est purement lié à la base de données, alors que [`blank`](#django.db.models.Field.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. > **Indication de valeurs manquantes** > > `blank=True` peut être utilisé avec des champs ayant `null=False`, mais cela exige que la méthode de modèle [`clean()`](/fr/6.1/ref/models/instances/#django.db.models.Model.clean) soit implémentée afin de fournir programmatiquement d’éventuelles valeurs manquantes. ### `choices` #### `Field.choices` Un objet dictionnaire ou itérable dans le format détaillé ci-dessous représentant les choix possibles pour ce champ. Si des choix sont fournis, ils sont contrôlés par la [validation des modèles](/fr/6.1/ref/models/instances/#validating-objects) et le composant de formulaire par défaut sera une liste déroulante contenant ces choix au lieu de la boîte de saisie de texte standard. S un dictionnaire est donné, l’élément clé est la valeur réelle à définir pour le modèle, et le second élément est la valeur visible par l’utilisateur. Par exemple : ``` YEAR_IN_SCHOOL_CHOICES = { "FR": "Freshman", "SO": "Sophomore", "JR": "Junior", "SR": "Senior", "GR": "Graduate", } ``` Il est aussi possible de transmettre une [séquence](https://docs.python.org/3/glossary.html#term-sequence) composée elle-même d’itérables de tuples binaires (par ex. `[(A1, B1), (A2, B2) ...]`) représentant les choix possibles pour ce champ. Le premier élément de chaque tuple est la valeur réelle à définir pour le modèle et le second élément est la valeur visible par l’utilisateur. Par exemple : ``` YEAR_IN_SCHOOL_CHOICES = [ ("FR", "Freshman"), ("SO", "Sophomore"), ("JR", "Junior"), ("SR", "Senior"), ("GR", "Graduate"), ] ``` `choices` peut aussi être défini comme un exécutable qui n’attend aucun argument et renvoie l’un des formats décrits ci-dessus. Par exemple : ``` def get_currencies(): return {i: i for i in settings.CURRENCIES} class Expense(models.Model): amount = models.DecimalField(max_digits=10, decimal_places=2) currency = models.CharField(max_length=3, choices=get_currencies) ``` La transmission d’un exécutable à `choices` peut être particulièrement indiqué lorsque par exemple les choix sont : - le résultat d’opérations intensives en entrées/sorties (qui pourrait être éventuellement mis en cache), tel que l’interrogation d’une base de données (interne ou externe) ou l’accès à des choix provenant d’un fichier statique ; - une liste globalement stable mais pouvant varier de temps à autre ou de projet en projet. On trouve par exemple dans cette catégorie des applications tierces fournissant un inventaire de valeurs bien connues, telles que des monnaies, des pays, des langues, des fuseaux horaires, etc. Il est généralement conseillé de définir les choix à l’intérieur de la classe d’un modèle et de définir des constantes judicieusement nommées pour chaque valeur : ``` from django.db import models class Student(models.Model): FRESHMAN = "FR" SOPHOMORE = "SO" JUNIOR = "JR" SENIOR = "SR" GRADUATE = "GR" YEAR_IN_SCHOOL_CHOICES = { FRESHMAN: "Freshman", SOPHOMORE: "Sophomore", JUNIOR: "Junior", SENIOR: "Senior", GRADUATE: "Graduate", } year_in_school = models.CharField( max_length=2, choices=YEAR_IN_SCHOOL_CHOICES, default=FRESHMAN, ) def is_upperclass(self): return self.year_in_school in {self.JUNIOR, self.SENIOR} ``` Bien qu’il soit possible de définir une liste de choix en dehors de la classe d’un modèle, puis de s’y référer, le fait de définir les choix et leurs étiquettes à l’intérieur de la classe du modèle permet de conserver toutes ces informations avec la classe qui les exploite ainsi que de faciliter la référence à ces choix (par exemple, `Student.SOPHOMORE` fonctionnera partout où le modèle `Student` a été importé). Vous pouvez aussi arranger les choix possibles dans des groupes nommés qui pourront être utilisés à des fins d’organisation : ``` MEDIA_CHOICES = { "Audio": { "vinyl": "Vinyl", "cd": "CD", }, "Video": { "vhs": "VHS Tape", "dvd": "DVD", }, "unknown": "Unknown", } ``` La clé du dictionnaire est le nom utilisé pour le groupe et la valeur contient les choix à l’intérieur du groupe, consistant en valeur de champ et nom lisible par les humains pour chaque option. Les options groupées peuvent être combinées à des options non groupées dans un seul dictionnaire (comme l’option `"unknown"` dans cet exemple). Il est aussi possible d’utiliser une séquence, par ex. une liste de tuples binaires : ``` MEDIA_CHOICES = [ ( "Audio", ( ("vinyl", "Vinyl"), ("cd", "CD"), ), ), ( "Video", ( ("vhs", "VHS Tape"), ("dvd", "DVD"), ), ), ("unknown", "Unknown"), ] ``` Notez que ces choix peuvent être constitués par n’importe quelle séquence, et pas nécessairement par une liste ou un tuple. Ceci vous permet de construire dynamiquement la liste des choix. Mais si vous commencer à bidouiller l’attribut [`choices`](#django.db.models.Field.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`](#django.db.models.ForeignKey). [`choices`](#django.db.models.Field.choices) est conçu pour les données statiques qui ne changent pas souvent, voire jamais. > **Note** > > Une nouvelle migration est produite chaque fois que l’ordre des choix `choices` change. Pour chaque champ de modèle ayant l’option [`choices`](#django.db.models.Field.choices), Django normalise les choix à une liste de tuples binaires et ajoute une méthode pour obtenir l’étiquette à afficher selon la valeur actuelle du champ. Voir [`get_FOO_display()`](/fr/6.1/ref/models/instances/#django.db.models.Model.get_FOO_display) dans la documentation de l’API de base de données. Unless [`blank=False`](#django.db.models.Field.blank) is set on the field along with a [`default`](#django.db.models.Field.default) then a label containing `"- Select an option -"` will be rendered with the select box. To override this behavior, add a tuple to `choices` containing `None`; e.g. `(None, 'Your String For Display')`. Alternatively, you can use an empty string instead of `None` where this makes sense - such as on a [`CharField`](#django.db.models.CharField). > **Changed in Django 6.1** > > The default blank label was changed from `"---------"` to > `"- Select an option -"`. #### Types énumératifs De plus, Django fournit des types énumératifs dont vous pouvez hériter pour définir des choix de manière concise : ``` from django.utils.translation import gettext_lazy as _ class Student(models.Model): class YearInSchool(models.TextChoices): FRESHMAN = "FR", _("Freshman") SOPHOMORE = "SO", _("Sophomore") JUNIOR = "JR", _("Junior") SENIOR = "SR", _("Senior") GRADUATE = "GR", _("Graduate") year_in_school = models.CharField( max_length=2, choices=YearInSchool, default=YearInSchool.FRESHMAN, ) def is_upperclass(self): return self.year_in_school in { self.YearInSchool.JUNIOR, self.YearInSchool.SENIOR, } ``` Ils fonctionnent de la même manière que le type [`enum`](https://docs.python.org/3/library/enum.html#module-enum) de la bibliothèque Python standard, mais avec quelques modifications : - Les valeurs des membres Enum sont des tuples de paramètres à utiliser lors de la construction du type de données concret. Django prend en charge l’ajout d’une chaîne supplémentaire à la fin du tuple pour servir de nom humainement lisible, dit `label`. Ce `label` peut être une chaîne traduisible différée. Ainsi dans la plupart des cas, la valeur d’un membre sera un tuple binaire `(valeur, étiquette)`. Voir ci-dessous pour [un exemple de sous-classe de choix](#field-choices-enum-subclassing) utilisant un type de données plus complexe. Si la valeur fournie n’est pas un tuple ou que le dernier élément n’est pas une chaîne (possiblement différée), la partie `label` est [automatiquement générée](#field-choices-enum-auto-label) à partir du nom du membre. - Une propriété `.label` est ajoutée aux valeurs, pour renvoyer le nom humainement lisible. - Un certain nombre de propriétés personnalisées sont ajoutées aux classes énumératives – `.choices`, `.labels`, `.values`, and `.names` – pour faciliter l’accès aux listes des ces parties séparées de l’énumération. > **Warning** > > Ces noms de propriétés ne peuvent pas être employés comme noms de membres car cela occasionnerait un conflit. - L’utilisation de [`enum.unique()`](https://docs.python.org/3/library/enum.html#enum.unique) est forcé pour être sûr qu’une même valeur ne puisse pas être définie plusieurs fois. C’est peu probable pour une définition de choix d’un champ. Notez que l’utilisation de `YearInSchool.SENIOR`, `YearInSchool['SENIOR']`, ou `YearInSchool('SR')` pour accéder ou rechercher des membres d’une énumération fonctionne comme espéré, tout comme les propriétés `.name` et `.value` des membres. Si vous n’avez pas besoin d’avoir des noms humainement lisibles et traduisibles, vous pouvez laisser faire la classe qui s’occupera de déduire le `label` à partir du nom du membre (remplaçant les soulignements par des espaces et en mettant en majuscules les premières lettres de chaque mot) : ```pycon >>> class Vehicle(models.TextChoices): ... CAR = "C" ... TRUCK = "T" ... JET_SKI = "J" ... >>> Vehicle.JET_SKI.label 'Jet Ski' ``` Comme le cas où les valeurs énumératives sont des nombres entiers est extrêmement courant, Django fournit une classe `IntegerChoices`. Par exemple ``` class Card(models.Model): class Suit(models.IntegerChoices): DIAMOND = 1 SPADE = 2 HEART = 3 CLUB = 4 suit = models.IntegerField(choices=Suit) ``` Il est aussi possible de faire usage de l”[API fonctionnelle des Enum](https://docs.python.org/3/howto/enum.html#functional-api) avec la restriction que les étiquettes `label` sont automatiquement générées comme expliqué précédemment : ```pycon >>> MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE") >>> MedalType.choices [('GOLD', 'Gold'), ('SILVER', 'Silver'), ('BRONZE', 'Bronze')] >>> Place = models.IntegerChoices("Place", "FIRST SECOND THIRD") >>> Place.choices [(1, 'First'), (2, 'Second'), (3, 'Third')] ``` Si vous avez besoin de prendre en charge un type de données concret autre que `int` ou `str`, vous pouvez hériter de `Choices` et du type de données souhaité, comme par exemple utiliser [`date`](https://docs.python.org/3/library/datetime.html#datetime.date) pour un champ [`DateField`](#django.db.models.DateField): ``` class MoonLandings(datetime.date, models.Choices): APOLLO_11 = 1969, 7, 20, "Apollo 11 (Eagle)" APOLLO_12 = 1969, 11, 19, "Apollo 12 (Intrepid)" APOLLO_14 = 1971, 2, 5, "Apollo 14 (Antares)" APOLLO_15 = 1971, 7, 30, "Apollo 15 (Falcon)" APOLLO_16 = 1972, 4, 21, "Apollo 16 (Orion)" APOLLO_17 = 1972, 12, 11, "Apollo 17 (Challenger)" ``` Il y a quelques restrictions dont il faut tenir compte : - Les types énumératifs ne prennent pas en charge les [groupes nommés](#field-choices-named-groups). - Comme une énumération avec type de données concret exige que toutes les valeurs correspondent au type, le remplacement de l’[étiquette vierge](#field-choices-blank-label) ne peut pas se faire en créant un membre avec une valeur `None`. Il faut plutôt définir l’attribut `__empty__` de la classe ``` class Answer(models.IntegerChoices): NO = 0, _("No") YES = 1, _("Yes") __empty__ = _("(Unknown)") ``` ### `db_column` #### `Field.db_column` Le nom de la colonne à utiliser pour ce champ dans la base de données. Si cet attribut est absent, Django utilise le nom du champ. Si le nom de la colonne dans la base de données est un mot réservé en SQL ou s’il contient des caractères non autorisés dans le nom d’une variable Python (notamment, le trait d’union), ce n’est pas un souci. Django met entre guillemets les noms de table et de colonne de manière transparente. ### `db_comment` #### `Field.db_comment` Le commentaire sur la colonne de base de données à utiliser pour ce champ. C’est utile pour documenter les champs pour ceux qui ont un accès direct à la base de données et qui ne lisent pas forcément votre code Django. Par exemple ``` pub_date = models.DateTimeField( db_comment="Date and time when the article was published", ) ``` ### `db_default` #### `Field.db_default` La valeur par défaut générée en base de données pour ce champ. Il peut s’agir d’une valeur littérale ou d’une fonction de base de données, telle que [`Now`](/fr/6.1/ref/models/database-functions/#django.db.models.functions.Now): ``` created = models.DateTimeField(db_default=Now()) ``` Des expressions plus complexes peuvent être utilisées, tant qu’elles sont composées de valeurs littérales et de fonctions de bases de données : ``` month_due = models.DateField( db_default=TruncMonth( Now() + timedelta(days=90), output_field=models.DateField(), ) ) ``` Les valeurs par défaut de bases de données ne peuvent pas se référer à d’autres champs ou modèles. Par exemple, ceci n’est pas valide : ``` end = models.IntegerField(db_default=F("start") + 50) ``` Si `db_default` et [`Field.default`](#django.db.models.Field.default) sont tous deux définis, `default` aura la priorité lors de la création d’instance à partir de code Python. `db_default` sera tout de même défini au niveau de la base de données et sera utilisé dans les cas d’insertion effectuée en dehors de l’ORM Django ou lors d’ajout de nouveaux champs dans une migration. Si un champ comporte un `db_default` sans valeur `default` et que le champ ne reçoit pas de valeur explicite, un objet `DatabaseDefault` est renvoyé comme valeur de ce champ pour des instances de modèle pas encore enregistrées. La valeur réelle du champ est déterminée par la base de données au moment où l’instance de modèle est enregistrée. ### `db_index` #### `Field.db_index` Si `True`, une index de base de données sera créé pour ce champ. > **Utilisez plutôt l’option indexes.** > > Si possible, utilisez plutôt l’option [`Meta.indexes`](/fr/6.1/ref/models/options/#django.db.models.Options.indexes). Dans presque tous les cas, [`indexes`](/fr/6.1/ref/models/options/#django.db.models.Options.indexes) offre plus de fonctionnalités que `db_index`. `db_index` pourrait être rendu obsolète dans le futur. ### `db_tablespace` #### `Field.db_tablespace` Le nom de l’[espace de tables de base de données](/fr/6.1/topics/db/tablespaces/) à utiliser pour l’index de ce champ, si ce champ est indexé. La valeur par défaut est le réglage [`DEFAULT_INDEX_TABLESPACE`](/fr/6.1/ref/settings/#std-setting-DEFAULT_INDEX_TABLESPACE) du projet, s’il est défini, ou l’attribut [`db_tablespace`](/fr/6.1/ref/models/options/#django.db.models.Options.db_tablespace) du modèle, s’il existe. Si le moteur de base de données ne prend pas en charge les espaces de tables, cette option est ignorée. ### `default` #### `Field.default` La valeur par défaut du champ. Cela peut être une valeur ou un objet exécutable. Dans ce dernier cas, l’objet est appelé lors de chaque création d’un nouvel objet. La valeur par défaut ne peut pas être un objet mutant (instance de modèle, `list`, `set`, etc.), car toutes les nouvelles instances du modèle utiliseraient une référence vers la même instance de cet objet. Au lieu de cela, imbriquez la valeur par défaut souhaitée dans un exécutable. Par exemple, si vous vouliez indiquer un `dict` par défaut pour un champ [`JSONField`](#django.db.models.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](/fr/6.1/topics/migrations/#migration-serializing). Consultez cette dernière documentation pour d’autres mises en garde. Pour les champs comme [`ForeignKey`](#django.db.models.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`](#django.db.models.ForeignKey.to_field) est défini) et non pas des instances de modèles. La valeur par défaut est utilisée lorsque de nouvelles instances de modèle sont créées et qu’aucune valeur n’est fournie pour le champ. Lorsque le champ est une clé primaire, la valeur par défaut est aussi utilisée si le champ est défini à `None`. La valeur par défaut peut aussi être utilisée au niveau de la base de données avec [`Field.db_default`](#django.db.models.Field.db_default). ### `editable` #### `Field.editable` Si `False`, le champ ne sera pas affiché dans l’administration de Django, ni dans d’éventuels formulaires basés sur [`ModelForm`](/fr/6.1/topics/forms/modelforms/#django.forms.ModelForm). Il sera aussi omis dans la phase de [validation de modèle](/fr/6.1/ref/models/instances/#validating-objects). La valeur par défaut est `True`. ### `error_messages` #### `Field.error_messages` Le paramètre `error_messages` permet de redéfinir les messages par défaut que le champ renvoie. Passez un dictionnaire dont les clés correspondent aux messages d’erreur que vous voulez redéfinir. Les clés des messages d’erreur comprennent `null`, `blank`, `invalid`, `invalid_choice`, `unique` et `unique_for_date`. D’autres clés de messages d’erreur sont définies pour chaque champ de la section [types de champs](#field-types) ci-dessous. Ces messages d’erreur ne se propagent souvent pas aux formulaires. Voir [Considérations sur les messages d’erreur des modèles](/fr/6.1/topics/forms/modelforms/#considerations-regarding-model-errormessages). ### `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`](#django.db.models.Field.help_text) si vous le souhaitez. Par exemple : ``` help_text = "Please use the following format: YYYY-MM-DD." ``` Accessoirement, vous pouvez utiliser du texte brut et [`django.utils.html.escape()`](/fr/6.1/ref/utils/#django.utils.html.escape) pour échapper n’importe quel caractère spécial HTML. Assurez-vous d’échapper tout texte d’aide qui proviendrait d’utilisateurs non fiables afin d’éviter des attaques de script inter-site. ### `primary_key` #### `Field.primary_key` Si la valeur est `True`, ce champ représentera la clé primaire du modèle. Si vous n’indiquez aucun paramètre `primary_key=True` dans les champs d’un modèle et que vous n’avez pas défini de clé primaire composite, 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`](/fr/6.1/ref/applications/#django.apps.AppConfig.default_auto_field) ou globalement dans le réglage [`DEFAULT_AUTO_FIELD`](/fr/6.1/ref/settings/#std-setting-DEFAULT_AUTO_FIELD). Pour en savoir plus, consultez [Champs clé primaire automatiques](/fr/6.1/topics/db/models/#automatic-primary-key-fields). `primary_key=True` implique [`null=False`](#django.db.models.Field.null) et [`unique=True`](#django.db.models.Field.unique). Seul un champ par modèle peut recevoir `primary_key=True`. Les clés primaires composites doivent être définies avec [`CompositePrimaryKey`](#django.db.models.CompositePrimaryKey) et non pas en définissant `primary_key=True` pour tous les champs formant la clé unique. 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. The primary key field is set to `None` when calling a model instance’s [`delete()`](/fr/6.1/ref/models/instances/#django.db.models.Model.delete) method. ### `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`](#django.db.models.Field.unique) dupliquée, une exception [`django.db.IntegrityError`](/fr/6.1/ref/exceptions/#django.db.IntegrityError) sera levée par la méthode [`save()`](/fr/6.1/ref/models/instances/#django.db.models.Model.save) du modèle. Cette option est valide pour tous les types de champs, sauf pour [`ManyToManyField`](#django.db.models.ManyToManyField) et [`OneToOneField`](#django.db.models.OneToOneField). Notez que lorsque `unique` vaut `True`, il n’est pas nécessaire de définir [`db_index`](#django.db.models.Field.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`](#django.db.models.DateField) ou [`DateTimeField`](#django.db.models.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`](#django.db.models.DateTimeField), seule la partie date du champ est prise en compte. De plus, lorsque [`USE_TZ`](/fr/6.1/ref/settings/#std-setting-USE_TZ) vaut `True`, le contrôle est effectué dans le [fuseau horaire en cours](/fr/6.1/topics/i18n/timezones/#default-current-time-zone) au moment où l’objet est enregistré. Cette contrainte est appliquée par [`Model.validate_unique()`](/fr/6.1/ref/models/instances/#django.db.models.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`](#django.db.models.Field.unique_for_date) implique des champs qui ne font pas partie d’un formulaire [`ModelForm`](/fr/6.1/topics/forms/modelforms/#django.forms.ModelForm) (par exemple si l’un des champs figure dans `exclude` ou que son attribut [`editable`](#django.db.models.Field.editable) vaut `False`), [`Model.validate_unique()`](/fr/6.1/ref/models/instances/#django.db.models.Model.validate_unique) passe outre la validation de la contrainte concernée. ### `unique_for_month` #### `Field.unique_for_month` Comme [`unique_for_date`](#django.db.models.Field.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`](#django.db.models.Field.unique_for_date) et [`unique_for_month`](#django.db.models.Field.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](/fr/6.1/topics/db/models/#verbose-field-names). ### `validators` #### `Field.validators` Une liste de validateurs à exécuter pour ce champ. Consultez la [documentation des validateurs](/fr/6.1/ref/validators/) pour plus d’informations. ## Types de champs ### `AutoField` #### `class AutoField(**options)` Un champ [`IntegerField`](#django.db.models.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](/fr/6.1/topics/db/models/#automatic-primary-key-fields). ### `BigAutoField` #### `class BigAutoField(**options)` Un entier 64 bits, ressemblant à un [`AutoField`](#django.db.models.AutoField) sauf qu’il garantit la couverture des nombres de `1` à `9223372036854775807`. ### `BigIntegerField` #### `class BigIntegerField(**options)` Un entier 64 bits, ressemblant à un [`IntegerField`](#django.db.models.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`](/fr/6.1/ref/forms/widgets/#django.forms.NumberInput). ### `BinaryField` #### `class BinaryField(max_length=None, **options)` Un champ pour stocker des données binaires brutes. Il peut recevoir des données de type [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes), [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray) ou [`memoryview`](https://docs.python.org/3/library/stdtypes.html#memoryview). Par défaut, `BinaryField` définit [`editable`](#django.db.models.Field.editable) à `False`, auquel cas il ne peut être inclus dans un formulaire [`ModelForm`](/fr/6.1/topics/forms/modelforms/#django.forms.ModelForm). #### `BinaryField.max_length` Facultatif. La taille maximale (en octets) du champ. Cette longueur maximale est contrôlée par la validation de Django en utilisant [`MaxLengthValidator`](/fr/6.1/ref/validators/#django.core.validators.MaxLengthValidator). > **Usage abusif de BinaryField** > > Bien qu’il puisse être tentant de vouloir stocker des fichiers dans la base de données, il s’agit d’une mauvaise idée dans 99 % des cas. Ce champ n’est *pas* une solution de remplacement d’une bonne gestion des [fichiers statiques](/fr/6.1/howto/static-files/). ### `BooleanField` #### `class BooleanField(**options)` Un champ vrai/faux. Le composant de formulaire par défaut de ce champ est un [`CheckboxInput`](/fr/6.1/ref/forms/widgets/#django.forms.CheckboxInput), ou [`NullBooleanSelect`](/fr/6.1/ref/forms/widgets/#django.forms.NullBooleanSelect) si [`null=True`](#django.db.models.Field.null). La valeur par défaut de `BooleanField` est `None` lorsque [`Field.default`](#django.db.models.Field.default) n’est pas défini. ### `CompositePrimaryKey` #### `class CompositePrimaryKey(*field_names, **options)` Un champ virtuel utilisé pour définir une clé primaire composite. Ce champ doit être défini pour l’attribut `pk` du modèle. Si présent, Django va créer la table de modèle sous-jacente avec une clé primaire composite. L’argument `*field_names` est une liste de noms de champs positionnels qui composent la clé primaire. Voir [Clés primaires composites](/fr/6.1/topics/composite-primary-key/) pour plus de détails. ### `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`](#django.db.models.TextField). Le composant de formulaire par défaut de ce champ est un [`TextInput`](/fr/6.1/ref/forms/widgets/#django.forms.TextInput). [`CharField`](#django.db.models.CharField) offre les paramètres supplémentaires suivants : #### `CharField.max_length` La longueur maximale du champ (en caractères). La longueur `max_length` est garantie au niveau de la base de données et dans la validation de Django grâce à [`MaxLengthValidator`](/fr/6.1/ref/validators/#django.core.validators.MaxLengthValidator). Ce paramètre est obligatoire pour tous les moteurs de base de données inclus dans Django à l’exception de PostgreSQL et SQLite qui prennent en charge les colonnes `VARCHAR` illimitées. > **Note** > > Si vous écrivez une application qui doit être portable sur plusieurs moteurs de base de données, il faut savoir qu’il y a des restrictions à propos de `max_length` pour certains de ces moteurs. Référez-vous aux [notes sur les moteurs de base de données](/fr/6.1/ref/databases/) pour plus de détails. #### `CharField.db_collation` Facultatif. Le nom de collation de base de données pour le champ. > **Note** > > Les noms de collation ne sont pas standardisés. De fait, ils ne sont pas portables entre les différents moteurs de base de données. > **Oracle** > > Oracle ne prend en charge les collations que lorsque le paramètre d’initialisation de base de données `MAX_STRING_SIZE` est défini à `EXTENDED`. ### `DateField` #### `class DateField(auto_now=False, auto_now_add=False, **options)` Une date, représentée en Python par une instance de `datetime.date`. Accepte quelques paramètres supplémentaires et facultatifs : #### `DateField.auto_now` Assigne automatiquement la valeur du champ à la date du jour lors de chaque enregistrement de l’objet. Utile pour les horodatages de « dernière modification ». Notez que c’est *toujours* la date actuelle qui est utilisée ; il ne s’agit pas seulement d’une valeur par défaut que l’on peut surcharger. La mise à jour automatique de ce champ ne se produit que lors de l’appel à [`Model.save()`](/fr/6.1/ref/models/instances/#django.db.models.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()`](/fr/6.1/ref/models/querysets/#django.db.models.query.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_add` Assigne automatiquement la valeur du champ à la date du jour lors du premier enregistrement de l’objet. Utile pour les horodatages de date de création. Notez que c’est *toujours* la date actuelle qui est utilisée ; il ne s’agit pas seulement d’une valeur par défaut que l’on peut surcharger. Ainsi, même si vous définissez une valeur pour ce champ lors de la création de l’objet, il sera ignoré. Si vous voulez pouvoir modifier ce champ, utilisez ce qui suit au lieu de définir `auto_now_add=True`: - Pour un champ [`DateField`](#django.db.models.DateField): `default=date.today` \- de [`datetime.date.today()`](https://docs.python.org/3/library/datetime.html#datetime.date.today) - Pour un champ [`DateTimeField`](#django.db.models.DateTimeField): `default=timezone.now` \- de [`django.utils.timezone.now()`](/fr/6.1/ref/utils/#django.utils.timezone.now) Le composant de formulaire par défaut de ce champ est un [`DateInput`](/fr/6.1/ref/forms/widgets/#django.forms.DateInput). L’interface d’administration ajoute un calendrier JavaScript ainsi qu’un raccourci pour « Aujourd’hui ». Contient une clé supplémentaire de message d’erreur `invalid_date`. Les options `auto_now_add`, `auto_now` et `default` sont mutuellement exclusives. Toute combinaison de ces options produira une erreur. > **Note** > > Avec l’implémentation actuelle, si `auto_now` ou `auto_now_add` sont activés, les paramètres de champ suivants sont définis automatiquement : `editable=False` et `blank=True`. > **Note** > > Les options `auto_now` et `auto_now_add` utilisent toujours la date dans le [fuseau horaire par défaut](/fr/6.1/topics/i18n/timezones/#default-current-time-zone) au moment de la création ou de la mise à jour. Si vos besoins sont différents, vous pouvez envisager d’utiliser votre propre fonction de valeur par défaut ou de surcharger `save()` au lieu de faire appel à `auto_now` ou `auto_now_add`. Ou encore d’utiliser un champ `DateTimeField` au lieu d’un champ `DateField` et de décider de la manière de gérer la conversion d’une heure/date vers une date au moment de son affichage. > **Warning** > > Utilisez toujours [`DateField`](#django.db.models.DateField) avec des instances `datetime.date`. > > Si vous avez des instances `datetime.datetime`, il est recommandé de les convertir d’abord en `datetime.date`. Sinon, [`DateField`](#django.db.models.DateField) va régionaliser l’instance `datetime.datetime` dans le [fuseau horaire par défaut](/fr/6.1/topics/i18n/timezones/#default-current-time-zone) et la convertir en instance `datetime.date` en enlevant la composante horaire. Ceci vaut aussi bien pour le stockage que pour la comparaison. > **Warning** > > On PostgreSQL and MySQL, arithmetic operations on a `DateField` with a > [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) return a `datetime` instead of a `date`. > This occurs because Python’s `timedelta` is converted to SQL > `INTERVAL`, and the SQL operation `date +/- interval` returns a > `timestamp` on these databases. > > To ensure a `date` result, use one of the following approaches. Either > explicitly cast the result to a date: > > ``` > import datetime > from django.db.models import DateField, F > from django.db.models.functions import Cast > > qs = MyModel.objects.annotate( > previous_day=Cast( > F("date_field") - datetime.timedelta(days=1), > output_field=DateField(), > ) > ) > ``` > > Or on PostgreSQL only, use integer arithmetic to represent days: > > ``` > from django.db.models import DateField, ExpressionWrapper, F > > qs = MyModel.objects.annotate( > previous_day=ExpressionWrapper( > F("date_field") - 1, # Subtract 1 day as integer > output_field=DateField(), > ) > ) > ``` ### `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`](#django.db.models.DateField). Le composant de formulaire par défaut de ce champ est un [`DateTimeInput`](/fr/6.1/ref/forms/widgets/#django.forms.DateTimeInput). L’interface d’administration utilise deux composants [`TextInput`](/fr/6.1/ref/forms/widgets/#django.forms.TextInput) séparés avec des raccourcis JavaScript. > **Warning** > > Utilisez toujours `DateFieldField` avec des instances `datetime.datetime`. > > Si vous avez des instances `datetime.date`, il est recommandé de les convertir d’abord en `datetime.datetime`. Sinon, [`DateTimeField`](#django.db.models.DateTimeField) va utiliser minuit dans le [fuseau horaire par défaut](/fr/6.1/topics/i18n/timezones/#default-current-time-zone) pour y ajouter la composante horaire. Ceci vaut aussi bien pour le stockage que pour la comparaison. Pour comparer la partie date d’un champ [`DateTimeField`](#django.db.models.DateTimeField) avec une instance `datetime.date`, utilisez l’expression de requête [`date`](/fr/6.1/ref/models/querysets/#std-fieldlookup-date). ### `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`](https://docs.python.org/3/library/decimal.html#decimal.Decimal). Les saisies sont validées en utilisant [`DecimalValidator`](/fr/6.1/ref/validators/#django.core.validators.DecimalValidator). Has the following arguments: #### `DecimalField.max_digits` The maximum number of digits allowed in the number. Note that this number must be greater than or equal to `decimal_places`. It’s always required on MySQL because this database doesn’t support numeric fields with no precision. It’s also required for all database backends when [`decimal_places`](#django.db.models.DecimalField.decimal_places) is provided. #### `DecimalField.decimal_places` The number of decimal places to store with the number. It’s always required on MySQL because this database doesn’t support numeric fields with no precision. It’s also required for all database backends when [`max_digits`](#django.db.models.DecimalField.max_digits) is provided. Par exemple, pour enregistrer un nombre jusqu’à `999.99` avec une précision de 2 chiffres après la virgule, vous devriez utiliser : ``` models.DecimalField(..., max_digits=5, decimal_places=2) ``` Et pour enregistrer un nombre jusqu’à un milliard environ avec une précision de 10 chiffres après la virgule : ``` models.DecimalField(..., max_digits=19, decimal_places=10) ``` Le composant de formulaire par défaut de ce champ est un [`NumberInput`](/fr/6.1/ref/forms/widgets/#django.forms.NumberInput) lorsque [`localize`](/fr/6.1/ref/forms/fields/#django.forms.Field.localize) vaut `False`, ou [`TextInput`](/fr/6.1/ref/forms/widgets/#django.forms.TextInput) dans le cas contraire. > **Note** > > Pour plus d’informations sur les différences entre les classes [`FloatField`](#django.db.models.FloatField) et [`DecimalField`](#django.db.models.DecimalField), consultez [FloatField vs. DecimalField](#floatfield-vs-decimalfield). IL est aussi important d’être conscient des [limites de SQLite](/fr/6.1/ref/databases/#sqlite-decimal-handling) à propos des champs décimaux. > **Changed in Django 6.1** > > Support for `DecimalField` with no precision was added on Oracle, > PostgreSQL, and SQLite. ### `DurationField` #### `class DurationField(**options)` Un champ pour stocker des périodes de temps, représentées en Python par des objets [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta). Avec PostgreSQL, le type de données utilisé est un `interval` et avec Oracle, le type de données est `INTERVAL DAY(9) TO SECOND(6)`. Sinon, c’est un grand nombre entier `bigint` de microsecondes qui est utilisé. > **Note** > > L’arithmétique des champs `DurationField` fonctionne la plupart du temps. Cependant, pour toutes les bases de données autres que PostgreSQL, la comparaison de valeurs d’un champ `DurationField` avec l’arithmétique des instances `DateTimeField` ne fonctionne pas comme on pourrait l’espérer. ### `EmailField` #### `class EmailField(max_length=254, **options)` Un champ [`CharField`](#django.db.models.CharField) qui vérifie que sa valeur est une adresse électronique valide en utilisant [`EmailValidator`](/fr/6.1/ref/validators/#django.core.validators.EmailValidator). ### `FileField` #### `class FileField(upload_to='', storage=None, max_length=100, **options)` Un champ de fichier à téléverser. > **Note** > > Le paramètre `primary_key` n’est pas pris en charge et génère une erreur s’il est utilisé. Il offre les paramètres facultatifs suivants : #### `FileField.upload_to` Cet attribut permet de définir le répertoire de téléversement et le nom de fichier. Il peut être défini de deux manières. Dans les deux cas, la valeur est transmise à la méthode [`Storage.save()`](/fr/6.1/ref/files/storage/#django.core.files.storage.Storage.save). Si vous indiquez une valeur textuelle ou un chemin [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path), la valeur peut contenir des chaînes de format [`strftime()`](https://docs.python.org/3/library/time.html#time.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 : ``` 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`](/fr/6.1/ref/files/storage/#django.core.files.storage.FileSystemStorage), la valeur textuelle sera ajoutée au chemin [`MEDIA_ROOT`](/fr/6.1/ref/settings/#std-setting-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 : ``` def user_directory_path(instance, filename): # file will be uploaded to MEDIA_ROOT/user_/ return "user_{0}/{1}".format(instance.user.id, filename) class MyModel(models.Model): upload = models.FileField(upload_to=user_directory_path) ``` #### `FileField.storage` Un objet de stockage ou un objet exécutable qui renvoie un objet de stockage. Celui-ci prend en charge l’enregistrement et la récupération des fichiers. Consultez [Gestion des fichiers](/fr/6.1/topics/files/) 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`](/fr/6.1/ref/forms/widgets/#django.forms.ClearableFileInput). L’utilisation d’un [`FileField`](#django.db.models.FileField) ou d’un [`ImageField`](#django.db.models.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`](/fr/6.1/ref/settings/#std-setting-MEDIA_ROOT) le chemin d’accès absolu vers un répertoire où Django peut enregistrer les fichiers téléversés (pour des raisons de performance, ces fichiers ne sont pas stockés en base de données). Indiquez dans [`MEDIA_URL`](/fr/6.1/ref/settings/#std-setting-MEDIA_URL) l’URL publique de base correspondant à ce répertoire. Assurez-vous que ce répertoire soit accessible en écriture par l’utilisateur du serveur web. 2. Ajoutez le champ [`FileField`](#django.db.models.FileField) ou [`ImageField`](#django.db.models.ImageField) à votre modèle, en définissant l’option [`upload_to`](#django.db.models.FileField.upload_to) pour indiquer dans quel sous-répertoire de [`MEDIA_ROOT`](/fr/6.1/ref/settings/#std-setting-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`](/fr/6.1/ref/settings/#std-setting-MEDIA_ROOT)). Il est très commode et courant d’utiliser l’attribut [`url`](#django.db.models.fields.files.FieldFile.url) offert par Django. Par exemple, considérant un [`ImageField`](#django.db.models.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`](/fr/6.1/ref/settings/#std-setting-MEDIA_ROOT) contient `'/home/media'` et que la valeur de [`upload_to`](#django.db.models.FileField.upload_to) est `'photos/%Y/%m/%d'`. La partie `'%Y/%m/%d'` de [`upload_to`](#django.db.models.FileField.upload_to) est du formatage [`strftime()`](https://docs.python.org/3/library/time.html#time.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`](/fr/6.1/ref/files/file/#django.core.files.File.name) et [`size`](/fr/6.1/ref/files/file/#django.core.files.File.size) respectivement. Pour plus d’informations sur les attributs et méthodes disponibles, consultez la référence de la classe [`File`](/fr/6.1/ref/files/file/#django.core.files.File) et le guide thématique [Gestion des fichiers](/fr/6.1/topics/files/). > **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`](#django.db.models.fields.files.FieldFile.url). En interne, c’est la méthode [`url()`](/fr/6.1/ref/files/storage/#django.core.files.storage.Storage.url) de la classe [`Storage`](/fr/6.1/ref/files/storage/#django.core.files.storage.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`](#django.db.models.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`](#django.db.models.CharField.max_length). #### `FileField` et `FieldFile` #### `class FieldFile` Lorsque vous accédez à un [`FileField`](#django.db.models.FileField) d’un modèle, vous recevez une instance de [`FieldFile`](#django.db.models.fields.files.FieldFile) comme substitut d’accès au fichier sous-jacent. L’API de [`FieldFile`](#django.db.models.fields.files.FieldFile) reflète celle de [`File`](/fr/6.1/ref/files/file/#django.core.files.File), avec une différence clé : *l’objet adapté par la classe n’est pas forcément une adaptation de l’objet fichier natif de Python*. C’est au contraire une adaptation du résultat de la méthode [`Storage.open()`](/fr/6.1/ref/files/storage/#django.core.files.storage.Storage.open), qui peut être un objet [`File`](/fr/6.1/ref/files/file/#django.core.files.File) ou une implémentation d’un stockage personnalisé de l’API de [`File`](/fr/6.1/ref/files/file/#django.core.files.File). En plus de l’API héritée de [`File`](/fr/6.1/ref/files/file/#django.core.files.File), comme `read()` et `write()`, [`FieldFile`](#django.db.models.fields.files.FieldFile) comprend plusieurs méthodes pouvant être utilisées pour interagir avec le fichier sous-jacent : > **Warning** > > Deux méthodes de cette classe, [`save()`](#django.db.models.fields.files.FieldFile.save) et [`delete()`](#django.db.models.fields.files.FieldFile.delete) enregistrent par défaut l’objet modèle du `FieldFile` associé dans la base de données. #### `FieldFile.name` Le nom du fichier contenant le chemin relatif depuis la racine de [`Storage`](/fr/6.1/ref/files/storage/#django.core.files.storage.Storage) du champ [`FileField`](#django.db.models.FileField) associé. #### `FieldFile.path` Une propriété en lecture seule pour accéder au chemin du fichier sur le système de fichiers local en appelant la méthode [`path()`](/fr/6.1/ref/files/storage/#django.core.files.storage.Storage.path) de la classe [`Storage`](/fr/6.1/ref/files/storage/#django.core.files.storage.Storage) sous-jacente. #### `FieldFile.size` Le résultat de la méthode sous-jacente [`Storage.size()`](/fr/6.1/ref/files/storage/#django.core.files.storage.Storage.size). #### `FieldFile.url` Une propriété en lecture seule pour accéder à l’URL relative du fichier, au travers de l’appel à la méthode [`url()`](/fr/6.1/ref/files/storage/#django.core.files.storage.Storage.url) de la classe [`Storage`](/fr/6.1/ref/files/storage/#django.core.files.storage.Storage) sous-jacente. #### `FieldFile.open(mode='rb')` Ouvre ou réouvre le fichier associé à cette instance dans le `mode` spécifié. Au contraire de la méthode Python standard `open()`, elle ne renvoie pas de descripteur de fichier. Comme le fichier sous-jacent est ouvert implicitement lors de son accès, il peut être inutile d’appeler cette méthode, sauf si l’on veut réinitialiser le pointeur du fichier sous-jacent ou que l’on veut changer le `mode`. #### `FieldFile.close()` Même comportement que la méthode `file.close()` standard de Python et ferme le fichier associé à l’instance actuelle. #### `FieldFile.save(name, content, save=True)` Cette méthode accepte un nom de fichier et le contenu du fichier, les transmet à la classe de stockage du champ puis associe le fichier ainsi stocké avec le champ du modèle. Si vous souhaitez attribuer manuellement des données de fichier avec des instances [`FileField`](#django.db.models.FileField) d’un modèle, la méthode `save()` est utilisée pour rendre persistantes ces données de fichier. Requiert deux paramètres obligatoires : `name` correspondant au nom du fichier et `content` qui représente un objet contenant le contenu du fichier. Le paramètre facultatif `save` indique si l’instance de modèle doit être enregistrée après la modification du fichier associé à ce champ. Sa valeur par défaut est `True`. Notez que le paramètre `content` doit être une instance de [`django.core.files.File`](/fr/6.1/ref/files/file/#django.core.files.File), et non pas de l’objet `file` de Python. Vous pouvez construire une instance de [`File`](/fr/6.1/ref/files/file/#django.core.files.File) à partir d’un objet Python `file` existant comme ceci : ``` from django.core.files import File # Open an existing file using Python's built-in open() f = open("/path/to/hello.world") myfile = File(f) ``` Ou il est aussi possible de le construire à partir d’une chaîne de caractères Python comme ceci : ``` from django.core.files.base import ContentFile myfile = ContentFile("hello world") ``` Pour plus d’informations, voir [Gestion des fichiers](/fr/6.1/topics/files/). #### `FieldFile.delete(save=True)` Supprime le fichier associé à cette instance et efface tous les attributs du champ. Remarque : cette méthode ferme le fichier s’il se trouve être ouvert lorsque `delete()` est appelée. Le paramètre facultatif `save` indique si l’instance de modèle doit être enregistrée après la suppression du fichier associé à ce champ. Sa valeur par défaut est `True`. Notez que lorsqu’un modèle est supprimé, les fichiers liés ne sont pas supprimés. Si vous devez effacer les fichiers orphelins, c’est à vous de le faire (par exemple avec une commande de gestion personnalisée lancée manuellement ou programmée de manière périodique par un outil tel que cron). ### `FilePathField` #### `class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options)` Un [`CharField`](#django.db.models.CharField) dont les choix sont limités aux noms de fichiers dans un répertoire déterminé du système de fichiers. Il possède quelques paramètres particuliers, dont le premier est **obligatoire** : #### `FilePathField.path` Obligatoire. Le chemin d’accès absolu vers le répertoire dont le contenu fournit la source des choix du [`FilePathField`](#django.db.models.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 ``` 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.match` Facultatif. Une expression régulière sous forme de chaîne de caractères qui sera utilisée par [`FilePathField`](#django.db.models.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`](#django.db.models.FilePathField.path) doivent être inclus. #### `FilePathField.allow_files` 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`](#django.db.models.FilePathField.allow_folders), soit `True`. #### `FilePathField.allow_folders` 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`](#django.db.models.FilePathField.allow_files), soit `True`. Le piège potentiel est que [`match`](#django.db.models.FilePathField.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`](#django.db.models.FilePathField.match) s’applique uniquement au nom du fichier (`foo.png` et `bar.png`). Les instances de [`FilePathField`](#django.db.models.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`](#django.db.models.CharField.max_length). ### `FloatField` #### `class FloatField(**options)` Un nombre flottant représenté en Python par une instance de `float`. Le composant de formulaire par défaut de ce champ est un [`NumberInput`](/fr/6.1/ref/forms/widgets/#django.forms.NumberInput) lorsque [`localize`](/fr/6.1/ref/forms/fields/#django.forms.Field.localize) vaut `False`, ou [`TextInput`](/fr/6.1/ref/forms/widgets/#django.forms.TextInput) dans le cas contraire. > **FloatField vs. DecimalField** > > La classe [`FloatField`](#django.db.models.FloatField) est parfois confondue avec la classe [`DecimalField`](#django.db.models.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`](https://docs.python.org/3/library/decimal.html#module-decimal). ### `GeneratedField` #### `class GeneratedField(* (Keyword-only parameters separator (PEP 3102)), expression, output_field, db_persist, **kwargs)` Un champ qui est toujours calculé en fonction d’autres champs du même modèle. Ce champ est géré et mis à jour par la base de données elle-même. Il utilise la syntaxe SQL `GENERATED ALWAYS`. Il existe deux sortes de colonnes auto-générées : persistantes et virtuelles. Une colonne auto-générée persistante est calculée au moment de son écriture (insertion/mise à jour) et occupe de l’espace comme si c’était une colonne normale. Une colonne auto-générée virtuelle n’occupe pas d’espace disque et est calculée au moment de sa lecture. Ainsi, une colonne auto-générée virtuelle est pareille à une vue, alors qu’un colonne auto-générée persistante est pareille à une vue matérialisée. #### `GeneratedField.expression` Une [`Expression`](/fr/6.1/ref/models/expressions/#django.db.models.Expression) utilisée par la base de données pour définir automatiquement la valeur du champ chaque fois que le modèle est modifié. Les expressions doivent être déterministes et se limiter à référencer des champs du même modèle (dans la même table de base de données). Les champs auto-générés ne peuvent pas faire référence à d’autres champs auto-générés. Les moteurs de base de données peuvent imposer des restrictions supplémentaires. #### `GeneratedField.output_field` Une instance de champ de modèle pour définir le type de données du champ. #### `GeneratedField.db_persist` Détermine si la colonne de base de données doit être stockée comme une colonne réelle. Si `False`, la colonne se comporte comme une colonne virtuelle et n’occupe aucun espace de stockage de base de données. PostgreSQL \< 18 only supports persisted columns. Oracle \< 23ai/26ai (23.7) only supports virtual columns. > **Changed in Django 6.1** > > Support for virtual `GeneratedField`s was added on Postgres 18+ and > for stored ones on Oracle 23ai/26ai (23.7+). > **Limites des bases de données** > > Il y a de nombreuses restrictions spécifiques aux diverses bases de données pour les champs auto-générés que Django ne contrôle pas, ce qui peut générer des erreurs au niveau de la base de données. Par exemple, PostgreSQL exige des fonctions et opérateurs référencés dans une colonne générée qu’ils soient marqués comme `IMMUTABLE`. > > Vous devriez toujours vérifier que `expression` est prise en charge pour votre base de données. Consultez les documentations [MariaDB](https://mariadb.com/kb/en/generated-columns/#expression-support), [MySQL](https://dev.mysql.com/doc/refman/en/create-table-generated-columns.html), [Oracle](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/CREATE-TABLE.html#GUID-F9CE0CC3-13AE-4744-A43C-EAC7A71AAAB6__BABIIGBD), [PostgreSQL](https://www.postgresql.org/docs/current/ddl-generated-columns.html) ou [SQLite](https://www.sqlite.org/gencol.html#limitations). > **Changed in Django 6.0** > > `GeneratedField`s are now automatically refreshed from the database on > backends that support it (SQLite, PostgreSQL, and Oracle) and marked as > deferred otherwise. [`null`](#django.db.models.Field.null) has no effect on `GeneratedField` since whether the column is nullable depends on the database and expression used. ### `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`](/fr/6.1/ref/forms/widgets/#django.forms.TextInput). La normalisation d’adresse IPv6 respecte la section 2.2 de la [**RFC 4291 Section 2.2**](https://datatracker.ietf.org/doc/html/rfc4291.html#section-2.2), y compris l’utilisation du format IPv4 suggéré dans le 3e paragraphe de cette section, comme `::ffff:192.0.2.0`. Par exemple, `2001:0::0:01` sera normalisé en `2001::1` et `::ffff:0a0a:0a0a` en `::ffff:10.10.10.10`. Tous les caractères sont convertis en minuscules. #### `GenericIPAddressField.protocol` Limite la validité des saisies au protocole indiqué. Les valeurs possibles sont `'both'` (les deux protocoles acceptés, valeur par défaut), `'IPv4'` ou `'IPv6'`. #### `GenericIPAddressField.unpack_ipv4` Décode les adresses IPv4 mappées comme `::ffff:192.0.2.1`. Si cette option est activée, cette adresse serait décodée 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. ### `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`](#django.db.models.FileField), mais valide également que l’objet téléversé est une image valide. En complément des attributs spéciaux disponibles pour [`FileField`](#django.db.models.FileField), un champ [`ImageField`](#django.db.models.ImageField) possède aussi les attributs `height` et `width`. Pour faciliter l’interrogation de ces attributs, [`ImageField`](#django.db.models.ImageField) possède les paramètres facultatifs suivants : #### `ImageField.height_field` Le nom d’un champ du modèle qui sera automatiquement renseigné avec la hauteur de l’image à chaque fois qu’un objet image est attribué. #### `ImageField.width_field` Le nom d’un champ du modèle qui sera automatiquement renseigné avec la largeur de l’image à chaque fois qu’un objet image est attribué. Nécessite la bibliothèque [pillow](https://pypi.org/project/pillow/). Les instances de [`ImageField`](#django.db.models.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`](#django.db.models.CharField.max_length). Le composant de formulaire par défaut de ce champ est un [`ClearableFileInput`](/fr/6.1/ref/forms/widgets/#django.forms.ClearableFileInput). ### `IntegerField` #### `class IntegerField(**options)` Un nombre entier. Les valeurs admises sont restreintes à certaines limites (dépendantes de la base de données). Les valeurs de `-2147483648` à `2147483647` sont compatibles avec toutes les bases de données prises en charge par Django. Il utilise [`MinValueValidator`](/fr/6.1/ref/validators/#django.core.validators.MinValueValidator) et [`MaxValueValidator`](/fr/6.1/ref/validators/#django.core.validators.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`](/fr/6.1/ref/forms/widgets/#django.forms.NumberInput) lorsque [`localize`](/fr/6.1/ref/forms/fields/#django.forms.Field.localize) vaut `False`, ou [`TextInput`](/fr/6.1/ref/forms/widgets/#django.forms.TextInput) dans le cas contraire. ### `JSONField` #### `class JSONField(encoder=None, decoder=None, **options)` Un champ pour stocker des données JSON encodées. En Python, les données sont représentées dans leur format natif correspondant : dictionnaires, listes, chaînes, nombres, booléens et `None`. `JSONField` est pris en charge avec MariaDB, MySQL, Oracle, PostgreSQL et SQLite (avec l’extension [JSON1 activée](/fr/6.1/ref/databases/#sqlite-json1)). #### `JSONField.encoder` Une sous-classe facultative de [`json.JSONEncoder`](https://docs.python.org/3/library/json.html#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`](https://docs.python.org/3/library/uuid.html#uuid.UUID)). Par exemple, vous pouvez utiliser la classe [`DjangoJSONEncoder`](/fr/6.1/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder). Contient `json.JSONEncoder` par défaut. #### `JSONField.decoder` Une sous-classe facultative de [`json.JSONDecoder`](https://docs.python.org/3/library/json.html#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. Pour interroger les champs `JSONField` dans la base de données, voir [Interrogation de JSONField](/fr/6.1/topics/db/queries/#querying-jsonfield). > **Valeur par défaut** > > Si vous donnez une valeur [`default`](#django.db.models.Field.default) à ce champ, assurez-vous que ce soit un objet exécutable tel que [`dict`](https://docs.python.org/3/library/stdtypes.html#dict) ou une fonction qui renvoie à chaque fois un nouvel objet. L’utilisation d’un objet mutable tel que `default={}` ou `defauilt=[]` n’est pas correct car cela crée une valeur par défaut mutable qui est alors partagée entre toutes les instances. > **Indexation** > > [`Index`](/fr/6.1/ref/models/indexes/#django.db.models.Index) et [`Field.db_index`](#django.db.models.Field.db_index) créent tous deux un index B-tree, qui n’est pas particulièrement utile lorsqu’on interroge un champ `JSONField`. Avec PostgreSQL uniquement, il est possible d’utiliser un index [`GinIndex`](/fr/6.1/ref/contrib/postgres/indexes/#django.contrib.postgres.indexes.GinIndex) qui est mieux adapté. > **Utilisateurs de PostgreSQL** > > PostgreSQL dispose de deux types de données natifs basés sur JSON : `json` et `jsonb`. La principale différence entre eux est la façon dont ils sont stockés et comment ils peuvent être interrogés. Le champ `json` de PostgreSQL est stocké comme la représentation textuelle d’origine du JSON et doit être décodé à la volée lorsqu’on l’interroge sur la base de clés. Le champ `jsonb` est stocké en fonction de la structure réelle du JSON qui permet l’indexation. En contre-partie, l’écriture du champ `jsonb` est légèrement plus coûteuse. `JSONField` utilise le type `jsonb`. > **Utilisateurs Oracle** > > La base de données Oracle ne prend pas en charge le stockage de valeurs scalaires en JSON. Seuls les objets et les tableaux JSON (représentés en Python par [`dict`](https://docs.python.org/3/library/stdtypes.html#dict) and [`list`](https://docs.python.org/3/library/stdtypes.html#list)) sont pris en charge. ### `PositiveBigIntegerField` #### `class PositiveBigIntegerField(**options)` Comme un [`PositiveIntegerField`](#django.db.models.PositiveIntegerField), mais n’autorise que des valeurs plus petites qu’un certain plafond (dépendant du moteur de base de données). Toutes les valeurs de `0` à `9223372036854775807` sont acceptées par toutes les bases de données prises en charge officiellement par Django. ### `PositiveIntegerField` #### `class PositiveIntegerField(**options)` Comme un champ [`IntegerField`](#django.db.models.IntegerField), mais doit être un entier positif ou zéro (`0`). Les valeurs doivent être comprises dans certaines limites (selon la base de données). 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`](#django.db.models.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](/fr/6.1/glossary/#term-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`](#django.db.models.CharField.max_length) (lisez les notes à propos de la portabilité entre bases de données de [`max_length`](#django.db.models.CharField.max_length)). Si [`max_length`](#django.db.models.CharField.max_length) n’est pas précisé, Django utilise la valeur 50 par défaut. L’option [`Field.db_index`](#django.db.models.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`](/fr/6.1/ref/contrib/admin/#django.contrib.admin.ModelAdmin.prepopulated_fields). Il utilise [`validate_slug`](/fr/6.1/ref/validators/#django.core.validators.validate_slug) ou [`validate_unicode_slug`](/fr/6.1/ref/validators/#django.core.validators.validate_unicode_slug) pour la validation. #### `SlugField.allow_unicode` Si la valeur est `True`, le champ accepte des lettres Unicode en plus des lettres ASCII de base. La valeur par défaut est `False`. ### `SmallAutoField` #### `class SmallAutoField(**options)` Comme un [`AutoField`](#django.db.models.AutoField), mais n’autorise que des valeurs plus petites qu’un certain plafond (dépendant du moteur de base de données). Toutes les valeurs de `1` jusqu’à `32767` sont acceptées par toutes les bases de données prises en charge officiellement par Django. ### `SmallIntegerField` #### `class SmallIntegerField(**options)` Comme un [`IntegerField`](#django.db.models.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`](/fr/6.1/ref/forms/widgets/#django.forms.Textarea). Si vous indiquez un attribut `max_length`, celui-ci se répercute sur le composant [`Textarea`](/fr/6.1/ref/forms/widgets/#django.forms.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`](#django.db.models.CharField). #### `TextField.db_collation` Facultatif. Le nom de collation de base de données pour le champ. > **Note** > > Les noms de collation ne sont pas standardisés. De fait, ils ne sont pas portables entre les différents moteurs de base de données. > **Oracle** > > Oracle ne prend pas en charge les collations pour les champs `TextField`. ### `TimeField` #### `class TimeField(auto_now=False, auto_now_add=False, **options)` Une heure, représentée en Python par une instance de `datetime.time`. Ce champ accepte les mêmes options d’auto-complétion qu’un champ [`DateField`](#django.db.models.DateField). Le composant de formulaire par défaut de ce champ est un [`TimeInput`](/fr/6.1/ref/forms/widgets/#django.forms.TimeInput). L’interface d’administration ajoute des raccourcis JavaScript. ### `URLField` #### `class URLField(max_length=200, **options)` Un champ [`CharField`](#django.db.models.CharField) pour les URL, validé par [`URLValidator`](/fr/6.1/ref/validators/#django.core.validators.URLValidator). Le composant de formulaire par défaut de ce champ est un [`URLInput`](/fr/6.1/ref/forms/widgets/#django.forms.URLInput). Comme pour les autres sous-classes de [`CharField`](#django.db.models.CharField), [`URLField`](#django.db.models.URLField) accepte le paramètre facultatif [`max_length`](#django.db.models.CharField.max_length). Si vous ne renseignez pas la valeur de [`max_length`](#django.db.models.CharField.max_length), elle prend la valeur 200 par défaut. ### `UUIDField` #### `class UUIDField(**options)` A field for storing universally unique identifiers. Uses Python’s [`UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID) class. When used on PostgreSQL and MariaDB, this stores in a `uuid` datatype, otherwise in a `char(32)`. Les identifiants universels uniques sont une bonne alternative aux champs [`AutoField`](#django.db.models.AutoField) pour les clés primaires [`primary_key`](#django.db.models.Field.primary_key). La base de données ne produit pas de UUID à votre place, c’est pourquoi il est recommandé d’utiliser [`default`](#django.db.models.Field.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`. > **Lookups on PostgreSQL and MariaDB** > > Using [`iexact`](/fr/6.1/ref/models/querysets/#std-fieldlookup-iexact), [`contains`](/fr/6.1/ref/models/querysets/#std-fieldlookup-contains), [`icontains`](/fr/6.1/ref/models/querysets/#std-fieldlookup-icontains), > [`startswith`](/fr/6.1/ref/models/querysets/#std-fieldlookup-startswith), [`istartswith`](/fr/6.1/ref/models/querysets/#std-fieldlookup-istartswith), [`endswith`](/fr/6.1/ref/models/querysets/#std-fieldlookup-endswith), or > [`iendswith`](/fr/6.1/ref/models/querysets/#std-fieldlookup-iendswith) lookups on PostgreSQL don’t work for values without > hyphens, because PostgreSQL and MariaDB store them in a hyphenated uuid > datatype type. ## Champs pour les relations Django définit aussi un ensemble de champs représentant les relations. ### `ForeignKey` #### `class ForeignKey(to, on_delete, **options)` Une relation plusieurs-à-un. Exige deux paramètres : la classe à laquelle le modèle est lié et l’option [`on_delete`](#django.db.models.ForeignKey.on_delete): ``` from django.db import models class Manufacturer(models.Model): name = models.TextField() class Car(models.Model): manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE) ``` Le premier argument positionnel peut être soit une classe de modèle concrète ou une [référence différée](#lazy-relationships) vers une classe de modèle. [Les relations récursives](#recursive-relationships), où un modèle possède une relation vers lui-même sont également acceptées. Voir [`ForeignKey.on_delete`](#django.db.models.ForeignKey.on_delete) pour plus de détails sur le second argument positionnel. Un index de base de données est automatiquement créé pour les champs `ForeignKey`. Vous pouvez le désactiver en définissant [`db_index`](#django.db.models.Field.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`](#django.db.models.Field.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`](#django.db.models.ForeignKey) accepte d’autres paramètres qui définissent les détails du fonctionnement de la relation. #### `ForeignKey.on_delete` When an object referenced by a [`ForeignKey`](#django.db.models.ForeignKey) is deleted, the referring objects need updating. The [`on_delete`](#django.db.models.ForeignKey.on_delete) argument specifies how this is done, and whether Django or your database makes the updates. For example, if you have a nullable [`ForeignKey`](#django.db.models.ForeignKey) and you want Django to set it to `None` when the referenced object is deleted: ``` user = models.ForeignKey( User, models.SET_NULL, blank=True, null=True, ) ``` The possible values for [`on_delete`](#django.db.models.ForeignKey.on_delete) are listed below. Import them from [`django.db.models`](/fr/6.1/topics/db/models/#module-django.db.models). The `DB_*` variants use the database to prevent deletions or update referring objects, whilst the other values make Django perform the relevant actions. The database variants are more efficient because they avoid fetching related objects, but `pre_delete` and `post_delete` signals won’t be sent when `DB_CASCADE` is used. The database variants cannot be mixed with Python variants (other than [`DO_NOTHING`](#django.db.models.DO_NOTHING)) in the same model and in models related to each other. > **Changed in Django 6.1** > > Support for `DB_*` variants of the `on_delete` attribute was added. Les valeurs possibles de [`on_delete`](#django.db.models.ForeignKey.on_delete) sont énumérées dans [`django.db.models`](/fr/6.1/topics/db/models/#module-django.db.models): - #### `CASCADE` Supprime en cascade. Django simule le comportement de la contrainte SQL `ON DELETE CASCADE` et supprime aussi l’objet contenant la clé `ForeignKey`. [`Model.delete()`](/fr/6.1/ref/models/instances/#django.db.models.Model.delete) n’est pas appelée pour les modèles liés, mais les signaux [`pre_delete`](/fr/6.1/ref/signals/#django.db.models.signals.pre_delete) et [`post_delete`](/fr/6.1/ref/signals/#django.db.models.signals.post_delete) sont envoyés pour tous les objets supprimés. - #### `DB_CASCADE` > **New in Django 6.1** Cascade deletes. Database-level version of [`CASCADE`](#django.db.models.CASCADE): the database deletes referred-to rows and the one containing the `ForeignKey`. - #### `PROTECT` Empêche la suppression de l’objet référencé en levant une exception [`ProtectedError`](/fr/6.1/ref/exceptions/#django.db.models.ProtectedError), une sous-classe de [`django.db.IntegrityError`](/fr/6.1/ref/exceptions/#django.db.IntegrityError). - #### `RESTRICT` Empêche la suppression de l’objet référencé en générant [`RestrictedError`](/fr/6.1/ref/exceptions/#django.db.models.RestrictedError) (une sous-classe de [`django.db.IntegrityError`](/fr/6.1/ref/exceptions/#django.db.IntegrityError)). Au contraire de [`PROTECT`](#django.db.models.PROTECT), la suppression de l’objet référencé est permise pour autant qu’il fasse aussi référence à un autre objet supprimé dans la même opération, mais via une liaison attr:CASCADE. Considérez cet ensemble de modèles : ``` class Artist(models.Model): name = models.CharField(max_length=10) class Album(models.Model): artist = models.ForeignKey(Artist, on_delete=models.CASCADE) class Song(models.Model): artist = models.ForeignKey(Artist, on_delete=models.CASCADE) album = models.ForeignKey(Album, on_delete=models.RESTRICT) ``` `Artist` peut être supprimé même si cela implique la suppression d’un `Album` qui est référencé par une chanson `Song`, car `Song` fait aussi référence à `Artist` au travers d’une relation en cascade. Par exemple : ```pycon >>> artist_one = Artist.objects.create(name="artist one") >>> artist_two = Artist.objects.create(name="artist two") >>> album_one = Album.objects.create(artist=artist_one) >>> album_two = Album.objects.create(artist=artist_two) >>> song_one = Song.objects.create(artist=artist_one, album=album_one) >>> song_two = Song.objects.create(artist=artist_one, album=album_two) >>> album_one.delete() # Raises RestrictedError. >>> artist_two.delete() # Raises RestrictedError. >>> artist_one.delete() (4, {'Song': 2, 'Album': 1, 'Artist': 1}) ``` - #### `SET_NULL` Place la valeur nulle dans [`ForeignKey`](#django.db.models.ForeignKey) ; ce n’est possible que si le paramètre [`null`](#django.db.models.Field.null) vaut `True`. - #### `DB_SET_NULL` > **New in Django 6.1** Set the [`ForeignKey`](#django.db.models.ForeignKey) value to `NULL`. This is only possible if [`null`](#django.db.models.Field.null) is `True`. Database-level version of [`SET_NULL`](#django.db.models.SET_NULL). - #### `SET_DEFAULT` Définit la valeur de [`ForeignKey`](#django.db.models.ForeignKey) à sa valeur par défaut ; il faut évidemment qu’une valeur par défaut existe pour le champ [`ForeignKey`](#django.db.models.ForeignKey). - #### `DB_SET_DEFAULT` > **New in Django 6.1** Set the [`ForeignKey`](#django.db.models.ForeignKey) value to its [`Field.db_default`](#django.db.models.Field.db_default) value, which must be set. If a row in the referenced table is deleted, the foreign key values in the referencing table will be updated to their [`Field.db_default`](#django.db.models.Field.db_default) values. `DB_SET_DEFAULT` is not supported on MySQL and MariaDB. - #### `SET()` Définit la valeur de [`ForeignKey`](#django.db.models.ForeignKey) à celle qui est transmise à [`SET()`](#django.db.models.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 fait rien. Si le moteur de base de données assure l’intégrité référentielle, ceci génère une exception [`IntegrityError`](/fr/6.1/ref/exceptions/#django.db.IntegrityError) sauf si vous ajoutez manuellement une contrainte SQL `ON DELETE` au champ de base de données. #### `ForeignKey.limit_choices_to` Définit une limite des choix disponibles pour ce champ lorsqu’il est affiché par un `ModelForm` ou dans le site d’administration (par défaut, tous les objets du jeu de requête sont offerts comme choix). Cette limite peut être un dictionnaire, un objet [`Q`](/fr/6.1/ref/models/querysets/#django.db.models.Q) ou un objet exécutable renvoyant un dictionnaire ou un objet [`Q`](/fr/6.1/ref/models/querysets/#django.db.models.Q). Par exemple : ``` staff_member = models.ForeignKey( User, on_delete=models.CASCADE, limit_choices_to={"is_staff": True}, ) ``` fait que le champ correspondant du formulaire `ModelForm` ne présente que la liste des instances `User` ayant `is_staff=True`. Cela peut être utile dans l’administration de Django. La forme « objet exécutable » peut être pratique par exemple quand on l’utilise avec le module Python `datetime` pour limiter les choix possibles en fonction d’intervalles de temps. Par exemple : ``` def limit_pub_date_choices(): return {"pub_date__lte": datetime.date.today()} limit_choices_to = limit_pub_date_choices ``` Si `limit_choices_to` est ou renvoie un [`objet Q`](/fr/6.1/ref/models/querysets/#django.db.models.Q), ce qui est utile pour des [requêtes complexes](/fr/6.1/topics/db/queries/#complex-lookups-with-q), il n’aura 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`](/fr/6.1/ref/contrib/admin/#django.contrib.admin.ModelAdmin.raw_id_fields) du formulaire `ModelAdmin` du modèle. > **Note** > > Si un objet exécutable est utilisé pour `limit_choices_to`, il sera appelé lors de chaque instanciation de formulaire. Il se peut également qu’il soit appelé lors de la validation d’un modèle, par exemple par une commande d’administration ou par le site d’administration. Ce dernier construit les jeux de requête pour valider les saisies de formulaires dans divers cas limites plusieurs fois, il faut donc tenir compte de l’éventualité de plusieurs appels de l’objet exécutable. #### `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`](#django.db.models.ForeignKey.related_query_name) (le nom à utiliser comme nom de filtre inverse à partir du modèle cible). Voir la [documentation des objets liés](/fr/6.1/topics/db/queries/#backwards-related-objects) 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](/fr/6.1/topics/db/models/#abstract-base-classes) ; et quand vous le faites, une [syntaxe particulière](/fr/6.1/topics/db/models/#abstract-related-name) 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, on_delete=models.CASCADE, related_name="+", ) ``` #### `ForeignKey.related_query_name` Le nom à utiliser comme nom de filtre inverse à partir du modèle cible. La valeur par défaut est identique à [`related_name`](#django.db.models.ForeignKey.related_name) ou à [`default_related_name`](/fr/6.1/ref/models/options/#django.db.models.Options.default_related_name) si l’un de ceux-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, on_delete=models.CASCADE, 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") ``` Comme [`related_name`](#django.db.models.ForeignKey.related_name), `related_query_name` prend en charge les étiquettes d’application et l’interpolation de classe via [une syntaxe particulière](/fr/6.1/topics/db/models/#abstract-related-name). #### `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é. Si vous faites référence à un autre champ, ce champ doit avoir `unique=True`. #### `ForeignKey.db_constraint` 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.swappable` Contrôle la réaction du système de migrations si cette clé [`ForeignKey`](#django.db.models.ForeignKey) pointe vers un modèle permutable. Quand elle vaut `True` (valeur par défaut), si la clé [`ForeignKey`](#django.db.models.ForeignKey) pointe vers un modèle qui correspond à la valeur actuelle de `settings.AUTH_USER_MODEL` (ou un autre réglage de modèle permutable), la relation est stockée dans la migration en utilisant une référence au réglage et non pas directement au modèle. Cette valeur ne devrait être changée à `False` que si l’on est certain que le modèle doit toujours pointer vers le modèle permuté, par exemple quand il s’agit d’un modèle de profil conçu spécialement pour le modèle d’utilisateur personnalisé. En définissant cette propriété à `False`, cela ne signifie pas que vous pouvez faire référence à un modèle permutable même quand il a été permuté, `False` signifie que les migrations effectuées avec cette clé `ForeignKey` vont toujours faire référence au modèle exact que vous avez défini (si un utilisateur essaie de faire fonctionner le modèle avec un modèle d’utilisateur pour lequel il n’a pas été prévu, les choses vont mal se passer). En cas de doute, laissez cette propriété à sa valeur par défaut, `True`. ### `ManyToManyField` #### `class ManyToManyField(to, **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`](#django.db.models.ForeignKey), y compris les relations [récursives](#recursive-relationships) et [différées](#lazy-relationships). Les objets liés peuvent être ajoutés, supprimés ou créés avec le gestionnaire [`RelatedManager`](/fr/6.1/ref/models/relations/#django.db.models.fields.related.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, ces noms de tables seront automatiquement tronquées et un hachage unique sera utilisé, par exemple `author_books_9cdf4`. Vous pouvez manuellement attribuer un nom à la table de jointure en utilisant l’option [`db_table`](#django.db.models.ManyToManyField.db_table). #### Paramètres [`ManyToManyField`](#django.db.models.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`](#django.db.models.ForeignKey.related_name). #### `ManyToManyField.related_query_name` Comme pour [`ForeignKey.related_query_name`](#django.db.models.ForeignKey.related_query_name). #### `ManyToManyField.limit_choices_to` Comme pour [`ForeignKey.limit_choices_to`](#django.db.models.ForeignKey.limit_choices_to). #### `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`](#django.db.models.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`](#django.db.models.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`](#django.db.models.ManyToManyField.symmetrical) à `False`. Cela forcera Django à ajouter un descripteur pour la relation inverse, autorisant la relation [`ManyToManyField`](#django.db.models.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`](#django.db.models.ManyToManyField.through) pour indiquer le modèle Django qui représente cette table intermédiaire. Le modèle `through` peut être indiqué soit en utilisant directement la classe de modèle, soit par une [référence différée](#lazy-relationships) à la classe de modèle. L’usage le plus fréquent de cette option est lorsque vous souhaitez associer des [données supplémentaires à une relation plusieurs-à-plusieurs](/fr/6.1/topics/db/models/#intermediary-manytomany). > **Note** > > Les relations récursives utilisant un modèle intermédiaire ne peuvent pas déterminer les noms d’accesseurs inverses, car ils seraient identiques. Vous devez définir un nom [`related_name`](#django.db.models.ForeignKey.related_name) pour au moins l’une d’entre elles. Si vous préférez que Django ne crée pas de relation inverse, définissez `related_name` à `'+'`. > **Ordre des clés étrangères dans les modèles intermédiaires** > > Lors de la définition d’une relation plusieurs-à-plusieurs asymétrique d’un modèle vers lui-même en utilisant un modèle intermédiaire dans définir [`through_fields`](#django.db.models.ManyToManyField.through_fields), la première clé étrangère du modèle intermédiaire sera celle qui représente le côté source du champ `ManyToManyField`, alors que la seconde représentera le côté cible. Par exemple : > > ``` > from django.db import models > > > class Manufacturer(models.Model): > name = models.CharField(max_length=255) > clients = models.ManyToManyField( > "self", symmetrical=False, related_name="suppliers", through="Supply" > ) > > > class Supply(models.Model): > supplier = models.ForeignKey( > Manufacturer, models.CASCADE, related_name="supplies_given" > ) > client = models.ForeignKey( > Manufacturer, models.CASCADE, related_name="supplies_received" > ) > product = models.CharField(max_length=255) > ``` > > Ici, le modèle `Manufacturer` définit la relation plusieurs-à-plusieurs avec les `clients` dans son rôle de `supplier` (fournisseur). Ainsi, la clé étrangère `supplier` (la source) doit venir avant la clé étrangère `client` (la cible) dans le modèle intermédiaire `Supply`. > > En indiquant [`through_fields=("supplier", "client")`](#django.db.models.ManyToManyField.through_fields) dans le champ `ManyToManyField`, l’ordre des clés étrangères du modèle `through` n’est plus important. 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 pour faire le lien entre les modèles, une clé primaire et deux clés étrangères. Une contrainte d’unicité est créée sur les deux clés étrangères. Si les modèles cible et source diffèrent, les champs suivants sont générés : - `id`: la clé primaire de la relation. - `_id`: le champ `id` du modèle qui déclare le champ `ManyToManyField`. - `_id`: le champ `id` du modèle vers lequel pointe le champ `ManyToManyField`. Si le champ `ManyToManyField` possède le même modèle comme cible et source, les champs suivants sont générés : - `id`: la clé primaire de la relation. - `from__id`: l’identifiant de l’instance qui pointe vers le modèle (c’est-à-dire l’instance source). - `to__id`: l’identifiant de l’instance vers laquelle pointe la relation (c’est-à-dire l’instance de modèle cible). 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 ``` Model.m2mfield.through.objects.all() ``` #### `ManyToManyField.through_fields` Utilisé seulement quand un modèle intermédiaire personnalisé a été défini. Django détermine normalement de manière automatique les champs du modèle intermédiaire utilisés pour établir une relation plusieurs-à-plusieurs. Cependant, considérez les modèles suivants : ``` from django.db import models class Person(models.Model): name = models.CharField(max_length=50) class Group(models.Model): name = models.CharField(max_length=128) members = models.ManyToManyField( Person, through="Membership", through_fields=("group", "person"), ) class Membership(models.Model): group = models.ForeignKey(Group, on_delete=models.CASCADE) person = models.ForeignKey(Person, on_delete=models.CASCADE) inviter = models.ForeignKey( Person, on_delete=models.CASCADE, related_name="membership_invites", ) invite_reason = models.CharField(max_length=64) ``` `Membership` possède *deux* clés étrangères vers `Person` (`person` et `inviter`), ce qui rend la relation ambiguë et Django ne peut pas savoir laquelle des deux clés il doit utiliser. Dans ce cas, vous devez définir explicitement la clé étrangère que Django doit utiliser au moyen de `through_fields`, comme dans l’exemple ci-dessus. `through_fields` accepte un tuple binaire `('champ1', 'champ2')`, où `champ1` est le nom de la clé étrangère vers le modèle qui définit la relation [`ManyToManyField`](#django.db.models.ManyToManyField) (group\` dans ce cas) et `champ2` le nom de la clé étrangère vers le modèle cible (`person` dans ce cas). Lorsque vous avez plus d’une clé étrangère d’un modèle intermédiaire vers l’un (ou même les deux) des modèles participant à une relation plusieurs-à-plusieurs, vous *devez* définir `through_fields`. Cela s’applique aussi aux [relations récursives](#recursive-relationships) lorsqu’un modèle intermédiaire est utilisé et qu’il y a plus de deux clés étrangères vers le modèle, ou que vous souhaitez définir explicitement laquelle des deux Django doit utiliser. #### `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` 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`. #### `ManyToManyField.swappable` Contrôle la réaction du système de migrations si ce champ [`ManyToManyField`](#django.db.models.ManyToManyField) pointe vers un modèle permutable. Quand elle vaut `True` (valeur par défaut), si le champ [`ManyToManyField`](#django.db.models.ManyToManyField) pointe vers un modèle qui correspond à la valeur actuelle de `settings.AUTH_USER_MODEL` (ou un autre réglage de modèle permutable), la relation est stockée dans la migration en utilisant une référence au réglage et non pas directement au modèle. Cette valeur ne devrait être changée à `False` que si l’on est certain que le modèle doit toujours pointer vers le modèle permuté, par exemple quand il s’agit d’un modèle de profil conçu spécialement pour le modèle d’utilisateur personnalisé. En cas de doute, laissez cette propriété à sa valeur par défaut, `True`. [`ManyToManyField`](#django.db.models.ManyToManyField) ne prend pas en charge le paramètre [`validators`](#django.db.models.Field.validators). [`null`](#django.db.models.Field.null) n’a aucun effet puisqu’il n’est pas possible d’exiger une relation au niveau de la base de données. ### `OneToOneField` #### `class OneToOneField(to, on_delete, parent_link=False, **options)` Une relation un-à-un. Conceptuellement, ceci est similaire à un champ [`ForeignKey`](#django.db.models.ForeignKey) avec l’attribut [`unique=True`](#django.db.models.Field.unique), 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](/fr/6.1/topics/db/models/#multi-table-inheritance) 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`](#django.db.models.ForeignKey), y compris toutes les options concernant les relations [récursives](#recursive-relationships) et [différées](#lazy-relationships). Si vous ne renseignez pas le paramètre [`related_name`](#django.db.models.ForeignKey.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 : ```pycon >>> 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`](/fr/6.1/ref/models/class/#django.db.models.Model.DoesNotExist) du modèle cible et on peut y accéder comme par un attribut de l’accesseur inverse. Par exemple, si un utilisateur ne possède par de superviseur dans une instance de modèle `MySpecialUser`: ``` try: user.supervisor_of except User.supervisor_of.RelatedObjectDoesNotExist: pass ``` De plus, `OneToOneField` accepte tous les paramètres supplémentaires acceptés par [`ForeignKey`](#django.db.models.ForeignKey), plus un paramètre supplémentaire : #### `OneToOneField.parent_link` Si ce paramètre vaut `True` et qu’il est utilisé dans un modèle qui hérite d’un autre [modèle concret](/fr/6.1/glossary/#term-concrete-model), 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](/fr/6.1/topics/db/examples/one_to_one/) pour des exemples d’utilisation du champ `OneToOneField`. ### Relations différées Les relations différées permettre de référencer des modèles par leur nom (chaînes de caractères) ou en créant des relations récursives. Il est possible d’utiliser des chaînes comme premier paramètre dans tout champ de relation pour faire référence à des modèles de manière différée Une référence différée peut être [récursive](#recursive-relationships), [relative](#relative-relationships) ou [absolue](#absolute-relationships). #### Récursive Pour définir une liaison où un modèle fait référence à lui-même, utilisez `"self"` comme premier argument du champ relationnel : ``` from django.db import models class Manufacturer(models.Model): name = models.TextField() suppliers = models.ManyToManyField("self", symmetrical=False) ``` Lorsqu’on l’utilise dans un [modèle abstrait](/fr/6.1/topics/db/models/#abstract-base-classes), la relation récursive est résolue de manière à ce que chaque sous-classe concrète fasse référence à elle-même. #### Relative Lorsqu’une relation doit être créée avec un modèle qui n’a pas encore été défini, ce dernier peut être référencé par son nom plutôt que par l’objet de 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): name = models.TextField() suppliers = models.ManyToManyField("self", symmetrical=False) ``` Les relations définies de cette façon pour des [modèles abstraits](/fr/6.1/topics/db/models/#abstract-base-classes) 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 : *`products/models.py`* ```python from django.db import models class AbstractCar(models.Model): manufacturer = models.ForeignKey("Manufacturer", on_delete=models.CASCADE) class Meta: abstract = True ``` *`production/models.py`* ```python from django.db import models from products.models import AbstractCar class Manufacturer(models.Model): name = models.TextField() class Car(AbstractCar): pass ``` Dans cet exemple, la relation `Car.manufacturer` sera résolue en `production.Manufacturer`, car elle pointe sur le modèle concret défini dans le fichier `production/models.py`. > **Modèles réutilisables avec des références relatives** > > Les références relatives permettent de créer des modèles abstraits réutilisables avec des relations qui peuvent être résolues en différentes implémentations de modèles référencés dans des sous-classes variées de différentes applications. #### Absolue Les références absolues indiquent un modèle par son étiquette d’application `app_label` et son nom de classe, ce qui permet de référencer des modèles d’autres applications. Ce type de relation différée peut aussi aider à résoudre des importations circulaires. Par exemple, si le modèle `Manufacturer` est défini dans une autre application nommée `thirdpartyapp`, il peut être référencé par : ``` class Car(models.Model): manufacturer = models.ForeignKey( "thirdpartyapp.Manufacturer", on_delete=models.CASCADE, ) ``` Les références absolues pointent toujours vers le même modèle, même lorsqu’elles figurent dans un [modèle abstrait](/fr/6.1/topics/db/models/#abstract-base-classes). ## Référence d’API des champs #### `class Field` `Field` est une classe abstraite qui représente une colonne de table de base de données. Django utilise des champs pour créer une table de base de données ([`db_type()`](#django.db.models.Field.db_type)), pour faire correspondre des types Python à une base de données ([`get_prep_value()`](#django.db.models.Field.get_prep_value)) et inversement ([`from_db_value()`](#django.db.models.Field.from_db_value)). A field is thus a fundamental piece in different Django APIs, notably the [`Model`](/fr/6.1/ref/models/instances/#django.db.models.Model) and the [`QuerySet`](/fr/6.1/ref/models/querysets/#django.db.models.query.QuerySet) APIs. Dans les modèles, un champ est instancié comme attribut de classe et représente une colonne de table de base de données, voir [Modèles](/fr/6.1/topics/db/models/). Il possède des attributs comme [`null`](#django.db.models.Field.null) et [`unique`](#django.db.models.Field.unique), ainsi que des méthodes que Django utilise pour faire correspondre la valeur du champ à des valeurs spécifiques à la base de données. Un champ `Field` est une sous-classe de [`RegisterLookupMixin`](/fr/6.1/ref/models/lookups/#django.db.models.lookups.RegisterLookupMixin), ce qui fait qu’à la fois [`Transform`](/fr/6.1/ref/models/lookups/#django.db.models.Transform) et [`Lookup`](/fr/6.1/ref/models/lookups/#django.db.models.Lookup) peuvent y être inscrits pour être exploités dans les requêtes `QuerySet` (par ex. `nom_champ__exact="foo"`). Toutes les [expressions de requête intégrées](/fr/6.1/ref/models/querysets/#field-lookups) sont inscrites par défaut. Tous les types de champs fournis par Django, tels que [`CharField`](#django.db.models.CharField), sont des implémentations dérivées de `Field`. Si vous avez besoin d’un nouveau type de champ, vous pouvez soit hériter d’un des champs de Django ou écrire une classe `Field` à partir de zéro. Dans tous les cas, consultez [Écriture de champs de modèles personnalisés](/fr/6.1/howto/custom-model-fields/). #### `description` Une description verbeuse du champ, par exemple pour l’application [`django.contrib.admindocs`](/fr/6.1/ref/contrib/admin/admindocs/#module-django.contrib.admindocs). La description peut prendre la forme : ``` description = _("String (up to %(max_length)s)") ``` où les paramètres sont interpolés à partir du `__dict__` du champ. #### `descriptor_class` Une classe implémentant le [protocole de descripteur](https://docs.python.org/3/reference/datamodel.html#descriptors) qui est instanciée et attribuée à l’attribut d’instance de modèle. Le constructeur doit accepter un seul paramètre, l’instance d’un champ. La surcharge de cet attribut de classe permet de personnaliser les comportements `get` et `set`. Pour faire correspondre un champ `Field` à un type particulier d’une base de données, Django expose plusieurs méthodes : #### `get_internal_type()` Renvoie une chaîne nommant ce champ à l’usage du moteur de base de données spécifique. Par défaut, c’est le nom de la classe qui est renvoyé. Voir [Émulation de types de champs intégrés](/fr/6.1/howto/custom-model-fields/#emulating-built-in-field-types) pour son utilisation dans des types de champs personnalisés. #### `db_type(connection)` Renvoie le type de donnée de la colonne de la base de données de la classe [`Field`](#django.db.models.Field), prenant en compte l’objet `connection`. Voir [Types de base de données personnalisés](/fr/6.1/howto/custom-model-fields/#custom-database-types) pour son utilisation dans des types de champs personnalisés. #### `rel_db_type(connection)` Renvoie le type de donnée de la colonne de la base de données, tel que `ForeignKey` et `OneToOneField` qui pointent vers [`Field`](#django.db.models.Field), prenant en compte l’objet `connection`. Voir [Types de base de données personnalisés](/fr/6.1/howto/custom-model-fields/#custom-database-types) pour son utilisation dans des types de champs personnalisés. Il existe trois situations principales où Django a besoin de faire interagir le moteur de base de données et les champs : - lorsqu’il interroge la base de données (valeur Python -\> valeur pour le moteur de base de données) - lorsqu’il charge des données à partir de la base de données (valeur du moteur de base de données -\> valeur Python) - lorsqu’il enregistre vers la base de données (valeur Python -\> valeur pour le moteur de base de données) Lors d’une interrogation, [`get_db_prep_value()`](#django.db.models.Field.get_db_prep_value) et [`get_prep_value()`](#django.db.models.Field.get_prep_value) sont utilisés : #### `get_prep_value(value)` `value` est la valeur actuelle de l’attribut de modèle, et la méthode doit renvoyer les données dans un format préparé spécialement pour être utilisé comme paramètre de la requête. Voir [Conversion d’objets Python en valeurs de requête](/fr/6.1/howto/custom-model-fields/#converting-python-objects-to-query-values) pour son utilisation. #### `get_db_prep_value(value, connection, prepared=False)` Convertit `value` vers une valeur spécifique au moteur de base de données. Par défaut, il renvoie `value` si `prepared=True` et [`get_prep_value(value)`](#django.db.models.Field.get_prep_value) sinon. Voir [Conversion de valeurs de requête en valeurs de base de données](/fr/6.1/howto/custom-model-fields/#converting-query-values-to-database-values) pour son utilisation. Lors du chargement de données, [`from_db_value()`](#django.db.models.Field.from_db_value) est utilisé : #### `from_db_value(value, expression, connection)` Convertit la valeur renvoyée par la base de données en un objet Python. C’est l’inverse de [`get_prep_value()`](#django.db.models.Field.get_prep_value). Cette méthode n’est pas utilisée pour la plupart des champs intégrés, car le moteur de base de données renvoie déjà le bon type Python, ou le moteur se charge lui-même de la conversion. `expression` est la même chose que `self`. Voir [Conversion de valeurs en objets Python](/fr/6.1/howto/custom-model-fields/#converting-values-to-python-objects) pour son utilisation. > **Note** > > Pour des raisons de performance, `from_db_value` n’est pas implémentée comme opération blanche pour les champs qui n’en ont pas besoin (tous les champs Django). Par conséquent, vous ne pouvez pas appeler `super` dans votre définition. Lors de l’enregistrement, [`pre_save()`](#django.db.models.Field.pre_save) et [`get_db_prep_save()`](#django.db.models.Field.get_db_prep_save) sont utilisés : #### `get_db_prep_save(value, connection)` Comme pour [`get_db_prep_value()`](#django.db.models.Field.get_db_prep_value), mais appelé lorsque la valeur du champ doit être *enregistrée* dans la base de données. Renvoie par défaut [`get_db_prep_value()`](#django.db.models.Field.get_db_prep_value). #### `pre_save(model_instance, add)` Méthode appelée avant [`get_db_prep_save()`](#django.db.models.Field.get_db_prep_save) pour préparer la valeur avant d’être enregistrée (par ex. pour [`DateField.auto_now`](#django.db.models.DateField.auto_now)). `model_instance` est l’instance à laquelle appartient ce champ et `add` indique si l’instance est enregistrée dans la base de données pour la première fois. Cette méthode doit renvoyer la valeur de l’attribut correspondant de `model_instance` pour ce champ. Le nom d’attribut est dans `self.attname` (défini par [`Field`](#django.db.models.Field)). Voir [Pré-traitement des valeurs avant enregistrement](/fr/6.1/howto/custom-model-fields/#preprocessing-values-before-saving) pour son utilisation. Les champs reçoivent souvent leur valeur dans un type différent, que ce soit par la sérialisation ou par les formulaires. #### `to_python(value)` Convertit la valeur dans le bon objet Python. Elle opère à l’inverse de [`value_to_string()`](#django.db.models.Field.value_to_string) et est également appelée dans [`clean()`](/fr/6.1/ref/models/instances/#django.db.models.Model.clean). Voir [Conversion de valeurs en objets Python](/fr/6.1/howto/custom-model-fields/#converting-values-to-python-objects) pour son utilisation. En plus de l’enregistrement dans la base de données, le champ doit aussi savoir comment sérialiser sa valeur : #### `value_from_object(obj)` Renvoie la valeur du champ pour l’instance de modèle donnée. Cette méthode est souvent utilisée par [`value_to_string()`](#django.db.models.Field.value_to_string). #### `value_to_string(obj)` Convertit `obj` en une chaîne. Utilisé pour sérialiser la valeur du champ. Voir [Conversion des données de champs pour la sérialisation](/fr/6.1/howto/custom-model-fields/#converting-model-field-to-serialization) pour son utilisation. When using [model forms](/fr/6.1/topics/forms/modelforms/), the `Field` needs to know which form field it should be represented by: #### `formfield(form_class=None, choices_form_class=None, **kwargs)` Renvoie le champ de formulaire [`django.forms.Field`](/fr/6.1/ref/forms/fields/#django.forms.Field) utilisé par défaut pour ce champ dans un formulaire [`ModelForm`](/fr/6.1/topics/forms/modelforms/#django.forms.ModelForm). Si [`formfield()`](#django.db.models.Field.formfield) est surchargée pour renvoyer `None`, ce champ sera exclu du formulaire [`ModelForm`](/fr/6.1/topics/forms/modelforms/#django.forms.ModelForm). Par défaut, si `form_class` et `choices_form_class` valent les deux `None`, c’est un champ [`CharField`](/fr/6.1/ref/forms/fields/#django.forms.CharField) qui sera renvoyé. Si le champ possède l’attribut [`choices`](#django.db.models.Field.choices) et que `choices_form_class` n’est pas renseigné, ce sera un champ [`TypedChoiceField`](/fr/6.1/ref/forms/fields/#django.forms.TypedChoiceField). Voir [Sélection du champ de formulaire pour un champ de modèle](/fr/6.1/howto/custom-model-fields/#specifying-form-field-for-model-field) pour son utilisation. #### `deconstruct()` Renvoie un tuple à 4 éléments avec suffisamment d’informations pour recréer le champ : 1. Le nom du champ dans le modèle. 2. Le chemin d’importation du champ (par ex. `"django.db.models.IntegerField"`). Il est recommandé d’indiquer la version la plus portable, donc moins le chemin est spécifique, mieux c’est. 3. Une liste de paramètres positionnels. 4. Un dictionnaire de paramètres nommés. Cette méthode doit être ajoutée aux champs créés avant la version 1.7 afin de pouvoir migrer leurs données en utilisant les [Migrations](/fr/6.1/topics/migrations/). ## Inscription et obtention d’expressions de recherche `Field` implémente l’[API d’inscription d’expressions de recherche](/fr/6.1/ref/models/lookups/#lookup-registration-api). Cette API peut être utilisée pour personnaliser les recherches possibles pour une classe de champ et ses instances, et la manière d’obtenir ces recherches depuis un champ. # Référence d’attributs des champs Chaque instance `Field` contient plusieurs attributs qui permettent d’inspecter son comportement. Utilisez ces attributs plutôt que de vous baser sur des contrôles de type `isinstance` lorsque vous avez besoin d’écrire du code qui dépend de la fonctionnalité d’un champ. Ces attributs peuvent être utilisée conjointement avec l’[API Model.\_meta](/fr/6.1/ref/models/meta/#model-meta-field-api) pour préciser une recherche de types de champs spécifiques. Les champs de modèles personnalisés devraient implémenter ces drapeaux. ## Attributs pour les champs #### `Field.auto_created` Drapeau booléen indiquant si le champ a été créé automatiquement, comme pour le champ `OneToOneField` utilisé dans un contexte d’héritage de modèles. #### `Field.concrete` Drapeau booléen indiquant si le champ est associé à une colonne de base de données. #### `Field.hidden` Drapeau booléen indiquant si un champ est masqué et qu’il ne devrait pas être renvoyé par [`Options.get_fields()`](/fr/6.1/ref/models/meta/#django.db.models.options.Options.get_fields) par défaut. Un exemple est le champ inverse d’une clé [`ForeignKey`](#django.db.models.ForeignKey) dont l’attribut `related_name` commence par `'+'`. #### `Field.is_relation` Drapeau booléen indiquant si un champ contient des références à un ou plusieurs autres modèles pour sa fonctionnalité (par ex. `ForeignKey`, `ManyToManyField`, `OneToOneField`, etc.). #### `Field.model` Renvoie le modèle dans lequel le champ est défini. Si un champ est défini dans la classe parent d’un modèle, `model` désigne alors la classe parente, et non pas la classe de l’instance. ## Attributs pour les champs de relation Ces attributs sont utilisés pour interroger la cardinalité et d’autres détails d’une relation. Ces attributs sont présents sur tous les champs ; cependant, ils n’ont des valeurs booléennes (plutôt que `None`) que si le champ est de type relationnel ([`Field.is_relation=True`](#django.db.models.Field.is_relation)). #### `Field.many_to_many` Drapeau booléen qui vaut `True` si le champ est une relation plusieurs-à-plusieurs ; `False` sinon. Le seul champ inclus dans Django pour lequel cet attribut vaut `True` est `ManyToManyField`. #### `Field.many_to_one` Drapeau booléen qui vaut `True` si le champ est une relation plusieurs-à-un, comme pour un champ `ForeignKey` ; `False` sinon. #### `Field.one_to_many` Drapeau booléen qui vaut `True` si le champ est une relation un-à-plusieurs, comme pour `GenericRelation` ou la contrepartie d’une clé `ForeignKey` ; `False` sinon. #### `Field.one_to_one` Drapeau booléen qui vaut `True` si le champ est une relation un-à-un, comme pour un champ `OneToOneField` ; `False` sinon. #### `Field.related_model` Pointe vers le modèle en lien avec le champ. Par exemple, `Author` dans `ForeignKey(Author, on_delete=models.CASCADE)`. Le `related_model` d’une clé `GenericForeignKey` vaut toujours `None`.