-
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
Implement rules in darglint
#458
Comments
Cool, I've never used but looks useful. Would this be an impactful plugin for you? Would it unblock any Ruff adoption? :) |
Hey @charliermarsh, yeah. I maintain a few packages with public APIs that would benefit from contributors being informed about documentation for arguments or exceptions raised being missing. A number of features would make Ruff a nice replacement for flake8: speed, compatibility with the rest of the Python ecosystem, pyproject.toml support. |
FWIW, [1] superlinear-ai/poetry-cookiecutter#125 |
👍 Helpful to hear! |
For me personally, they're probably DAR101, DAR102, DAR201, DAR202 and to a lesser extent DAR301, DAR302, DAR401 and DAR402 |
For me, I use |
We just discovered ruff in my team. It's amazing, and I'd like to thank you for all the great work! We used to run flake8 along with darglint. Unfortunately since ruff does not yet implement darglint rules we still have to keep darglint alongside ruff which is a shame given how slow darglint is. Reimplementing darglint within ruff is definitely the feature we are most looking forward to! For us the most important rules are probably those related to the parameters (and returns) and their types: We understand that maintaining an open-source project can be a lot of work and we want to express our appreciation for all the effort that goes into it. We were wondering if there's any update on when this issue might be addressed? Any information would be greatly appreciated. Thank you! |
Very helpful, thank you! It's not something I've started working on actively (and would make for a good contribution if there are any eager contributors reading this :)), but that set of rules at least is probably not too much work to support, and this issue has a lot of thumbs-up votes so I'll try to get to it soon-ish. I'll post here when I'm able to take it on. |
Looking into starting on this. |
Super exciting to hear that this is in the works. We just switched to ruff instead of
|
It would be great if it could add darglint’s feature that checks if docstrings match a particular style (whether it be Sphinx, Google, or something else) |
Implementing darglint could handle some flake8 exceptions, as well as part of docformatter I guess? |
@charliermarsh Is there an update on implementing darglint features in ruff? Thank you for all of your work on this project! |
Hey, unfortunately Thanks a lot for all your very good work! fin swimmer |
I'm currently considering taking this on as a project over the next few weeks, but it's competing with some other priorities so not a firm commitment yet :) I definitely hear that this something users want, and it's something I want Ruff to support too -- just a question of when, will post here when I have a clear decision. |
Great to hear work is close to being started. We also rely a lot on
|
Hello @charliermarsh! I manage to convert almost all checks to ruff, except for Darling, do you have any idea whether this will be done? |
As mentioned in Discord, registering my interest in taking a stab at this. |
Using pydocstyle we are using the google style with typing. We strictly use typing in python, so repeating the types in the Doc string serves no purpose and is just redundant. Having rules like DAR103: The docstring parameter type doesn't match function. or DAR105: The docstring parameter type is malformed. certainly would help to keep Doc string and parameter declaration aligned, it's still redundant and we'd rather enforce that no types are specified in the Doc string. Seems darglint doesn't provide such a rule. Edit: Just found this issue which raises the same wish: #9070 |
Hoping to see this as well! Ruff already encompasses most of my CI linting checks, this would be a great addition. Meanwhile, in case it is useful for other people, I decided to take a stab and implement a version that is sufficient for my needs: https://github.com/AloizioMacedo/pystaleds. It intends primarily to check for mismatches of the parameters in the function signature and the arguments in the docstring. It is very experimental, but I can already use it in my projects while ruff doesn't support a similar feature : ) |
@Spenhouet fwiw pydoclint has an see also my config above |
@ddelange Thanks for sharing, that would introduce a new tool just for this small requirement. Would much more prefer if this would be covered by a linting rule within ruff. |
Just wanted to add my voice to those saying that this would be a really useful feature. Thanks for all the amazing work on Ruff! |
I wonder if at this point, it would be better to implement pydoclint in ruff instead of darglint? (This is prompted by the recent PR #11471.) Pydoclint has
|
Strong +1 for this. pydoclint is really great and pretty fast already, but ruff could improve on this and extend it further. Also some issues might be autofixable. |
Are there rules that are present in |
I know of at least two:
These two rules are the only reason we use darglint, everything else that we want is covered by pydoclint. |
Interesting, ok. Those are the exact rules added in #11471. |
I'm the author of pydoclint. I think these two pydoclint violation codes cover DAR401 and 402:
If they don't cover what you want, please feel free to open an issue. |
@jsh9 I don't think those check the exception types. For example, if I have a function like this, which sometimes raises a def _str_to_bool(informal_bool: str) -> bool:
"""
Translate a commonly used boolean ``str`` into a real ``bool``.
Args:
informal_bool: A boolean represented as ``str``, like ``"true"``, ``"no"``, ``"off"``, etc.
Returns:
``True`` or ``False`` to match the intent of ``informal_bool``.
Raises:
ZeroDivisionError: This doesn't look like enough like a ``bool`` to translate.
"""
if informal_bool.lower() in ('true', 't', 'yes', 'y', 'on', '1'):
return True
if informal_bool.lower() in ('false', 'f', 'no', 'n', 'off', '0'):
return False
raise ValueError(f"{informal_bool} doesn't look like a boolean") # pragma: no cover $ darglint nt2
nt2/casters.py:_str_to_bool:29: DAR401: -r ValueError
nt2/casters.py:_str_to_bool:39: DAR402: +r ZeroDivisionError
$ pydoclint nt2
Loading config from user-specified .toml file: pyproject.toml
No config found in pyproject.toml.
Skipping files that match this pattern: \.git|\.tox
nt2/__init__.py
nt2/casters.py
nt2/converters.py
nt2/dumpers.py
nt2/ui.py
nt2/yamlpath_tools.py
🎉 No violations 🎉 |
Thanks @AndydeCleyre ! I've opened a new issue (jsh9/pydoclint#158) on pydoclint to add this feature. |
…extraneous-exception` (`DOC501`, `DOC502`) (#11471) ## Summary These are the first rules implemented as part of #458, but I plan to implement more. Specifically, this implements `docstring-missing-exception` which checks for raised exceptions not documented in the docstring, and `docstring-extraneous-exception` which checks for exceptions in the docstring not present in the body. ## Test Plan Test fixtures added for both google and numpy style.
This might be superseded by #12434
https://pypi.org/project/darglint/
Error Codes
The text was updated successfully, but these errors were encountered: