CODEWITHSUNDEEP
pythonsyntaxdocstring
vlad-ardelean
vlad-ardelean

Reputation: 7622

I've been using this docstring syntax for 2 years now, what's it called, who specifies it, and is it "ok" to use it?

I've been using this weird syntax for a long time now, and am getting quite good at it. It's like taking the good part about java, and having that in Python. It's awesome, I like it, my IDE even caught some bugs because of the annotations.

I don't know however who specified this syntax, how official it is, and I don't know the exact rules for it.

Admittedly, I'm using PyCharm, but I don't know if this would work in other IDEs, or if it's just PyCharm syntax - I don'w want to think it is, and I'd like to use a docstring syntax that works for other tools as well.

Moreover, I see the amazon people using this kind of syntax in their python library boto: https://github.com/boto/boto/blob/develop/boto/beanstalk/layer1.py#L83

Here's an example of the syntax.

def asdf(name, descriptions, weird_dict):
    """
    :type weird_dict: dict[tuple[str|None],list[dict[int,str]|MyClass]]
    :param weird_dict: description description

    :type name: str
    :param list[str] descriptions: Description and type annotation

    :param str name: Here I declared the "suggested" type, and can also describe the param

    :return:  Here I just describe what's returned
    :rtype: int
    """

Please tell me, if anyone knows, what is the name of this syntax, who specifies it, and how I can find more info about it, because I tried a few times and just ended up on the PyCharm site.

Upvotes: 2

Views: 154

Answers (1)

Cory Kramer
Cory Kramer

Reputation: 117856

That is reStructuredText Docstring Format as specified by PEP 287

PyCharm also has the following docstring formats under the Python Integrated Tools settings

Upvotes: 2

Related Questions