terrencepreilly / darglint

A python documentation linter which checks that the docstring description matches the definition.
MIT License
483 stars 41 forks source link

False positive on missing parameters #146

Closed dclong closed 3 years ago

dclong commented 3 years ago

I have a file containing the following code.

#!/usr/bin/env python3
"""Filesystem related util functions.
"""
import re
from typing import Union, List, Tuple, Iterable
from pathlib import Path

def update_file(
    path: Path,
    regex: List[Tuple[str, str]] = None,
    exact: List[Tuple[str, str]] = None,
    append: Union[str, Iterable[str]] = None,
    exist_skip: bool = True,
) -> None:
    """Update a text file using regular expression substitution.

    :param path: A Path object to the file to be updated.
    :param regex: A list of tuples containing regular expression patterns
        and the corresponding replacement text.
    :param exact: A list of tuples containing exact patterns and the corresponding replacement text.
    :param append: A string of a list of lines to append.
        When append is a list of lines, "\n" is automatically added to each line.
    :param exist_skip: Skip appending if already exists.
    """
    if isinstance(path, str):
        path = Path(path)
    text = path.read_text()
    if regex:
        for pattern, replace in regex:
            text = re.sub(pattern, replace, text)
    if exact:
        for pattern, replace in exact:
            text = text.replace(pattern, replace)
    if append:
        if not isinstance(append, str):
            append = "\n".join(append)
        if not exist_skip or append not in text:
            text += append
    path.write_text(text)

With the following configuration,

[darglint]
docstring_style=sphinx
message_template={path}:{line}: {msg_id}: {msg}

darglint reports missing parameters.

f2.py:14: DAR101: - append
f2.py:14: DAR101: - exact
f2.py:14: DAR101: - exist_skip
f2.py:14: DAR101: - path
f2.py:14: DAR101: - regex
terrencepreilly commented 3 years ago

Looks like you have an improperly escaped newline in your docstring. If you change the docstring to a raw docstring (i.e. r"""..."""), everything works as expected.

It looks like when the ast module returns the docstring, because this line is indented 4 spaces less than all others, it doesn't adjust the indentation correctly. And darglint can't (?) preprocess the docstring correct the indentation because that would involve parsing the python module, and not just the docstring.