# PEP 3107 - Function Annotations（函数注解）：为你的函数增添魔法注释

嗨，亲爱的小伙伴们！今天让我们一起来探索一下 Python 世界中超级有趣又实用的 PEP 3107 - Function Annotations（函数注解）吧！

一、什么是函数注解？

函数注解就像是给函数贴上的小标签，告诉大家这个函数的参数和返回值是什么样的“小秘密”。想象一下，当你走进一个神秘的花园，每个植物上都有一个小牌子告诉你它是什么花，是不是感觉特别贴心？函数注解就是这样的小牌子，让其他开发者更容易理解你的函数在干什么。

比如，我们可以这样写一个带有注解的函数：

def multiply_numbers(a: int, b: int) -> int:
    return a * b

在这里，a: int 和 b: int 告诉我们参数 a 和 b 应该是整数类型，-> int 则表示这个函数会返回一个整数。

二、函数注解的好处

1. 提高代码的可读性
   当别人看到你的代码时，一眼就能明白函数的输入和输出期望，不用再费劲去猜啦。

2. 自我文档化
   函数注解本身就是一种很好的文档形式，让你的代码更有“自解释”的能力。

3. 辅助静态检查工具
   虽然 Python 是动态类型的语言，但一些静态检查工具可以利用函数注解来帮你发现潜在的类型错误，提前给你提个醒。

三、如何使用函数注解

1. 基本数据类型注解
   像整数、浮点数、字符串、布尔值这些常见的数据类型，都可以直接写在参数后面。

def divide(a: float, b: float) -> float:
    if b == 0:
        raise ValueError("除数不能为 0")
    return a / b

2. 复杂数据类型注解
   对于列表、字典、元组等复杂的数据结构，我们可以从 typing 模块中引入相应的类型来注解。

from typing import List, Dict

def process_data(data_list: List[int], data_dict: Dict[str, int]) -> None:
    for num in data_list:
        print(num)
    for key, value in data_dict.items():
        print(f"{key}: {value}")

3. 自定义类作为注解
   如果你有自己定义的类，也可以把它们用在函数注解里哦。

class Person:
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

def greet(person: Person) -> str:
    return f"Hello, {person.name}"

4. 多个参数的注解
   如果函数有多个参数，每个参数都可以有自己的注解，清晰明了。

def calculate_area(length: float, width: float) -> float:
    return length * width

5. 可选参数的注解
   对于可选参数，可以使用 Optional 来注解。

from typing import Optional

def get_value(key: str, default_value: Optional[int] = None) -> Optional[int]:
    # 查找并返回对应的值，如果没有则返回默认值或 None
    pass

四、函数注解的注意事项

1. 注解只是提示，不是强制约束
   Python 不会在运行时强制检查函数注解的类型是否匹配，所以还是要靠我们自己在代码中保证类型的正确性。

2. 保持注解的准确性和更新
   如果函数的功能或参数类型发生了变化，一定要记得更新注解，不然会给别人造成误解哦。

好啦，小伙伴们，希望你们现在对 PEP 3107 - Function Annotations 有了更深入的了解和喜爱！快去给自己的函数加上这些可爱的注解，让代码变得更加清晰和有趣吧！

# 一个综合的函数注解示例
from typing import List, Optional

class Book:
    def __init__(self, title: str, author: str, pages: int):
        self.title = title
        self.author = author
        self.pages = pages

def find_books_by_author(author: str, available_books: List[Book], min_pages: Optional[int] = None) -> List[Book]:
    result = []
    for book in available_books:
        if book.author == author and (min_pages is None or book.pages >= min_pages):
            result.append(book)
    return result