False positive DOC405

[ddelange]

Hi 👋

The following throws a

164: DOC405: Function `yields` has both "return" and "yield" statements. Please use Generator[YieldType, SendType, ReturnType] as the return type annotation, and put your yield type in YieldType and return type in ReturnType. More details in https://jsh9.github.io/pydoclint/notes_generator_vs_iterator.html

false positive. Interestingly, when I remove the Args section from the docstring, the false positive is no longer thrown.

from contextlib import contextmanager


@contextmanager
def yields(db: Optional[int]) -> Iterator[int]:
    """Test a function.

    Args:
        db: the database

    Yields:
        Some stuff.
    """
    if db is not None:
        yield db
        return

    db = ...
    yield db

[jsh9]

Hi @ddelange , did you check out the page that's included at the end of the error message: https://jsh9.github.io/pydoclint/notes_generator_vs_iterator.html

Do you think what the page says makes sense?

[ddelange]

Hi @jsh9 👋

It should definitely be legal to annotate the above function as Iterator[int]. The return statement is only present for (early) exit, not to actually return a value (which would need to be mentioned in the docstring). This example only ever yields an int.

From python docs:

In a generator function, the return statement indicates that the generator is done and will cause StopIteration to be raised. The returned value (if any) is used as an argument to construct StopIteration and becomes the StopIteration.value attribute.

[jabbera]

I just ran into this as well and without a way to disable errors line by line I've had to remove pydoclint from my pre-commit

[jsh9]

Hi @jabbera and @ddelange ,

What do you think of the following logic?

• If there is a bare return (i.e., just return without anything behind it, not even return None), suppress DOC405
• As long as there is anything after return, raise DOC405

The purpose of DOC405 is to persuade users to use a Generator when they are actually returning something. And I guess this use case of yours is an edge case.

[ddelange]

sounds good:) typing docs corroborate this approach: Generator[int, None, None] may be typed as Iterator[int].

since return None and return are equivalent statements, both fall under this category imo, and some linters might force either of both for style.

[jabbera]

@jsh9 I think that sounds good. I actually went back and baselined with the error to get it suppressed so I'm actually good, but would love to get rid of the baseline!

[jsh9]

The fix is published in version 0.5.19.