List of missing arguments not displayed in D417 Missing argument description error

[martinResearch]

When I get D417 errors the list of missing argument is not displayed in the error message.
It would be much more convenient to have the list of missing argument displayed in the error message.

Looking at the code this list get generated here
but does not end up being displayed in the final error message.

example:

def f(a: str, b: str) -> None:
    """
    Simple function

    Arguments:
    ---------
    a: some argument
    """
    print(a+b)

yields

D417 Missing argument descriptions in the docstring

while I would like to get

D417 Missing argument descriptions in the docstring for argument b

[martinResearch]

actually it seems to be working when using directly pydocstyle, but not when done through flake8 so it seems like it is a flake8 problem instead.

[sigmavirus24]

Interesting. This should probably be opened against flake8-docstrings as that has to coalesce a violation to what Flake8 expects. I expect we're relying on message there from https://github.com/PyCQA/pydocstyle/blob/1011866e6ea91a1fbcb4b01520d2a348becc7de1/src/pydocstyle/violations.py#L17 but it might not be doing the right thing (as message would be building everything but unfortunately includes the code which might be why it doesn't use that).

[sigmavirus24]

I transferred it flake8-docstrings for you

[asottile]

it looks like .message includes that context but has a different problem -- it adds an extra : in the message after the code (which makes it incompatible with flake8)

two ideas there:

1. replace out the colon (seems a little fragile)
2. reimplement pydocstyle's additional message logic (also seems kinda fragile)

[martinResearch]

I am not sure to understand why option 1 would be fragile. What do you think could break this solution? If flake8 does not handle error messages with ":" then it seems sensible to replace these, at the cost of denaturing some error messages. Alternatively, could flake8 be modified to handle error messages with ":" ?

[asottile]

pydocstyle has changed the format twice now looking at the git history of flake8-docstrings and I see no reason it wouldn;t change again

changing flake8 is kinda out of the question -- a single plugin doing it wrong shouldn't loosen the framework

[martinResearch]

"a single plugin doing it wrong" not sure to have enough context to understand why using a ":" in the error message is wrong. Is it wrong independently of flake8's requirements? If so, is it documented anywhere that error messages should not use ":" outside the flake8 context? Or is that wrong only in the sense that it is not supported by flake8 and no other flake8 plug-in do that ? If so, why would that be a negative thing to loosen flake8 requirement ? it seems to me like it would then be an improvement of flake8 to support it, and could potentially benefit other plugins.

[asottile]

yes, the documented message format is code then space then message

changing that would break lots of things

[s0undt3ch]

If the format is [code] [message], then that's easy to parse, and message could virtually contain anything, so why restrain it?

[s0undt3ch]

In my case, pydocstyle reports

src/pytestshellutils/shell.py:327 in public method `run`:
        D417: Missing argument descriptions in the docstring (argument(s) cwd, env are missing descriptions in 'run' docstring)

While flake8 ...

flake8...............................................................................Failed
- hook id: flake8
- exit code: 1

src/pytestshellutils/shell.py:327:1: D417 Missing argument descriptions in the docstring

[s0undt3ch]

Ok, so, it's explicitly only using shor_desc .... Why not the message attribute?

In my case, that seems to be the root cause for now showing what arguments are missing

[asottile]

@s0undt3ch I appreciate you trying to help but we've already come to that above and have a reason why message is problematic

[s0undt3ch]

Is the : problematic because of programmatically parsing flake8 output?
Anyway, don't know the whole code base to better form an opinion/solution.

[s0undt3ch]

We should create(yet another) open standard for linter messages 🤣

[asottile]

I mean there is flake8's standard which is CODE ASCII_SPACE MESSAGE that's why pydocstyle's (.message) CODE COLON SPACE MESSAGE does not work -- that's the whole point of the issue