Python 函数特性及高阶函数拾遗

     @decorator1
     @decorator2
     def func(): ...
     # 等价于 func = decorator1(decorator2(func))

     def auth(role):  # 外层接收参数
         def decorator(func):  # 内层接收函数
             def wrapper(*args,**kwargs):
                 if check_role(role): return func(*args,**kwargs)
                 else: raise PermissionError
             return wrapper
         return decorator

def my_decorator(func):
    def wrapper(*args, **kwargs):
        """装饰器内部的包装函数"""
        return func(*args, **kwargs)
    return wrapper

@my_decorator
def say_hello():
    """原函数的文档字符串"""
    print("Hello!")

print(say_hello.__name__)  # 输出：wrapper（而非 say_hello）
print(say_hello.__doc__)   # 输出：装饰器内部的包装函数（而非原文档字符串）。

from functools import wraps

def my_decorator(func):
    @wraps(func)  # 关键：复制元数据到 wrapper
    def wrapper(*args, **kwargs):
        """装饰器内部的包装函数"""
        return func(*args, **kwargs)
    return wrapper

@my_decorator
def say_hello():
    """原函数的文档字符串"""
    print("Hello!")

print(say_hello.__name__)  # 输出：say_hello（正确保留）
print(say_hello.__doc__)   # 输出：原函数的文档字符串（正确保留）。

from functools import wraps

def log_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        print(f"调用函数：{func.__name__}，参数：{args}, {kwargs}")
        result = func(*args, **kwargs)
        print(f"函数返回：{result}")
        return result
    return wrapper

@log_decorator
def add(x: int, y: int) -> int:
    """计算两数之和"""
    return x + y

print(help(add))  # 正确显示原函数签名和文档字符串。

from functools import wraps

def my_decorator(func):
    @wraps(func, assigned=("__name__", "__doc__"), updated=())
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

  def outer():
      x = 10
      def inner():
          return x + 5
      return inner

  def timer(func):
      def wrapper(*args):
          start = time.time()
          result = func(*args)
          print(f"Time: {time.time() - start}")
          return result
      return wrapper

  def counter():
      count = 0
      def inc():
          nonlocal count
          count +=1
          return count
      return inc

from __future__ import annotations
"""Python函数特性详解示例

本模块展示了Python函数的各种高级特性，包括：
1. 泛型函数与类型形参（Python 3.12+）
2. 默认参数陷阱及解决方案
3. 类型标注及其应用
4. 参数传递规则
5. 函数对象及其属性
"""
from typing import TypeVar, Generic, Optional, Union, Any
from functools import wraps
import inspect
import time


# 1. 泛型函数示例
T = TypeVar('T')

def process[T](data: list[T]) -> T | None:
    """泛型函数示例
    
    在Python 3.12+中，可以使用类型形参语法定义泛型函数
    底层实现：函数对象会包含__type_params__属性存储类型参数
    """
    # 获取类型参数信息
    type_params = process.__type_params__
    print(f"类型参数: {type_params}")
    return data[0] if data else None

# 2. 默认参数陷阱演示
class DefaultArgsDemo:
    """演示默认参数的陷阱和解决方案"""
    
    @staticmethod
    def buggy_append(item: Any, lst: list = []) -> list:
        """有缺陷的默认参数实现
        
        默认参数在函数定义时就被求值，而不是在调用时，这个默认值会成为函数对象的一个属性（存储在 __defaults__ 中）
        这个默认值会在整个程序运行期间一直存在，而不是每次调用时重新创建，所有调用共享同一个列表对象
        设计原因：- 函数在 Python 中是一等对象，默认参数是函数对象的属性，而不是局部变量
        它在某些场景下很有用，比如实现缓存或记忆化
        """
        lst.append(item)
        return lst
    
    @staticmethod
    def safe_append(item: Any, lst: Optional[list] = None) -> list:
        """安全的默认参数实现
        
        使用None作为标记，在函数调用时创建新的列表
        - None 是不可变对象，作为默认值是安全的 - 每次调用函数时都会创建新的列表
        """
        if lst is None:
            lst = []  # 每次调用时创建新的列表
        lst.append(item)
        return lst

# 3. 参数传递规则示例
def demonstrate_args(
    pos_only_arg: str, /,           # 仅位置参数
    standard_arg: int,              # 标准参数
    *args: tuple[str, ...],         # 可变位置参数
    kw_only_arg: float = 1.0,       # 仅关键字参数
    **kwargs: Any                   # 可变关键字参数
) -> None:
    """展示不同类型的参数传递
    
    参数解析过程：
    1. 首先处理位置参数
    2. 然后处理关键字参数
    3. 多余的位置参数存入*args
    4. 多余的关键字参数存入**kwargs
    """
    print(f"位置参数: {pos_only_arg}")
    print(f"标准参数: {standard_arg}")
    print(f"可变位置参数: {args}")
    print(f"仅关键字参数: {kw_only_arg}")
    print(f"可变关键字参数: {kwargs}")

# 4. 函数对象及属性研究
def function_introspection_demo():
    """演示函数对象的内省机制"""
    def example_func(a: int, b: str = "default") -> None:
        """示例函数"""
        pass

    # 显示函数的各种属性
    print(f"函数名: {example_func.__name__}")
    print(f"文档字符串: {example_func.__doc__}")
    print(f"类型注解: {example_func.__annotations__}")
    print(f"默认参数: {example_func.__defaults__}")
    print(f"所在模块: {example_func.__module__}")
    
    # 使用inspect模块获取更多信息
    sig = inspect.signature(example_func)
    print(f"函数签名: {sig}")
    for name, param in sig.parameters.items():
        print(f"参数 {name}: {param.kind}, 默认值: {param.default}")

# 5. 装饰器与闭包示例
def timing_decorator(func):
    """测量函数执行时间的装饰器
    
    展示了闭包和装饰器的实现原理
    """
    @wraps(func)  # 保留原函数的元数据
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        end = time.perf_counter()
        print(f"{func.__name__} 执行时间: {end - start:.6f} 秒")
        return result
    return wrapper

@timing_decorator
def slow_function(n: int) -> int:
    """测试装饰器的示例函数"""
    time.sleep(n)
    return n

# TypeVar(用于定义泛型类型变量) 示例
from typing import TypeVar, List, Sequence

# 基础 TypeVar
T = TypeVar('T')  # 可以是任何类型
S = TypeVar('S', bound=str)  # 限制为 str 或其子类
N = TypeVar('N', int, float)  # 限制为 int 或 float
K = TypeVar('K', bound='BaseClass')  # 限制为 BaseClass 或其子类

def first_element[T](lst: List[T]) -> T | None:
    """返回列表的第一个元素"""
    return lst[0] if lst else None

def string_operation[S](text: S) -> S:
    """只接受字符串类型的操作"""
    return text

def number_operation[N](num: N) -> N:
    """只接受数字类型的操作"""
    return num

class BaseClass:
    pass

class SubClass(BaseClass):
    pass

def process_base[K](item: K) -> K:
    """只接受 BaseClass 及其子类的操作"""
    return item

def demonstrate_typevar():
    """演示 TypeVar 的各种用法"""
    # 基础 TypeVar 示例
    print(first_element([1, 2, 3]))  # 输出: 1
    print(first_element(["a", "b"]))  # 输出: "a"
    
    # 带边界的 TypeVar
    print(string_operation("hello"))  # 正确
    # print(string_operation(123))  # 类型检查器会报错
    
    # 带约束的 TypeVar
    print(number_operation(42))  # 正确
    print(number_operation(3.14))  # 正确
    # print(number_operation("123"))  # 类型检查器会报错
    
    # 类型边界示例
    base = BaseClass()
    sub = SubClass()
    print(process_base(base))  # 正确
    print(process_base(sub))   # 正确
    # print(process_base("wrong"))  # 类型检查器会报错

# 6. 高阶函数示例
from typing import Callable, TypeVar, Any, Type  # Added Type import

R = TypeVar('R')  # 返回值类型
T = TypeVar('T')  # 输入参数类型

# 检查泛型函数定义
def process[T](data: list[T]) -> T | None:
    return data[0] if data else None

def first_element[T](lst: List[T]) -> T | None:
    return lst[0] if lst else None

"""
- [T, R] ：定义了两个类型参数，T和R分别代表不同的类型
- f: Callable[[T], R] ：第一个参数f是一个函数，接收T类型参数，返回R类型结果
- g: Callable[[Any], T] ：第二个参数g是一个函数，接收任意类型参数，返回T类型结果
- -> Callable[[Any], R] ：返回一个新函数，这个函数接收任意类型参数，返回R类型结果
def add_one(x: int) -> int:  # f函数，T=int, R=int
    return x + 1

def double(x: int) -> int:   # g函数
    return x * 2

# compose(add_one, double)(3) 等价于 add_one(double(3))
result = compose(add_one, double)(3)  # 结果为7：先3*2=6，再6+1=7
"""
def compose[T, R](f: Callable[[T], R], g: Callable[[Any], T]) -> Callable[[Any], R]:
    """函数组合：返回一个新函数 h(x) = f(g(x))"""
    def composed_function(x: Any) -> R:
        return f(g(x))
    return composed_function

"""
这是一个装饰器工厂，用于创建具有重试功能的装饰器。

- [T] ：定义一个类型参数，代表被装饰函数的返回类型
- times: int ：重试次数
- on_exception: Type[Exception] ：指定需要捕获的异常类型
- -> Callable[[Callable[..., T]], Callable[..., T]] ：返回一个装饰器函数，这个装饰器接收并返回相同签名的函数
最外层 Callable[X, Y] 表示一个函数，其中：
- X 是参数类型列表
- Y 是返回值类型
Callable[..., T] 中的 ... 表示接受任意数量和类型的参数， T 表示返回值类型

@retry[str](times=3)  # 指定返回类型为str，最多重试3次
def unstable_operation() -> str:
    if random.random() < 0.7:  # 70%概率失败
        raise ConnectionError("连接失败")
    return "操作成功"
"""
def retry[T](times: int, on_exception: Type[Exception] = Exception) -> Callable[[Callable[..., T]], Callable[..., T]]:
    """创建一个装饰器，在异常时重试指定次数，返回的装饰器函数decorator接收一个函数func，并返回包装后的函数wrapper。这里使用了@wraps(func)来保留原函数的元数据"""
    def decorator(func: Callable[..., T]) -> Callable[..., T]: #- 接收原始函数 func 作为参数- 返回包装后的函数 wrapper
        @wraps(func)
        def wrapper(*args: Any, **kwargs: Any) -> T: #- 使用 @wraps(func) 保留原函数的元数据 - 实现重试逻辑 - *args 和 **kwargs 用于接收任意参数
            for attempt in range(times):
                try:
                    return func(*args, **kwargs)
                except on_exception as e:
                    if attempt == times - 1:  # 最后一次尝试
                        raise e
                    print(f"尝试 {attempt + 1} 失败，准备重试...")
            raise RuntimeError("不应该到达这里")
        return wrapper
    return decorator

def demonstrate_higher_order_functions():
    """演示高阶函数的使用"""
    # 1. 函数组合示例
    def double(x: int) -> int:
        return x * 2
    
    def add_one(x: int) -> int:
        return x + 1
    
    # 组合函数：先double再add_one
    double_then_add = compose(add_one, double)
    print(f"double_then_add(3) = {double_then_add(3)}")  # 应该输出7 (3*2+1)
    
    # 2. 重试装饰器示例
    @retry(times=3)
    def unstable_operation() -> str:
        """模拟一个不稳定的操作"""
        import random
        if random.random() < 0.7:  # 70%的概率失败
            raise ConnectionError("连接失败")
        return "操作成功"
    
    try:
        result = unstable_operation()
        print(f"操作结果: {result}")
    except Exception as e:
        print(f"最终失败: {e}")

# 在main函数中添加高阶函数演示
def main():
    """运行所有示例"""
    # 1. 测试泛型函数
    print("\n1. 泛型函数示例:")
    print("函数的类型参数信息:")
    print(f"类型参数列表: {process.__type_params__}")  # 输出类型参数信息
    print("\n具体调用示例:")
    #print(process[int]([1, 2, 3]))新语法但报错了
    print(process([1, 2, 3]))
    #print(process[str](["a", "b"]))
    print(process(["a", "b"]))

    # 2. 测试默认参数
    print("\n2. 默认参数示例:")
    demo = DefaultArgsDemo()
    print("有缺陷的实现:")
    # 在函数定义时，空列表[]就被创建并绑定到函数对象上
    print(demo.buggy_append.__defaults__)  # 输出: ([],)
    print(demo.buggy_append(1))
    print(demo.buggy_append(2))  # 会看到累积效果
    
    print("\n安全的实现:")
    print(demo.safe_append(1))
    print(demo.safe_append(2))  # 每次都是新列表
    
    # 3. 测试参数传递
    print("\n3. 参数传递示例:")
    demonstrate_args("pos", 42, "extra1", "extra2", 
                    kw_only_arg=2.0, extra_kw="value")
    
    # 4. 函数内省
    print("\n4. 函数内省示例:")
    function_introspection_demo()
    
    # 5. 装饰器测试
    print("\n5. 装饰器示例:")
    slow_function(1)
    
    # 添加 TypeVar 演示
    print("\n6. TypeVar 示例:")
    demonstrate_typevar()
    
    # 添加高阶函数演示
    print("\n7. 高阶函数示例:")
    demonstrate_higher_order_functions()

if __name__ == "__main__":
    main()

def factory(...) -> Callable[[原函数类型], 装饰后函数类型]:
    def decorator(func: 原函数类型) -> 装饰后函数类型:
        def wrapper(...) -> 返回值类型:
            # 装饰逻辑
        return wrapper
    return decorator