Configuration

Before going any further, make sure that you are familiar with flake8 configuration process.

By default we encourage everyone to use setup.cfg to store all the configuration to all python projects.

Shareable configurations

If you need to make sure that all projects share the same configuration you might be interested in nitpick tool to lint your config. We highly recommend to use nitpick together with wemake-python-styleguide.

Configuring

Provides configuration options for wemake-python-styleguide.

We do not like our linter to be highly configurable. Since, people may take the wrong path or make wrong decisions. We try to make all defaults as reasonable as possible.

However, you can currently adjust some complexity options. Why? Because we are not quite sure about the ideal values.

All options are configurable via flake8 CLI.

flake8 --max-returns=2 --max-arguments=4

Or you can provide options in setup.cfg or similar supported files.

[flake8]
max-returns = 2
max-arguments = 4

We use setup.cfg as a default way to provide configuration.

You can also show all options that flake8 supports by running:

flake8 --help

General options

  • min-name-length - minimum number of chars to define a valid

    variable and module name, defaults to 2

  • max-name-length - maximum number of chars to define a valid

    variable and module name, defaults to 45

  • i-control-code - whether you control ones who use your code,

    more rules are enforced when you do control it, opposite to --i-dont-control-code, defaults to True

  • i-dont-control-code - whether you control ones who use your code,

    more rules are enforced when you do control it, opposite to --i-control-code, defaults to True

  • nested-classes-whitelist - list of nested classes’ names we allow to use,

    defaults to (‘Meta’, ‘Params’, ‘Config’)

  • max-noqa-comments - maximum number of noqa allowed in a module,

    defaults to 10

  • allowed-domain-names - list of allowed domain names, defaults to

    ()

  • forbidden-domain-names - list of forbidden domain names, defaults to

    ()

  • forbidden-inline-ignore - list of codes of violations or

    class of violations that are forbidden to ignore inline, defaults to ()

  • exps-for-one-empty-line - number of expressions in

    function or method body for available empty line (without code) 2

Complexity options

  • max-returns - maximum allowed number of return

    statements in one function, defaults to 5

  • max-local-variables - maximum allowed number of local

    variables in one function, defaults to 5

  • max-expressions - maximum allowed number of expressions

    in one function, defaults to 9

  • max-arguments - maximum allowed number of arguments in one function,

    defaults to 5

  • max-module-members - maximum number of classes and functions

    in a single module, defaults to 7

  • max-methods - maximum number of methods in a single class,

    defaults to 7

  • max-line-complexity - maximum line complexity measured in number of

    ast nodes per line, defaults to 14

  • max-jones-score - maximum Jones score for a module, which is equal

    to the median of all lines complexity sum, defaults to 12

  • max-imports - maximum number of imports in a single module,

    defaults to 12

  • max-imported-names - maximum number of imported names

    in a single module, defaults to 50

  • max-base-classes - maximum number of parent classes inside a class

    definition, defaults to 3

  • max-decorators - maximum number of decorators for single function

    or class definition, defaults to 5

  • max-string-usages - maximum number of repeated String constants

    in your modules, defaults to 3

  • max-awaits - maximum allowed number of await

    expressions in one function, defaults to 5

  • max-try-body-length - maximum amount of try node body length,

    defaults to 1

  • max-module-expressions - maximum number of expression

    usages in a module, defaults to 7

  • max-function-expressions - maximum number of expression

    usages in a function or method, defaults to 4

  • max-asserts - maximum number of assert statements in a function,

    default to 5

  • max-access-level - maximum number of access level in an expression,

    defaults to 4

  • max-attributes - maximum number of public instance attributes,

    defaults to 6

  • max-raises - maximum number of raises in a function,

    defaults to 3

  • max-cognitive-score - maximum amount of cognitive complexity

    per function, defaults to 12

  • max-cognitive-average - maximum amount of cognitive complexity

    per module, defaults to 8 (‘Meta’, ‘Params’, ‘Config’)

  • max-call-level - maximum number of call chains, defaults to

    3

  • max-annotation-complexity - maximum number of nested annotations,

    defaults to 3

  • max-import-from-members - maximum number of names that can be imported

    from module, defaults to 8

  • max-tuple-unpack-length - maximum number of variables in tuple unpacking,

    defaults to 4

Formatter options

  • show-violation-links - whether to show violation shortlinks in the

    formatter output False

Plugins

Note

Remember to check the configuration with nitpick.

It is also important to configure different plugins that we ship with this module.

All recommended settings can be found in our styleguide.toml.

You can basically configure them as you wish, including stylistic (like --quotes from flake8-quotes) and important things (like --max-complexity from mccabe). Our flake8.toml file is available with the core settings for flake8.

flake8-isort

We use flake8-isort to check style of imports in our code. To avoid triggering these checks, you can either use “wemake” isort profile or update your configuration with the following lines:

# Inside `setup.cfg`:

[isort]
include_trailing_comma = true
use_parentheses = true
multi_line_output = 3

Our isort.toml file is available with the core settings for isort.

darglint

We use darglint to ensure that docstrings match NumPy documentation style. To avoid triggering these checks, please ensure that your configuration contains following settings:

# Inside `setup.cfg`

[darglint]
strictness = long

Our darglint.toml file is available with the core settings for isort.

Warning

There is a known issue with darglint’s performance when using google or numpy documentation style, if you face long running times during the linting process you can use the sphinx style by setting docstring-style = sphinx in the ["setup.cfg".flake8] section in a nitpick configuration file. Otherwise, you can run darglint manually and through CIs only, disabling it in flake8 args with --darglint-ignore-regex='.*'.

Ignoring violations

We know that people might not agree with 100% of our rules. But we still want to provide the best experience for all users.

So, you can disable some checks, that you are not ok with. Note: you might accidentally break the consistency of this project, when you disable some checks. Report these cases.

There are three ways to ignore some specific violations:

  1. Inline ignore with # noqa: comment and comma separated violation codes

  2. Command line argument --ignore with comma separated violation codes

  3. Configuration line inside setup.cfg, example

You can ignore:

  1. Whole WPS letters, this will completely turn off all our custom checks

  2. Some specific group (naming, complexity, consistency, best practices, etc) with WPS and the first number of this group

  3. Some specific violation with the full violation code

Use per-file-ignores option, so it is possible to ignore violations on a per-file bases. It means, that you can have different set of violations ignored for different files.

Example:

# Inside `setup.cfg`:
[flake8]
per-file-ignores =
  # There are multiple `assert`s in tests, we allow them:
  tests/*.py: S101

Further reading

Read more about ignoring violations in the official flake8 docs.