如何在Python类型提示中为参数指定多个字符串选项

方法一：类型提示+运行时校验 #

你写的Union['image', 'video']只是静态类型提示，不会在运行时限制参数值，必须补充运行时校验逻辑才能真正拦截非法输入：

from typing import Union
import pandas as pd

class YourClass:
    def get_all_creatives_from_accounts(self, 
                                        accounts=None,
                                        kind: Union['image', 'video'] = "video",
                                        limit_per_page=100) -> pd.DataFrame:
        # 校验参数是否在允许范围内
        if kind not in ('image', 'video'):
            raise ValueError(f"kind参数只能是'image'或'video'，你传入的是{kind}")
        # 后续业务逻辑编写
        # ...
        return pd.DataFrame()

这种方式兼顾了IDE的静态提示能力和运行时的参数合法性检查，简单直接。

方法二：使用枚举类（更规范的复用方案） #

如果该参数的可选值需要在多处复用，用枚举类管理更清晰，还能避免硬编码字符串带来的错误：

from enum import Enum
import pandas as pd

class CreativeKind(Enum):
    IMAGE = 'image'
    VIDEO = 'video'

class YourClass:
    def get_all_creatives_from_accounts(self, 
                                        accounts=None,
                                        kind: CreativeKind = CreativeKind.VIDEO,
                                        limit_per_page=100) -> pd.DataFrame:
        # 如需使用字符串值，通过kind.value获取
        kind_str = kind.value
        # 后续业务逻辑编写
        # ...
        return pd.DataFrame()

调用时直接传入枚举成员即可：

obj = YourClass()
obj.get_all_creatives_from_accounts(kind=CreativeKind.IMAGE)

如果需要兼容字符串输入，可以加一层转换逻辑：

from typing import Union

def get_all_creatives_from_accounts(self, 
                                    accounts=None,
                                    kind: Union[CreativeKind, str] = CreativeKind.VIDEO,
                                    limit_per_page=100) -> pd.DataFrame:
    if isinstance(kind, str):
        try:
            kind = CreativeKind(kind)
        except ValueError:
            raise ValueError(f"kind参数只能是'image'或'video'，你传入的是{kind}")
    kind_str = kind.value
    # ...

方法三：使用typing.Literal（Python 3.8+） #

用Literal可以更精准地标注可选的字符串值，配合运行时检查使用：

from typing import Literal
import pandas as pd

class YourClass:
    def get_all_creatives_from_accounts(self, 
                                        accounts=None,
                                        kind: Literal['image', 'video'] = "video",
                                        limit_per_page=100) -> pd.DataFrame:
        if kind not in ('image', 'video'):
            raise ValueError(f"kind参数只能是'image'或'video'，你传入的是{kind}")
        # ...
        return pd.DataFrame()

Literal比Union的提示更精准，IDE会直接显示允许的字符串选项，但同样需要运行时校验来保证参数合法性。

内容的提问来源于stack exchange，提问作者Fernando Jesus Garcia Hipola