rr-/docstring_parser

Fails to parse google style when ",optional" in docstring.

rob-blackbourn opened this issue · 7 comments

rob-blackbourn commented

Hi,

Great project!

The following docstring fails to find the type for arg4 and arg5:

    text = """A mock function

    A function to use in tests

    Args:
        arg1 (str): The first arg
        arg2 (List[int]): The second arg
        arg3 (datetime): The third arg
        arg4 (Optional[Decimal], optional): The fourth arg. Defaults to Decimal('1').
        arg5 (Optional[float], optional): The fifth arg. Defaults to None.

    Raises:
        ValueError: It doesn't actually raise this error

    Returns:
        Dict[str, Any]: The args as a dictionary
    """

This can be fixed by changing line 102 of google.py from

        m = re.match(r"(\S+) \((\S+)\)$", before)

to

        m = re.match(r"\s*(.+?)\s*\(\s*(.*[^\s]+)\s*\)", before)

Rob

rr- commented

Hi, could you link to example where this kind of documentation is used, and how you'd like it to be parsed? Cause as-is, type_name contains a literal string Optional[float], optional which I don't think will be very useful.

rob-blackbourn commented

I agree it's weird.

The example I gave was autogenerated by the VSCode autoDocstring extension. The ",optional" appears whenever the default argument "= None" is applied.

I can't find a formal grammar for Google docstring, but the sphinx napoleon docstring extension has some examples here. This is where a stole the regex :-O

I'm not sure how it should be parsed. My current problem is that the argument name can't be identified (it returns "arg4 (Optional[Decimal], optional)"), so I miss the description. One possibility would be to add another property to the DocstringParam class `is_optional', but you would want this to be consistent with other docstring formats, which might not be possible.

rr- commented

Added basic support for , optional on master as well as a couple of changes inspired by yours, lmk if it works for you

For ReST I fill is_optional by checking if it ends with ? :–] like str?. On second there is also Optional[str] which I haven't added support for… Maybe I overdid it after all and type_name should be opaque. Please let me know your thoughts.

rob-blackbourn commented

Perfect!

Can you publish to pypi?

rr- commented

Released as 0.5

rob-blackbourn commented

Thank you :)

rob-blackbourn commented

FYI I'm using docstring-parser for a REST framework. Just done my first pre-release version.