The system check framework is a set of static checks for validating Django\nprojects. It detects common problems and provides hints for how to fix them.\nThe framework is extensible so you can easily add your own checks.
\nChecks can be triggered explicitly via the check command. Checks are\ntriggered implicitly before most commands, including runserver and\nmigrate. For performance reasons, checks are not run as part of the\nWSGI stack that is used in deployment. If you need to run system checks on your\ndeployment server, trigger them explicitly using check.
Serious errors will prevent Django commands (such as runserver) from\nrunning at all. Minor problems are reported to the console. If you have\ninspected the cause of a warning and are happy to ignore it, you can hide\nspecific warnings using the SILENCED_SYSTEM_CHECKS setting in your\nproject settings file.
A full list of all checks that can be raised by Django can be found in the\nSystem check reference.
\nThe framework is flexible and allows you to write functions that perform\nany other kind of check you may require. The following is an example stub\ncheck function:
\nfrom django.core.checks import Error, register\n\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\nThe check function must accept an app_configs argument; this argument is\nthe list of applications that should be inspected. If None, the check must\nbe run on all installed apps in the project.
The check will receive a databases keyword argument. This is a list of\ndatabase aliases whose connections may be used to inspect database level\nconfiguration. If databases is None, the check must not use any\ndatabase connections.
The **kwargs argument is required for future expansion.
The function must return a list of messages. If no problems are found as a\nresult of the check, the check function must return an empty list.
\nThe warnings and errors raised by the check method must be instances of\nCheckMessage. An instance of\nCheckMessage encapsulates a single reportable\nerror or warning. It also provides context and hints applicable to the\nmessage, and a unique identifier that is used for filtering purposes.
The concept is very similar to messages from the message framework or the logging framework.\nMessages are tagged with a level indicating the severity of the message.
There are also shortcuts to make creating messages with common levels easier.\nWhen using these classes you can omit the level argument because it is\nimplied by the class name.
Lastly, your check function must be registered explicitly with system check\nregistry. Checks should be registered in a file that’s loaded when your\napplication is loaded; for example, in the AppConfig.ready() method.
You can pass as many tags to register as you want in order to label your\ncheck. Tagging checks is useful since it allows you to run only a certain\ngroup of checks. For example, to register a compatibility check, you would\nmake the following call:
from django.core.checks import register, Tags\n\n\n@register(Tags.compatibility)\ndef my_check(app_configs, **kwargs):\n # ... perform compatibility checks and collect errors\n return errors\nYou can register «deployment checks» that are only relevant to a production\nsettings file like this:
\n@register(Tags.security, deploy=True)\ndef my_check(app_configs, **kwargs): ...\nThese checks will only be run if the check --deploy option is used.
You can also use register as a function rather than a decorator by\npassing a callable object (usually a function) as the first argument\nto register.
The code below is equivalent to the code above:
\ndef my_check(app_configs, **kwargs): ...\n\n\nregister(my_check, Tags.security, deploy=True)\nIn some cases, you won’t need to register your check function – you can\npiggyback on an existing registration.
\nFields, constraints, models, model managers, template engines, task backends,\nand database backends all implement a check() method that is already\nregistered with the check framework. If you want to add extra checks, you can\nextend the implementation on the base class, perform any extra checks you need,\nand append any messages to those generated by the base class. It’s recommended\nthat you delegate each check to separate methods.
Consider an example where you are implementing a custom field named\nRangedIntegerField. This field adds min and max arguments to the\nconstructor of IntegerField. You may want to add a check to ensure that\nusers provide a min value that is less than or equal to the max value. The\nfollowing code snippet shows how you can implement this check:
from django.core import checks\nfrom django.db import models\n\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 self.max is not None and 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 []\nIf you wanted to add checks to a model manager, you would take the same\napproach on your subclass of Manager.
If you want to add a check to a model class, the approach is almost the same:\nthe only difference is that the check is a classmethod, not an instance\nmethod:
\nclass MyModel(models.Model):\n @classmethod\n def check(cls, **kwargs):\n errors = super().check(**kwargs)\n # ... your own checks ...\n return errors\nMessages are comparable. That allows you to easily write tests:
\nfrom django.core.checks import Error\n\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)\nGiven the need to register certain checks when the application loads, it can be\nuseful to test their integration within the system checks framework. This can\nbe accomplished by using the call_command()\nfunction.
For example, this test demonstrates that the SITE_ID setting must be\nan integer, a built-in check from the sites framework:
from django.core.management import call_command\nfrom django.core.management.base import SystemCheckError\nfrom django.test import SimpleTestCase, modify_settings, override_settings\n\n\nclass SystemCheckIntegrationTest(SimpleTestCase):\n @override_settings(SITE_ID="non_integer")\n @modify_settings(INSTALLED_APPS={"prepend": "django.contrib.sites"})\n def test_non_integer_site_id(self):\n message = "(sites.E101) The SITE_ID setting must be an integer."\n with self.assertRaisesMessage(SystemCheckError, message):\n call_command("check")\nConsider the following check which issues a warning on deployment if a custom\nsetting named ENABLE_ANALYTICS is not set to True:
from django.conf import settings\nfrom django.core.checks import Warning, register\n\n\n@register("myapp", deploy=True)\ndef check_enable_analytics_is_true_on_deploy(app_configs, **kwargs):\n errors = []\n if getattr(settings, "ENABLE_ANALYTICS", None) is not True:\n errors.append(\n Warning(\n "The ENABLE_ANALYTICS setting should be set to True in deployment.",\n id="myapp.W001",\n )\n )\n return errors\nGiven that this check will not raise a SystemCheckError, the presence of\nthe warning message in the stderr output can be asserted like so:
from io import StringIO\n\nfrom django.core.management import call_command\nfrom django.test import SimpleTestCase, override_settings\n\n\nclass EnableAnalyticsDeploymentCheckTest(SimpleTestCase):\n @override_settings(ENABLE_ANALYTICS=None)\n def test_when_set_to_none(self):\n stderr = StringIO()\n call_command("check", "-t", "myapp", "--deploy", stderr=stderr)\n message = (\n "(myapp.W001) The ENABLE_ANALYTICS setting should be set "\n "to True in deployment."\n )\n self.assertIn(message, stderr.getvalue())\n