Python自定义函数常见报错：TypeError与NameError排查指南

Traceback (most recent call last):
  File "app/main.py", line 42, in <module>
    render_report(user_id=101, format_type="pdf")
  File "app/services/report.py", line 18, in render_report
    content = format_content(template, user_id)
  File "app/services/formatter.py", line 7, in format_content
    return template + ": " + user_id
TypeError: can only concatenate str (not "int") to str

def calculate_pay(hourly_rate, hours_worked):
    return hourly_rate * hours_worked

# 错误调用 1：缺少必需的位置参数
calculate_pay(50)
# 抛出: TypeError: calculate_pay() missing 1 required positional argument: 'hours_worked'

# 错误调用 2：传递了过多未知位置参数
calculate_pay(50, 40, 1.5)
# 抛出: TypeError: calculate_pay() takes 2 positional arguments but 3 were given

def get_total_score(scores):
    sum = 0  # 危险！局部变量名与内置函数 sum 冲突
    for s in scores:
        sum += s
    
    # 试图再次使用内置 sum 计算均值
    avg = sum(scores) / len(scores)  # 此时 sum 是 int 类型的 150，并非函数！
    return avg

def compute_discount(price: float, discount_percent: float) -> float:
    # 防御性转换，确保参与算术运算的变量类型确凿
    p = float(price)
    d = float(discount_percent)
    if not (0.0 <= d <= 1.0):
        raise ValueError("折扣率必须在 0 到 1 之间")
    return round(p * (1.0 - d), 2)

# ❌ 错误做法：在定义之前调用
run_pipeline()  # NameError: name 'run_pipeline' is not defined

def run_pipeline():
    print("Pipeline executed.")

# -------------------------------------------------------------
# ✔ 规范做法：将执行逻辑收拢到模块入口保护块中
def run_pipeline():
    print("Pipeline executed.")

if __name__ == "__main__":
    run_pipeline()  # 此时 run_pipeline 已经由 def 成功注册

def process_order(items):
    summary_count = len(items)  # 局部变量
    return summary_count > 0

process_order(["apple", "banana"])
print(summary_count)  # ❌ NameError: name 'summary_count' is not defined

retry_count = 3  # 全局变量

def try_request():
    if retry_count > 0:  # 报错发生在这行！
        print("Retrying...")
    retry_count = 0     # 关键原因：函数体内存在赋值语句！

try_request()

• 推荐方案（纯函数设计）：将变量作为参数传入，计算后用 return 传出，保持函数独立可测；
• 次选方案（明确全局修改）：如果确实需要就地修改全局状态，在函数第一行显式声明 global retry_count（若为嵌套函数则声明 nonlocal）。

# 业务文件: shipping.py

# 初始调用（尝试计算重 5kg、VIP 用户、目标城市上海的运费）
fee = calculate_shipping(5, "VIP", city="Shanghai")

def calculate_shipping(weight, user_level, base_rate=15):
    if user_level == "VIP":
        discount = 0.8
    total_fee = base_rate + (weight * 2) * discount  # 普通用户会漏定义 discount
    return total_fee

from typing import Optional

def calculate_shipping(
    weight: float,
    user_level: str = "Normal",
    base_rate: float = 15.0,
    city: Optional[str] = None,
    **extra_attrs
) -> float:
    """计算订单运费，具备严格的参数校验与类型安全保障。"""
    w = float(weight)
    b = float(base_rate)
    
    # 初始化局部默认值，杜绝分支漏赋引发的 NameError
    discount = 1.0
    if user_level.upper() == "VIP":
        discount = 0.8
    elif user_level.upper() == "SVIP":
        discount = 0.6
        
    final_fee = (b + (w * 2.0)) * discount
    return round(final_fee, 2)

if __name__ == "__main__":
    # 验证测试用例
    print("VIP 运费:", calculate_shipping(5, "VIP", city="Shanghai"))    # 20.0
    print("普通运费:", calculate_shipping(5, "Normal", city="Beijing")) # 25.0