Python 字典 output 的文档字符串文档

Question

What is the recommended way to document a dictionary (dict) output in python docstring for a function?

I was looking at a few tutorials including this from datacamp but I can't seem to find a good example.

def example_function(arg1: str, arg2: list) -> dict(str, dict):
    '''
    Returns a dictionary of examples

    Args:
        arg1(str): description of argument 1
        arg2(list): description of argument 2

    Returns:
        dict(str, dict): dictionary of examples
        <example of output>

For instance, I want to show that the output of the above function has the following structure, where key1 and key2 will always be in the output

{
    "example": {
        "key1": "value1",
        "key2": "value2"
    }
}

Thank you in advance, would be great if I could have some reference links as well: :)

Answer 1

First note that this is not called "docstring documentation" but "type hints".
This is exactly what you want: https://www.python.org/dev/peps/pep-0589/ (This PEP is accepted as of Python 3.8)
Further reading: the typing module: https://docs.python.org/3/library/typing.html
This is an example code snippet:

from typing import TypedDict

class ExampleDataDict(TypedDict):
    key1: str
    key2: str

class ExampleDict(TypedDict):
    example: ExampleDataDict

d: ExampleDict = {
    "example": {
        "key1": "value1",
        "key2": "value2"
    }
}