flake8_rst_docstrings.py

"""Check Python docstrings validate as reStructuredText (RST).

This is a plugin for the tool flake8 tool for checking Python
source code.
"""

import ast
import re

import restructuredtext_lint as rst_lint

try:
    # if sphinx is available, get the filtering regex from it directly
    from sphinx.ext.autodoc import py_ext_sig_re
except ImportError:
    # otherwise use own copy from Sphinx 4.3.1 (hasn't changed since
    # it was added in 0.6 so probably pretty safe)
    py_ext_sig_re = re.compile(
        r"""^ ([\w.]+::)?            # explicit module name
              ([\w.]+\.)?            # module and/or class name(s)
              (\w+)  \s*             # thing name
              (?: \((.*)\)           # optional: arguments
               (?:\s* -> \s* (.*))?  #           return annotation
              )? $                   # and nothing more
              """,
        re.VERBOSE,
    )

__version__ = "0.3.0"


rst_prefix = "RST"
rst_fail_load = 900
# rst_fail_parse = 901
# rst_fail_all = 902
rst_fail_lint = 903

# Level 1 - info
code_mapping_info = {
    "Possible title underline, too short for the title.": 1,
    "Unexpected possible title overline or transition.": 2,
}

# Level 2 - warning
code_mapping_warning = {
    # XXX ends without a blank line; unexpected unindent:
    "Block quote ends without a blank line; unexpected unindent.": 1,
    "Bullet list ends without a blank line; unexpected unindent.": 2,
    "Definition list ends without a blank line; unexpected unindent.": 3,
    "Enumerated list ends without a blank line; unexpected unindent.": 4,
    "Explicit markup ends without a blank line; unexpected unindent.": 5,
    "Field list ends without a blank line; unexpected unindent.": 6,
    "Literal block ends without a blank line; unexpected unindent.": 7,
    "Option list ends without a blank line; unexpected unindent.": 8,
    # Other:
    "Inline strong start-string without end-string.": 10,
    "Blank line required after table.": 11,
    "Title underline too short.": 12,
    "Inline emphasis start-string without end-string.": 13,
    "Inline literal start-string without end-string.": 14,
    "Inline interpreted text or phrase reference start-string without end-string.": 15,
    "Multiple roles in interpreted text (both prefix and suffix present; only one allowed).": 16,  # noqa: E501
    "Mismatch: both interpreted text role suffix and reference suffix.": 17,
    "Literal block expected; none found.": 18,
    "Inline substitution_reference start-string without end-string.": 19,
}

# Level 3 - error
code_mapping_error = {
    "Unexpected indentation.": 1,
    "Malformed table.": 2,
    # e.g. Unknown directive type "req".
    'Unknown directive type "*".': 3,
    # e.g. Unknown interpreted text role "need".
    'Unknown interpreted text role "*".': 4,
    # e.g. Undefined substitution referenced: "dict".
    'Undefined substitution referenced: "*".': 5,
    # e.g. Unknown target name: "license_txt".
    'Unknown target name: "*".': 6,
    # e.g. Error in "code" directive:
    'Error in "*" directive:': 7,
}

# Level 4 - severe
code_mapping_severe = {"Unexpected section title.": 1}

code_mappings_by_level = {
    1: code_mapping_info,
    2: code_mapping_warning,
    3: code_mapping_error,
    4: code_mapping_severe,
}


def code_mapping(
    level, msg, extra_directives, extra_roles, extra_substitutions, default=99
):
    """Return an error code between 0 and 99."""
    try:
        return code_mappings_by_level[level][msg]
    except KeyError:
        pass
    # Following assumes any variable messages take the format
    # of 'Fixed text "variable text".' only:
    # e.g. 'Unknown directive type "req".'
    # ---> 'Unknown directive type'
    # e.g. 'Unknown interpreted text role "need".'
    # ---> 'Unknown interpreted text role'
    # e.g. 'Undefined substitution referenced: "subst".'
    # ---> 'Undefined substitution referenced:'
    if msg.count('"') == 2 and ' "' in msg:
        value = msg.split('"', 2)[1]
        txt = msg.replace(' "' + value + '"', ' "*"')
        if txt == 'Unknown directive type "*".' and value in extra_directives:
            return 0
        if txt == 'Unknown interpreted text role "*".' and value in extra_roles:
            return 0
        if (
            txt == 'Undefined substitution referenced: "*".'
            and value in extra_substitutions
        ):
            return 0
        return code_mappings_by_level[level].get(txt, default)
    return default


class reStructuredTextChecker:
    """Checker of Python docstrings as reStructuredText."""

    name = "rst-docstrings"
    version = __version__

    def __init__(self, tree, filename="(none)"):
        """Initialise."""
        self.tree = tree
        self.filename = filename

    @classmethod
    def add_options(cls, parser):
        """Add RST directives, roles and substitutions options."""
        parser.add_option(
            "--rst-directives",
            metavar="LIST",
            default="",
            parse_from_config=True,
            comma_separated_list=True,
            help="Comma-separated list of additional RST directives.",
        )
        parser.add_option(
            "--rst-roles",
            metavar="LIST",
            default="",
            parse_from_config=True,
            comma_separated_list=True,
            help="Comma-separated list of additional RST roles.",
        )
        parser.add_option(
            "--rst-substitutions",
            metavar="LIST",
            default="",
            parse_from_config=True,
            comma_separated_list=True,
            help="Comma-separated list of additional RST substitutions.",
        )

    @classmethod
    def parse_options(cls, options):
        """Adding black-config option."""
        cls.extra_directives = options.rst_directives
        cls.extra_roles = options.rst_roles
        cls.extra_substitutions = options.rst_substitutions

    def run(self):
        """Use docutils to check docstrings are valid RST."""
        if self.tree is None:
            msg = "%s%03i %s" % (
                rst_prefix,
                rst_fail_load,
                "Failed to load file: %s" % self.err,
            )
            yield 0, 0, msg, type(self)
        else:
            wanted = (
                ast.Module,
                ast.ClassDef,
                ast.FunctionDef,
                ast.AsyncFunctionDef,
            )
            for node in ast.walk(self.tree):
                if not isinstance(node, wanted):
                    continue
                docstring = ast.get_docstring(node, clean=True)
                if not docstring:
                    # People can use flake8-docstrings to report missing docstrings
                    continue
                # strip the first line if it's a signature
                firstline = docstring.splitlines()[0]
                if py_ext_sig_re.match(firstline.strip()):
                    # replace by an empty line so the line number
                    # doesn't need to be adjusted
                    docstring = docstring.replace(firstline, "", 1)

                try:
                    rst_errors = list(rst_lint.lint(docstring))
                except Exception as err:
                    # e.g. UnicodeDecodeError
                    msg = "%s%03i %s" % (
                        rst_prefix,
                        rst_fail_lint,
                        "Failed to lint docstring: %s - %s" % (node.name, err),
                    )
                    yield 0, 0, msg, type(self)
                    continue

                if rst_errors:
                    try:
                        node.body[0].end_lineno
                        # Worked, on Python 3.8+ and can trust the start
                        start = node.body[0].lineno - 1  # AST value 1 based
                    except AttributeError:
                        # On Python 3.7 or older, and must compute start line
                        start = (
                            node.body[0].lineno
                            - ast.get_docstring(node, clean=False).count("\n")
                            - 1
                        )
                    assert (
                        node.body[0].lineno >= 1 and start >= 0
                    ), "Bad start line, node line number %i for: %s\n" % (
                        node.body[0].lineno,
                        docstring,
                    )
                for rst_error in rst_errors:
                    # TODO - make this a configuration option?
                    if rst_error.level <= 1:
                        continue
                    # Levels:
                    #
                    # 0 - debug   --> we don't receive these
                    # 1 - info    --> RST1## codes
                    # 2 - warning --> RST2## codes
                    # 3 - error   --> RST3## codes
                    # 4 - severe  --> RST4## codes
                    #
                    # Map the string to a unique code:
                    msg = rst_error.message.split("\n", 1)[0]
                    code = code_mapping(
                        rst_error.level,
                        msg,
                        self.extra_directives,
                        self.extra_roles,
                        self.extra_substitutions,
                    )
                    if not code:
                        # We ignored it, e.g. a known Sphinx role
                        continue
                    assert 0 < code < 100, code
                    code += 100 * rst_error.level
                    msg = "%s%03i %s" % (rst_prefix, code, msg)

                    # We don't know the column number, leaving as zero.
                    yield start + rst_error.line, 0, msg, type(self)