<type>documentation</type>
<domain>warnings</domain>
<id>external-checkers</id>
<title>External Code Quality Checkers</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Errors and warnings found by external checkers like ``ruff``, ``flake8``, mypy``, ``pep8`` and ``pylint`` may
be interleaved with those found by Wing. Wing will filter the warnings through its
list of rules to disable warnings.  This can be used to quickly disable unwanted warnings,
for example those that are stylistic in nature and not real problems in code.

To enable any external checker, check the ``Enable External Checkers`` option at the
bottom of the ``Configuration: Defaults`` page in the ``Code Warnings`` tool. Then press
the ``Configure`` button to select which checkers to enable and when to run them. External
checkers may be run when a file is opened, after it is saved to disk, or both. Checkers
will also be re-run if warnings are updated manually from the code warnings menu in the
editor or the ``Options`` menu in the ``Code Warnings`` tool.

The command line used to run the checker is configured under its tab in the ``Configure``
dialog. By default, Wing runs the ``Python Executable`` configured in ``Project
Properties`` with the ``-m`` argument to load the checker. This means that the checker
must be installed into the selected Python, usually with ``pip`` or ``conda`` if using
Anaconda Python.

Note that some checkers take a long time to run on even moderately sized source files
and may consume significant amounts of CPU time.  To prevent checks from consuming
too many resources, Wing will skip checks on any file above the threshold set in the
``Maximum File Size`` option in the external checker's configuration.  When a file
is skipped, a message will appear briefly in the status area at the bottom of the
IDE window and in the ``Code Warnings`` tool.

Once external checkers have been configured, Wing runs them, parses the output, and merges
its warnings into the ``Code Warnings`` tool and the editor's code warnings indicators. To
view the raw output of the checkers that Wing is running, select ``External Checker
Console`` from the ``Options`` menu in the ``Code Warnings`` tool.

**Flake8 Configuration**

The configuration page for ``flake8`` includes two additional options:

(1) ``Use Detected Indent Size`` causes Wing to pass the indentation size it has
    detected for the file being checked to ``flake8`` using its ``--indent-size``
    command line option.  For files that do not yet contain any indentation,
    the `Editor > Indentation > Default Indent Size <script:show_preferences_gui(prefname="edit.indent-size")>`__
    preference is used instead.  When this is disabled, flake8's default of 
    4 is used instead.  Default=disabled.
    
(2) ``Use Configured Line Length`` tells Wing to pass the line length configured
    with the `Editor > Line Wrapping > Reformatting Wrap Column <script:show_preferences_gui(prefname="edit.text-wrap-column")>`__ 
    to ``flake8`` using its ``--max-line-length`` command line option.  When this
    is disabled, flake8's default line length is used instead.  Default=enabled.
    
**Pylint Configuration**

The configuration page for ``pylint`` includes three additional options for enabling or
disabling warnings based on the priority assigned by Pylint (errors, warnings, and
informational messages) to make it easy to enable or disable all warnings of a
particular priority. These options work if the default pylint output format
is used or if ``{msg_id}`` is somewhere in the output format specified with 
``--output-format``; if ``{msg_id}`` is not in the output format, all warnings
will be classified as informational.


