wemake-python-styleguide

Common errors

• C101 Coding magic comment not found

  cause The Python file is missing a coding magic comment (e.g., `# -*- coding: utf-8 -*-`) at the top, which wemake-python-styleguide enforces.
  fix Add `# -*- coding: utf-8 -*-` (or similar) as the first or second line of your Python files.

• C0304 Final newline missing

  cause The linter detected that a file does not end with a newline character, a common PEP8 violation.
  fix Ensure all Python files end with a single newline character. Most IDEs can be configured to do this automatically on save.

• WPS214 Too many methods in a class (7 > 6)

  cause The linter is enforcing a strict maximum number of methods per class (default 6), indicating potential violation of the Single Responsibility Principle.
  fix Refactor the class to reduce the number of methods, often by extracting related functionality into smaller helper classes or functions. Adjust the `max-methods` option in your `flake8` configuration if the default is too restrictive for your project.

• WPS210 Too many local variables (5 > 4)

  cause A function or method exceeds the maximum allowed number of local variables (default 4), suggesting excessive complexity or too many responsibilities.
  fix Refactor the function into smaller, more focused units, or use data structures to group related variables. Adjust the `max-local-variables` option in your `flake8` configuration if the default is too restrictive.

• flake8: error: unrecognized arguments: --select=WPS

  cause wemake-python-styleguide is installed, but flake8 is not detecting the 'WPS' selection option, likely because `flake8` itself is not installed or incorrectly configured, or `--select=WPS` is not the first argument when used with other flake8 arguments.
  fix Ensure `flake8` is installed (`pip install flake8`). Always specify `--select=WPS` directly after `flake8` if using it from the command line, or configure `select = WPS` in your `setup.cfg` or `pyproject.toml` under the `[flake8]` section.

Warnings

• breaking Version 1.0.0 introduced a significant breaking change by shifting to 'ruff compatibility'. Many rules previously handled by wemake-python-styleguide (and its internal flake8 plugins) were removed and are now expected to be covered by ruff. Users must integrate ruff into their workflow alongside flake8.
  Fix: Ensure you install and configure 'ruff' (e.g., in `pyproject.toml`) and run `ruff format && ruff check` before `flake8 --select=WPS`. Review the v1.0.0 changelog for removed WPS codes.
• gotcha wemake-python-styleguide is exceptionally strict and opinionated. New users will almost certainly encounter a large number of violations, even on well-written code, and will need to carefully configure ignored rules in `setup.cfg` or `pyproject.toml`.
  Fix: Start with the default configuration, then systematically address or disable specific rules (e.g., using `# noqa` comments, `per-file-ignores`, or `ignore =` in `setup.cfg`) until your codebase passes. Refer to the documentation for each WPS code.
• gotcha The complete linting experience now relies on running *both* `ruff` and `flake8 --select=WPS`. Simply running `flake8` without `ruff` (or without `--select=WPS`) will result in an incomplete set of checks and missed violations.
  Fix: Always include `ruff format .`, `ruff check .`, and `flake8 --select=WPS .` in your CI/CD pipelines and local pre-commit hooks. Adjust configuration files (e.g., `pyproject.toml` for `ruff`, `setup.cfg` for `flake8`) to match.
• deprecated Many specific WPS violation codes were removed in v1.0.0 because their checks are now handled by ruff or pylint. Relying on these old codes in configurations will no longer have an effect.
  Fix: Review your `flake8` configuration (`setup.cfg`, `.flake8`) and remove any `WPS` codes explicitly listed as removed in the v1.0.0 changelog. Use `ruff`'s corresponding rule codes instead where applicable.
• gotcha The linter actively discourages excessive use of `# noqa` comments. The `WPS402` rule will flag modules with too many such comments, indicating potential issues with code quality or over-ignoring rules.
  Fix: Instead of sprinkling `# noqa` comments, try to refactor code to adhere to the style guide, or disable specific rules globally or per-file in your `setup.cfg` if they truly do not fit your project's needs.

Install

• pip install wemake-python-styleguide Install latest version

Imports

• CLI tool

  wps explain <code>

  wemake-python-styleguide is primarily used as a flake8 plugin or via its CLI for specific utilities like `wps explain` to look up violation documentation locally. It is not typically imported into Python code for direct use.
• flake8 integration
  wrong:

  import wemake_python_styleguide

  correct:

  flake8 --select=WPS .

  Users typically interact with wemake-python-styleguide indirectly through the flake8 CLI, not by directly importing it as a Python module. The '--select=WPS' flag is crucial for activating its rules.

Quickstart

Install `wemake-python-styleguide` alongside `flake8` and `ruff`. Create a `pyproject.toml` (for Ruff configuration) and/or `setup.cfg` (for Flake8 configuration, including `--select=WPS`). The recommended workflow involves running `ruff format`, `ruff check`, and then `flake8 --select=WPS` sequentially. This ensures Ruff handles most style and formatting, leaving wemake-python-styleguide to apply its unique opinionated rules.

pip install wemake-python-styleguide flake8 ruff

# --- pyproject.toml ---
# [tool.ruff]
# line-length = 88 # Or your preferred length
# target-version = "py310"
#
# [tool.flake8]
# select = "WPS"
# max-complexity = 10
# max-line-length = 88

# Run ruff first for formatting and many common lints
ruff format .
ruff check .

# Then run wemake-python-styleguide specific checks via flake8
flake8 --select=WPS .