Python静态方法多返回类型的类型提示写法及最佳实践咨询

一、正确的返回类型提示写法 #

你之前用or标注返回类型的写法是错误的，Python类型提示不支持这种语法。要实现「根据参数值返回不同类型」的类型注解，需要结合@overload装饰器和Literal类型，让类型检查器能识别参数值对应的返回类型：

Python 3.10+ 简洁写法 #

from typing import overload, Literal
import pandas as pd
import numpy as np
from typing import List, Tuple

class BatterySimulation:
    @staticmethod
    @overload
    def transform_schedule(
        schedule: List[dict],
        time_step: int,
        offset_power: pd.DataFrame,
        internal_use: Literal[True]
    ) -> Tuple[pd.DataFrame, np.array]:
        ...  # 仅签名，无实现

    @staticmethod
    @overload
    def transform_schedule(
        schedule: List[dict],
        time_step: int,
        offset_power: pd.DataFrame,
        internal_use: Literal[False] = ...
    ) -> pd.DataFrame:
        ...  # 仅签名，无实现

    @staticmethod
    def transform_schedule(
        schedule: List[dict],
        time_step: int,
        offset_power: pd.DataFrame,
        internal_use: bool = True
    ):
        # 实际业务逻辑实现
        if internal_use:
            return pd.DataFrame(), np.array([])
        else:
            return pd.DataFrame()

兼容Python 3.9及以下版本的写法 #

如果你的项目还在使用旧版本Python，需要用Union替代|，且Literal需要从typing_extensions库导入：

from typing import overload, Union, Tuple, List
from typing_extensions import Literal
import pandas as pd
import numpy as np

class BatterySimulation:
    @staticmethod
    @overload
    def transform_schedule(
        schedule: List[dict],
        time_step: int,
        offset_power: pd.DataFrame,
        internal_use: Literal[True]
    ) -> Tuple[pd.DataFrame, np.array]:
        ...

    @staticmethod
    @overload
    def transform_schedule(
        schedule: List[dict],
        time_step: int,
        offset_power: pd.DataFrame,
        internal_use: Literal[False] = ...
    ) -> pd.DataFrame:
        ...

    @staticmethod
    def transform_schedule(
        schedule: List[dict],
        time_step: int,
        offset_power: pd.DataFrame,
        internal_use: bool = True
    ):
        # 实际业务逻辑实现
        if internal_use:
            return pd.DataFrame(), np.array([])
        else:
            return pd.DataFrame()

二、这种根据参数返回不同类型的写法是否属于不良实践？ #

分场景判断：

• 可接受的场景：如果internal_use仅作为内部调用的开关，对外暴露的API明确说明外部调用时必须传False，且这么做是为了避免重复计算（比如内部需要复用中间生成的数组，外部不需要），这种写法有一定合理性。
• 不推荐的场景：如果这个方法同时对外暴露，很容易让外部调用者困惑——传不同布尔值得到完全不同的返回结构，会增加调用代码的复杂度，还容易引发类型错误。

更优的替代方案：

1. 拆分方法：把内部逻辑和对外逻辑拆成两个独立方法，比如_transform_schedule_internal（返回元组，仅内部调用）和transform_schedule（返回DataFrame，对外暴露），公共逻辑抽成私有辅助函数。
2. 统一返回结构：如果一定要保留单个方法，可以把额外的数组作为可选返回值，比如返回Tuple[pd.DataFrame, Optional[np.array]]，无论internal_use取值如何，返回结构一致，只是第二个值在外部调用时为None。

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