From 386a6dc3d76fe01df1929503b00755bfce987b32 Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Tue, 28 Jul 2015 09:31:44 -0400 Subject: [PATCH] [1.8.x] Fixed #25174 -- Moved some details of CheckMessage to the reference guide. Backport of faa2a0f662ed6fe0b90d10e98cc8ee3795d9307c from master --- docs/ref/checks.txt | 60 ++++++++++++++++++++++++++ docs/topics/checks.txt | 96 ++++++++++++++++-------------------------- 2 files changed, 96 insertions(+), 60 deletions(-) diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt index 0509a13db5..70cc5ee8eb 100644 --- a/docs/ref/checks.txt +++ b/docs/ref/checks.txt @@ -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 `. +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 ------------ diff --git a/docs/topics/checks.txt b/docs/topics/checks.txt index b840c4b942..9be7c65805 100644 --- a/docs/topics/checks.txt +++ b/docs/topics/checks.txt @@ -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 ` or the :doc:`logging framework -`. 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 +` or the :doc:`logging framework `. +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)