Autofix docstrings with typing changes?

[petermattia]

First off, thanks for ruff, really an amazing utility for the python ecosystem!

We're slowly enabling more rules with ruff. We just enabled the UP rule set, which mostly caught outdated typing conventions. Wondering if it would be possible to (ideally) auto-fix the docstrings or perhaps somehow warn the user that the docstrings may require updating as well?

Example:

• A minimal code snippet that reproduces the bug.

ruff .

• The command you invoked (e.g., ruff /path/to/file.py --fix), ideally including the --isolated flag.

ruff .

• The current Ruff settings (any relevant sections from your pyproject.toml).

We're using numpy-style docstrings. Also, the UP set of rules is added.

[tool.ruff]
select = ["UP", ...]

[tool.ruff.pydocstyle]
convention = "numpy"

• The current Ruff version (ruff --version).

0.0.275

[charliermarsh]

This is a really nice idea... It's probably a ways off, I think we need a proper docstring parser to support it (rather than the pydocstyle-inspired regular expressions we use now), but it would be really cool.

[petermattia]

No worries, thank you!

[smackesey]

I would love this feature-- huge value-add in terms of ensuring our API docs are accurate.

FWIW robust docstring parsing/formatting/linting would be a huge feather in ruff's cap, the existing tooling ecosystem for this is terrible given what a universal problem it is.

[jorgegomezcq]

FWIW robust docstring parsing/formatting/linting would be a huge feather in ruff's cap, the existing tooling ecosystem for this is terrible given what a universal problem it is.

darglint is a related tool but it looks like it was deprecated last December:

https://github.com/terrencepreilly/darglint

There's also pyment but it has its rough edges that I've run into:

https://github.com/dadadel/pyment

These might be good projects to consult when implementing #5541

[T-256]

FWIW(?) I interested in PEP 727 that may deprecate type definitions in docstrings in future.

from typing import Annotated, Doc

def create_user(
    name: Annotated[str, Doc("The user's name")],
    age: Annotated[int, Doc("The user's age")],
    cursor: DatabaseConnection | None = None,
) -> Annotated[User, Doc("The created user after saving in the database")]:
    """Create a new user in the system.

    It needs the database connection to be already initialized.
    """

[ShivMunagala]

pydoclint (https://github.com/jsh9/pydoclint) partly does this, it doesn't autofix afaik but it can warn a user if there is a mismatch between docstring and typehints.

[petermattia]

Yea, we currently use pydoclint as a precommit hook. Generally good enough for our purposes, but would be nice to drop it and consolidate with ruff.