wemake-python-styleguide

The linter operates as a flake8 plugin using a specific sequence of components to identify code issues:

1. flake8: Runs the Checker alongside other plugins.
2. Checker: Orchestrates the process by requesting Transformation steps before analysis begins.
3. Transformation: Performs AST (Abstract Syntax Tree) transformations.
4. Visitor: The Checker runs various Visitor instances that traverse the code.
5. Violation: Visitor instances raise Violation objects when bad code is detected, which are then reported by flake8 to the user.

To implement the actual checking logic, define protected methods within your visitor class that raise a violation. Use self.add_violation(ViolationClass(node)) to report issues.

If logic is reused across multiple visitors, move it to the logics/ package to decouple it.

class WrongComprehensionVisitor(BaseNodeVisitor):
    _max_ifs = 1

    def _check_ifs(self, node: ast.comprehension) -> None:
        if len(node.ifs) > self._max_ifs:
            # This will restrict to have more than 1 `if`
            # in your comprehensions:
            self.add_violation(MultipleIfsInComprehensionViolation(node))

    def visit_comprehension(self, node: ast.comprehension) -> None:
        self._check_ifs(node)
        self.generic_visit(node)

When writing a built-in extension, you must select a base class from wemake_python_styleguide.visitors.base based on the scope of the linting task:

• Filename-based visitor: Use this if you need to lint module names (e.g., disallowing numbers in filenames).
• tokenize-based visitor: Use this for low-level lexical analysis (e.g., disallowing specific characters or tokens like the number 3).
• ast-based visitor: Use this for structural analysis of the code (e.g., disallowing multiplication of exactly two numbers).

The wemake formatter is a custom formatter for flake8 designed to be compact and informative. You can activate it via the command line or by configuring your setup.cfg file.

# Via command line
flake8 --format=wemake your_module.py

# Via setup.cfg
[flake8]
format = wemake

When using certain editors, you may need to disable the built-in wemake-python-styleguide formatter to avoid conflicts. To do this, set the default formatter in your editor configuration using:

format = default

Use a custom File Watcher to get real-time feedback on every file save. This approach is useful if the Flake8 Support plugin does not pick up your WPS installation.

1. Open Settings (or Preferences on macOS).
2. Navigate to Tools → File Watchers.
3. Click + and choose <custom>.
4. Configure the following settings:
   • Name: wemake-python-styleguide
   • File type: Python
   • Scope: Project Files
   • Program: flake8 (or the full path to the binary)
   • Arguments: --select=WPS $FilePath$
   • Output paths to refresh: $FilePath$
   • Working directory: $ProjectFileDir$
5. In the Advanced Options section, enable:
   • Auto-save edited files to trigger the watcher
   • Trigger the watcher on external changes
6. Click OK.

To visually identify code problems more easily, enable the --show-source option. This displays the specific line of code and a pointer to the error. You can pass this as a CLI argument or set it in setup.cfg.

flake8 . --format=wemake --show-source

[flake8]
show-source = True