Python中能否仅声明函数重载间变化的参数？

针对你遇到的重载函数重复声明公共参数的问题，有几种实用方式可以减少代码冗余，同时保持类型检查的准确性：

1. 使用类型别名复用类型定义 #

将重复的参数类型、返回类型定义成类型别名，修改时只需更新别名，无需逐个修改重载：

from typing import overload, Literal, TypeAlias
from enum import Enum

class ReturnType(Enum):
    NONE = 1
    SCALAR = 2
    VECTOR = 3

# 复用参数类型
SqlParam: TypeAlias = str
LogQueryParam: TypeAlias = bool

# 复用返回类型
ScalarResult: TypeAlias = int | float | bool | str
VectorResult: TypeAlias = list[ScalarResult]

@overload
def perform_query(
    sql: SqlParam, return_type: Literal[ReturnType.NONE], log_query: LogQueryParam = ...
) -> None: ...

@overload
def perform_query(
    sql: SqlParam, return_type: Literal[ReturnType.SCALAR], log_query: LogQueryParam = ...
) -> ScalarResult: ...

@overload
def perform_query(
    sql: SqlParam, return_type: Literal[ReturnType.VECTOR], log_query: LogQueryParam = ...
) -> VectorResult: ...

def perform_query(
    sql: SqlParam, return_type: ReturnType, log_query: LogQueryParam = False
):
    pass

2. 使用ParamSpec提取公共参数（Python 3.10+） #

利用ParamSpec将公共参数的签名提取出来，结合TypeVar关联返回类型，进一步简化重载的参数声明：

from typing import overload, Literal, ParamSpec, TypeVar
from enum import Enum

class ReturnType(Enum):
    NONE = 1
    SCALAR = 2
    VECTOR = 3

# 定义公共参数的签名
P = ParamSpec('P')
# 定义关联返回类型的TypeVar
R = TypeVar('R', None, int | float | bool | str, list[int | float | bool | str])

@overload
def perform_query(
    sql: str, log_query: bool = ..., return_type: Literal[ReturnType.NONE]
) -> None: ...

@overload
def perform_query(
    sql: str, log_query: bool = ..., return_type: Literal[ReturnType.SCALAR]
) -> int | float | bool | str: ...

@overload
def perform_query(
    sql: str, log_query: bool = ..., return_type: Literal[ReturnType.VECTOR]
) -> list[int | float | bool | str]: ...

def perform_query(
    sql: str, return_type: ReturnType, log_query: bool = False
):
    pass

注：这种写法将公共参数前置，通过ParamSpec统一管理，部分类型检查工具（如mypy）需开启对应配置以支持完整推断。

3. 编辑器重构工具辅助 #

如果仅担心参数名修改的维护成本，可利用编辑器的批量重构功能（如PyCharm、VS Code的重命名功能），只需修改一次参数名，所有重载中的对应参数会自动更新，无需手动逐个调整。

目前Python标准库的重载语法无法完全避免参数名的重复声明，但通过上述方法可大幅降低代码冗余和维护成本。

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