|
|
@@ -29,12 +29,21 @@ The framework is flexible and allows you to write functions that perform
|
|
|
any other kind of check you may require. The following is an example stub
|
|
|
check function::
|
|
|
|
|
|
- from django.core.checks import register
|
|
|
+ from django.core.checks import Error, register
|
|
|
|
|
|
@register()
|
|
|
def example_check(app_configs, **kwargs):
|
|
|
errors = []
|
|
|
# ... your check logic here
|
|
|
+ if check_failed:
|
|
|
+ errors.append(
|
|
|
+ Error(
|
|
|
+ 'an error',
|
|
|
+ hint=None,
|
|
|
+ obj=checked_object,
|
|
|
+ id='myapp.E001',
|
|
|
+ )
|
|
|
+ )
|
|
|
return errors
|
|
|
|
|
|
The check function *must* accept an ``app_configs`` argument; this argument is
|
|
|
@@ -48,75 +57,25 @@ Messages
|
|
|
The function must return a list of messages. If no problems are found as a result
|
|
|
of the check, the check function must return an empty list.
|
|
|
|
|
|
-.. class:: CheckMessage(level, msg, hint, obj=None, id=None)
|
|
|
-
|
|
|
The warnings and errors raised by the check method must be instances of
|
|
|
:class:`~django.core.checks.CheckMessage`. An instance of
|
|
|
:class:`~django.core.checks.CheckMessage` encapsulates a single reportable
|
|
|
error or warning. It also provides context and hints applicable to the
|
|
|
message, and a unique identifier that is used for filtering purposes.
|
|
|
|
|
|
-The concept is very similar to messages from the :doc:`message
|
|
|
-framework </ref/contrib/messages>` or the :doc:`logging framework
|
|
|
-</topics/logging>`. Messages are tagged with a ``level`` indicating the
|
|
|
-severity of the message.
|
|
|
-
|
|
|
-Constructor arguments are:
|
|
|
-
|
|
|
-``level``
|
|
|
- The severity of the message. Use one of the
|
|
|
- predefined values: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``,
|
|
|
- ``CRITICAL``. If the level is greater or equal to ``ERROR``, then Django
|
|
|
- will prevent management commands from executing. Messages with
|
|
|
- level lower than ``ERROR`` (i.e. warnings) are reported to the console,
|
|
|
- but can be silenced.
|
|
|
-
|
|
|
-``msg``
|
|
|
- A short (less than 80 characters) string describing the problem. The string
|
|
|
- should *not* contain newlines.
|
|
|
-
|
|
|
-``hint``
|
|
|
- A single-line string providing a hint for fixing the problem. If no hint
|
|
|
- can be provided, or the hint is self-evident from the error message, the
|
|
|
- hint can be omitted, or a value of ``None`` can be used.
|
|
|
-
|
|
|
-``obj``
|
|
|
- Optional. An object providing context for the message (for example, the
|
|
|
- model where the problem was discovered). The object should be a model, field,
|
|
|
- or manager or any other object that defines ``__str__`` method (on
|
|
|
- Python 2 you need to define ``__unicode__`` method). The method is used while
|
|
|
- reporting all messages and its result precedes the message.
|
|
|
-
|
|
|
-``id``
|
|
|
- Optional string. A unique identifier for the issue. Identifiers should
|
|
|
- follow the pattern ``applabel.X001``, where ``X`` is one of the letters
|
|
|
- ``CEWID``, indicating the message severity (``C`` for criticals,
|
|
|
- ``E`` for errors and so). The number can be allocated by the application,
|
|
|
- but should be unique within that application.
|
|
|
+The concept is very similar to messages from the :doc:`message framework
|
|
|
+</ref/contrib/messages>` or the :doc:`logging framework </topics/logging>`.
|
|
|
+Messages are tagged with a ``level`` indicating the severity of the message.
|
|
|
|
|
|
There are also shortcuts to make creating messages with common levels easier.
|
|
|
-When using these methods you can omit the ``level`` argument because it is
|
|
|
+When using these classes you can omit the ``level`` argument because it is
|
|
|
implied by the class name.
|
|
|
|
|
|
-.. class:: Debug(msg, hint, obj=None, id=None)
|
|
|
-.. class:: Info(msg, hint, obj=None, id=None)
|
|
|
-.. class:: Warning(msg, hint, obj=None, id=None)
|
|
|
-.. class:: Error(msg, hint, obj=None, id=None)
|
|
|
-.. class:: Critical(msg, hint, obj=None, id=None)
|
|
|
-
|
|
|
-Messages are comparable. That allows you to easily write tests::
|
|
|
-
|
|
|
- from django.core.checks import Error
|
|
|
- errors = checked_object.check()
|
|
|
- expected_errors = [
|
|
|
- Error(
|
|
|
- 'an error',
|
|
|
- hint=None,
|
|
|
- obj=checked_object,
|
|
|
- id='myapp.E001',
|
|
|
- )
|
|
|
- ]
|
|
|
- self.assertEqual(errors, expected_errors)
|
|
|
+* :class:`Debug`
|
|
|
+* :class:`Info`
|
|
|
+* :class:`Warning`
|
|
|
+* :class:`Error`
|
|
|
+* :class:`Critical`
|
|
|
|
|
|
Registering and labeling checks
|
|
|
-------------------------------
|
|
|
@@ -232,3 +191,20 @@ the only difference is that the check is a classmethod, not an instance method::
|
|
|
errors = super(MyModel, cls).check(**kwargs)
|
|
|
# ... your own checks ...
|
|
|
return errors
|
|
|
+
|
|
|
+Writing Tests
|
|
|
+-------------
|
|
|
+
|
|
|
+Messages are comparable. That allows you to easily write tests::
|
|
|
+
|
|
|
+ from django.core.checks import Error
|
|
|
+ errors = checked_object.check()
|
|
|
+ expected_errors = [
|
|
|
+ Error(
|
|
|
+ 'an error',
|
|
|
+ hint=None,
|
|
|
+ obj=checked_object,
|
|
|
+ id='myapp.E001',
|
|
|
+ )
|
|
|
+ ]
|
|
|
+ self.assertEqual(errors, expected_errors)
|
Tim Graham