Proper Google docstring for lists

Question

I've been using the Google Docstring format described here but I'm wondering if there is an agreed upon method for documenting lists of a known type.

I've been using

def function(a_list)
    """

    Args:
        a_list (list[dict]): a list of dictionaries
    """
    ...

Is this correct?

I don't know about that particular format, but a common way to indicate a list is `type[]`. For what it's worth, it doesn't look like the actual google style guide encourages use of types in that format, but rather just a plain english indication of the type http://google.github.io/styleguide/pyguide.html?showone=Comments#Comments — CollinD, Nov 04 '16 at 22:34

score 3 · Accepted Answer · answered Apr 03 '20 at 20:51

3

Given the advances in type hinting that didn't exist when I first asked this question I would now defer to that style:

from typing import List

def function(a_list: List[dict])
    """

    Args:
        a_list (List[dict]): a list of dictionaries
    """
    ...

answered Apr 03 '20 at 20:51

Eric Blum

I would like to also note that as of python 3.9, one can use `list[dict]` instead of importing the `List` type from `typing` and using that – Eric Blum Apr 03 '23 at 18:01

1 Answers1