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,53 @@
+"""Integration testing of wps explain command."""
+
+import subprocess
+
+import pytest
+
+
+def _popen_in_shell(args: str) -> tuple[subprocess.Popen, str, str]:
+    """Run command in shell."""
+    # shell=True is needed for subprocess.Popen to
+    # locate the installed wps command.
+    process = subprocess.Popen(  # noqa: S602 (insecure shell=True)
+        args,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        shell=True,
+    )
+    stdin, stdout = process.communicate()
+    return process, stdin, stdout
+
+
+def test_command(snapshot):
+    """Test that command works and formats violations as expected."""
+    process, stdout, stderr = _popen_in_shell('wps explain WPS123')
+    assert process.returncode == 0, (stdout, stderr)
+    assert stdout == snapshot
+    assert not stderr
+
+
+@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, stdout, stderr = _popen_in_shell(command)
+    assert process.returncode == 1, (stdout, stderr)
+    assert not stdout
+    assert stderr == snapshot
+
+
+def test_no_command_specified(snapshot):
+    """Test command displays error message when no subcommand provided."""
+    process, stdout, stderr = _popen_in_shell('wps')
+    stdout, stderr = process.communicate()
+    assert process.returncode != 0, (stdout, stderr)
+    assert not stdout
+    assert stderr == snapshot

tests/test_cli/test_explain_internals.py

@@ -0,0 +1,30 @@
+"""Unit testing of wps explain command."""
+
+import pytest
+
+from wemake_python_styleguide.cli.commands.explain import (
+    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__

wemake_python_styleguide/cli/cli_app.py

@@ -0,0 +1,38 @@
+import argparse
+
+from wemake_python_styleguide.cli.commands.explain.command import ExplainCommand
+
+
+def _configure_arg_parser() -> argparse.ArgumentParser:
+    """Configures CLI arguments and subcommands."""
+    parser = argparse.ArgumentParser(
+        prog='wps', description='WPS command line tool'
+    )
+    sub_parsers = parser.add_subparsers(
+        help='sub-parser for exact wps commands',
+        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=ExplainCommand())
+
+    return parser
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse CLI arguments."""
+    parser = _configure_arg_parser()
+    return parser.parse_args()
+
+
+def main() -> int:
+    """Main function."""
+    args = parse_args()
+    return int(args.func(args=args))

wemake_python_styleguide/cli/commands/base.py

@@ -0,0 +1,25 @@
+"""Contains files common for all wps commands."""
+
+from abc import ABC, abstractmethod
+from argparse import Namespace
+from typing import Generic, TypeVar
+
+_ArgsT = TypeVar('_ArgsT')
+
+
+class AbstractCommand(ABC, Generic[_ArgsT]):
+    """ABC for all commands."""
+
+    _args_type: type[_ArgsT]
+
+    def __call__(self, args: Namespace) -> int:
+        """Parse arguments into the generic namespace."""
+        args_dict = vars(args)  # noqa: WPS421
+        args_dict.pop('func')  # argument classes do not expect that
+        cmd_args = self._args_type(**args_dict)
+        return self._run(cmd_args)
+
+    @abstractmethod
+    def _run(self, args: _ArgsT) -> int:
+        """Run the command."""
+        raise NotImplementedError

wemake_python_styleguide/cli/commands/explain/command.py

@@ -0,0 +1,47 @@
+"""Contains command implementation."""
+
+from typing import final
+
+from attrs import frozen
+
+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
+
+
+@final
+@frozen
+class ExplainCommandArgs:
+    """Arguments for wps explain command."""
+
+    violation_code: str
+
+
+@final
+class ExplainCommand(AbstractCommand[ExplainCommandArgs]):
+    """Explain command impl."""
+
+    _args_type = ExplainCommandArgs
+
+    def _run(self, args: ExplainCommandArgs) -> 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

wemake_python_styleguide/cli/commands/explain/message_formatter.py

@@ -0,0 +1,22 @@
+"""Provides tools for formatting explanations."""
+
+import textwrap
+
+from wemake_python_styleguide.cli.commands.explain.violation_loader import (
+    ViolationInfo,
+)
+from wemake_python_styleguide.constants import SHORTLINK_TEMPLATE
+
+
+def _remove_newlines_at_ends(text: str) -> str:
+    """Remove leading and trailing newlines."""
+    return text.strip('\n\r')
+
+
+def format_violation(violation: ViolationInfo) -> str:
+    """Format violation information."""
+    cleaned_docstring = _remove_newlines_at_ends(
+        textwrap.dedent(violation.docstring)
+    )
+    violation_url = SHORTLINK_TEMPLATE.format(f'WPS{violation.code}')
+    return f'{cleaned_docstring}\n\nSee at website: {violation_url}'

wemake_python_styleguide/cli/commands/explain/module_loader.py

@@ -0,0 +1,38 @@
+import importlib
+from collections.abc import Collection
+from pathlib import Path
+from types import ModuleType
+from typing import Final
+
+_VIOLATION_MODULE_BASE: Final = 'wemake_python_styleguide.violations'
+
+
+def get_violation_submodules() -> Collection[ModuleType]:
+    """Get all possible violation submodules."""
+    submodule_names = _get_all_possible_submodule_names(_VIOLATION_MODULE_BASE)
+    return [
+        importlib.import_module(submodule_name)
+        for submodule_name in submodule_names
+    ]
+
+
+def _get_all_possible_submodule_names(module_name: str) -> Collection[str]:
+    """Get .py submodule names listed in given module."""
+    root_module = importlib.import_module(module_name)
+    root_paths = root_module.__path__
+    names = []
+    for root in root_paths:
+        names.extend([
+            f'{module_name}.{name}'
+            for name in _get_all_possible_names_in_root(root)
+        ])
+    return names
+
+
+def _get_all_possible_names_in_root(root: str) -> Collection[str]:
+    """Get .py submodule names listed in given root path."""
+    return [
+        path.name.removesuffix('.py')
+        for path in Path(root).glob('*.py')
+        if '__' not in path.name  # filter dunder files like __init__.py
+    ]