Python 中的函数签名：详解与实例

函数签名（Function Signature）在 Python 中是对函数调用接口的结构化描述，它定义了函数接收参数的方式、类型提示以及返回值信息。Python 的函数签名具有灵活性，不强制参数类型，但能清晰展示函数的使用规则。

一、函数签名的核心组成

Python 函数签名主要包含以下要素：

函数名称
参数列表（名称、类型注解、默认值、参数种类）
返回值注解

我们可以使用标准库 inspect 模块的 signature() 函数来查看和分析函数签名。

二、不同类型的函数签名实例

1. 基础函数签名

最基本的函数签名包含必选参数和类型注解：

import inspect

def add(a: int, b: int) -> int:
    return a + b

# 获取函数签名
sig = inspect.signature(add)
print(f"函数签名: {sig}")  # 输出: (a: int, b: int) -> int

# 分析参数
for param in sig.parameters.values():
    print(f"参数名: {param.name}, 类型: {param.annotation}, 种类: {param.kind}")

输出：

函数签名: (a: int, b: int) -> int
参数名: a, 类型: <class 'int'>, 种类: POSITIONAL_OR_KEYWORD
参数名: b, 类型: <class 'int'>, 种类: POSITIONAL_OR_KEYWORD

2. 包含默认值的函数签名

当参数有默认值时，签名会明确标示：

def greet(name: str, greeting: str = "Hello") -> str:
    return f"{greeting}, {name}!"

sig = inspect.signature(greet)
print(f"函数签名: {sig}")  # 输出: (name: str, greeting: str = 'Hello') -> str

for param in sig.parameters.values():
    print(f"参数名: {param.name}, 默认值: {param.default if param.default is not inspect.Parameter.empty else '无'}")

输出：

函数签名: (name: str, greeting: str = 'Hello') -> str
参数名: name, 默认值: 无
参数名: greeting, 默认值: Hello

3. 包含可变参数的函数签名

*args 和 **kwargs 会在签名中特殊标示：

def sum_numbers(*args: int, multiplier: int = 1) -> int:
    return sum(args) * multiplier

sig = inspect.signature(sum_numbers)
print(f"函数签名: {sig}")  # 输出: (*args: int, multiplier: int = 1) -> int

for param in sig.parameters.values():
    print(f"参数名: {param.name}, 种类: {param.kind}")

输出：

函数签名: (*args: int, multiplier: int = 1) -> int
参数名: args, 种类: VAR_POSITIONAL
参数名: multiplier, 种类: KEYWORD_ONLY

4. 关键字-only 参数的函数签名

使用 * 分隔符可以定义关键字-only 参数：

def create_user(name: str, *, age: int, email: str) -> dict:
    return {"name": name, "age": age, "email": email}

sig = inspect.signature(create_user)
print(f"函数签名: {sig}")  # 输出: (name: str, *, age: int, email: str) -> dict

for param in sig.parameters.values():
    print(f"参数名: {param.name}, 种类: {param.kind}")

输出：

函数签名: (name: str, *, age: int, email: str) -> dict
参数名: name, 种类: POSITIONAL_OR_KEYWORD
参数名: age, 种类: KEYWORD_ONLY
参数名: email, 种类: KEYWORD_ONLY

5. 位置-only 参数的函数签名

Python 3.8+ 支持使用 / 定义位置-only 参数：

def divide(a: float, b: float, /) -> float:
    return a / b

sig = inspect.signature(divide)
print(f"函数签名: {sig}")  # 输出: (a: float, b: float, /) -> float

for param in sig.parameters.values():
    print(f"参数名: {param.name}, 种类: {param.kind}")

输出：

函数签名: (a: float, b: float, /) -> float
参数名: a, 种类: POSITIONAL_ONLY
参数名: b, 种类: POSITIONAL_ONLY

6. 混合类型参数的函数签名

实际应用中，函数签名经常混合多种参数类型：

def complex_function(
    a: int,                  # 位置或关键字参数
    b: str,                  # 位置或关键字参数
    /,                       # 位置-only 参数结束标记
    c: float = 0.0,          # 关键字或位置参数（但在/后，只能关键字传入）
    *,                       # 关键字-only 参数开始标记
    d: bool = False,         # 关键字-only 参数
    **kwargs: str            # 可变关键字参数
) -> None:
    pass

sig = inspect.signature(complex_function)
print(f"函数签名: {sig}")

for param in sig.parameters.values():
    print(f"参数名: {param.name}, 种类: {param.kind}")

输出：

函数签名: (a: int, b: str, /, c: float = 0.0, *, d: bool = False, **kwargs: str) -> None
参数名: a, 种类: POSITIONAL_ONLY
参数名: b, 种类: POSITIONAL_ONLY
参数名: c, 种类: POSITIONAL_OR_KEYWORD
参数名: d, 种类: KEYWORD_ONLY
参数名: kwargs, 种类: VAR_KEYWORD

三、函数签名的实际应用

1. 参数验证

可以使用函数签名在运行时验证参数是否符合要求：

def validate_arguments(func, *args, **kwargs):
    sig = inspect.signature(func)
    try:
        # 绑定参数并验证
        bound_args = sig.bind(*args, **kwargs)
        print("参数验证通过")
        return bound_args
    except TypeError as e:
        print(f"参数错误: {e}")
        return None

# 测试函数
def greet(name: str, age: int = 18) -> str:
    return f"Hello, {name} (age {age})"

# 正确调用
validate_arguments(greet, "Alice", 30)  # 输出: 参数验证通过

# 错误调用（类型不匹配，但Python本身不强制类型检查）
validate_arguments(greet, 123, "30")  # 输出: 参数验证通过（类型注解仅为提示）

# 错误调用（参数数量不匹配）
validate_arguments(greet, "Bob", 25, "extra")  # 输出: 参数错误: too many positional arguments

2. 动态生成函数调用

函数签名可用于动态生成符合要求的函数调用：

def dynamic_call(func,** params):
    sig = inspect.signature(func)
    # 过滤掉函数不接受的参数
    valid_params = {k: v for k, v in params.items() if k in sig.parameters}
    return func(**valid_params)

# 使用示例
def create_profile(name: str, age: int, city: str = "Unknown") -> dict:
    return {"name": name, "age": age, "city": city}

# 传入额外参数会被过滤
data = {"name": "Charlie", "age": 35, "city": "New York", "extra": "ignored"}
print(dynamic_call(create_profile,** data))  # 输出: {'name': 'Charlie', 'age': 35, 'city': 'New York'}

四、总结

Python 的函数签名是函数接口的结构化描述，通过 inspect 模块可以方便地获取和分析。函数签名包含以下关键信息：

参数名称和顺序
参数类型注解（提示性）
参数默认值
参数种类（位置-only、位置或关键字、关键字-only、可变位置、可变关键字）
返回值注解

函数签名的主要作用是：

明确函数的正确调用方式
支持 IDE 提供自动补全和类型提示
便于在运行时进行参数验证
为动态函数调用提供依据

理解和利用函数签名可以帮助我们编写更清晰、更健壮的代码，特别是在开发框架、装饰器或通用工具函数时非常有用。

posted @ 2025-10-11 01:32 wangya216 阅读(56) 评论(0) 收藏举报

刷新页面返回顶部