python - 类型注释 Pandas DataFrame

Question

如果函数或方法返回 Pandas DataFrame，您如何记录列名和列类型？有没有办法在 Python 的内置类型注释中执行此操作，还是您只使用文档字符串？

如果您只使用文档字符串，您如何格式化它们以尽可能简洁？

Answer 1

文档字符串格式

我使用 numpy docstring公约作为基础。如果函数的输入参数或返回参数是具有预定列 的 pandas 数据框，那么我将添加一个 reStructuredText 样式 table带有参数描述的列描述。例如:

def random_dataframe(no_rows):
    """Return dataframe with random data.

    Parameters
    ----------
    no_rows : int
        Desired number of data rows.

    Returns
    -------
    pd.DataFrame
        Dataframe with with randomly selected values. Data columns are as follows:

        ==========  ==============================================================
        rand_int    randomly chosen whole numbers (as `int`)
        rand_float  randomly chosen numbers with decimal parts (as `float`)
        rand_color  randomly chosen colors (as `str`)
        rand_bird   randomly chosen birds (as `str`)
        ==========  ==============================================================

    """
    df = pd.DataFrame({
        "rand_int": np.random.randint(0, 100, no_rows),
        "rand_float": np.random.rand(no_rows),
        "rand_color": np.random.choice(['green', 'red', 'blue', 'yellow'], no_rows),
        "rand_bird": np.random.choice(['kiwi', 'duck', 'owl', 'parrot'], no_rows),
    })

    return df

奖励:sphinx 兼容性

上述文档字符串格式与 sphinx autodoc 兼容文档生成器。这是 sphinx 自动生成的 HTML 文档中的文档字符串的样子(使用 nature 主题):