[1.8.x] Fixed #25174 -- Moved some details of CheckMessage to the reference guide.
Backport of faa2a0f662 from master
This commit is contained in:
Tim Graham
parent
466950fa98
commit
386a6dc3d7
|
|
@ -4,6 +4,8 @@ System check framework
|
|||
|
||||
.. versionadded:: 1.7
|
||||
|
||||
.. currentmodule:: django.core.checks
|
||||
|
||||
The system check framework is a set of static checks for validating Django
|
||||
projects. It detects common problems and provides hints for how to fix them.
|
||||
The framework is extensible so you can easily add your own checks.
|
||||
|
|
@ -11,6 +13,64 @@ The framework is extensible so you can easily add your own checks.
|
|||
For details on how to add your own checks and integrate them with Django's
|
||||
system checks, see the :doc:`System check topic guide </topics/checks>`.
|
||||
|
||||
API Reference
|
||||
=============
|
||||
|
||||
``CheckMessage``
|
||||
-----------------
|
||||
|
||||
.. class:: CheckMessage(level, msg, hint, obj=None, id=None)
|
||||
|
||||
The warnings and errors raised by system checks must be instances of
|
||||
``CheckMessage``. An instance 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.
|
||||
|
||||
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.
|
||||
|
||||
There are subclasses to make creating messages with common levels easier. When
|
||||
using them 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)
|
||||
|
||||
Builtin checks
|
||||
==============
|
||||
|
||||
Builtin tags
|
||||
------------
|
||||
|
||||
|
|
|
|||
|
|
@ -31,12 +31,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
|
||||
|
|
@ -50,75 +59,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
|
||||
-------------------------------
|
||||
|
|
@ -234,3 +193,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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue