Complains about newline between list of Args and Returns

[kannes]

Complains about newline between list of Args and Returns. https://github.com/google/styleguide/blob/gh-pages/pyguide.md#383-functions-and-methods has an example that is structured like this.

def f(x):
    """summary

    more text
    here
    yeeeee

    Args:
        x: something

    Returns:
        something else
    """
    pass

$ darglint -v 2 /tmp/d.py 
/tmp/d.py:f:10: S001: Syntax error: s Unable to parse word: expected TokenType.WORD but received TokenType.NEWLINE

PS: Thanks for this awesome tool!

[terrencepreilly]

Good catch. I think that in your example the problem is with the whitespace. Darglint sees 8 spaces after x:something, and it thinks that the Args section is going to have another variable, but instead it sees a newline.

I think there's something else going on with the example docstring you linked to. I'll try to look into it this weekend.

This should be pretty easy to fix. Thanks for submitting it!

[kannes]

Sweet!

I did test the other docstring (from Google) but the only messages I got made sense as darglint detected the "returns" and "raises" in the docstring with no matching code in the body of the (non-existant) function. At least that's how I understood it.

[terrencepreilly]

Okay, this issue should be resolved as of version 0.5.1. You were right about the example docstring, everything was parsing correctly with that.

[kannes]

Now it allows multiple blank lines between Args and Returns though. But looking at Google's guide I found no rules on this at all, only the example itself. Not sure if this should be allowed. Personally I don't like it but hmmmm.. Testcase below.

def f(a):
    """summary

    more text

    Args:
        a: a value

    Returns:
        well fed
    """
    return "yummyumm"

[terrencepreilly]

I agree that it looks bad. The stylistic error support in darglint is a little lacking at the moment. Ideally, I'd like to have different levels of strictness (lenient by default). Then an error would be raised for something like your example above, if the user has set strict mode for their project.

The roadmap currently just has "Add style errors and suggestions" in it. I'll add a more detailed description including this extra-spaces problem, and a settings option.

It might be a little while until I get to it, because it could require rewriting a portion of the parser. (Changing it to a GLR parser, and accumulating stylistic warnings as parsing fails.)