def function_name(parameter1, parameter2, ...):
    """
    Docstring: 描述函数的功能、参数和返回值 (可选但强烈推荐)
    """
    # 函数体: 实现功能的代码
    # ...
    return value # 可选，用于返回结果

# 定义一个简单的问候函数
def greet():
    """打印一句问候语。"""
    message = "大家好！欢迎学习Python函数定义！"
    print(message)

greet()

# 查看文档字符串,方便查看函数的使用，这个方法可以不掌握
print(greet.__doc__)
# 实际上，当你在py文件中，鼠标悬停在函数上按住ctrl即可点击函数跳转到其内部查看函数的定义

# 定义一个带一个参数的问候函数
def greet_person(name):
    """根据给定的名字打印问候语。

    Args:
        name (str): 要问候的人的名字。
    """
    message = f"你好, {name}! 很高兴认识你。"
    print(message)

greet_person("张三")  # 输出: 你好, 张三! 很高兴认识你。

# 定义一个带多个参数的函数 (例如，在机器学习中计算两个特征的和)
def add_features(feature1, feature2):
    """计算两个数值特征的和。

    Args:
        feature1 (float or int): 第一个特征值。
        feature2 (float or int): 第二个特征值。
    """
    total = feature1 + feature2
    print(f"{feature1} + {feature2} = {total}")

add_features(10, 25)       # 输出: 10 + 25 = 35

# add_features(5) 
# 这会报错，因为少了一个参数 TypeError

# 定义一个计算和并返回结果的函数
def calculate_sum(a, b):
    """计算两个数的和并返回结果。

    Args:
        a (float or int): 第一个数。
        b (float or int): 第二个数。

    Returns:
        float or int: 两个数的和。
    """
    result = a + b
    return result
    print("hhh")

calculate_sum(2, 3)

# 函数可以返回多种类型的数据，包括列表、字典等
# 例如，在数据预处理中，一个函数可能返回处理后的特征列表
def preprocess_data(raw_data_points):
    """模拟数据预处理，例如将所有数据点乘以2。

    Args:
        raw_data_points (list): 原始数据点列表。

    Returns:
        list: 处理后的数据点列表。
    """
    processed = []
    for point in raw_data_points:
        processed.append(point * 2) # 假设预处理是乘以2
    return processed

data = [1, 2, 3, 4, 5]
processed_data = preprocess_data(data)

print(f"原始数据: {data}")
print(f"预处理后数据: {processed_data}") # 输出: [2, 4, 6, 8, 10]

print("\n--- 变量作用域示例 ---")
global_var = "我是一个全局变量"

def scope_test():
    local_var = "我是一个局部变量"
    print(f"在函数内部，可以看到局部变量: '{local_var}'")
    print(f"在函数内部，也可以看到全局变量: '{global_var}'")
    # global_var = "尝试在函数内修改全局变量" # 如果没有 global 声明，这会创建一个新的局部变量 global_var
    # print(f"在函数内部，修改后的 '全局' 变量: '{global_var}'")

scope_test()

print(f"\n在函数外部，可以看到全局变量: '{global_var}'")

# print(f"在函数外部，不能看到局部变量: {local_var}") # 这会产生 NameError，因为 local_var 只在函数内存在

def describe_pet(animal_type, pet_name):
    """显示宠物的信息。"""
    print(f"\n我有一只 {animal_type}.")
    print(f"我的 {animal_type} 的名字叫 {pet_name.title()}.")

describe_pet("猫", "咪咪") # 使用关键字参数，顺序不重要

假设一个复杂的绘图函数
plot_data(data, x_col, y_col, "blue", "-", True, False, "My Plot", "X-axis", "Y-axis") # 不清晰

使用关键字参数
plot_data(data=my_data, x_column='time', y_column='value',
          color='blue', linestyle='-', show_grid=True, use_log_scale=False,
          title="My Awesome Plot", xlabel="Time (s)", ylabel="Value") # 非常清晰

describe_pet(animal_type="猫", pet_name="咪咪") # 使用关键字参数，顺序不重要
describe_pet(pet_name="旺财", animal_type="狗") # 顺序改变，但结果正确

def describe_pet_default(pet_name, animal_type="狗"): # animal_type 有默认值
    """显示宠物的信息，动物类型默认为狗。"""
    print(f"我有一只 {animal_type}.")
    print(f"我的 {animal_type} 的名字叫 {pet_name.title()}.")

describe_pet_default(pet_name="小黑") # animal_type 使用默认值 "狗"
describe_pet_default(pet_name="雪球", animal_type="仓鼠") # 提供 animal_type，覆盖默认值
# 注意：带默认值的参数必须放在没有默认值的参数之后

def make_pizza(size, *toppings):
    """概述要制作的比萨。
    *toppings 会将所有额外的位臵参数收集到一个元组中。
    """
    print(f"\n制作一个 {size} 寸的比萨，配料如下:")
    if toppings: # 只要toppings不为空元组，就会执行
        for topping in toppings:
            print(f"- {topping}")
    else:
        print("- 原味 (无额外配料)")

make_pizza(12, "蘑菇")
make_pizza(16, "香肠", "青椒", "洋葱")
make_pizza(9) # toppings 会是空元组

def build_profile(first_name, last_name, **user_info):
    """创建一个字典，其中包含我们知道的有关用户的一切。
    **user_info 会将所有额外的关键字参数收集到一个字典中。
    """
    profile = {}
    profile['first_name'] = first_name
    profile['last_name'] = last_name
    for key, value in user_info.items():
        profile[key] = value
    return profile

user_profile = build_profile('爱因斯坦', '阿尔伯特',
                             location='普林斯顿',
                             field='物理学',
                             hobby='小提琴')
print(f"\n用户信息: {user_profile}")
# 输出: {'first_name': '爱因斯坦', 'last_name': '阿尔伯特', 'location': '普林斯顿', 'field': '物理学', 'hobby': '小提琴'}

# 同时出现 *args 和 **kwargs，注意参数的传入顺序
def process_data(id_num, name, *tags, status="pending", **details): # 注意，这里的status 是仅关键字参数，必须通过关键词传值
    print(f"ID: {id_num}")
    print(f"Name: {name}")
    print(f"Tags (*args): {tags}")
    print(f"Status: {status}")          # status 是一个有默认值的普通关键字参数
    print(f"Details (**kwargs): {details}")
    print("-" * 20)

# 调用1:
process_data(101, "Alice", "vip", "new_user", location="USA", age=30)
# ID: 101
# Name: Alice
# Tags (*args): ('vip', 'new_user')  <-- "vip", "new_user" 是多余的位置参数，被 *tags 收集
# Status: pending                    <-- status 使用默认值，因为调用中没有 status=...
# Details (**kwargs): {'location': 'USA', 'age': 30} <-- location 和 age 是多余的关键字参数，被 **details 收集
# --------------------

# 调用2:
process_data(102, "Bob", status="active", department="Sales")
# ID: 102
# Name: Bob
# Tags (*args): ()                   <-- 没有多余的位置参数
# Status: active                     <-- status 被关键字参数 'active' 覆盖
# Details (**kwargs): {'department': 'Sales'} <-- department 是多余的关键字参数
# --------------------

# 调用3:
process_data(103, "Charlie", "admin") # 'admin' 会被 *tags 捕获
# ID: 103
# Name: Charlie
# Tags (*args): ('admin',)
# Status: pending
# Details (**kwargs): {}
# --------------------

# 调用4: (演示关键字参数也可以用于定义中的位置参数)
process_data(name="David", id_num=104, profession="Engineer")
# ID: 104
# Name: David
# Tags (*args): ()
# Status: pending
# Details (**kwargs): {'profession': 'Engineer'}
# --------------------