Darglint replacement tool: pydoclint

[jsh9]

Hi @jrjsmrtn, @ddelange, @ericmjl, @thatlittleboy, @Kludex, @cidrblock, @ssbarnea, @finswimmer, @edgarrmondragon, @lsorber, @anthonyburdi,

I followed this Ruff issue (astral-sh/ruff#458) and saw that you were all using Darglint and all wanted a faster solution.

I implemented pydoclint (the repo that this post is in) a few months ago in pure Python, and it's much much faster than Darglint. In addition, it discovers a lot of docstring style violations that Darglint does not.

If you are interested, please feel free to try it out. Any feedback is welcome!

Additional notes:

1. I have no affiliation with Ruff's authors. I did make a suggestion to them to implement pydoclint instead of Darglint into Ruff (Implement rules in darglint astral-sh/ruff#458 (comment)), but they did not reply to it.

2. pydoclint is not a drop-in replacement of Darglint: if you adopt pydoclint, you'll likely discover more style violations (they are still docstring style violations but Darglint could not detect them).

[ericmjl]

Hi @jsh9! Thank you for making pydoclint! I wanted to share that I wrote a blog post about switching to pydoclint from darglint: https://ericmjl.github.io/blog/2023/10/9/check-docstrings-blazing-fast-with-pydoclint/

Thanks again for your contribution to the open source community!

[jsh9]

Hi @ericmjl , thank you for the kind words! Btw your blog series contain lot of other useful info too!

[ddelange]

Cool tool, looks like it's time to switch!

I tried it out on one of my repos, and I'm getting some errors for a valid Google style docstring (see also docstring docs on type annotations):

src/mapply/parallel.py
    62: DOC107: Function `multiprocessing_imap`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
    62: DOC103: Function `multiprocessing_imap`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [**kwargs: ]. Arguments in the docstring but not in the function signature: [kwargs: ].
    62: DOC404: Function `multiprocessing_imap` yield type(s) in docstring not consistent with the return annotation. The yield type (the 0th arg in Generator[...]/Iterator[...]): Iterator; docstring "yields" section types:
Loading config from user-specified .toml file: pyproject.toml
File "pyproject.toml" does not exist; nothing to load.

And even if i go

-    args=(),
+    args: Tuple[Any, ...] = (),
-    **kwargs,
+    **kwargs: Any,

I'll still get

src/mapply/parallel.py
    62: DOC103: Function `multiprocessing_imap`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [**kwargs: Any]. Arguments in the docstring but not in the function signature: [kwargs: ].
    62: DOC404: Function `multiprocessing_imap` yield type(s) in docstring not consistent with the return annotation. The yield type (the 0th arg in Generator[...]/Iterator[...]): Any; docstring "yields" section types:
Loading config from user-specified .toml file: pyproject.toml
File "pyproject.toml" does not exist; nothing to load.

So:

• it seems like pydoclint doesn't like **kwargs (and maybe *args?)
• it seems like pydoclint doesn't like Yields in google style with type annotation in the function signature instead of in the docstring
• the last line docstring "yields" section types: seems to be truncated -- missing the Yields statement from the codebase

[ddelange]

and for the others, i'll configure to ignore:

-   repo: https://github.com/jsh9/pydoclint
    rev: 0.3.4
    hooks:
    -   id: pydoclint
        args: [--style=google, --arg-type-hints-in-docstring=False, --check-return-types=False, --check-yield-types=False]

is that the suggested solution? shouldn't --check-return-types=False, --check-yield-types=False be default for --style=google?

[ddelange]

integrated 🎉 ddelange/mapply#46

[jsh9]

Hi @ddelange , thank you very much for the feedback!

ah, for DOC103 it seems to want **kwargs in the docstring instead of plain kwargs

I have a slight preference in using **kwargs rather than plain kwargs in the docstring, because I think it is more explicit and visually easier to spot.

But if you have stronger rationale of why plain kwargs is better, I could be convinced otherwise.

is that the suggested solution? shouldn't --check-return-types=False, --check-yield-types=False be default for --style=google?

Yeah, I guess so.

I actually am not very familiar with default "flavor" for Google-style docstring. From my vague memory, Google doesn't enforce any flavor, it instead suggests.

One advantage of setting --arg-type-hints-in-docstring=True (regardless of numpy/Google/Sphinx style) is: if your functions have many arguments (say 50), the docstring will be long, and looking up the types of a particular argument may be easier of the type is written into the docstring.

[jsh9]

That said, I did add this section in the documentation for Google-style docstring writers: https://jsh9.github.io/pydoclint/notes_for_users.html#5-notes-for-google-style-users

This hopefully can make the adoption easier for people.

(One thing that I'm hesitant to implement is different default configs for different styles: numpy, Google, Sphinx. This would be difficult to remember, and hence more difficult to maintain.)

[ddelange]

The type hints (also the return type) find their way back into the docs generated from the docstring: https://mapply.readthedocs.io/en/stable/_code_reference/mapply.html#mapply.mapply.mapply

I think if youd duplicate the return type into the docstring, it will also lead to duplicate information on readthedocs (but haven't verified that).

[cidrblock]

TY, we're making the switch slowly...

[jsh9]

There's actually a good way to gradually adopt pydoclint. A user of pydoclint implemented it as a code change, and it's the --baseline option: https://jsh9.github.io/pydoclint/config_options.html#12---baseline

[jsh9]

(I should probably write this --baseline thing into the documentation so that it's easier for new users to find.)

[edgarrmondragon]

Great work on this! Migration from darglint was a breeze 🙂

[jsh9]

Good to know that!