如何为Pandas DataFrame及自定义类添加Python函数注解？

1. 第三方类的类型注解 #

直接引用（常规操作） #

只要你已经导入了目标类，直接把类名写在注解位置即可，完全符合PEP规范。以你的_columns_calculator方法为例：

import pandas as pd
from pylatex import Document

class LaTeXTableGenerator:
    @classmethod
    def _columns_calculator(cls, df: pd.DataFrame) -> str:
        """根据DataFrame列数生成LaTeX表格格式字符串（如'cccc'）
        
        Args:
            df: 用于计算列数的pandas DataFrame对象
            
        Returns:
            对应列数的'c'拼接字符串
        """
        return 'c' * len(df.columns)

# 普通函数示例（PyLaTeX Document类注解）
def set_doc_title(doc: Document, title: str) -> None:
    doc.append(title)

延迟引用（解决导入问题） #

如果遇到循环导入，或者不想提前加载第三方库，有两种方式：

• 用字符串包裹类名（PEP 484支持）：

class LaTeXTableGenerator:
    @classmethod
    def _columns_calculator(cls, df: "pd.DataFrame") -> str:
        import pandas as pd  # 可在方法内延迟导入
        return 'c' * len(df.columns)

• 导入from __future__ import annotations（Python 3.7+），所有注解会被当作字符串处理，运行时才解析：

from __future__ import annotations
import pandas as pd
from pylatex import Document

class LaTeXTableGenerator:
    @classmethod
    def _columns_calculator(cls, df: pd.DataFrame) -> str:
        return 'c' * len(df.columns)

2. 自定义类的类型注解 #

同文件内的自定义类 #

直接用类名就行；如果类定义在方法/函数之后，同样可以用上述的annotations导入或字符串形式：

from __future__ import annotations

class CustomDoc:
    pass

def process_doc(doc: CustomDoc) -> None:
    pass

# 类定义在函数后的场景
def create_doc() -> CustomDoc:
    return CustomDoc()

class CustomDoc:
    pass

跨文件的自定义类 #

从对应模块导入类后直接使用：

from my_modules import CustomDoc

def handle_doc(doc: CustomDoc) -> None:
    pass

3. 符合PEP规范的细节 #

• PEP 257：文档字符串不用重复注解的类型信息，但可以补充额外要求（比如df需包含有效列）。
• PEP 8：注解和参数间留一个空格，返回箭头->前后各留一个空格，比如df: pd.DataFrame -> str。
• PEP 3107：类型注解仅做提示，不影响运行，但可以用mypy工具做静态检查，提前发现类型错误。

内容的提问来源于stack exchange，提问作者piJT