Flake8¶

User (Global)¶

The user settings are read from the ~/.config/flake8 file (or the ~/.flake8 file on Windows). Example:

[flake8]
ignore = E226,E302,E41
max-line-length = 160
exclude = tests/*
max-complexity = 10

Per-Project¶

At the project level, the tox.ini, setup.cfg, .pep8 or .flake8 files are read if present. Only the first file is considered. If this file does not have a [flake8] section, no project specific configuration is loaded.

Per Code Line¶

To ignore one line of code add # NOQA as a line comment.

Default¶

If the ignore option is not in the configuration and not in the arguments, only the error codes E123/E133, E226 and E241/E242 are ignored (see the warning and error codes).

Settings¶

This is a (likely incomplete) list of settings that can be used in your config file. In general, any settings that pycodestyle supports we also support and we add the ability to set max-complexity as well.

• exclude: comma-separated filename and glob patterns default: .svn,CVS,.bzr,.hg,.git,__pycache__
• filename: comma-separated filename and glob patterns default: *.py
• select: select errors and warnings to enable which are off by default
• ignore: skip errors or warnings
• max-line-length: set maximum allowed line length default: 79
• format: set the error format
• max-complexity: McCabe complexity threshold

flake8.engine¶

flake8.engine.get_parser()¶

This returns an instance of optparse.OptionParser with all the extensions registered and options set. This wraps pep8.get_parser.

flake8.engine.get_style_guide(**kwargs)¶

Parse the options and configure the checker. This returns a sub-class of pep8.StyleGuide.

flake8.hooks¶

flake8.hooks.git_hook(complexity=-1, strict=False, ignore=None, lazy=False)¶

This is the function used by the git hook.

Parameters:

complexity (int) – (optional), any value > 0 enables complexity checking with mccabe strict (bool) – (optional), if True, this returns the total number of errors which will cause the hook to fail ignore (str) – (optional), a comma-separated list of errors and warnings to ignore lazy (bool) – (optional), allows for the instances where you don’t add the files to the index before running a commit, e.g., git commit -a

Returns:

total number of errors if strict is True, otherwise 0

flake8.hooks.hg_hook(ui, repo, **kwargs)¶

This is the function executed directly by Mercurial as part of the hook. This is never called directly by the user, so the parameters are undocumented. If you would like to learn more about them, please feel free to read the official Mercurial documentation.

flake8.main¶

flake8.main.main()¶

Parse options and run checks on Python source.

flake8.main.check_file(path, ignore=(), complexity=-1)¶

Checks a file using pep8 and pyflakes by default and mccabe optionally.

Parameters:	path (str) – path to the file to be checked ignore (tuple) – (optional), error and warning codes to be ignored complexity (int) – (optional), enables the mccabe check for values > 0

flake8.main.check_code(code, ignore=(), complexity=-1)¶

Checks code using pep8 and pyflakes by default and mccabe optionally.

Parameters:	code (str) – code to be checked ignore (tuple) – (optional), error and warning codes to be ignored complexity (int) – (optional), enables the mccabe check for values > 0

class flake8.main.Flake8Command(dist, **kw)¶

The Flake8Command class is used by setuptools to perform checks on registered modules.

flake8.util¶

For AST checkers, this module has the iter_child_nodes function and handles compatibility for all versions of Python between 2.5 and 3.3. The function was added to the ast module in Python 2.6 but is redefined in the case where the user is running Python 2.5

A real example: McCabe¶

Below is an example from mccabe for how to write your setup.py file for your Flake8 extension.

# https://github.com/flintwork/mccabe/blob/0.2/setup.py#L38:L42
# -*- coding: utf-8 -*-
from setuptools import setup

# ...

setup(
    name='mccabe',

    # ...

    install_requires=[
        'setuptools',
    ],
    entry_points={
        'flake8.extension': [
            'C90 = mccabe:McCabeChecker',
        ],
    },

    # ...

)

In mccabe.py you can see that extra options are added to the parser when flake8 registers the extension:

# https://github.com/flintwork/mccabe/blob/0.2/mccabe.py#L225:L254
class McCabeChecker(object):
    """McCabe cyclomatic complexity checker."""
    name = 'mccabe'
    version = __version__
    _code = 'C901'
    _error_tmpl = "C901 %r is too complex (%d)"
    max_complexity = 0

    def __init__(self, tree, filename):
        self.tree = tree

    @classmethod
    def add_options(cls, parser):
        parser.add_option('--max-complexity', default=-1, action='store',
                          type='int', help="McCabe complexity threshold")
        parser.config_options.append('max-complexity')

    @classmethod
    def parse_options(cls, options):
        cls.max_complexity = options.max_complexity

    def run(self):
        if self.max_complexity < 0:
            return
        visitor = PathGraphingAstVisitor()
        visitor.preorder(self.tree, visitor)
        for graph in visitor.graphs.values():
            if graph.complexity() >= self.max_complexity:
                text = self._error_tmpl % (graph.entity, graph.complexity())
                yield graph.lineno, 0, text, type(self)

Since that is the defined entry point in the above setup.py, flake8 finds it and uses it to register the extension.

If we wanted the extension or a check to be optional, you can add off_by_default = True to our entry point. For example, we could update mccabe.py with this variable as shown below:

# https://github.com/flintwork/mccabe/blob/0.2/mccabe.py#L225:L254
class McCabeChecker(object):
    """McCabe cyclomatic complexity checker."""
    name = 'mccabe'
    version = __version__
    off_by_default = True

If we wanted to run the optional extension or check, we need to specify the error and warnings via the --enable-extension command line argument. In our case, we could run flake8 --enable-extension=C90 which would enable our off_by_default example version of the mccabe extension.

2.6.0 - 2016-06-15¶

• Requirements Change Switch to pycodestyle as all future pep8 releases will use that package name
• Improvement Allow for Windows users on select versions of Python to use --jobs and multiprocessing
• Improvement Update bounds on McCabe
• Improvement Update bounds on PyFlakes and blacklist known broken versions
• Improvement Handle new PyFlakes warning with a new error code: F405

2.5.5 - 2016-06-14¶

• Bug Fix setuptools integration when parsing config files
• Bug Don’t pass the user’s config path as the config_file when creating a StyleGuide

2.5.4 - 2016-02-11¶

• Bug Missed an attribute rename during the v2.5.3 release.

2.5.3 - 2016-02-11¶

• Bug Actually parse output_file and enable_extensions from config files

2.5.2 - 2016-01-30¶

• Bug Parse output_file and enable_extensions from config files
• Improvement Raise upper bound on mccabe plugin to allow for version 0.4.0

2.5.1 - 2015-12-08¶

• Bug Properly look for .flake8 in current working directory (GitLab#103)
• Bug Monkey-patch pep8.stdin_get_value to cache the actual value in stdin. This helps plugins relying on the function when run with multiprocessing. (GitLab#105, GitLab#107)

2.5.0 - 2015-10-26¶

• Improvement Raise cap on PyFlakes for Python 3.5 support
• Improvement Avoid deprecation warnings when loading extensions (GitLab#59, GitLab#90)
• Improvement Separate logic to enable “off-by-default” extensions (GitLab#67)
• Bug Properly parse options to setuptools Flake8 command (GitLab!41)
• Bug Fix exceptions when output on stdout is truncated before Flake8 finishes writing the output (GitLab#69)
• Bug Fix error on OS X where Flake8 can no longer acquire or create new semaphores (GitLab#74)

2.4.1 - 2015-05-18¶

• Bug Do not raise a SystemError unless there were errors in the setuptools command. (GitLab#39, GitLab!23)
• Bug Do not verify dependencies of extensions loaded via entry-points.
• Improvement Blacklist versions of pep8 we know are broken

2.4.0 - 2015-03-07¶

• Bug Print filenames when using multiprocessing and -q option. (GitLab#31)

• Bug Put upper cap on dependencies. The caps for 2.4.0 are:

  • pep8 < 1.6 (Related to GitLab#35)
  • mccabe < 0.4
  • pyflakes < 0.9

  See also GitLab#32

• Bug Files excluded in a config file were not being excluded when flake8 was run from a git hook. (GitHub#2)

• Improvement Print warnings for users who are providing mutually exclusive options to flake8. (GitLab#8, GitLab!18)

• Feature Allow git hook configuration to live in .git/config. See the updated VCS hooks docs for more details. (GitLab!20)

2.3.0 - 2015-01-04¶

• Feature: Add --output-file option to specify a file to write to instead of stdout.
• Bug Fix interleaving of output while using multiprocessing (GitLab#17)

2.2.5 - 2014-10-19¶

• Flush standard out when using multiprocessing
• Make the check for “# flake8: noqa” more strict

2.2.4 - 2014-10-09¶

• Fix bugs triggered by turning multiprocessing on by default (again)

  Multiprocessing is forcibly disabled in the following cases:

  • Passing something in via stdin
  • Analyzing a diff
  • Using windows

• Fix –install-hook when there are no config files present for pep8 or flake8.

• Fix how the setuptools command parses excludes in config files

• Fix how the git hook determines which files to analyze (Thanks Chris Buccella!)

2.2.3 - 2014-08-25¶

• Actually turn multiprocessing on by default

2.2.2 - 2014-07-04¶

• Re-enable multiprocessing by default while fixing the issue Windows users were seeing.

2.2.1 - 2014-06-30¶

• Turn off multiple jobs by default. To enable automatic use of all CPUs, use --jobs=auto. Fixes #155 and #154.

2.2.0 - 2014-06-22¶

• New option doctests to run Pyflakes checks on doctests too
• New option jobs to launch multiple jobs in parallel
• Turn on using multiple jobs by default using the CPU count
• Add support for python -m flake8 on Python 2.7 and Python 3
• Fix Git and Mercurial hooks: issues #88, #133, #148 and #149
• Fix crashes with Python 3.4 by upgrading dependencies
• Fix traceback when running tests with Python 2.6
• Fix the setuptools command python setup.py flake8 to read the project configuration

2.1.0 - 2013-10-26¶

• Add FLAKE8_LAZY and FLAKE8_IGNORE environment variable support to git and mercurial hooks
• Force git and mercurial hooks to repsect configuration in setup.cfg
• Only check staged files if that is specified
• Fix hook file permissions
• Fix the git hook on python 3
• Ignore non-python files when running the git hook
• Ignore .tox directories by default
• Flake8 now reports the column number for PyFlakes messages

2.0.0 - 2013-02-23¶

• Pyflakes errors are prefixed by an F instead of an E
• McCabe complexity warnings are prefixed by a C instead of a W
• Flake8 supports extensions through entry points
• Due to the above support, we require setuptools
• We publish the documentation
• Fixes #13: pep8, pyflakes and mccabe become external dependencies
• Split run.py into main.py, engine.py and hooks.py for better logic
• Expose our parser for our users
• New feature: Install git and hg hooks automagically
• By relying on pyflakes (0.6.1), we also fixed #45 and #35

1.7.0 - 2012-12-21¶

• Fixes part of #35: Exception for no WITHITEM being an attribute of Checker for Python 3.3
• Support stdin
• Incorporate @phd’s builtins pull request
• Fix the git hook
• Update pep8.py to the latest version

1.6.2 - 2012-11-25¶

• fixed the NameError: global name ‘message’ is not defined (#46)

1.6.1 - 2012-11-24¶

• fixed the mercurial hook, a change from a previous patch was not properly applied
• fixed an assumption about warnings/error messages that caused an exception to be thrown when McCabe is used

1.6 - 2012-11-16¶

• changed the signatures of the check_file function in flake8/run.py, skip_warning in flake8/util.py and the check, checkPath functions in flake8/pyflakes.py.
• fix --exclude and --ignore command flags (#14, #19)
• fix the git hook that wasn’t catching files not already added to the index (#29)
• pre-emptively includes the addition to pep8 to ignore certain lines. Add # nopep8 to the end of a line to ignore it. (#37)
• check_file can now be used without any special prior setup (#21)
• unpacking exceptions will no longer cause an exception (#20)
• fixed crash on non-existent file (#38)

1.5 - 2012-10-13¶

• fixed the stdin
• make sure mccabe catches the syntax errors as warnings
• pep8 upgrade
• added max_line_length default value
• added Flake8Command and entry points if setuptools is around
• using the setuptools console wrapper when available

1.4 - 2012-07-12¶

• git_hook: Only check staged changes for compliance
• use pep8 1.2

1.3.1 - 2012-05-19¶

• fixed support for Python 2.5

1.3 - 2012-03-12¶

• fixed false W402 warning on exception blocks.

1.2 - 2012-02-12¶

• added a git hook
• now Python 3 compatible
• mccabe and pyflakes have warning codes like pep8 now

1.1 - 2012-02-14¶

• fixed the value returned by –version
• allow the flake8: header to be more generic
• fixed the “hg hook raises ‘physical lines’” bug
• allow three argument form of raise
• now uses setuptools if available, for ‘develop’ command

1.0 - 2011-11-29¶

• Deactivates by default the complexity checker
• Introduces the complexity option in the HG hook and the command line.

0.9 - 2011-11-09¶

• update pep8 version to 0.6.1
• mccabe check: gracefully handle compile failure

0.8 - 2011-02-27¶

• fixed hg hook
• discard unexisting files on hook check

0.7 - 2010-02-18¶

• Fix pep8 initialization when run through Hg
• Make pep8 short options work when run through the command line
• Skip duplicates when controlling files via Hg

0.6 - 2010-02-15¶

• Fix the McCabe metric on some loops