materials/documenting-python-code/docstring_formats.py at e459b5ef399ffc968ccb8aa2868bed4e360ace18 · realpython/materials · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
"""The same function documented in four common docstring formats.

Compare the output of help() on each function to see how the Google,
reStructuredText, NumPy/SciPy, and Epytext formats look.
"""

import pandas as pd


def get_spreadsheet_cols_google(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Args:
        file_loc (str): The file location of the spreadsheet
        print_cols (bool): A flag used to print the columns to the console
            (default is False)

    Returns:
        list: a list of strings representing the header columns
    """

    if file_loc.lower().endswith(".csv"):
        file_data = pd.read_csv(file_loc)
    else:
        file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def get_spreadsheet_cols_rest(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    :param file_loc: The file location of the spreadsheet
    :type file_loc: str
    :param print_cols: A flag used to print the columns to the console
        (default is False)
    :type print_cols: bool
    :returns: a list of strings representing the header columns
    :rtype: list
    """

    if file_loc.lower().endswith(".csv"):
        file_data = pd.read_csv(file_loc)
    else:
        file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def get_spreadsheet_cols_numpy(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Parameters
    ----------
    file_loc : str
        The file location of the spreadsheet
    print_cols : bool, optional
        A flag used to print the columns to the console (default is False)

    Returns
    -------
    list
        a list of strings representing the header columns
    """

    if file_loc.lower().endswith(".csv"):
        file_data = pd.read_csv(file_loc)
    else:
        file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def get_spreadsheet_cols_epytext(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    @type file_loc: str
    @param file_loc: The file location of the spreadsheet
    @type print_cols: bool
    @param print_cols: A flag used to print the columns to the console
        (default is False)
    @rtype: list
    @returns: a list of strings representing the header columns
    """

    if file_loc.lower().endswith(".csv"):
        file_data = pd.read_csv(file_loc)
    else:
        file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


if __name__ == "__main__":
    for func in (
        get_spreadsheet_cols_google,
        get_spreadsheet_cols_rest,
        get_spreadsheet_cols_numpy,
        get_spreadsheet_cols_epytext,
    ):
        print(f"--- {func.__name__} ---")
        print(func.__doc__)