CODEWITHSUNDEEP
pythonpycharmpydoc
Martin Melka
Martin Melka

Reputation: 7789

How to denote return type tuple in Google-style Pydoc for Pycharm?

In Pycharm I want to have a documented function that returns a tuple so that I can get code completion on it. The style of comments is Google-style.

This works correctly:

def func():
    """

    Returns:
        str: something

    """
    pass

Typing func(). correctly shows methods for str.

However, typing this does not work anymore:

def func():
    """

    Returns:
        (int, str): something

    """
    pass

a, b = func()

Typing b. does not offer anything.

I know that PyCharm is capable of parsing tuples, because this code works:

def func():
    """

    :rtype: (int, str)
    """
    pass

a, b = func()

However, this is not according to the Google style.

How do I document a function according to the standard so that Pycharm will pick up on the return types?

Upvotes: 19

Views: 8131

Answers (5)

Jaden Taylor
Jaden Taylor

Reputation: 13

Here's an example of what I might use. You can adapt the same style if you wish.

def getChildren(fs, pid: str, pidJson: dict = {}):
    """Gets the children pids of a pid.

    Args:
        fs (FamilySearch.FamilySearch): the object to interact with Family Search through
        pid (str): the id of the person to get the parents for
        pidJson (dict): the json object returned from Family Search
    Returns:
        NamedTuple: values(pid (str), children (list))
            pid (str): the original pid passed in
            children (list): the children of the pid passed in
    """

Upvotes: 0

Talendar
Talendar

Reputation: 2087

Here is how I'd do it:

from typing import Tuple

def func() -> Tuple[int, str]:
    """ (...)

    Returns:
        A tuple containing, respectively, an int (<meaning of the
        returned int>) and a string (<meaning of the returned string>).
    """

PyCharm (and Sphinx, if you're using it to parse your docstrings) will correctly know the return type of your function and you'll have a clean and nice description of the function's return value.

Upvotes: 5

JGC
JGC

Reputation: 6363

If your main goal is to achieve auto-completion in PyCharm I would suggest using type hinting on the function definition (Tuple[int, str]).

from typing import Tuple

def func() -> Tuple[int, str]:
    """

    :rtype: (int, str)
    """
    pass

a, b = func()

I know your question is about how to achieve this through the docstring, but my strong recommendation is to make use of type hinting since it will allow tools like mypy to validate your code (something that can't be done with docstrings - Can mypy check docstrings?).

I am not saying you shouldn't also include types in docstrings, just that your IDE is more likely to support static type hinting, and static type hinting allows you to use a greater degree of granularity in your definitions.

Upvotes: 0

Scott P.
Scott P.

Reputation: 1074

Would the type hints as specified by PEP 484 not be valid?

Python 3 docs for typing module

Python PEP 484

from typing import Tuple

def func():
    """

    :rtype: Tuple[int, str]
    """
    pass

a, b = func()

Upvotes: 2

Darth_Sourav
Darth_Sourav

Reputation: 116

from doc pages of sphinxcontrib

The Returns section supports any reStructuredText formatting,
including literal blocks::

        {
            'param1': param1,
            'param2': param2
        }

Documentation

this says that Google style supports the reStructuredText formatting inside, and using below format returns me the tuple autocomplete options.

def func():
    """

    Returns:
        :rtype: (int, str)

    """
    pass

a, b = func()

can this be the solution you were looking for?

Upvotes: 0

Related Questions