[Malcolmlisk]

You can do that as a docstring inside the function. There are even some basic rules like...

def extract_coordiates( unreseted_idx_from_df, json_data: dict, notna_idxs: list, na_idxs: list ) -> list:

    """
    Extracting coordinates from the json_data['data'] and returning the 4
    positions of those as an array

    Parameters
    ----------
    json_data: json
        Data extracted from tabula.read_pdf and using output_format='json'
    notna_idxs: list
        List of id's from the dataframe that ha no na values.
    na_idxs: list
        List of id's from the dataframe with na

    Returns
    -------
    List of tuple coordinates:
        [(1, 2), (2, 2), (4, 3), (1, 4)]
    """

Thing is, that you may want to get fast information in the linter with this type hinting. If you need to read the documentation on big functions over and over, that means that's not clear at all, and having basic type hinting while typing the atributes is going to be clearer.

You are right, that some docstrings are necesary. But that does not mean that is the best practice. The best practice is use both, type hinting and docstrings.

[zokier]

I think you misinterpreted parent comment. My reading was that they would have preferred type-hints to be defined as part of docstring style comments instead of having the type hints inline with the code. From tooling point of view it doesn't make any difference, both forms should be functionally equivalent.

[nerdponx]

Sphinx does process type hints in docstring comments, but I'm grateful that Mypy didn't take the approach of requiring a docstring.