Issue 3241: CLI tool to explain violations

.pre-commit-config.yaml

@@ -47,7 +47,7 @@ repos:
     hooks:
       - id: check-useless-excludes
 
-exclude: ^(tests/fixtures/|tests/test_formatter/__snapshots__/)
+exclude: ^(tests/fixtures/|tests/test_formatter/__snapshots__/|tests/test_cli/__snapshots__/)
 
 ci:
   autofix_commit_msg: "[pre-commit.ci] auto fixes from pre-commit.com hooks"

CHANGELOG.md

@@ -17,6 +17,14 @@ Semantic versioning in our case means:
   change the client facing API, change code conventions significantly, etc.
 
 
+## 1.1.0 WIP
+
+### Command line utility
+
+This version introduces `wps` CLI tool.
+- `wps explain <code>` command can be used to access WPS violation docs (same as on website) without internet access
+
+
 ## 1.0.1 WIP
 
 ### Bugfixes

docs/index.rst

@@ -13,6 +13,7 @@
   pages/usage/configuration.rst
   pages/usage/violations/index.rst
   pages/usage/formatter.rst
+  pages/usage/cli.rst
 
 
 .. toctree::

docs/pages/usage/cli.rst

@@ -0,0 +1,32 @@
+Command line tool
+=================
+
+.. versionadded:: 1.1.0
+
+WPS has a command-line utility named ``wps``
+
+Here are listed all the subcommands it has.
+
+.. rubric:: ``wps explain``
+
+This command can be used to get description of violation.
+It will be the same description that is located on the website.
+
+Syntax: ``wps explain <code>``
+
+Examples:
+
+.. code:: bash
+
+   $ wps explain WPS115
+   WPS115 (UpperCaseAttributeViolation)
+
+   WPS115 - Require ``snake_case`` for naming class attributes.
+   ...
+
+.. code:: bash
+
+   $ wps explain 116
+   WPS116 (ConsecutiveUnderscoresInNameViolation)
+
+   WPS116 - Forbid using more than one consecutive underscore in variable names.

pyproject.toml

@@ -273,3 +273,6 @@ disallow_any_explicit = false
 module = "wemake_python_styleguide.compat.packaging"
 # We allow unused `ignore` comments, because we cannot sync it between versions:
 warn_unused_ignores = false
+
+[tool.poetry.scripts]
+wps = "wemake_python_styleguide.cli.cli_app:main"

tests/test_cli/__snapshots__/test_explain.ambr

@@ -0,0 +1,54 @@
+# serializer version: 1
+# name: test_command
+  '''
+  WPS123 — Forbid unused variables with multiple underscores.
+
+  Reasoning:
+      We only use ``_`` as a special definition for an unused variable.
+      Other variables are hard to read. It is unclear why would one use it.
+
+  Solution:
+      Rename unused variables to ``_``
+      or give it some more context with an explicit name: ``_context``.
+
+  Example::
+
+      # Correct:
+      some_element, _next_element, _ = some_tuple()
+      some_element, _, _ = some_tuple()
+      some_element, _ = some_tuple()
+
+      # Wrong:
+      some_element, _, __  = some_tuple()
+
+  .. versionadded:: 0.12.0
+
+  See at website: https://pyflak.es/WPS123
+
+  '''
+# ---
+# name: test_command_on_not_found[wps explain 10000]
+  '''
+  Violation "10000" not found
+
+  '''
+# ---
+# name: test_command_on_not_found[wps explain NOT_A_CODE]
+  '''
+  Violation "NOT_A_CODE" not found
+
+  '''
+# ---
+# name: test_command_on_not_found[wps explain WPS10000]
+  '''
+  Violation "WPS10000" not found
+
+  '''
+# ---
+# name: test_no_command_specified
+  '''
+  usage: wps [-h] {explain} ...
+  wps: error: the following arguments are required: {explain}
+
+  '''
+# ---

tests/test_cli/test_explain.py

@@ -0,0 +1,121 @@
+"""Test that wps explain command works fine."""
+
+import os
+import platform
+import subprocess
+
+import pytest
+
+from wemake_python_styleguide.cli.commands.explain import (
+    message_formatter,
+    violation_loader,
+)
+from wemake_python_styleguide.violations.best_practices import (
+    InitModuleHasLogicViolation,
+)
+from wemake_python_styleguide.violations.naming import (
+    UpperCaseAttributeViolation,
+)
+from wemake_python_styleguide.violations.oop import BuiltinSubclassViolation
+
+
+@pytest.mark.parametrize(
+    'violation_params',
+    [
+        (115, UpperCaseAttributeViolation),
+        (412, InitModuleHasLogicViolation),
+        (600, BuiltinSubclassViolation),
+    ],
+)
+def test_violation_getter(violation_params):
+    """Test that violation loader can get violation by their codes."""
+    violation_code, expected_class = violation_params
+    violation = violation_loader.get_violation(violation_code)
+    assert violation.code is not None
+    assert violation.docstring == expected_class.__doc__
+
+
+@pytest.mark.parametrize(
+    'test_params',
+    [
+        ('  text\n  text\n  text', 'text\ntext\ntext'),
+        ('  text\n\ttext\r\n  text', 'text\n  text\ntext'),
+        (' text\n    \n\n text', 'text\n   \n\ntext'),
+        ('\n\n', '\n\n'),
+        ('text', 'text'),
+        ('text\ntext', 'text\ntext'),
+        ('', ''),
+        ('    ', '    '),
+    ],
+)
+def test_indentation_removal(test_params):
+    """Test that indentation remover works in different conditions."""
+    input_text, expected = test_params
+    actual = message_formatter._remove_indentation(input_text)  # noqa: SLF001
+    assert actual == expected
+
+
+violation_mock = violation_loader.ViolationInfo(
+    identifier='Mock',
+    code=100,
+    docstring='docstring',
+    section='mock',
+)
+violation_string = 'docstring\n\nSee at website: https://pyflak.es/WPS100'
+
+
+def test_formatter():
+    """Test that formatter formats violations as expected."""
+    formatted = message_formatter.format_violation(violation_mock)
+    assert formatted == violation_string
+
+
+def _popen_in_shell(args: str) -> subprocess.Popen:  # pragma: no cover
+    """Run command in shell."""
+    encoding = 'utf-8'
+    # Some encoding magic. Calling with shell=True on Windows
+    # causes everything to be in cp1251. shell=True is needed
+    # for subprocess.Popen to locate the installed wps command.
+    if platform.system() == 'Windows':
+        encoding = 'cp1251'
+    return subprocess.Popen(  # noqa: S602 (insecure shell=True)
+        args,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        universal_newlines=True,
+        encoding=encoding,
+        env=os.environ,
+        shell=True,
+    )
+
+
+def test_command(snapshot):
+    """Test that command works and formats violations as expected."""
+    process = _popen_in_shell('wps explain WPS123')
+    stdout, stderr = process.communicate()
+    assert process.returncode == 0, (stdout, stderr)
+    assert stdout == snapshot
+
+
+@pytest.mark.parametrize(
+    'command',
+    [
+        'wps explain 10000',
+        'wps explain NOT_A_CODE',
+        'wps explain WPS10000',
+    ],
+)
+def test_command_on_not_found(command, snapshot):
+    """Test command works when violation code is wrong."""
+    process = _popen_in_shell(command)
+    stdout, stderr = process.communicate()
+    assert process.returncode == 1, (stdout, stderr)
+    assert stderr == snapshot
+
+
+def test_no_command_specified(snapshot):
+    """Test command displays error message when no subcommand provided."""
+    process = _popen_in_shell('wps')
+    stdout, stderr = process.communicate()
+    assert process.returncode != 0, (stdout, stderr)
+    assert stderr == snapshot

wemake_python_styleguide/cli/application.py

@@ -0,0 +1,14 @@
+"""Provides WPS CLI application class."""
+
+from typing import final
+
+from wemake_python_styleguide.cli.commands.explain.command import ExplainCommand
+
+
+@final
+class Application:
+    """WPS CLI application class."""
+
+    def run_explain(self, args) -> int:
+        """Run explain command."""
+        return ExplainCommand().run(args)

wemake_python_styleguide/cli/cli_app.py

@@ -0,0 +1,44 @@
+"""Main CLI utility file."""
+
+import argparse
+import sys
+
+from wemake_python_styleguide.cli.application import Application
+
+
+def _configure_arg_parser(app: Application) -> argparse.ArgumentParser:
+    """Configures CLI arguments and subcommands."""
+    parser = argparse.ArgumentParser(
+        prog='wps', description='WPS command line tool'
+    )
+    sub_parsers = parser.add_subparsers(help='sub-command help')
+    sub_parsers.required = True
+
+    parser_explain = sub_parsers.add_parser(
+        'explain',
+        help='Get violation description',
+    )
+    parser_explain.add_argument(
+        'violation_code',
+        help='Desired violation code',
+    )
+    parser_explain.set_defaults(func=app.run_explain)
+
+    return parser
+
+
+def parse_args(app: Application) -> argparse.Namespace:
+    """Parse CLI arguments."""
+    parser = _configure_arg_parser(app)
+    return parser.parse_args()
+
+
+def main() -> int:
+    """Main function."""
+    app = Application()
+    args = parse_args(app)
+    return int(args.func(args))
+
+
+if __name__ == '__main__':
+    sys.exit(main())

wemake_python_styleguide/cli/commands/base.py

@@ -0,0 +1,12 @@
+"""Contains files common for all wps commands."""
+
+from abc import ABC, abstractmethod
+
+
+class AbstractCommand(ABC):
+    """ABC for all commands."""
+
+    @abstractmethod
+    def run(self, args) -> int:
+        """Run the command."""
+        raise NotImplementedError

wemake_python_styleguide/cli/commands/explain/command.py

@@ -0,0 +1,32 @@
+"""Contains command implementation."""
+
+from wemake_python_styleguide.cli.commands.base import AbstractCommand
+from wemake_python_styleguide.cli.commands.explain import (
+    message_formatter,
+    violation_loader,
+)
+from wemake_python_styleguide.cli.output import print_stderr, print_stdout
+
+
+def _clean_violation_code(violation_str: str) -> int:
+    """Get int violation code from str violation code."""
+    violation_str = violation_str.removeprefix('WPS')
+    try:
+        return int(violation_str)
+    except ValueError:
+        return -1
+
+
+class ExplainCommand(AbstractCommand):
+    """Explain command impl."""
+
+    def run(self, args) -> int:
+        """Run command."""
+        code = _clean_violation_code(args.violation_code)
+        violation = violation_loader.get_violation(code)
+        if violation is None:
+            print_stderr(f'Violation "{args.violation_code}" not found')
+            return 1
+        message = message_formatter.format_violation(violation)
+        print_stdout(message)
+        return 0