Using type aliases in docstrings

Question

Is there a best practice for using type aliases or typing objects in docstrings?

This question might attract opinion based answers. But it could also be that there is a widely accepted convention or external tool support for a particular solution.

Related question

---

Example: a function returns a dictionary with string keys and values. What type would you put into the docstring under the "Returns" section? (I am using pandas style docstrings.)

Option 1: just say it's a dict.

import typing

strstrdict = typing.Dict[str, str]

def foo() -> strstrdict:
    '''
    bla bla

    Returns
    -------
    dict
        A dictionary with string keys and values that represents ...
    '''
    # code

Option 2: use a type alias.

import typing

strstrdict = typing.Dict[str, str]

def foo() -> strstrdict:
    '''
    bla bla

    Returns
    -------
    strstrdict
        A dictionary with string keys and values that represents ...
    '''
    # code

Option 3: put "typing.Dict[str, str]" into the docstring.

import typing

strstrdict = typing.Dict[str, str]

def foo() -> strstrdict:
    '''
    bla bla

    Returns
    -------
    typing.Dict[str, str]
        A dictionary with string keys and values that represents ...
    '''
    # code

Option 4: something else?

EDIT 1

"I am using pandas style docstrings" Are you looking for answer for just this style or in general?

I guess the optimal answer would cover the general and specific case as much as possible. I mentioned the pandas style to make clear why there is a "Returns" section and no instructions like ":param:". I'm not dead set on the style with respect to an answer.

Do you actually include the aliases in your documentation, i.e. can users discover what the alias strstrdict is?

Currently there's no documentation for the alias. The user could view themodule.strstrdict. I'm open to suggestions here.

EDIT 2

The style guide I linked to coincidentally mentions a dict with string keys and values. The answer I am looking for should also cover cases like this:

from typing import Any, Callable, ContextManager, Iterable

ContextCallables = ContextManager[Iterable[Callable[[int, int], Any]]]

def foo() -> ContextCallabes:
    '''
    bla bla

    Returns
    -------
    ???
           some description
    '''
    # code

Answer 1

Since you explicitly mentioned the doc-style convention that you are following, there shouldn't be an issue with opinion-based answers.

We can check the pandas docstring guide section about parameter types:

For complex types, define the subtypes. For dict and tuple, as more than one type is present, we use the brackets to help read the type (curly brackets for dict and normal brackets for tuple).

This means you should document the Dict[str, str] as follows:

Returns
-------
dict of {str : str}
    Some explanation here ...

You can check the docs for more examples, including other types.