L’infrastructure de contrôle du système est un ensemble de contrôles statiques pour valider les projets Django. Elle détecte les problèmes courants et fournit des conseils sur la façon de les corriger. L’infrastructure est extensible de sorte que vous pouvez facilement ajouter vos propres contrôles.
\nLes contrôles peuvent être déclenchées de manière explicite par la commande check. Les contrôles sont déclenchés implicitement avant la plupart des commandes, y compris runserver et migrate. Pour des raisons de performance, les contrôles ne sont pas effectués dans le contexte de la pile WSGI utilisée en mode déployé. Si vous avez besoin d’effectuer les contrôles systèmes sur le serveur de déploiement, appelez explicitement la commande check.
Les erreurs graves empêcheront les commandes de Django (comme runserver) de fonctionner, tout court. Les problèmes mineurs sont signalés dans la console. Si vous avez inspecté la cause d’un avertissement et que vous êtes content de l’ignorer, vous pouvez masquer des avertissements spécifiques en utilisant le réglage SILENCED_SYSTEM_CHECKS dans votre fichier de réglages du projet.
Une liste complète de tous les contrôles pouvant être levées par Django peuvent être trouvés dans la référence des contrôles système.
\nLe système est souple et vous permet d’écrire des fonctions qui effectuent tout autre type de contrôle dont vous auriez besoin. Ce qui suit est un exemple de squelette d’une fonction de contrôle :
\nfrom django.core.checks import Error, register\n\n@register()\ndef example_check(app_configs, **kwargs):\n errors = []\n # ... your check logic here\n if check_failed:\n errors.append(\n Error(\n 'an error',\n hint='A hint.',\n obj=checked_object,\n id='myapp.E001',\n )\n )\n return errors\nLa fonction de contrôle doit accepter un argument app_configs; cet argument est la liste des applications qui doivent être inspectés. Si None, la vérification doit être effectué sur toutes les applications installées du projet.
Le contrôle recevra un paramètre nommé databases. Il s’agit d’une liste des alias de bases de données dont les connexions peuvent être utilisées pour inspecter la configuration au niveau base de données. Si databases vaut None, le contrôle ne doit utiliser aucune connexion de base de données.
Le paramètre **kwargs est nécessaire pour prendre en compte de futures modifications.
La fonction doit renvoyer une liste de messages. Si aucun problème n’est détecté suite à la vérification, la fonction de contrôle doit renvoyer une liste vide.
\nLes avertissements et les erreurs levés par la méthode de contrôle doivent être des instances de CheckMessage. Une instance de CheckMessage encapsule une seule erreur à signaler ou un seul avertissement. Elle fournit également des conseils et le contexte applicable au message, et un identifiant unique qui est utilisé à des fins de filtrage.
Le concept est très similaire aux messages du système de message ou de la journalisation. Les messages sont étiquettés avec un level indiquant la gravité du message.
Il existe également des raccourcis pour faciliter la création des messages avec les niveaux de base. Lorsque vous utilisez ces classes, vous pouvez omettre le paramètre level car il est sous-entendu par le nom de la classe.
Finalement, votre fonction de contrôle doit être explicitement inscrite dans le registre des contrôles systèmes. Les contrôles doivent être inscrits dans un fichier qui est chargé au moment du chargement de l’application. Par exemple, dans la méthode AppConfig.ready().
Vous pouvez passer autant d’étiquettes que vous le souhaitez à register pour labeliser votre contrôle. L’étiquetage des contrôles est utile car elle vous permet de n’exécuter qu’un certain groupe de contrôles. Par exemple, pour enregistrer un contrôle de compatibilité, vous feriez l’appel suivant :
from django.core.checks import register, Tags\n\n@register(Tags.compatibility)\ndef my_check(app_configs, **kwargs):\n # ... perform compatibility checks and collect errors\n return errors\nVous pouvez inscrire des « contrôles de déploiement » qui ne sont applicables qu’à un fichier de réglages de production de la manière suivante :
\n@register(Tags.security, deploy=True)\ndef my_check(app_configs, **kwargs):\n ...\nCes contrôles ne seront exécutés que si l’option check --deploy est utilisée.
Vous pouvez aussi employer register comme une fonction au lieu d’un décorateur en lui transmettant un objet exécutable (habituellement une fonction) comme premier paramètre.
Le code ci-dessous est équivalent au code ci-dessus :
\ndef my_check(app_configs, **kwargs):\n ...\nregister(my_check, Tags.security, deploy=True)\nDans certains cas, vous n’aurez pas besoin d’enregistrer votre fonction de contrôle – vous pouvez la greffer sur un enregistrement existant.
\nLes champs, les modèles, les gestionnaires de modèle et les moteurs de base de données implémentent tous une méthode check() qui est déjà enregistrée auprès du système de vérification. Si vous souhaitez ajouter des contrôles supplémentaires, vous pouvez étendre l’implémentation de la classe de base, effectuer tous contrôles supplémentaires nécessaires, et ajouter tous les messages à ceux générés par la classe de base. Il est recommandé que vous déléguiez chaque contrôle à des méthodes distinctes.
Prenons un exemple où vous implémentez un champ personnalisé nommé RangedIntegerField. Ce champ ajoute les arguments min et max au constructeur d”IntegerField. Vous pourriez ajouter une vérification afin de vous assurer que les utilisateurs fournissent une valeur min qui est inférieur ou égale à la valeur max. Le code suivant montre comment vous pouvez mettre en œuvre ce contrôle :
from django.core import checks\nfrom django.db import models\n\nclass RangedIntegerField(models.IntegerField):\n def __init__(self, min=None, max=None, **kwargs):\n super().__init__(**kwargs)\n self.min = min\n self.max = max\n\n def check(self, **kwargs):\n # Call the superclass\n errors = super().check(**kwargs)\n\n # Do some custom checks and add messages to `errors`:\n errors.extend(self._check_min_max_values(**kwargs))\n\n # Return all errors and warnings\n return errors\n\n def _check_min_max_values(self, **kwargs):\n if (self.min is not None and\n self.max is not None and\n self.min > self.max):\n return [\n checks.Error(\n 'min greater than max.',\n hint='Decrease min or increase max.',\n obj=self,\n id='myapp.E001',\n )\n ]\n # When no error, return an empty list\n return []\nSi vous vouliez ajouter des contrôles à un gestionnaire de modèle, vous prendriez la même approche avec votre sous-classe de Manager.
Si vous souhaitez ajouter un contrôle à une classe de modèle, l’approche est presque la même : la seule différence est que le contrôle est une méthode de classe, pas une méthode d’instance :
\nclass MyModel(models.Model):\n @classmethod\n def check(cls, **kwargs):\n errors = super().check(**kwargs)\n # ... your own checks ...\n return errors\nLes messages sont comparables. Cela vous permet d’écrire facilement des tests :
\nfrom django.core.checks import Error\nerrors = checked_object.check()\nexpected_errors = [\n Error(\n 'an error',\n hint='A hint.',\n obj=checked_object,\n id='myapp.E001',\n )\n]\nself.assertEqual(errors, expected_errors)\n