root/docs/trunk/model-api.txt

=================================
Document de référence des modÚles
=================================

Un modÚle est une description unique et définitive de vos données. Il contient
les champs et comportements essentiels des données que vous stockez.
Généralement, chaque modÚle correspond à une seule table de base de données.

Les bases:

    * Chaque modÚle est une classe Python qui étend ``django.db.models.Model``.
    * Chaque attribut du modÚle représente un champ de base de données.
    * Les méta-données du modÚle (informations n'étant pas des champs) vont dans
      une classe interne nommée ``Meta``.
    * Les méta-données utilisées pour le site d'administration de Django vont
      dans une classe interne nommée ``Admin``.
    * Avec tout cela, Django vous donne une API d'accÚs à la base de données
      générée automatiquement, qui est décrite dans la `Documentation de 
      référence pour l'API de base de données`_.

Pour accompagner ce document, n'hésitez pas à  jeter un œil au `dépÃŽt officiel
des exemples de modÚle`_.
(Dans le paquetage des sources de Django, ces exemples sont dans le répertoire
``tests/modeltests``.)

.. _Documentation de référence pour l'API de base de données: 
   ../db_api/
.. _dépÎt officiel des exemples de modÚle: 
   ../models/

Exemple rapide
==============

Ce modÚle d'exemple définit une ``Personne``, qui possÚde un ``prenom`` et un
``nom``::

    from django.db import models

    class Personne(models.Model):
        prenom = models.CharField(maxlength=30)
        nom = models.CharField(maxlength=30)

``prenom`` et ``nom`` sont des *champs* du modÚle. Chaque champ est déclaré
comme un attribut de classe, et chaque attribut correspond à une colonne de base
de données.

Le modÚle ``Personne`` ci-dessus créerait une table de base de données comme
celle-ci::

    CREATE TABLE monappli_personne (
        "id" serial NOT NULL PRIMARY KEY,
        "prenom" varchar(30) NOT NULL,
        "nom" varchar(30) NOT NULL
    );

Quelques notes techniques:

    * Le nom de la table, ``monappli_personne``, est automatiquement dérivé de
      quelques méta-données du modÚle mais peut être personnalisé. Lisez _`Noms 
      de table` un peu plus bas.
    * Un champ ``id`` est ajouté automatiquement, mais ce comportement peut être
      modifié. Lisez `Les champs de clé primaire automatiques`_ plus bas.
    * Le code SQL ``CREATE TABLE`` de cet exemple est formaté en utilisant la
      syntaxe de PostgreSQL, mais il est bon de noter que Django adapte son code
      SQL au backend de la base de données spécifiée dans votre `fichier de 
      configuration`_.

.. _fichier de configuration: 
   ../settings/

Les champs
==========

La partie la plus importante d'un modÚle -- et la seule partie requise d'un
modÚle -- est la liste des champs de base de données qu'il définit. Les champs
sont définis par attributs de classe.

Par exemple::

    class Musicien(models.Model):
        prenom = models.CharField(maxlength=50)
        nom = models.CharField(maxlength=50)
        instrument = models.CharField(maxlength=100)

    class Album(models.Model):
        artiste = models.ForeignKey(Musicien)
        nom = models.CharField(maxlength=100)
        date_de_sortie = models.DateField()
        nb_etoiles = models.IntegerField()

Restrictions des noms de champ
------------------------------

Django place seulement deux restrictions sur les noms de champs d'un modÚle:

    1. Un nom de champ ne peut pas être un mot réservé du langage Python, parce
       que cela produirait une erreur de syntaxe Python. Par exemple::

           class Exemple(models.Model):
               pass = models.IntegerField() # 'pass' est un mot réservé !

    2. Un nom de champ ne peut pas contenir plusieurs underscores consécutifs, à 
       cause de la maniÚre dont fonctionne la syntaxe de requête de recherche 
       dans Django. Par exemple::

           class Exemple(models.Model):
               foo__bar = models.IntegerField() 'foo__bar' a deux underscores !

Ces limitations peuvent être contournées car votre nom de champ de doit pas
nécessairement correspondre au nom de colonne de votre base de données. Lisez
`db_column`_ plus bas.

Les mots réservés du SQL, tels que ``join``, ``where`` ou ``select``, *sont*
permis comme noms de champ du modÚle, parce que Django échappe tous les noms de
table et colonne de base de données dans toutes les requêtes en SQL. Il utilise
la syntaxe entre guillemets adaptée à votre moteur de base de données.

Les types de champ
------------------

Chaque champ de votre modÚle devrait être une instance de la classe ``Field``
appropriée. Django utilise les types de classe de champs pour déterminer
quelques points:

    * Le type de la colonne de base de données (par exemple, ``INTEGER``,
      ``VARCHAR``).
    * Le widget à utiliser dans l'interface d'administration de Django, si vous
      envisagez de l'utiliser (par exemple, ``<input type="text">``, ``<select>``).
    * La validation minimale des données saisies dans le site d'admin de Django
      et dans les manipulateurs.

Voici tout les types de champs disponibles:

``AutoField``
~~~~~~~~~~~~~

C'est un ``IntegerField`` qui s'incrémente automatiquement selon les IDs
disponibles. Vous aurez rarement à l'utiliser directement ; un champ de clé
primaire sera automatiquement ajouté à votre modÚle si vous ne spécifiez pas une
instruction contraire. Lisez les `Les champs de clé primaire automatiques`_.

``BooleanField``
~~~~~~~~~~~~~~~~

Un champs vrai/faux.

L'interface d'admin le représente par une boîte de choix (checkbox).

``CharField``
~~~~~~~~~~~~~

Un champ de chaîne de caractÚres, pour les chaînes courtes comme longues.

Pour les trÚs longues chaînes de texte, préférez plutÎt ``TextField``.

L'interface d'admin le représente par un ``<input type="text">`` (une entrée à 
simple ligne).

``CharField`` possÚde un argument supplémentaire requis, ``maxlength``, la
longueur maximale (en caractÚres) du champ. Le maxlength est imposé au niveau base de données et
est utilisé par Django pour la validation.

``CommaSeparatedIntegerField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Un champ de nombres entiers séparés par des virgules. Comme dans ``CharField``,
l'argument ``maxlength`` est requis.

``DateField``
~~~~~~~~~~~~~

Un champ de date. PossÚde quelques arguments supplémentaires facultatifs:

    ======================  ===================================================
    Argument                Description
    ======================  ===================================================
    ``auto_now``            Définit automatiquement le champ à la date courante
                            à chaque fois que l'objet est enregistré. Utile
                            pour les champs « derniÚre-modif ». Notez que la date
                            actuelle est *toujours* utilisée ; ce n'est pas
                            seulement une valeur par défaut que vous pourriez
                            modifier.

    ``auto_now_add``        Définit automatiquement le champ à la date courante
                            quand l'objet est créé la premiÚre fois. Utile pour
                            contenir les dates de création. Notez que la date
                            actuelle est *toujours* utilisée ; ce n'est pas
                            seulement une valeur par défaut que vous pourriez
                            modifier.
    ======================  ===================================================

L'interface d'admin le représente par un ``<input type="text">`` avec un
calendrier JavaScript et un raccourci pour « Aujourd'hui ».

``DateTimeField``
~~~~~~~~~~~~~~~~~

Un champ de date et heure. Prend les mêmes options supplémentaires que
``DateField``.

L'interface d'admin le représente par deux champs ``<input type="text">``, avec
des raccourcis JavaScript.

``EmailField``
~~~~~~~~~~~~~~

Un ``CharField`` qui vérifie que la valeur est une adresse de courrier 
électronique valide.
``maxlength`` n'est pas accepté.

``FileField``
~~~~~~~~~~~~~

Un champ d'envoi de fichier.

PossÚde un argument supplémentaire obligatoire, ``upload_to``, définissant un
chemin local du systÚme de fichiers où les fichiers reçus devraient être
conservés. Ce chemin peut contenir du `formatage strftime (en)`_, qui sera
remplacé par la date et/ou l'heure où le fichier est reçu (ainsi ces fichiers
reçus ne remplissent pas un répertoire donné).

L'interface d'admin le représente par un ``<input type="file">`` (un widget
d'envoi de fichier).

Utiliser un ``FileField`` ou un ``ImageField`` (voir ci-dessous) dans un modÚle
requiert quelques étapes:

    1. Dans votre fichier de configuration, vous aurez besoin de définir
       ``MEDIA_ROOT`` avec le chemin absolu vers un répertoire où vous aimeriez 
       que Django stocke les fichiers reçus. (Pour des raisons de performance, 
       ces fichiers ne sont pas stockés dans la base de données.) Définissez 
       ``MEDIA_URL`` avec l'URL de base publique représentant ce répertoire. 
       Assurez-vous que ce répertoire a les droits en écriture pour le compte 
       utilisateur de celui qui lance le serveur Web.

    2. Ajoutez le ``FileField`` ou le ``ImageField`` dans votre modÚle,
       assurez-vous de définir l'option ``upload_to`` pour dire à Django dans quel
       sous-répertoire de ``MEDIA_ROOT`` il devrait conserver les fichiers reçus.

    3. Tout ce qui sera stocké dans la base de données sera un chemin vers le
       fichier (relativement à ``MEDIA_ROOT``). Vous aurez certainement à 
       utiliser la fonction utilitaire ``get_<fieldname>_url`` fournie par 
       Django. Par exemple, si votre ``ImageField`` s'appelle ``mug_shot``, 
       vous pouvez obtenir l'URL absolue de votre image dans un template avec 
       ``{{ object.get_mug_shot_url }}``.

.. _`formatage strftime (en)`: http://docs.python.org/lib/module-time.html#l2h-1941

``FilePathField``
~~~~~~~~~~~~~~~~~

Un champ dont les choix sont limités aux noms de fichier d'un certain répertoire
du systÚme de fichiers. PossÚde trois arguments spéciaux, dont le premier est
requis:

    ======================  ===================================================
    Argument                Description
    ======================  ===================================================
    ``path``                Obligatoire. Le chemin absolu du systÚme de
                            fichiers d'un répertoire dans lequel ce
                            ``FilePathField`` est censé générer ses choix.
                            Par exemple: ``"/home/images"``.

    ``match``               Facultatif. Une expression rationnelle, sous forme
                            de chaîne de caractÚres, que ``FilePathField``
                            utilisera pour filtrer les noms de fichier. Notez
                            que cette regex sera appliquée au nom de base du
                            fichier, et non au chemin complet. Par exemple:
                            ``"foo.*\.txt^"``, qui va garder un fichier nommé
                            ``foo23.txt`` mais pas ``bar.txt`` ni
                            ``foo23.gif``.

    ``recursive``           Facultatif. Soit ``True``, soit ``False``.
                            ``False`` par défaut. Spécifie si tous les
                            sous-répertoires de ``path`` devraient être inclus.
    ======================  ===================================================

Bien-sûr, ces trois arguments peuvent être utilisés ensemble.

Une grande source d'erreur potentielle vient du fait que ``match`` s'applique
sur le nom de base du fichier, et non sur le chemin complet. Donc, cet
exemple::

    FilePathField(path="/home/images", match="foo.*", recursive=True)

...va garder ``/home/images/foo.gif`` mais pas ``/home/images/foo/bar.gif``
parce que le ``match`` s'appliquera sur le nom de base du fichier (``foo.gif`` et
``bar.gif``).

``FloatField``
~~~~~~~~~~~~~~

Un nombre à virgule flottante. PossÚde deux arguments **obligatoires**:

    ======================  ===================================================
    Argument                Description
    ======================  ===================================================
    ``max_digits``          Le nombre maximal de chiffres permis dans le
                            nombre.

    ``decimal_places``      Le nombre de décimales aprÚs la virgule pour
                            stocker le nombre.
    ======================  ===================================================

Par exemple, pour stocker des nombres jusqu'à 999 avec une résolution de 2
chiffres aprÚs la virgule, vous utiliseriez::

    models.FloatField(..., max_digits=5, decimal_places=2)

Et poour stocker des nombres jusqu'Ã  approximativement un milliard avec une
résolution de 10 chiffres aprÚs la virgule::

    models.FloatField(..., max_digits=19, decimal_places=10)

L'interface d'admin le représente par un ``<input type="text">`` (une entrée à 
une seule ligne).

``ImageField``
~~~~~~~~~~~~~~

Comme ``FileField``, mais contrÎle que l'objet reçu est une image valide.
PossÚde deux arguments supplémentaires facultatifs, ``height_field`` et
``width_field``, qui, si définis, auto-redimensionneront à la largeur et hauteur
donnée l'image à chaque fois que l'intance de modÚle est sauvegardée.

Requiert la `BibliothÚque d'Imagerie Python - PIL (en)`_.

.. _BibliothÚque d'Imagerie Python - PIL (en): http://www.pythonware.com/products/pil/

``IntegerField``
~~~~~~~~~~~~~~~~

Un entier.

L'interface d'admin le représente par un ``<input type="text">`` (une entrée à 
une seule ligne).

``IPAddressField``
~~~~~~~~~~~~~~~~~~

Une adresse IP, dans son format de chaîne de caractÚres (c'est-à -dire
"24.124.1.30").

L'interface d'admin le représente par un ``<input type="text">`` (une entrée à 
une seule ligne).

``NullBooleanField``
~~~~~~~~~~~~~~~~~~~~

Comme un ``BooleanField``, sauf qu'il admet ``NULL`` comme un des choix. 
Utilisez cela à la place d'un ``BooleanField`` avec ``null=True``.

L'interface d'admin le représente par une boîte ``<select>`` avec les choix
"Inconnu", "Oui" et "Non".

``PasswordField``
~~~~~~~~~~~~~~~~~  

Un ``PasswordField`` est comme un ``TextField`` à part que les caractÚres entrés
sont masqués, typiquement par une astérisque (*), lorsqu'ils sont saisis dans un
formulaire. Notez que même si la donnée est masquée en entrée, elle est envoyée
en texte clair au serveur et stocké en plein texte dans la base de données. Des
mesures supplémentaires (telles que l'usage de HTTPS) sont nécessaires pour
assurer la sécurité des données envoyées depuis un formulaire. Ce champ est
probablement plus utile lorsqu'il est employé dans un `manipulateur personnalisé`_ 
et non directement dans un modÚle.

.. _manipulateur personnalisé: ../forms/#custom-forms-and-manipulators

``PhoneNumberField``
~~~~~~~~~~~~~~~~~~~~

Un ``CharField`` qui vérifie que la valeur est un numéro de téléphone américain
valide (au format ``XXX-XXX-XXXX``).

``PositiveIntegerField``
~~~~~~~~~~~~~~~~~~~~~~~~

Comme un ``IntegerField``, sauf qu'il doit être positif.

``PositiveSmallIntegerField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Comme un ``PositiveIntegerField``, Ã  part qu'il admet seulement les valeurs
inférieures à une certaine limite (qui dépend de la base de données).

``SlugField``
~~~~~~~~~~~~~

« Slug » est un terme anglophone employé dans le jargon de la publication. Un 
slug est un court libellé pour désigner quelque chose, contenant seulement des
lettres, des nombres, des underscores ou des traits d'union. Ils sont
généralement utilisés dans les URLs.

Dans la version en développement de Django, vous pouvez spécifier ``maxlength``.
Si ``maxlength`` n'est pas spécifié, Django utilisera une longueur par défaut de
50. Dans les versions précédentes de Django, il n'est pas possible de modifier la
longueur de 50.

Implique que ``db_index=True``.

Accepte une option supplémentaire, ``prepopulate_from``, qui est une liste de
champs depuis laquelle on peut auto-générer le slug, via JavaScript, dans le
formulaire de description d'un objet de l'interface d'admin::

    models.SlugField(prepopulate_from=("prenom", "nom"))

``prepopulate_from`` n'accepte pas les DateTimeFields.

L'interface d'admin représente un ``SlugField`` par un ``<input type="text">``
(une entrée à une seule ligne).

``SmallIntegerField``
~~~~~~~~~~~~~~~~~~~~~

Comme un ``IntegerField``, à part qu'il admet seulement les valeurs inférieures
à une certaine limite (qui dépend de la base de données).

``TextField``
~~~~~~~~~~~~~

Un champ de texte long.

L'interface d'admin le représente par un ``<textarea>`` (une entrée à lignes
multiples).

``TimeField``
~~~~~~~~~~~~~

Une heure. Accepte les mêmes options d'auto-définition que ``DateField`` et
``DateTimeField``.

L'interface d'admin le représente par un ``<input type="text">`` avec quelques
raccourcis JavaScript.

``URLField``
~~~~~~~~~~~~

Un champ pour une URL. Si l'option ``verify_exists`` est à ``True`` (par défaut),
l'existence de l'URL donnée sera vérifiée (c'est-à -dire que l'URL charge et ne
renvoie pas une réponse 404).

L'interface d'admin le représente par un ``<input type="text">`` (une entrée à 
une seule ligne).

``USStateField``
~~~~~~~~~~~~~~~~

Une abbréviation de deux lettres désignant un état américain.

L'interface d'admin le représente par un ``<input type="text">`` (une entrée
d'une seule ligne).

``XMLField``
~~~~~~~~~~~~

Un ``TextField`` qui vérifie que la valeur est du XML valide qui correspond au
schéma donné. Prend un argument obligatoire, ``schema_path``, qui est un chemin
du systÚme de fichier vers un schéma RelaxNG_ à partir duquel le champ sera
contrÎlé.

.. _RelaxNG: http://www.relaxng.org/

Les options de champ
--------------------

Les arguments suivants sont disponibles pour tous les types de champ. Ils sont
tous facultatifs.

``null``
~~~~~~~~

S'il est mis à ``True``, Django stockera les valeurs vides comme des ``NULL``
dans la base de données.
Par défaut, ``False``.

Notez que les valeurs de chaîne vide seront toujours stockées sous forme de
chaînes vides, et non en tant que ``NULL`` -- donc utilisez ``null=True`` pour
les champs qui ne sont pas des chaînes de caractÚres, tels que les entiers, les
booléens et les dates.

Inutile d'utiliser ``null`` sur les champs basés sur des chaînes de caractÚres,
tels que ``CharField`` et ``TextField``, sauf si vous avez une excellente
raison. Si un champ basé sur des chaînes de caractÚres possÚde l'option
``null=True``, cela signifie qu'il y a deux valeurs possibles pour "pas de
données":
``NULL``, et la chaîne vide. Dans la plupart des cas, il est redondant d'avoir
deux valeurs possibles pour "pas de donnée"; la convention adoptée par Django
est d'utiliser la chaîne vide plutÎt que ``NULL``.

``blank``
~~~~~~~~~

S'il est mis à ``True``, on permet que le champ soit vide.

Notez que celui-ci est différent de ``null``. ``null`` est purement lié à la
base de données, alors que ``blank`` est lié au contrÎle de la validité de la
saisie. Si un champ a l'option ``blank=True``, le systÚme de validation dans le
site d'admin de Django autorisera la saisie de valeur vide. Si un champ a l'option
``blank=False``, le champ sera obligatoire.

``choices``
~~~~~~~~~~~

Une séquence itérable (par exemple, une liste ou un tuple) constitué de 2-tuples
qui seront utilisé comme liste à choix multiples pour ce champ.

Si cette option est donnée, l'interface d'admin de Django utilisera une boîte
de sélection au lieu du champ de texte standard et limitera les choix aux choix
donnés.

Une liste à choix multiples ressemble à ceci::

    GRADES_ECOLE_SPORTIVE = (
        ('PS', 'Poussin'),
        ('MN', 'Minime'),
        ('JR', 'Junior'),
        ('SR', 'Sénior'),
        ('VT', 'Vétéran'),
    )

Le premier élément de chaque tuple est la valeur qui sera en fait stockée. Le
second élément est la définition qui sera affichée à l'utilisateur pour ce
choix-là .

Les listes à choix multiples peuvent être aussi bien définies à l'intérieur de
votre classe de modÚle::

    class Toto(models.Model):
        LISTE_GENRES = (
            ('H', 'Homme'),
            ('F', 'Femmme'),
        )
        genre = models.CharField(maxlength=1, choices=LISTE_GENRES)

Qu'à l'extérieur de votre classe de modÚle::

    LISTE_GENRES = (
        ('H', 'Homme'),
        ('F', 'Femme'),
    )
    class Toto(models.Model):
        genre = models.CharField(maxlength=1, choices=LISTE_GENRES)

Enfin, notez que ces choix peuvent être n'importe quel objet itérable -- pas
nécessairement une liste ou un tuple. Cela vous permet de construire des listes
à choix multiples dynamiquement. Mais si vous vous retrouvez à coder les objets
que vous passez dans ``choices`` pour être dynamique, il serait probablement
mieux que vous utilisiez une table de base de données à part avec une clé
étrangÚre ``ForeignKey``. ``choices`` est censé être utilisé pour de la donnée
statique qui ne change plus.

``core``
~~~~~~~~

Pour des objets qui sont édités à l'intérieur d'un objet lié.

Dans l'interface d'admin de Django, si tous les champs « core » dans un objet
édité imbriqué sont vides, alors cet objet est supprimé.

Une erreur est déclenchée si on a une relation d'édition imbriquée sans au moins
un champ ``core=True``.

Merci de noter que chaque champ marqué "core" est traité comme un champ requis
par le site d'admin de Django. En particulier, cela signifie que vous devriez
mettre ``core=True`` sur tout les champs obligatoire dans votre objet lié qui
est édité à l'intérieur d'un autre.

``db_column``
~~~~~~~~~~~~~

Le nom de la colonne de base de données à utiliser pour ce champ. S'il n'est pas
fourni, Django utilisera le nom du champ.

Si votre nom de colonne est un mot réservé du langage SQL, ou s'il contient des
caractÚres qui ne sont pas permis dans les noms de variable Python -- notamment,
le trait d'union -- c'est bon. Django met entre guillemets les noms de tables et 
de colonnes de maniÚre transparente.

``db_index``
~~~~~~~~~~~~

S'il est mis à ``True``, ``django-admin.py sqlindexes`` affichera une
instruction ``CREATE INDEX``
pour ce champ.

``default``
~~~~~~~~~~~

La valeur par défaut du champ.

``editable``
~~~~~~~~~~~~

S'il est mis à ``False``, le champ ne sera pas éditable dans l'interface
d'admin. Par défaut, ``True``.

``help_text``
~~~~~~~~~~~~~

Un texte d'aide supplémentaire à afficher sous le champ dans le formulaire
d'édition d'un objet de l'interface d'admin. C'est utile pour la documentation,
même si votre objet n'a pas de formulaire d'administration.

``primary_key``
~~~~~~~~~~~~~~~

S'il est mis à ``True``, ce champ est la clé primaire du modÚle.

Si vous ne spécifiez ``primary_key=True`` pour aucun champ de votre modÚle,
Django ajoutera automatiquement ce champ::

    id = models.AutoField('ID', primary_key=True)

Ainsi, vous n'avez pas besoin de définir ``primary_key=True`` sur l'un de vos
champs, sauf si voulez changer ce comportement par défaut de clé primaire.

``primary_key=True`` implique ``blank=False``, ``null=False`` et
``unique=True``. Seule une clé primaire est permise par objet.

``radio_admin``
~~~~~~~~~~~~~~~

Par défaut, l'interface d'admin de Django utilise la boîte de sélection
(<select>) pour les champs de clé étrangÚre ``ForeignKey`` ou qui ont l'option
``choices`` définie. Si ``radio_admin`` est mis à ``True``, Django utilisera
des boutons radios à la place.

À ne pas utiliser pour les champs autres que ``ForeignKey`` ou ayant l'option
``choices`` définie.

``unique``
~~~~~~~~~~

S'il est mis à ``True``, le champ devra être unique sur toute la table.

Ce contrÎle est effectué au niveau base de données, ainsi qu'au niveau des
formulaires d'administration de Django.

``unique_for_date``
~~~~~~~~~~~~~~~~~~~

Donnez-lui comme valeur le nom d'un ``DateField`` ou d'un ``DateTimeField`` pour
demander que ce champ soit unique en fonction de la valeur du champ de date.

Par exemple, si vous avez un champ  ``titre`` qui possÚde
``unique_for_date="pub_date"``, alors Django n'autorisera pas la saisie de deux
enregistrements avec le même ``titre`` et ``pub_date``.

Ce contrÎle est effectué au niveau des formulaires d'administration de Django, mais
pas au niveau de la base de données.

``unique_for_month``
~~~~~~~~~~~~~~~~~~~~

Comme ``unique_for_date``, mais la contrainte d'unicité du champ se fait en
fonction du mois.

``unique_for_year``
~~~~~~~~~~~~~~~~~~~

Comme ``unique_for_date`` et ``unique_for_month``.

``validator_list``
~~~~~~~~~~~~~~~~~~

Une liste de validateurs supplémentaires à appliquer sur le champ. Chacuns
doivent être appelables (callable) en prenant les paramÚtres ``field_data, all_data``
et déclenchant ``django.core.validators.ValidationError`` en cas d'erreurs.
(Lisez la `documentation des validateurs`_.)

Django fournit quelques validateurs. Ils se trouvent dans
``django.core.validators``.

.. _documentation des validateurs: ../forms/#validators

Noms de champs explicites
-------------------------

Chaque type de champ, excepté ``ForeignKey``, ``ManyToManyField`` et
``OneToOneField``, prend un argument facultatif en premiÚre position -- un
nom explicite. Si le nom explicite n'est pas donné, Django le créera
automatiquement en utilisant le nom de l'attribut du champ, en convertissant les
underscores en espaces.

Dans cet exemple, le nom explicite est ``"Prénom de la personne"``::

    prenom = models.CharField("Prénom de la personne", maxlength=30)

Dans cet exemple, le nom explicite est ``"prenom"``::

    prenom = models.CharField(maxlength=30)

``ForeignKey``, ``ManyToManyField`` et ``OneToOneField`` requiÚrent que le
premier argument soit une classe de modÚle, donc il faut utiliser l'argument
mot-clé ``verbose_name``::

    sondage = models.ForeignKey(Sondage, verbose_name="le sondage associé")
    sites = models.ManyToManyField(Site, verbose_name="liste de sites")
    lieu = models.OneToOneField(Lieu, verbose_name="lieu associé")

Nous convenons de ne pas mettre de majuscule à la premiÚre lettre du
``verbose_name``. Django mettra automatiquement la majuscule à la premiÚre
lettre lorsque ça sera nécessaire.

Les relations
-------------

C'est clair, la puissance des bases de données relationnelles repose sur les
relations entre les tables. Django offre la possibilité de définir les trois
types de relations les plus courantes entre des tables de données: many-to-one
(1..n), many-to-many (n..n) and one-to-one (1..1).

Les relations many-to-one
~~~~~~~~~~~~~~~~~~~~~~~~~

Pour définir une relation « many-to-one », utilisez ``ForeignKey``. Vous
l'utilisez simplement comme n'importe quel autre type ``Field``: en l'incluant
comme un attribut de classe du modÚle.

``ForeignKey`` requiert un argument en premiÚre position: La classe à laquelle
le modÚle est reliée.

Par exemple, si un modÚle ``Voiture`` a un ``Constructeur`` -- à savoir qu'un
``Constructeur`` fabrique plusieurs voitures mais chaque ``Voiture`` n'a qu'un
seul ``Constructeur`` -- utilisez les définitions suivantes::

    class Constructeur(models.Model):
        # ...

    class Voiture(models.Model):
        constructeur = models.ForeignKey(Constructeur)
        # ...

Pour créer une relation récursive -- un objet qui a une relation "many-to-one"
avec lui-même -- utilisez ``models.ForeignKey('self')``.

Si vous avez besoin de créer une relation sur un modÚle qui n'a pas encore été
défini, vous pouvez utiliser le nom du modÚle, plutÎt que l'objet du modÚle
lui-même::

    class Voiture(models.Model):
        constructeur = models.ForeignKey('Constructeur')
        # ...

    class Constructeur(models.Model):
        # ...

Notez, cependant, que cette fonctionnalité d'utiliser des chaînes de caractÚres
pour définir des noms de modÚle dans ``ForeignKey`` est assez récente, et peut
buguer un peu dans certains cas.

DerriÚre tout ça, Django concatÚne ``"_id"`` au nom du champ pour créer son nom
de colonne de base de données. Dans l'exemple ci-dessus, la table de base de
données pour le modÚle ``Voiture`` aura une colonne ``constructeur_id``. (Vous
pouvez le changer explicitement en spécifiant ``db_column``; voir ``db_column``
plus bas.)  Cependant, votre code ne devrait jamais avoir à traiter avec le nom
de colonne de la base de données, sauf si vous écrivez du code SQL perso. Vous
traiterez toujours avec les noms de champ de votre objet de modÚle.

Il est suggéré, mais non indispensable, que le nom d'un champ ``ForeignKey``
(``constructeur`` dans l'exemple ci-dessus) soit le nom du modÚle, en
minuscules. Vous pouvez, bien-sûr, appeler le champ de la maniÚre que vous
voulez. Par exemple::

    class Voiture(models.Model):
        societe_qui_la_fabrique = models.ForeignKey(Constructeur)
        # ...

Consultez `l'exemple de modÚle utilisant une relation Many-to-one`_ pour un
exemple complet.

.. _l'exemple de modÚle utilisant une relation Many-to-one: 
   ../models/many_to_one/

Les champs ``ForeignKey`` prennent un certain nombre d'arguments supplémentaires
pour définir comment devraient fonctionner les relations. Tous sont facultatifs:

    =======================  ===========================================================
    Argument                 Description
    =======================  ===========================================================
    ``edit_inline``          S'il n'est pas mis à ``False``, l'objet est
                             édité "en ligne" à l'intérieur de la page de
                             l'objet associé, de maniÚre imbriquée. Cela
                             signifie que l'objet n'aura pas sa propre
                             interface d'admin. Utilisez soit
                             ``models.TABULAR``, soit ``models.STACKED``, qui,
                             respectivement, désignent que les objets inbriqués
                             sont affiché comme un tableau ou comme une "pile"
                             de définitions de champs.

    ``limit_choices_to``     Un dictionnaire d'arguments de recherche et de
                             valeurs (voir le `document de référence de l'API
                             de base de données`_) qui limite les choix
                             disponible dans l'interface d'admin pour cet
                             objet. Utilisez-le avec ``models.LazyDate`` pour
                             limiter les choix des objets selon la date. Par
                             exemple::

                                limit_choices_to = {'pub_date__lte': models.LazyDate()}

                             autorise seulement le choix des objets liés avec
                             un ``pub_date`` antérieure à la date et heure
                             actuelle pour être choisi.

                             À la place d'un dictionnaire, ça peut aussi être
                             un objet ``Q`` (un objet avec une méthode
                             ``get_sql()``) pour des requêtes plus complexe.

                             Non compatible avec ``edit_inline``.

    ``max_num_in_admin``     Pour les objets édités "en ligne", il s'agit du
                             nombre maximum d'objets liés à afficher dans
                             l'interface d'admin.
                             Ainsi, si une pizza ne peut avoir que 10
                             ingrédients, ``max_num_in_admin=10`` s'assurera
                             qu'un utilisateur n'entre jamais plus de 10
                             ingrédients à la fois.

                             Notez que ça ne vérifiera pas si 10 ingrédients ont déjà 
                             été crées. Cette option ne contrÎle que
                             l'interface d'admin; il ne s'occupe pas du niveau
                             API Python ni du niveau base de données.

    ``min_num_in_admin``     Le nombre minimum d'objets liés affichés dans
                             l'interface d'admin. Normalement, au stade de la
                             création, les objets "en ligne" sont montrés au
                             nombre de ``num_in_admin``, et au stade de
                             l'édition, des objects vide sont montrés au
                             nombre de ``num_extra_on_change`` en plus de tous
                             les objets liés pré-existants. Cependant, il n'y
                             aura jamais d'objets liés affichés à un nombre
                             inférieur à ``min_num_in_admin``.

    ``num_extra_on_change``  Le nombre de champs vides d'objets liés
                             supplémentaires, montrés au stade de modification.

    ``num_in_admin``         Le nombre par défaut d'objets "en ligne" à 
                             afficher sur la page de l'objet au stade de
                             l'ajout.

    ``raw_id_admin``         Affiche seulement un champ pour saisir un nombre
                             entier à la place d'un menu déroulant. C'est utile
                             lorsqu'il est lié à un type d'objet qui aura trop
                             d'enregistrements pour faire une boîte de
                             sélection pratique.

                             Non utilisé avec ``edit_inline``.

    ``related_name``         Le nom à utiliser pour la relation depuis l'objet
                             lié vers l'objet courant. Regardez la
                             `documentation sur les objets liés`_ pour une
                             explication complÚte et des exemples.

    ``to_field``             Le champs de l'objet lié sur lequel porte la
                             relation. Par défaut, Django utilise la clé
                             primaire de l'objet lié.
    =======================  ===========================================================

.. _`document de référence de l'API de base de données`: ../db_api/
.. _`documentation sur les objets liés`: ../db_api/#related-objects

Les relations many-to-many
~~~~~~~~~~~~~~~~~~~~~~~~~~

Pour définir une relation many-to-many, utilisez la classe ``ManyToManyField``.
Vous n'avez qu'Ã  l'utiliser comme n'importe quelle autre classe de type
``Field``: en l'incluant comme un attribut de classe dans votre modÚle.

``ManyToManyField`` requiert un argument obligatoire: la classe vers laquelle le
modÚle est lié.

Par exemple, si une ``Pizza`` a de multiples objets ``Ingredient`` --
c'est-à -dire qu'un ``Ingredient`` peut être sur plusieurs pizzas et que chaque
``Pizza`` a plusieurs ingrédients -- voici comment vous représenteriez cela::

    class Ingredient(models.Model):
        # ...

    class Pizza(models.Model):
        # ...
        ingredients = models.ManyToManyField(Ingredient)

Comme avec la classe ``ForeignKey``, une relation sur soi-même peut être définie
en utilisant la chaîne de caractÚres ``'self'`` à la place du nom du modÚle, et
vous pouvez référencer des modÚles non encore définis en utilisant une chaîne de
caractÚres contenant le nom du modÚle.

Il est suggéré, mais non requis, que le nom d'un champ ``ManyToManyField``
(``ingredients`` dans l'exemple ci-dessus) soit un pluriel décrivant l'ensemble
des objets du modÚle lié.

DerriÚre tout ça, Django crée une table de jointure intermédiaire pour
représenter la relation many-to-many.

La définition de ``ManyToManyField`` dans l'un ou l'autre modÚle n'a pas
d'importance, mais vous devez le faire dans un seul des modÚles -- pas dans les
deux.

Généralement, les instances de ``ManyToManyField`` devraient être définies dans
l'objet qui sera édité dans l'interface d'admin, si vous utilisez celle de
Django. Dans l'exemple précédent, ``ingredients`` est dans ``Pizza`` (plutÎt
qu'avoir un champ ``ManyToManyField`` ``pizzas`` dans ``Ingredient``) parce qu'il
est plus naturel de penser à une pizza ayant des ingrédients que à un ingrédient
présent dans plusieurs pizzas. Avec la maniÚre dont c'est défini dans l'exemple,
le formulaire d'administration de ``Pizza`` proposerait aux utilisateurs de
sélectionner les ingrédients.

Regardez `L'exemple de relation many-to-many entre modÚles`_ pour un exemple
complet.

.. _L'exemple de relation many-to-many entre modÚles: ../models/many_to_many/

Les objets ``ManyToManyField`` prennent un certain nombre d'arguments
supplémentaires pour définir la façon dont la relation devrait fonctionner. 
Tous sont facultatifs:

    =======================  ==================================================
    Argument                 Description
    =======================  ==================================================
    ``related_name``         Lisez la description dans la section
                             ``ForeignKey`` plus haut.

    ``filter_interface``     Utilise une interface de filtrage Javascript
                             discrÚte et astucieuse au lieu d'un
                             ``<select multiple>`` à l'utilité discutable, dans
                             le formulaire d'administration de cet objet.
                             La valeur devrait être ``models.HORIZONTAL`` ou
                             ``models.VERTICAL`` (c'est à dire que l'interface
                             devrait être empilée horizontalement ou
                             verticalement).

    ``limit_choices_to``     Lisez la description dans la section
                             ``ForeignKey`` plus haut.

    ``symmetrical``          Uniquement employé dans la définition de champs
                             ManyToManyFields sur eux-mêmes.
                             Considérez le modÚle suivant:

                               class Personne(models.Model):
                                   amis = models.ManyToManyField("self")

                             Lorsque Django traite ce modÚle, il reconnait
                             avoir affaire à un ``ManyToManyField`` sur
                             lui-même, et par conséquent, il n'ajoute pas
                             d'attribut ``personne_set`` Ã  la classe
                             ``Personne``. À la place, le ``ManyToManyField``
                             garantit d'être symétrique -- c'est-à -dire que si
                             je suis ton ami, donc tu es mon ami.

                             Si vous ne voulez pas de symétrie dans vos
                             relations ``ManyToMany`` avec ``'self'``,
                             définissez ``symmetrical`` à ``False``. Cela
                             forcera Django à ajouter un descripteur pour la
                             relation inverse, permettant aux relations
                             ``ManyToMany`` d'être asymétriques.

    =======================  ==================================================

Les relations one-to-one
~~~~~~~~~~~~~~~~~~~~~~~~

La sémantique des relations one-to-one est en cours de changement, nous ne vous
recommandons donc pas de les utiliser. Si cela ne vous fait pas partir en
courant, jetez un œil à ceci.

Pour définir une relation one-to-one, utilisez la classe ``OneToOneField``. Vous
n'avez qu'Ã  l'employer comme n'importe quelle autre classe de type ``Field``: en
l'incluant comme attribut de classe dans votre modÚle.

Il est des plus utiles sur la clé primaire d'un objet quand celui-ci "étend" un
autre objet d'une certaine façon.

``OneToOneField`` requiert un argument obligatoire: La classe vers laquelle le
modÚle est lié.

Par exemple, si vous êtes en train de construire une base de données de "lieux",
vous définirez des données basiques tels qu'une adresse, un numéro de téléphone,
etc. dans la base de données. Puis, si vous voulez construire une base de
données de restaurants étendant la définition d'un lieu, plutÎt que de vous
répéter et de repliquer ces champs dans le modÚle ``Restaurant``, vous pourrez
relier ``Restaurant`` à ``Lieu`` grâce à ``OneToOneField`` (parce qu'un
restaurant "est-un" lieu).

Comme avec ``ForeignKey``, une relation vers soi-même peut être définie en
utilisant la chaîne de caractÚres ``"self"`` à la place du nom de modÚle ; les
références vers des modÚles non encore définis peuvent être faites en utilisant 
une chaîne de caractÚres contenant le nom du modÚle.

Ce ``OneToOneField`` remplacera en fait le champ de clé primaire ``id`` (puisque
les relations one-to-one partagent la même clé primaire), et sera affiché comme
un champ en lecture seule lorsque vous éditerez un objet dans l'interface
d'admin:

Regardez `l'exemple de relation one-to-one entre modÚles`_ pour un exemple
complet.

.. _l'exemple de relation one-to-one entre modÚles: ../models/one_to_one/

Les options Meta
================

Définissez des métadonnées pour votre modÚle en utilisant une classe interne
``Meta``, comme ceci::

    class Foo(models.Model):
        bar = models.CharField(maxlength=30)

        class Meta:
            # ...

Les métadonnées de modÚle sont « tout ce qui n'est pas un champ », telles que 
les options de tri, etc.

Voici une liste de toutes les options ``Meta`` possibles. Aucune option n'est
obligatoire. Ajouter la définition ``class Meta`` dans un modÚle est tout à 
fait optionnel.

``db_table``
------------

Le nom de la table de base de données à utiliser pour le modÚle::

    db_table = 'album_de_musique'

Si non défini, Django utilisera ``app_label + '_' + model_class_name``.
Voir « Les noms de table » plus bas pour plus de détails.

Si le nom de votre table de base de données est un mot réservé SQL, ou contient
des caractÚres non permis dans les noms de variable Python -- notamment, le
tiret -- cette option est faite pour vous. Django s'occupe ensuite de placer les
noms de table et de colonne entre quotes automatiquement.

``get_latest_by``
-----------------

Le nom d'un ``DateField`` ou ``DateTimeField`` dans le modÚle. Cela spécifie le
champ par défaut à utiliser dans la méthode ``latest()`` de votre modÚle
``Manager``.

Exemple::

    get_latest_by = "date_commande"

Regardez les `docs sur latest()`_ pour plus de détails.

.. _docs sur latest(): ../db_api/#latest-field-name-none

``order_with_respect_to``
-------------------------

Marque cet objet comme « triable » respectivement au champ donné. Ceci est presque
toujours utilisé avec des objets liés pour permettre de les trier respectivement
à un objet parent. Par exemple, si une ``Reponse`` est liée à un objet
``Question``, et qu'une question possÚde plus d'une réponse, et que l'ordre des
réponses importe, vous ferez ceci::

    class Reponse(models.Model):
        question = models.ForeignKey(Question)
        # ...

        class Meta:
            order_with_respect_to = 'question'

``ordering``
------------

Le tri par défaut pour l'objet, utilisé pour obtenir des listes d'objets::

    ordering = ['-date_commande']

Il s'agit d'un tuple ou d'une liste de chaînes de caractÚres. Chaque chaîne est
un nom de champ avec un préfixe facultatif "-", qui indique un ordre
décroissant. Les champs sans un "-" devant seront triés dans l'ordre croissant.
Utilisez la chaîne "?" pour mélanger aléatoirement.

Par exemple, pour trier selon un champ ``date_publication`` de maniÚre
croissante, utilisez ceci::

    ordering = ['date_publication']

Pour trier selon ``date_publication`` de maniÚre décroissante, utilisez ceci::

    ordering = ['-date_publication']

Pour trier selon ``date_publication`` de maniÚre décroissante, puis selon
``auteur`` de maniÚre croissante, utilisez ceci::

    ordering = ['-date_publication', 'auteur']

Regardez `Spécifier un ordre de tri`_ pour plus d'exemples.

Notez que, sans regarder combien de champs sont dans ``ordering``, le site
d'administration utilise seulement le premier champ.

.. _Spécifier un ordre de tri: ../models/ordering/

``permissions``
---------------

Ce sont des permissions supplémentaires pour entrer dans la table de permission
lors de la création de cet objet. Les permissions d'ajout, suppression et
modification sont automatiquement créées pour chaque objet dont ``admin`` est
défini. Cet exemple spécifie une permission supplémentaire,
``peut_livrer_pizzas``::

    permissions = (("peut_livrer_pizzas", "Peut livrer des pizzas"),)

Il s'agit d'une liste ou d'un tuple formé de paire (tuples de 2 éléments) dans
le format ``(code_de_la_permission, nom_intuitif_de_la_permission)``.

``unique_together``
-------------------

Définit les noms de champ qui, pris ensemble, doivent être uniques::

    unique_together = (("livreur", "restaurant"),)

Il s'agit d'une liste de listes des champs qui doivent être uniques lorsqu'ils
sont considérés ensemble. C'est utilisé dans l'administration de Django et est
renforcé au niveau de la base de données (c'est-à -dire que l'instruction
``UNIQUE`` appropriée est incluse dans la clause ``CREATE TABLE``).