w wyl123ly 的博客
MD

Python-03-函数与模块

43 KB 2026.10.11 原文件

Python-03-函数与模块

本篇讲什么

函数是把"做什么"与"怎么用"分开的最小单位,模块是把函数组织成可复用、可测试单元的载体。本篇覆盖:

参数机制(位置/关键字/默认值陷阱/*args/**kwargs/仅关键字 */仅位置 /)、函数是一等对象、LEGB 作用域与 global/nonlocal、闭包(含循环变量延迟绑定陷阱)、lambda 与 map/filter/sorted 的配合、递归与深度限制、类型注解、模块与包(import 四种形式、if __name__ == "__main__"、__init__.py、sys.path 搜索顺序)、标准库与第三方库的边界、常用内置函数。

读完后你应该能解释:为什么默认参数写成 [] 会出 bug、为什么 lambda 在循环里全都返回最后一个值、为什么你的脚本一被 import 就执行了。


一、是什么

  • 函数(function):一段有名字、可带参数、可返回值的代码块。Python 的函数是对象(一等公民),能被赋值、传参、返回、放进容器。
  • 模块(module):一个 .py 文件(或一个用 C 写的扩展),本身也是一个对象,拥有独立的命名空间(module.__dict__)。导入模块 = 执行该文件顶层代码一次,并把结果存进 sys.modules 缓存。
  • 包(package):含 __init__.py 的目录(常规包)或由多个目录组成的命名空间包(PEP 420 起,__init__.py 不再是硬性要求)。包用来把模块按命名空间分层,例如 myapp.db.models。

三者关系:函数是代码的复用单位,模块是文件的复用单位,包是目录的复用单位。


二、为什么这样设计

设计动机代价
参数默认值在定义时求值一次函数调用更快(不用每次重算默认值),语义简单默认值是可变对象时会被"记住",产生跨调用的状态泄漏
*args 收成 tuple、**kwargs 收成 dict一个语法覆盖"可变参数"与"转发参数"两种需求,装饰器/包装器写起来自然签名不自解释,需要类型注解或文档补齐
函数是一等对象无需专门的"函数指针"语法即可实现回调、策略表、装饰器滥用匿名函数会牺牲可读性与可调试性(栈里全是 <lambda>)
作用域在编译期确定(LEGB)局部变量访问可以编译成按下标取(LOAD_FAST),比字典查找快得多函数里只要出现赋值,该名字在整个函数内就是局部名,容易出现 UnboundLocalError
闭包(closure)让"带状态的函数"不必写类,lambda/装饰器/回调都靠它循环变量延迟绑定是最经典的坑
模块只执行一次并缓存避免重复初始化、保证单例语义(配置对象、连接池)循环导入会拿到"半成品模块";模块名遮蔽标准库会导致诡异错误
if __name__ == "__main__"让一个文件既能当脚本执行、又能被安全导入忘记写会让导入方意外执行副作用(写文件、起服务、甚至 sys.exit)

一句话总结

Python 用"默认值只算一次 + 名字在编译期定域 + 模块只执行一次"换来了速度与简单,代价是三处必须记住的语义:可变默认参数、闭包延迟绑定、导入副作用。


三、核心内容

3.1 函数定义与文档字符串

def 名字(参数列表) -> 返回类型注解:
    """文档字符串(docstring)"""
    函数体
    return 值

docstring 的规范见 PEP 257:首行是一句话摘要(祈使句、以句号结尾),空一行后写详细说明;被 help()、inspect.getdoc()、Sphinx、IDE 悬浮提示读取。它不是注释,是运行时可访问的对象属性(f.__doc__)。

3.2 参数机制全表

Python 的函数签名可以同时包含五类参数,书写顺序固定:

def f(仅位置, /, 位置或关键字, *args, 仅关键字, **kwargs):
参数种类语法传入方式收到的类型典型用途
位置或关键字cf(1) 或 f(c=1)原对象普通参数
仅位置(3.8+,PEP 570)/ 之前只能 f(1)原对象参数名可能被改的实现细节;C 函数包装
仅关键字(PEP 3102)* 之后只能 f(e=1)原对象强制可读性,避免位置参数顺序错误
可变位置*argsf(1, 2, 3)tuple转发不定数量参数
可变关键字**kwargsf(a=1, b=2)dict包装/装饰器透传

默认值规则:有默认值的参数必须排在无默认值参数之后;*args 之后的参数自动变成仅关键字。

概念规则
默认值求值时机函数定义时求值一次,之后所有调用共享同一个对象
参数传递语义传的是"对象引用的副本":改可变对象的内容会影响调用方,重新绑定名字不会
调用时解包f(*seq) 展开为位置参数,f(**mapping) 展开为关键字参数(PEP 448 起可在同一调用里混用)
缺参 / 多参都抛 TypeError,消息会指出缺了哪个关键字参数

3.3 函数是一等对象

函数对象上常见的属性:

属性含义
__name__函数名(lambda 的名字是 "<lambda>")
__doc__文档字符串
__defaults__位置参数默认值组成的元组(可以在这里观察到可变默认参数)
__kwdefaults__仅关键字参数的默认值字典
__annotations__注解字典
__module__、__qualname__定义所在模块与限定名
__closure__闭包捕获的 cell 元组,cell.cell_contents 取实际值
__code__字节码与常量等编译产物

因为函数是对象,所以可以:存进列表/字典当"策略表"、作为参数传给高阶函数(sorted(key=...))、作为返回值(工厂函数、装饰器)。

3.4 LEGB 作用域规则

名字查找顺序:

顺序作用域说明
1Local当前函数内绑定的名字
2Enclosing外层函数的局部作用域(仅嵌套函数可见)
3Global当前模块的顶层名字
4Built-in内置命名空间(len、print…)

关键性质:

  • 作用域在编译期确定。函数体内只要出现对某名字的赋值(x = ...、for x in ...、import x、def x()、except E as x),该名字在整个函数体内就是局部名——即使赋值语句在 print(x) 之后。
  • global x 让赋值落到模块命名空间;nonlocal x 让赋值落到最近的外层函数作用域(该绑定必须已存在,否则 SyntaxError)。
  • 类体不是方法的外层作用域:方法里直接写 value 找不到类属性 value,必须 self.value 或 ClassName.value。
  • 推导式有自己的作用域,for 变量不会泄漏(Python 3)。

3.5 闭包(closure)

闭包 = 函数 + 它捕获的外层变量(cell)。当内层函数引用了外层函数的局部变量,并且内层函数被返回或传出时,外层函数的栈帧虽然结束,但变量被"装进 cell"继续存活。

def outer():
    n = 0                    ← n 被内层函数引用
    def inner():
        nonlocal n           ← 声明"我要改外层的 n"
        n += 1
        return n
    return inner             ← inner 带着 cell(n)一起返回

c = outer()     # c.__closure__[0].cell_contents == 0
c()             # 1
c()             # 2  ← 状态保存在闭包里
outer()()       # 1  ← 新的 outer() 调用产生新的 cell,互不影响
用途说明
带状态的函数计数器、累加器、简易"对象"
装饰器包装函数、记录调用、缓存(见 [[Python-07-进阶特性]])
回调工厂为每个对象生成专属回调
延迟计算生成器/惰性求值里保存上下文

代价:闭包会延长外层变量(以及它引用的对象)的生命周期,长期持有大对象会阻止垃圾回收;调试时变量不在常规栈里,需要在 IDE 里看 __closure__。

3.6 lambda 与函数式三件套

lambda 参数: 表达式 只能包含一个表达式,不能有语句、不能有注解、不能多行。

场景推荐说明
作为 key= 的简短取值lambda x: x[1]也可用 operator.itemgetter(1),更快且可读
排序/分组的一次性映射lambda不要赋值给变量(PEP 8 建议用 def)
需要文档字符串/多行逻辑deflambda 无法写 docstring
逐元素变换生成器表达式或列表推导式比 map(lambda ...) 更清晰
累积归约functools.reduce内置 sum/max/math.prod 能覆盖时优先用它们

map / filter 在 Python 3 里返回迭代器(惰性、只能消费一次);functools.reduce 从内置移到了 functools。

3.7 递归与递归深度限制

递归的两个必要条件:终止条件和规模递减。经典例子斐波那契的朴素递归:

加缓存(记忆化)后每个 只算一次:

Python 的硬约束:

事项值/说明
默认递归上限sys.getrecursionlimit() == 1000(CPython 实测最多约 998 层函数调用)
超限异常RecursionError: maximum recursion depth exceeded
尾调用优化没有。return f(...) 不会复用栈帧,Python 之父明确否决了 TCO(会破坏栈回溯)
提高上限的风险sys.setrecursionlimit(106) 可能因 C 栈耗尽而段错误崩溃**,比抛异常更糟
正确出路改成迭代、用显式栈/队列、或加记忆化把指数级降为多项式

3.8 类型注解基础

注解只是元数据,CPython 不做任何运行时检查(def f(x: int) 传字符串一样能跑),要检查得用 mypy/pyright 等静态工具。

写法版本说明
def f(x: int) -> str:3.0+函数注解
x: int = 03.6+(PEP 526)变量注解
list[int]、dict[str, int]3.9+内置泛型(PEP 585),之前要 List[int]
`int \None`3.10+(PEP 604)联合类型,之前要 Optional[int]
from __future__ import annotations3.7+注解变字符串、延迟求值,解决前向引用
type Vector = list[float]3.12+(PEP 695)类型别名语句
def first[T](xs: list[T]) -> T:3.12+(PEP 695)泛型函数语法
默认延迟求值注解3.14+(PEP 649/749)注解在需要时才求值,以官方最新文档为准

3.9 模块:import 的四种形式

形式写法绑定到当前命名空间的名字适用
导入模块import jsonjson首选:来源清晰
起别名import numpy as npnp长名字、社区约定简称
导入具体成员from json import dumps, loadsdumps、loads用得极频繁、名字不易混淆
通配导入from json import *模块全部公开名字禁止:污染命名空间、无法追溯来源

补充规则:

  • from pkg.mod import name 会先执行整个模块,再取出属性。
  • from x import * 只导入 __all__ 里列出的名字;没有 __all__ 则导入所有不以 _ 开头的名字。
  • 模块对象缓存在 sys.modules,重复 import 只取缓存,不会重新执行;要强制重载用 importlib.reload(mod)(调试用,生产慎用)。
  • 用 mod.__file__ 可以看到这个模块到底从哪里加载,排查"装错环境/被同名文件遮蔽"的利器。

3.10 if __name__ == "__main__" 的作用与原理

每个模块都有一个 __name__ 属性:

运行方式__name__ 的值
python script.py"__main__"
python -m pkg.mod"__main__"(同时可以被 pkg.mod 再次导入)
import script"script"(模块名)
python -c "...""__main__"

所以 if __name__ == "__main__": main() 的含义是"只有作为入口脚本运行时才执行这段代码"。它解决的问题是:同一个文件既能被命令行直接运行,又能被其他模块安全导入而不产生副作用(不写文件、不连数据库、不调 sys.exit)。

3.11 包与 __init__.py

myapp/
├── __init__.py          ← 常规包的标记 + 包级初始化 + 对外 API 收口
├── config.py
├── db/
│   ├── __init__.py
│   ├── models.py
│   └── session.py
└── cli.py
概念说明
常规包(regular package)含 __init__.py 的目录;导入包时执行该文件
命名空间包(namespace package,PEP 420)没有 __init__.py 的目录也能当包,可跨多个目录位置合并同名包
__init__.py 的职责标记常规包、做轻量初始化、用 __all__ 控制 import *、把子模块的公共 API 提升到包名(from .core import Engine)
相对导入from . import config、from ..db import session,只能用于包内模块,不能用于入口脚本
运行方式差异python -m myapp.cli 会以包上下文运行(相对导入可用);python myapp/cli.py 不会(相对导入报错),包内脚本一律用 -m

3.12 sys.path 与模块搜索顺序

import x 时,解释器按 sys.path 列表从前到后查找 x:先找内置模块(sys.builtin_module_names),再按路径找 x.py / x/__init__.py / 扩展模块。sys.path 的构成(实测于 python -c,CPython 3.12):

顺序内容说明
0''表示当前工作目录(脚本方式运行时是脚本所在目录)
1..n标准库目录(含 python312.zip、DLLs、Lib)官方安装自带
最后Lib/site-packages第三方包安装位置
可插入PYTHONPATH 环境变量按顺序插在脚本目录之后、标准库之前
可插入sys.path.append/insert运行时修改,能用但会让依赖关系隐式化

要点:

  • 脚本目录优先于标准库:如果你的目录里有个 random.py,import random 会导到你的文件,标准库被遮蔽,随后所有依赖 random 的库都会诡异崩坏。不要用标准库模块名给文件命名。
  • python -m 包.模块 时 sys.path[0] 是当前工作目录;python script.py 时是脚本所在目录。这解释了"在 A 目录能跑、在 B 目录不能跑"的现象。
  • 虚拟环境的作用就是让 site-packages 指向项目自己的目录,见 Python-08-虚拟环境与包管理。

3.13 标准库与第三方库

维度标准库(stdlib)第三方库(PyPI)
来源随解释器安装,位于 Lib/pip install 装到 site-packages/
例子json、re、datetime、pathlib、sqlite3、logging、collections、itertoolsrequests、numpy、pandas、fastapi、pytest
版本升级跟解释器走,不能单独升级每个项目可锁不同版本
依赖无可能带来几十个间接依赖
选型建议能用标准库就用(少一个依赖少一个风险)需要生态/性能/成熟方案时用

判断一个模块是谁:module.__file__ 落在 site-packages 就是第三方;python -m pip show 包名 看版本与来源。包管理细节见 工具-03-包管理器。

3.14 内置常用函数速查

函数作用复杂度 / 说明
len(x)长度
sum(it, start=0)求和;3.12+ 对浮点用补偿求和
any(it) / all(it)是否存在真值 / 是否全为真短路;空序列分别是 False / True
min / max极值,支持 key= 与 default=(空序列不报错)
sorted(it, key=, reverse=)排序并返回新列表,稳定
reversed(seq)反向迭代器不复制序列
enumerate(it, start=0)下标 + 元素返回迭代器
zip(*its, strict=False)并行迭代默认按最短截断,strict=True(3.10+)报错
map(f, *its) / filter(f, it)逐元素映射 / 过滤返回迭代器,只能消费一次
isinstance(obj, cls)类型判断支持元组与继承关系,优于 type(x) is T
callable(obj)是否可调用判断是否有 __call__
repr / str调试表示 / 用户表示repr 目标是可重建对象的字符串
abs round pow divmod数学pow(a, b, m) 是模幂,密码学常用
getattr / setattr / hasattr动态属性反射入口
open打开文件见 [[Python-05-异常与文件IO]]

四、怎么用(可运行示例)

4.1 定义、docstring 与函数对象属性

def normalize_name(raw: str, *, strip_middle: bool = True) -> str:
    """把姓名规范化为 'First Last' 形式。

    为什么放在函数里:姓名清洗规则会在导入、搜索、展示多处复用,
    集中在一处才能保证行为一致。

    Args:
        raw: 原始姓名,可能含多余空格或大小写混乱。
        strip_middle: 是否丢弃中间名,默认 True。

    Returns:
        规范化后的姓名。
    """
    parts = raw.split()
    if strip_middle and len(parts) > 2:
        parts = [parts[0], parts[-1]]
    return " ".join(p.capitalize() for p in parts)


print(normalize_name("  ada   lovelace   byron "))
print(normalize_name("ada lovelace byron", strip_middle=False))

# docstring 不是注释,是运行时可读取的属性
print(normalize_name.__doc__.splitlines()[0])
print(normalize_name.__name__, normalize_name.__defaults__, normalize_name.__kwdefaults__)
print(normalize_name.__annotations__)
help(normalize_name)      # 在交互式解释器里查看(这里演示调用方式)

4.2 参数全谱:仅位置 /、仅关键字 、args、**kwargs

def request(method, url, /, *, timeout=5.0, retries=3, **headers):
    """method/url 只能位置传入;timeout/retries 只能关键字传入;其余关键字收进 headers。"""
    return {
        "method": method.upper(),
        "url": url,
        "timeout": timeout,
        "retries": retries,
        "headers": headers,
    }


print(request("get", "/users", timeout=2.0, Authorization="Bearer x"))
print(request("post", "/users", **{"Content-Type": "application/json"}))

# 仅位置参数不能被写成关键字:参数名属于实现细节,可以放心重命名
try:
    request(method="get", url="/users")
except TypeError as e:
    print("仅位置参数:", e)

# 仅关键字参数漏传会立刻报错,避免"位置参数顺序写反"这类静默 bug
try:
    request("get", "/users", 2.0)
except TypeError as e:
    print("仅关键字参数:", e)

# 调用时解包:* 展开位置参数,** 展开关键字参数
args = ("get", "/health")
kwargs = {"timeout": 1}
print(request(*args, **kwargs))

# 观察签名(写装饰器、做参数校验时很有用)
import inspect

print(inspect.signature(request))

4.3 默认值陷阱:可变默认参数

# 错误:默认值在定义时创建一次,所有调用共享同一个列表
def add_bad(item, bucket=[]):
    bucket.append(item)
    return bucket


print(add_bad(1), add_bad(2))          # [1, 2] [1, 2] —— 第二次调用"记住了"第一次的结果
print(id(add_bad.__defaults__[0]))     # 就是那个被共享的列表对象


# 正确:用 None 作为哨兵,在函数体内按需创建
def add_good(item, bucket=None):
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket


print(add_good(1), add_good(2))        # [1] [2]

# 默认值只在定义时求值一次,所以"用当前时间做默认值"会永远是同一个时间
import time


def stamp(t=time.time()):
    return t


first = stamp()
time.sleep(0.05)
print(first == stamp())                # True —— 不是"每次调用取当前时间"

# 想要动态默认值就传 None 再在函数里取
def stamp_live(t=None):
    return time.time() if t is None else t


time.sleep(0.05)
print(stamp_live() > first)

4.4 函数是一等对象:策略表

def area_rect(w, h):
    return w * h


def area_triangle(w, h):
    return w * h / 2


# 函数可以放进字典当"策略表",替代一长串 if/elif
SHAPES = {
    "rect": area_rect,
    "triangle": area_triangle,
    # lambda 适合这种一次性、无名字需求的场合
    "circle": lambda w, h: 3.14159 * (w / 2) ** 2,
}


def compute(shape, w, h):
    if shape not in SHAPES:
        raise ValueError(f"未知形状:{shape}")
    return SHAPES[shape](w, h)


print(compute("rect", 3, 4), compute("triangle", 3, 4), round(compute("circle", 3, 3), 2))

# 函数作为参数传给高阶函数
def apply_twice(fn, value):
    return fn(fn(value))


print(apply_twice(lambda v: v + 3, 1))    # 7

# 函数作为返回值:工厂函数
def make_multiplier(factor):
    def multiply(x):
        return x * factor      # factor 被闭包捕获
    return multiply


double = make_multiplier(2)
triple = make_multiplier(3)
print(double(5), triple(5), double is triple)

4.5 LEGB 与 global / nonlocal

x = 10          # 全局


def read_global():
    return x    # L 里没有 → 找到 G


def unbound_demo():
    try:
        print(x)      # 报错!因为下面有 x = 20,x 在整个函数内被视为局部名
    except UnboundLocalError as e:
        return f"UnboundLocalError: {e}"
    x = 20


print(read_global(), "|", unbound_demo())


def write_global():
    global x          # 声明"我改的是模块级 x"
    x = 20


write_global()
print("global 修改后:", x)


def outer():
    total = 0

    def add(n):
        nonlocal total        # 改外层函数的 total,而不是新建局部变量
        total += n
        return total

    return add


acc = outer()
print(acc(1), acc(2), acc(3))

# 类体不是方法的外层作用域
class Config:
    timeout = 30

    def bad(self):
        try:
            return timeout            # NameError:找不到类体的 timeout
        except NameError as e:
            return f"NameError: {e}"

    def good(self):
        return self.timeout           # 正确:通过实例访问


print(Config().bad(), "|", Config().good())

4.6 闭包:计数器与循环变量延迟绑定

def make_counter():
    """闭包版计数器:状态藏在 cell 里,不污染全局。"""
    count = 0

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

    return counter


c1, c2 = make_counter(), make_counter()
print(c1(), c1(), c2())                # 1 2 1 —— 两次 make_counter 互相独立
print(c1.__closure__[0].cell_contents)  # 2 —— 可以直接观察闭包里的值

# 经典陷阱:循环变量的延迟绑定
funcs_bad = [lambda: i for i in range(3)]
print([f() for f in funcs_bad])        # [2, 2, 2] —— 三个函数共享同一个 i,调用时 i 已是 2

# 修复一:默认参数在定义时求值,把当前值"拍照"固定下来
funcs_fix1 = [lambda i=i: i for i in range(3)]
print([f() for f in funcs_fix1])       # [0, 1, 2]

# 修复二:工厂函数,每次调用产生新的 cell
def make_getter(i):
    return lambda: i


print([make_getter(i)() for i in range(3)])     # [0, 1, 2]

# 修复三:functools.partial 绑定参数
import functools

funcs_fix3 = [functools.partial(lambda i: i, i) for i in range(3)]
print([f() for f in funcs_fix3])       # [0, 1, 2]

4.7 lambda 与 map / filter / sorted / reduce

import functools

nums = [3, -1, 4, -1, 5]

# map:逐元素变换(返回迭代器,只能消费一次)
squares = map(lambda v: v * v, nums)
print(list(squares))     # [9, 1, 16, 1, 25]
print(list(squares))     # [] —— 迭代器已耗尽,这是新手最常见的"数据消失"

# 更清晰的等价写法(推荐):生成器表达式
print([v * v for v in nums])

# filter:按条件过滤
print(list(filter(lambda v: v > 0, nums)))    # [3, 4, 5]
print(list(filter(None, [0, 1, "", "a", None])))   # [1, 'a'] —— f=None 表示按真值过滤

# sorted + key:按绝对值排序
print(sorted(nums, key=abs))

# reduce:累积归约(能用 sum/max/any 就别用 reduce)
print(functools.reduce(lambda acc, v: acc + v, nums, 0))   # 10

# 多可迭代对象:map 与 zip 一样按最短截断
print(list(map(lambda a, b: a + b, [1, 2, 3], [10, 20])))   # [11, 22]

4.8 递归:从朴素到缓存再到迭代

import functools
import sys

# 1) 朴素递归:正确但指数级慢(重复计算同一子问题)
def fib_naive(n):
    return n if n < 2 else fib_naive(n - 1) + fib_naive(n - 2)


print(fib_naive(20))          # 6765,n 再大就要等很久
print(sys.getrecursionlimit())     # 1000(默认值)

# 2) 记忆化:@cache 把重复子问题的结果存起来,时间从 O(phi^n) 降到 O(n)
@functools.cache
def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)


print(fib(200) % 1000)             # 525,瞬间返回
print(fib.cache_info())            # CacheInfo(hits=..., misses=..., maxsize=None, currsize=...)

# 3) 迭代:空间 O(1),且不受递归深度限制,适合生产代码
def fib_iter(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a


print(fib_iter(200) % 1000)        # 525,与 fib(200) 一致


# 4) 递归深度实测
def depth(n=0):
    try:
        return depth(n + 1)
    except RecursionError:
        return n


print("实际可用深度约", depth())     # 约 998(上限 1000,解释器自身已占用若干帧)

# 5) 递归必须显式写终止条件,否则直接 RecursionError
def no_base(n):
    return no_base(n + 1)


try:
    no_base(0)
except RecursionError as e:
    print("RecursionError:", e)

4.9 类型注解

from __future__ import annotations   # 让注解延迟求值:注解里可以用还没定义的名字

from typing import get_type_hints


def merge(a: dict[str, int], b: dict[str, int]) -> dict[str, int]:
    """合并两个计数字典,同名键相加。注解只是给人和静态检查工具看的,运行时不校验。"""
    out = dict(a)
    for k, v in b.items():
        out[k] = out.get(k, 0) + v
    return out


print(merge({"a": 1}, {"a": 2, "b": 3}))
print(merge.__annotations__)          # 由于 future import,这里是字符串
print(get_type_hints(merge))          # 解析后的真实类型


def find_user(uid: int) -> str | None:      # 3.10+ 的联合类型语法(PEP 604)
    return "ada" if uid == 1 else None


print(find_user(1), find_user(2))

# 3.12+ 的类型别名与泛型函数(PEP 695)
type Row = dict[str, str]


def first[T](items: list[T]) -> T:
    """返回第一个元素,T 在调用时被推断。"""
    return items[0]


print(first([1, 2, 3]), first(["a", "b"]))

# 注解不会阻止错误类型(这正是需要 mypy/pyright + 单测的原因)
def add(a: int, b: int) -> int:
    return a + b


print(add(1, 2), add("1", "2"))       # 3 12 —— 字符串拼接照样通过,注解没有任何运行时约束

4.10 模块的两种身份与四种 import

# 不新建文件也能观察"直接运行 vs 被导入"的差别
src = '''
print("__name__ =", __name__)
if __name__ == "__main__":
    print("以脚本身份运行:执行主流程")
else:
    print("被导入:只提供函数,不执行主流程")
'''

# 模拟 python mymod.py
exec(compile(src, "mymod.py", "exec"), {"__name__": "__main__"})
# 模拟 import mymod
exec(compile(src, "mymod.py", "exec"), {"__name__": "mymod"})

四种导入形式对照(放在 main.py 里):

import json                          # 推荐:来源清晰,json.dumps(...)
import numpy as np                   # 别名:社区约定
from json import dumps, loads        # 只导入需要的成员,名字短
# from json import *                 # 禁止:污染命名空间,看不出名字从哪来

payload = dumps({"ok": True})
print(payload, loads(payload))

import sys

print(json is sys.modules["json"])   # True —— 模块只执行一次,之后都取缓存
print(json.__file__)                 # 看它到底从哪个文件加载

标准入口写法:

"""myapp/cli.py —— 包的入口模块。"""

import sys


def main(argv: list[str] | None = None) -> int:
    # 返回退出码而不是直接 sys.exit,便于单元测试
    args = sys.argv[1:] if argv is None else argv
    print("参数:", args)
    return 0


if __name__ == "__main__":
    # 只有 python -m myapp.cli 或 python cli.py 时才执行
    raise SystemExit(main())

4.11 包的结构、__init__.py 与相对导入

# 目录结构:
# myapp/
# ├── __init__.py        from .core import Engine  /  __all__ = ["Engine"]
# ├── core.py            class Engine: ...
# └── db/
#     ├── __init__.py
#     └── session.py     from ..core import Engine   ← 相对导入:上跳一级到 myapp

# myapp/db/session.py 里可以这样写:
# from ..core import Engine
# from . import helpers        # 同级模块

# 运行方式决定相对导入是否可用:
#   python -m myapp.cli          ← 在包上下文里运行,相对导入可用(推荐)
#   python myapp/cli.py          ← 以独立脚本运行,相对导入会抛 ImportError

print("包内模块请一律用 python -m 运行")

4.12 sys.path 实测与模块搜索

import sys

# 只查看前几项,观察顺序:当前目录 → 标准库 → site-packages
for i, p in enumerate(sys.path[:6]):
    print(i, repr(p))

在本机 CPython 3.12 上 python -c 的实测输出('' 表示当前工作目录):

0 ''
1 '...\python312.zip'
2 '...\DLLs'
3 '...\Lib'
4 '...\python'
5 '...\Lib\site-packages'
# 运行时插路径:能用,但会让依赖关系变隐式,优先用"装成包 + venv"的方案
import sys
sys.path.insert(0, "D:/DSH_Workspace/Prog1/tools")

# 想知道某个模块实际从哪来(排查"装错环境/被同名文件遮蔽")
import json
print(json.__file__)

# 强制重新加载(改完模块不想重启解释器时用,生产代码不要依赖)
import importlib
importlib.reload(json)

4.13 内置函数实战:短路与惰性

log = []


def probe(v):
    log.append(v)         # 记录"被真正求值过"的元素
    return v              # 必须返回元素本身,any/all 的短路行为才可观察


print(any(probe(v) for v in [1, 2, 3]), log)      # True [1] —— any 在第一个真值处短路
log.clear()
print(all(probe(v) for v in [1, 2, 3]), log)      # True [1, 2, 3] —— 全为真才走完
log.clear()
print(all(probe(v) for v in [1, 0, 3]), "log =", log)   # False log = [1, 0] —— 0 处短路

print(len((1, 2)), sum((1, 2, 3), 100), min([3, 1], default=0), max([], default="none"))
print(list(zip("abc", [1, 2])), list(enumerate(["a"], start=5)))
print(sorted([(1, "a"), (1, "b")], key=lambda t: t[0]))   # 稳定:相等键保持原顺序

五、注意事项与常见坑

坑 1:可变默认参数(最经典的 Python 陷阱)

def f(item, bucket=[]) 里的 [] 在定义时创建一次,之后每次调用都共享它,于是"上一次调用的数据"会出现在下一次结果里。同理还有 ={}、=set()、=SomeObject()。正确写法是默认值用 None,函数体内 if bucket is None: bucket = []。

坑 2:默认参数在定义时求值,不是每次调用

def log(msg, t=time.time()) 里的 t 永远是模块导入那一刻的时间。需要动态默认值就传 None 再在函数内计算。

坑 3:闭包与循环变量的延迟绑定

[lambda: i for i in range(3)] 里的三个 lambda 共享同一个 i,全部返回 2。修复方式:默认参数 lambda i=i: i、工厂函数、或 functools.partial。这个坑在"给一批按钮绑定回调"时最容易踩到。

坑 4:UnboundLocalError 与"我以为在改全局变量"

函数体内只要出现对名字的赋值,该名字整个函数内都是局部的。print(x) 写在 x = 20 之前就报 UnboundLocalError: cannot access local variable 'x'。想改全局要显式 global,想改外层函数变量要 nonlocal(且外层必须已有该绑定,否则 SyntaxError)。

坑 5:参数传递是"引用的副本"

传列表进函数,函数内 lst.append(x) 会影响调用方(同一个对象);而 lst = [1, 2] 只让局部名字重新绑定,调用方看不到。需要"不改原对象"时在函数内先 copy,并在 docstring 里写清楚。

坑 6:map/filter/zip/生成器是"一次性"的

它们是迭代器,遍历一次就空了。list(map(f, data)) 之后再遍历同一个 map 对象得到空列表。需要多次使用就物化成 list,或者每次重新构造。

坑 7:递归没有尾调用优化

Python 不会把 return f(...) 优化成循环,深度受 sys.getrecursionlimit()(默认 1000,实测约 998 层)限制,超限抛 RecursionError。不要用 sys.setrecursionlimit(106) 硬顶**——C 栈耗尽会直接段错误(进程崩溃且没有 Python 异常可捕获)。首选改成迭代或加 @functools.cache。

坑 8:忘记写 if __name__ == "__main__"

后果是"一被 import 就跑主流程":写文件、发请求、开服务,甚至 sys.exit() 把导入方一起干掉。入口脚本一律加这个守卫,且把主逻辑放进 main() 函数里。

坑 9:用标准库模块名给自己的文件命名

目录里有 random.py、json.py、types.py、email.py 时,import random 会导入你的文件,标准库被遮蔽,接着依赖它们的第三方库会以奇怪的方式失败。排查手段:python -c "import random; print(random.__file__)"。

坑 10:循环导入(circular import)

a.py 导入 b、b 又导入 a,会得到 ImportError: cannot import name ... (partially initialized module) 或拿到不完整的模块对象。解法:① 把公共部分抽到第三个模块;② 把导入移到函数内部(延迟导入);③ 改成导入模块本身而不是成员(import a + a.func(),属性访问发生在运行时)。

**坑 11:from module import * 与"变量改名导致 import 失效"**

通配导入会把一堆名字塞进当前命名空间,覆盖同名变量、让静态分析失效。少数合法场景是在 __init__.py 里配合 __all__ 收口对外 API。

坑 12:把 lambda 赋值给变量

f = lambda x: x + 1 得到的函数 __name__ 是 "<lambda>",栈回溯里只显示 <lambda>,无法写 docstring。PEP 8 明确建议:需要名字就用 def。

实践建议

1. 每个函数只做一件事,名字用动词短语;参数超过 4 个考虑封装成 dataclass。

2. 纯函数(不依赖外部可变状态)最容易测试,把 I/O 与计算分离。

3. 用 def main(argv=None) -> int + raise SystemExit(main()) 的模式,让入口逻辑可单测。

4. 给公开函数写类型注解,CI 里跑 mypy 或 pyright;测试见 工具-04-测试基础。

5. 包内一律 python -m 包.模块 运行,避免相对导入报错。


六、练习题

  1. 基础题:写一个函数 describe(name, age=None, *, city="未知"),当 age 为 None 时输出"<name> 的年龄未知",否则输出"<name>(<age>)来自 <city>"。要求 city 只能以关键字传入,并说明为什么这样设计比 describe(name, age, city) 更不容易出错。
  1. 基础题:下面的函数有什么 bug?给出两种修复方式并说明差别。

```python

def collect(value, seen={}):

seen[value] = seen.get(value, 0) + 1

return seen

```

  1. 进阶题:实现 make_adder(n),返回一个把入参加 n 的函数;再实现 make_counter(start=0, step=1),返回一个每次调用返回下一个值的函数(用闭包 + nonlocal)。额外要求:为 make_counter 增加 reset() 能力,说明你会怎么设计返回值。
  1. 进阶题:写一个 safe_summary(rows) 函数:rows 是 list[tuple[str, float]],返回 dict[str, float],键为名称、值为总和;同名键累加,非法行(长度不足或值不是数字)跳过并在函数返回时通过 logging.warning 记录条数(re/logging 用法见 Python-06-常用标准库)。要求写 docstring 与类型注解。
  1. 思考题:为什么 Python 选择"模块只执行一次 + 用 __name__ 区分身份",而不是像某些语言那样要求显式的入口点声明?这种设计在"既能当库又能当命令行工具"的双用途文件上带来什么好处,又带来哪些风险(结合循环导入与导入副作用谈)?

七、常见问题(FAQ)

Q1:为什么我的函数"记住了"上一次调用的数据?

A:九成是可变默认参数。默认值在 def 执行时创建一次,之后所有调用共享同一个对象,函数里对它的修改会保留下来(可以通过 f.__defaults__ 亲眼看到)。改成 None 哨兵模式:def f(x, acc=None): acc = [] if acc is None else acc。

Q2:为什么循环里创建的 lambda 全部返回最后一个值?

A:闭包捕获的是变量本身而不是变量的值,循环结束时该变量的最终值被所有闭包共享。修复:lambda i=i: i(用默认参数拍照)、用工厂函数为每个值创建独立作用域、或用 functools.partial。

Q3:if __name__ == "__main__" 到底解决什么问题?

A:它让一个文件有两种身份。直接运行时 __name__ 是 "__main__",可以执行主流程;被 import 时 __name__ 是模块名,主流程被跳过,导入方只得到函数和类。没有它,任何 import 都会触发文件顶层的全部副作用(包括 sys.exit),并且无法对它做单元测试。

Q4:什么时候该用闭包,什么时候该写类?

A:只需要一个行为 + 一点私有状态时用闭包(计数器、回调、装饰器、配置好的转换函数),代码更短、无可继承的表面 API;一旦需要多个方法、需要被继承、需要 isinstance 判断、需要序列化或需要清晰的字段时,用类或 dataclass(见 Python-04-面向对象)。经验法则:闭包超过两个状态变量、或需要暴露三个以上操作时,改写类。

Q5(补充):import 会重复执行模块吗?

A:不会。模块第一次导入时执行并存入 sys.modules,之后再 import 只是从缓存取对象。要重新执行需 importlib.reload(mod),且它不会更新已经 from mod import name 绑定的旧引用——这也是"改了代码必须重启进程"的原因。


相关笔记

  • Python-01-环境与基础语法 —— 变量绑定、真值测试与 is/== 的基础
  • Python-02-内置数据结构 —— 元组解包、zip/enumerate、推导式与生成器表达式
  • Python-04-面向对象 —— 何时从闭包升级为类、dataclass 与特殊方法
  • Python-07-进阶特性 —— 装饰器、迭代器与生成器、functools 深入
  • Python-08-虚拟环境与包管理 —— site-packages、依赖安装与项目结构
  • Python-06-常用标准库 —— logging、json、pathlib、re 等标准库用法
  • JavaScript-02-函数与作用域 —— 对照:JS 的 this、闭包与提升
  • 工具-03-包管理器 —— pip/PyPI 与依赖管理
  • 工具-04-测试基础 —— 可测试的函数设计与单元测试
  • 00-索引 —— 返回全库导航

参考来源

  • 官方教程:定义函数、参数、解包、lambda、文档字符串:<https://docs.python.org/3/tutorial/controlflow.html>
  • 官方教程:模块与包、__name__、sys.path 入门:<https://docs.python.org/3/tutorial/modules.html>
  • 复合语句参考(def 语法、装饰器、global/nonlocal):<https://docs.python.org/3/reference/compound_stmts.html>
  • 执行模型(名字绑定、作用域、LEGB):<https://docs.python.org/3/reference/executionmodel.html>
  • 导入系统(sys.path、sys.modules、查找器与加载器):<https://docs.python.org/3/reference/import.html>
  • 内置函数(map、filter、zip、enumerate、sorted、any、all):<https://docs.python.org/3/library/functions.html>
  • functools(cache、lru_cache、partial、reduce、cmp_to_key):<https://docs.python.org/3/library/functools.html>
  • typing(注解与静态类型工具):<https://docs.python.org/3/library/typing.html>
  • sys(sys.path、sys.modules、getrecursionlimit):<https://docs.python.org/3/library/sys.html>
  • Functional Programming HOWTO:<https://docs.python.org/3/howto/functional.html>
  • 术语表(argument、closure、iterator 等):<https://docs.python.org/3/glossary.html>
  • PEP 257 Docstring Conventions:<https://peps.python.org/pep-0257/>
  • PEP 3102 Keyword-Only Arguments(*):<https://peps.python.org/pep-3102/>
  • PEP 570 Python Positional-Only Parameters(/,3.8+):<https://peps.python.org/pep-0570/>
  • PEP 318 Decorators for Functions and Methods:<https://peps.python.org/pep-0318/>
  • PEP 484 Type Hints:<https://peps.python.org/pep-0484/>
  • PEP 526 Syntax for Variable Annotations:<https://peps.python.org/pep-0526/>
  • PEP 604 Allow writing union types as X | Y(3.10+):<https://peps.python.org/pep-0604/>
  • PEP 695 Type Parameter Syntax(3.12+):<https://peps.python.org/pep-0695/>
  • PEP 420 Implicit Namespace Packages:<https://peps.python.org/pep-0420/>
  • 说明:默认递归上限、注解延迟求值(PEP 649/749,3.14+)等版本敏感行为以官方最新文档为准。