3

In a lot of my python projects I use the Darglint docstring linter as part of the pre-commit hooks. But this cool piece of software has been archived since Dec 16, 2022.

Since it is not longer maintained, I think it is a good idea to start looking for an replacement, that is better maintained.

Do you have any recommendations for a nice and maintained python docstring linter that works with google style docstrings and can be used as a pre-commit hook?


Edit since I learned something new:

In addition to the above requirements another one emerged: The docstring linter has to check whether the docstring are in line with the actual code (e.g. number and name of arguments).

3 Answers 3

2

I adopted darglint and renamed my fork to darglint2. I'm now maintaining it as a side project. Contributions are welcome!

2

Ruff

Python linter, written in Rust, docs, repo, MIT license, pre-commit hook

Feature request to reimplement darglint: https://github.com/astral-sh/ruff/issues/458

Does Ruff support NumPy- or Google-style docstrings?

Yes! To enable specific docstring convention, add the following to your pyproject.toml:

[tool.ruff.pydocstyle]
convention = "google"  # Accepts: "google", "numpy", or "pep257".
1

I did some searching too and found some tools in that direction, but non of them seems to be a suitable replacement for darglint:

  • As mentioned by Gounou, Ruff does (among other things) docstring linting. But it goes about it differently: Consider a function with 2 arguments and a docstring which only talks about one argument. Ruff is fine with this, but will make sure that your docstring does not exceed the defined line-length. darglint on the other hand is unhappy because you forgot to mention an argument. In my mind ruff and darglint would add to each other significantly, so it is a good idea to mention Ruff here.
  • The same holds true for flake8-docstrings, which adds an extension for the pydocstyle tool to flake8. It does not check if your docstrings are aligned with your actual code. The problem with additional_dependencies (in which flake8-docstrings is used) in the pre-commits is that they stay untouched from pre-commit autoupdate, creating manual workload.

These findings are actually in line with what the darglint developer said to be his goal.

Currently there does not seem to be a suitable replacement for darglint.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.