Loading docs/ref/checks.txt +60 −0 Original line number Diff line number Diff line Loading @@ -2,6 +2,8 @@ System check framework ====================== .. 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. Loading @@ -9,6 +11,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 ------------ Loading docs/topics/checks.txt +36 −60 Original line number Diff line number Diff line Loading @@ -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 Loading @@ -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 ------------------------------- Loading Loading @@ -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) Loading
docs/ref/checks.txt +60 −0 Original line number Diff line number Diff line Loading @@ -2,6 +2,8 @@ System check framework ====================== .. 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. Loading @@ -9,6 +11,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 ------------ Loading
docs/topics/checks.txt +36 −60 Original line number Diff line number Diff line Loading @@ -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 Loading @@ -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 ------------------------------- Loading Loading @@ -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)
