"Raises:" section exception name format

[raddessi]

Hi! First off, I love this linter so thank you for the work on it. FYI I actually just set up a plugin for SublimeText integration here. On to the actual question:

Do you know of a formal style for exception names in the Raises section of the docstrings in the google style guide? When using a builtin exception I use the normal style of:

Raises:
    BuiltinException: blah

But when I have a function that raises some nonstandard exception class (sometimes which is in a 3rd party module) I usually use the full path to the exception since there may be duplicates in various modules and clarity in docs is nice imo. IE:

Raises: 
    foo.bar.SomeOtherException: blah

I'm really not sure if this goes against the official style guide, the docs ive seen seem to be a little unclear there. If it doesn't go around it, how would you feel about adding functionality to match a raise SomeOtherException to the foo.bar.SomeOtherException declaration? I don't mind sending a PR but I just want to check first. Thanks

[terrencepreilly]

FYI I actually just set up a plugin for SublimeText integration here.

Ah, cool! I'll make sure to add this to the readme so that others can find it more easily.

I'm not aware of any formal style for exception names. To be honest, I don't believe Google ever intended for their docstring style to be parsed, so I don't think there is anything very formally specified. Every example I've ever seen in official documentation just uses the class name, and not the path.

Being able to include the full path does in fact sound like a good idea, though. (Especially if the exception is raised in some called function, and isn't imported into the current package.)

If you'd like to submit a pull request, feel free. Just let me know if you need any help. I'm currently working on refactoring some uglier parts of darglint before handling style errors a little more gracefully, but that shouldn't conflict with this.

[raddessi]

Yeah I'd buy that they never intended it. They are pretty loose on the actual definitions in most cases, only giving examples. I'm glad to hear having the full path to the exception makes sense to somebody else though, at least in some specific use cases. I'll try to set something up when I get time but that comes and goes. Have a great week!

[smithfred]

I'd argue for support for exception name format(s) that would be valid names in the function/method:

So for the former:

from foo import bar
import baz
from qux import QuxError


def stuff(...) -> ...:
    """Do stuff.

    Raises:
        bar.BarError: ...
        baz.baz2.BazError: ...
        QuxError: ...

    """
    ...