La validation de formulaires et de champs¶

La validation de formulaire intervient lorsque les données sont nettoyées. Si vous souhaitez personnaliser ce processus, il y a plusieurs points d’entrée où des changements peuvent se faire, chacun visant un objectif différent. Trois types de méthodes de nettoyage sont exécutés durant le traitement d’un formulaire. Elles sont normalement exécutées lorsque la méthode is_valid() d’un formulaire est appelée. Il y a d’autres opérations qui peuvent aussi provoquer le nettoyage et la validation (l’accès à l’attribut errors ou l’appel direct à full_clean()), mais en principe, cela ne fait pas partie du processus normal.

En général, toute méthode de nettoyage peut générer l’exception ValidationError si un problème survient lors du traitement des valeurs, en passant des informations adéquates au constructeur de ValidationError. Voir ci-dessous pour les bonnes pratiques de génération de ValidationError. Si aucune exception ValidationError n’est produite, la méthode doit renvoyer la valeur nettoyée (normalisée) sous forme d’objet Python.

La plupart de la validation peut se faire à l’aide de validateurs, de simples fonctions utilitaires pouvant facilement être réutilisées. Il s’agit de simples fonctions (ou objets exécutables) acceptant un seul paramètre et générant une exception ValidationError en cas de saisie non valide. Les validateurs sont exécutés après l’appel aux méthodes to_python et validate du champ.

La validation d’un formulaire est partagée en plusieurs étapes, qui peuvent être personnalisées ou surchargées :

• La méthode to_python() d’un champ Field est la première étape de toute validation. Elle transforme la valeur dans le bon type de données et génère ValidationError si ce n’est pas possible. Cette méthode accepte la valeur brute provenant du composant et renvoie la valeur convertie. Par exemple, un champ FloatField transforme la donnée en un objet Python float ou génère une exception ValidationError.

• La méthode validate() d’un champ Field se charge de la validation spécifique du champ qui ne convient pas pour un validateur. Elle accepte une valeur ayant déjà été convertie dans le bon type et génère une exception ValidationError en cas d’erreur. Cette méthode ne renvoie rien et ne doit pas modifier la valeur. Elle peut être surchargée pour gérer de la logique de validation que vous ne pouvez ou ne voulez pas placer dans un validateur.

• La méthode run_validators() d’un champ lance tous les validateurs du champ et rassemble toutes les erreurs dans une seule exception ValidationError. Il n’est en principe pas utile de surcharger cette méthode.

• La méthode clean() d’une sous-classe de champ est responsable de l’exécution de to_python(), validate() et run_validators() dans le bon ordre et de la propagation des erreurs. Si à tout moment l’une de ces méthodes génère une exception ValidationError, la validation s’arrête et cette erreur est propagée. Cette méthode renvoie les données nettoyées qui sont ensuite insérées dans le dictionnaire cleaned_data du formulaire.

• La méthode clean_<nom_du_champ>() est appelée pour une sous-classe de formulaire – où <nom_du_champ> est remplacé par le nom de l’attribut de champ de formulaire. Cette méthode s’occupe de tout nettoyage spécifique à cet attribut, sans considération du type de champ concerné. Cette méthode ne reçoit aucun paramètre. Vous devez chercher vous-même la valeur du champ dans self.cleaned_data et vous rappeler qu’il s’agira à ce moment d’un objet Python, pas de la chaîne initialement soumise avec le formulaire (la valeur figure dans cleaned_data parce que la méthode générale clean() du champ aura déjà nettoyé la valeur une première fois).

  Par exemple, si vous souhaitiez valider que le contenu d’un champ CharField nommé serialnumber est unique, clean_serialnumber() serait le bon endroit pour le faire. Vous n’avez pas besoin d’un champ spécifique (ce n’est qu’un CharField), mais vous avez besoin d’une séquence de validation propre au champ de formulaire et, si possible, de nettoyer/normaliser les données.

  La valeur renvoyée par cette méthode remplace la valeur existante dans cleaned_data, il doit donc s’agir soit de la valeur de cleaned_data (même si cette méthode ne l’a pas modifiée), soit d’une nouvelle valeur propre.

• La méthode clean() de la sous-classe de formulaire peut effectuer toute validation nécessitant d’accéder à plusieurs champs de formulaire. C’est ici que vous pouvez placer des contrôles du genre : si le champ A est renseigné , le champ B doit contenir une adresse de messagerie valide. Cette méthode peut renvoyer un dictionnaire complètement différent si elle le souhaite, et ce résultat sera utilisé comme contenu de cleaned_data.

  Comme les méthodes de validation des champs ont été exécutées au moment où clean() est appelée, vous avez aussi accès à l’attribut errors du formulaire qui contient toutes les erreurs générées lors du nettoyage individuel des champs.

  Notez que toute erreur générée par votre version de Form.clean() ne sera associée à aucun champ particulier. Elles sont attribuées à un « champ » spécial nommé __all__ auquel il est possible d’accéder par la méthode non_field_errors() en cas de besoin. Si vous souhaitez lier une erreur à un champ spécifique du formulaire, vous devrez appeler add_error().

  Notez également qu’il faut tenir compte de considérations particulières lors de la surcharge de la méthode clean() d’une sous-classe de ModelForm (voir la documentation de ModelForm pour plus d’informations).

Ces méthodes sont exécutées dans l’ordre metnionné ci-dessus, un champ après l’autre. C’est-à-dire que pour chaque champ du formulaire (dans l’ordre où ils ont été déclarés dans la définition du formulaire), la méthode Field.clean() (ou sa version surchargée) est exécutée, puis clean_<nom_du_champ>(). Finalement, après que ces deux méthodes ont été exécutées pour chaque champ, la méthode Form.clean() ou sa version surchargée est exécutée dans tous les cas, même si les méthodes précédentes ont généré des erreurs.

Des exemples pour chacune de ces méthodes sont présentés ci-dessous.

Comme mentionné, chacune de ces méthodes peut générer une exception ValidationError. Pour chaque champ, si la méthode Field.clean() gènère une erreur ValidationError, la méthode de nettoyage spécifique au champ n’est pas appelée. Cependant, les méthodes de nettoyage de tous les autres champs sont tout de même exécutées.

raise ValidationError(
    _('Invalid value: %(value)s'),
    code='invalid',
    params={'value': '42'},
)

ValidationError(_('Invalid value: %s') % value)

# Good
raise ValidationError([
    ValidationError(_('Error 1'), code='error1'),
    ValidationError(_('Error 2'), code='error2'),
])

# Bad
raise ValidationError([
    _('Error 1'),
    _('Error 2'),
])

from django.core import validators
from django.forms import CharField

class SlugField(CharField):
    default_validators = [validators.validate_slug]

slug = forms.SlugField()

slug = forms.CharField(validators=[validators.validate_slug])

from django import forms
from django.core.validators import validate_email

class MultiEmailField(forms.Field):
    def to_python(self, value):
        """Normalize data to a list of strings."""
        # Return an empty list if no input was given.
        if not value:
            return []
        return value.split(',')

    def validate(self, value):
        """Check if value consists only of valid emails."""
        # Use the parent's handling of required fields, etc.
        super().validate(value)
        for email in value:
            validate_email(email)

class ContactForm(forms.Form):
    subject = forms.CharField(max_length=100)
    message = forms.CharField()
    sender = forms.EmailField()
    recipients = MultiEmailField()
    cc_myself = forms.BooleanField(required=False)

from django import forms

class ContactForm(forms.Form):
    # Everything as before.
    ...

    def clean_recipients(self):
        data = self.cleaned_data['recipients']
        if "fred@example.com" not in data:
            raise forms.ValidationError("You have forgotten about Fred!")

        # Always return a value to use as the new cleaned data, even if
        # this method didn't change it.
        return data

from django import forms

class ContactForm(forms.Form):
    # Everything as before.
    ...

    def clean(self):
        cleaned_data = super().clean()
        cc_myself = cleaned_data.get("cc_myself")
        subject = cleaned_data.get("subject")

        if cc_myself and subject:
            # Only do something if both fields are valid so far.
            if "help" not in subject:
                raise forms.ValidationError(
                    "Did not send for 'help' in the subject despite "
                    "CC'ing yourself."
                )

def clean(self):
    super().clean()
    cc_myself = self.cleaned_data.get("cc_myself")
    ...

from django import forms

class ContactForm(forms.Form):
    # Everything as before.
    ...

    def clean(self):
        cleaned_data = super().clean()
        cc_myself = cleaned_data.get("cc_myself")
        subject = cleaned_data.get("subject")

        if cc_myself and subject and "help" not in subject:
            msg = "Must put 'help' in subject when cc'ing yourself."
            self.add_error('cc_myself', msg)
            self.add_error('subject', msg)