Pylint: W9006: missing-raises-doc false positive when declaring multiple exceptions in SphinxDocstring

[StephenBrown2]

Steps to reproduce

Using load-plugins=pylint.extensions.docparams

1. Create a function which potentially raises multiple Exceptions:

def function_name(args):
    if isinstance(args, dict):
        raise TypeError
    elif isinstance(args, str):
        raise ValueError
    else:
        raise ValidationError

1. Document such functionality as :raises TypeError, ValueError, ValidationError

    """ A function that raises exceptions

    :param args: The arguments
    :type args: int

    :raises TypeError, ValueError, ValidationError:
    """

1. Get [W9006(missing-raises-doc), function_name] "ValueError" not documented as being raised, et al.

Full test file:

#!/usr/bin/env python3

class ValidationError(Exception):
    pass

def function_name(args):
    """ A function that raises exceptions

    :param args: The arguments
    :type args: int

    :raises TypeError, ValueError, ValidationError:
    """
    if isinstance(args, dict):
        raise TypeError
    elif isinstance(args, str):
        raise ValueError
    else:
        raise ValidationError

Current behavior

************* Module test_raises
test_raises.py:6: [W9006(missing-raises-doc), function_name] "TypeError" not documented as being raised
test_raises.py:6: [W9006(missing-raises-doc), function_name] "ValueError" not documented as being raised
test_raises.py:6: [W9006(missing-raises-doc), function_name] "ValidationError" not documented as being raised

Expected behavior

pylint passes / Your code has been rated at 10.00/10

pylint --version output

$ pylint --version
pylint 2.2.2
astroid 2.1.0
Python 3.7.2 (default, Jan 10 2019, 23:51:51)
[GCC 8.2.1 20181127]

Notes

Sphinx properly parses the Exception types raised and links them individually, so I believe only a small change would be needed in the regex here and parsing of such here to allow for comma+whitespace (, *) separated types.

[PCManticore]

Thanks for reporting the issue @StephenBrown2 This could definitely be supported.

[gaurikholkar]

Hi, I'd like to take this up!

[PCManticore]

Hey @gaurikholkar Sure thing! @StephenBrown2 left some indications regarding what needs to be modified and where. Let me know if there's anything else you might need before tackling this issue.

[gaurikholkar]

hi @PCManticore, got a little busy with work. Will try to get this done in a day or two!

[sebastianmika]

Hi - any update on this really slightly annoying issue @gaurikholkar? If not I would spend some time trying to fix it - it is in my way :-)

[gaurikholkar]

@sebastianmika giving it a try now

[gaurikholkar]

@StephenBrown2, I'm unsure about the regex pattern here. Could you maybe give me pointers regarding the same?

Should the expression here

re_raise_raw = r"""
        :                       # initial colon
        (?:                     # Sphinx keyword
        raises?|
        except|exception
        )
        \s+                     # whitespace
        (?:                     # type declaration
        ({type})
        \s+
        )?
        (\w+)                   # Parameter name
        \s*                     # whitespace
        :                       # final colon
        """.format(
        type=re_type

be

re_raise_raw = r"""
        :                       # initial colon
        (?:                     # Sphinx keyword
        raises?|
        except|exception
        )
        \s+                     # whitespace
        (?:                     # type declaration
        ({type},\s})+|({type})
        \s+
        )?
        (\w+)                   # Parameter name
        \s*                     # whitespace
        :                       # final colon
        """.format(
        type=re_type

[StephenBrown2]

That's about where I got stuck too. I believe that would probably work or at least be a good start. I would say to try by writing a test case using the Steps to Reproduce in the OP, and tweak until it passes. Sorry I can't be of more help with that!