-
Notifications
You must be signed in to change notification settings - Fork 1.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Autofix docstrings with typing changes? #5541
Comments
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. |
No worries, thank you! |
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. |
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 |
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.
""" |
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. |
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. |
First off, thanks for
ruff
, really an amazing utility for the python ecosystem!We're slowly enabling more rules with
ruff
. We just enabled theUP
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:
ruff .
ruff /path/to/file.py --fix
), ideally including the--isolated
flag.ruff .
pyproject.toml
).We're using
numpy
-style docstrings. Also, theUP
set of rules is added.ruff --version
).0.0.275
The text was updated successfully, but these errors were encountered: