False positive for return annotations using |

[haakonvt]

I have a few files using the pipe operator instead of typing.Union, and I get what I think looks like a false positive DOC203.

To reproduce:

from typing import Sequence

class Foo:
    pass

class Bar:
    def fn(self, a: Foo | Sequence[Foo]) -> Foo | int:
        """Some description.

        Args:
            a (Foo | Sequence[Foo]): Some description.

        Returns:
            Foo | int: Some description.

        Examples:

            Some examples
        """
        return ...

When running the following file through pydoclint I get the following output:

Loading config from user-specified .toml file: pyproject.toml
Found options defined in pyproject.toml:
{'style': 'google',
 'exclude': 'tests/|scripts/',
 'quiet': True,
 'require_return_section_when_returning_nothing': True,
 'arg_type_hints_in_signature': True,
 'arg_type_hints_in_docstring': True,
 'allow_init_docstring': False,
 'check_return_types': True,
 'check_arg_order': True}
aaaa.py
    9: DOC203: Method `Bar.fn` return type(s) in docstring not consistent with the return annotation. 
    Return annotation types: ['Foo | int']; docstring return section types: ['']

Do I have to use -> Union[Foo, int]:? Or what's wrong here 🤔

[jsh9]

Hi @haakonvt , thanks for reporting this issue!

I did some research, and this is actually due to a bug in docstring_parser (the docstring parser that pydoclint uses to parse Google-style and Sphinx-style docstrings.

When it sees this

Returns:
    Foo | int: Some description.

it thinks the whole Foo | int: Some description. is the description of the return value.

But it can process Union[Foo, int] correctly.

Let me post an issue over there.

[haakonvt]

Oh, I see. Thanks for following up @jsh9 😄

[jsh9]

The fix on the docstring_parser side is not that difficult, just tweaking a regex.

However, there is not a lot of activities on that tool (its last release was almost a year ago, from September 2022). To deliver the fix to pydoclint users quickly, I forked it (https://github.com/jsh9/docstring_parser_fork), fixed it (jsh9/docstring_parser_fork#1), and published the fix to PyPI (https://pypi.org/project/docstring-parser-fork/).

[jsh9]

Published. Please try out version 0.1.9: https://github.com/jsh9/pydoclint/releases/tag/0.1.9

[haakonvt]

Swoosh, I love it! Thanks!