标准库地图与模块选择方法

◎

本节目标

按任务查询 Python 标准库分区、模块选择、平台可用性和验证方法。

版本基线

Python 3.14

语言前置

零基础

标准库更适合按任务检索，而不是按模块名称背诵。先用标准库总览定位分区，再用模块索引查名称；交互式探索可用 help()，探查导入规格可用 importlib.util.find_spec()。采用前还要核对可用性说明。本页从任务、输入输出、平台和验证四个边界组织选择方法；具体文件操作见文件、路径、流、临时文件与目录操作，文本和数据格式分别见文本处理、正则表达式与 Unicode与结构化数据、序列化、压缩与 SQLite。

后续章节	本批核对的核心模块与对象
文件、路径、流、临时文件与目录操作	pathlib、io、tempfile、shutil
文本处理、正则表达式与 Unicode	str、bytes、codecs、unicodedata、re
结构化数据、序列化、压缩与 SQLite	json、csv、tomllib、pickle、struct、gzip、bz2、lzma、zipfile、tarfile、sqlite3
collections、itertools、functools 与 operator	collections、itertools、functools、operator
数值、随机、统计、精确计算与日期时间	math、decimal、fractions、random、secrets、statistics、datetime、zoneinfo、time
操作系统、命令行参数与子进程	os、sys、argparse、subprocess、signal
线程、进程、任务与 asyncio	threading、queue、multiprocessing、concurrent.futures、asyncio
网络与常用互联网协议	socket、selectors、ssl、urllib.parse、urllib.request、http.client、email、smtplib、imaplib、poplib

标准库的范围与边界

标准库是随 Python 分发的库参考范围，其中既有访问系统能力的内建模块，也有用 Python 写成的通用模块；它不等于语言语法、内置对象，也不等于第三方包。任务需要“无需额外依赖的通用能力”时先从标准库候选开始；需要特定生态协议或业务框架时，再明确评估第三方依赖。

from pathlib import Path

report = Path("report.txt")

pathlib 解决的是路径对象和文件系统路径操作，不负责把任意业务对象序列化成文件内容。常见误区是把“文档列出的模块”误当成任一安装、任一平台都必然拥有的能力；分发包、可选组件和宿主条件仍应逐项核对。

从任务出发选择模块

模块选择先从任务、输入、输出和约束开始：输入是文本还是字节、输出要不要互操作、是否需要路径语义、是否涉及网络或并发、资源和安全边界是什么。比如把 Python 值变成可交换的 JSON 文本，应选 json；只做 URL 成分解析，应选 urllib.parse，而不是由模块名相似性决定。

import json

payload = json.dumps({"course": "Python"})

json.dumps() 的输出是 JSON 文本，不是任意 Python 对象的无损存档，也不替代输入来源的信任判断。把“能导入”当作“符合格式、精度、性能和安全约束”会让选择在接口边界处失效；集合与惰性迭代的候选可接续函数式、集合与迭代工具。

发现模块与核对文档

先通过总览和模块索引缩小名称，再读目标 API 的参数、返回值、异常和可用性说明；help() 适合交互式查看对象帮助。importlib.util.find_spec() 回答的是模块是否可发现，不是行为是否正确；名称含点时，它还可能导入父包，因此不是没有副作用的业务验证。

import importlib.util

available = importlib.util.find_spec("json") is not None

这个探针只说明当前导入机制找到了规格，不能证明目标功能满足输入数据、权限、网络、编码或平台条件。不要把 find_spec() 的真值写成兼容性承诺；需要行为保证时，在目标环境运行针对任务的最小测试。

文本、二进制与数据模块地图

文本查找和模式匹配从 str、string、re 出发，Unicode 属性查 unicodedata；字节布局选 struct，编解码和流转换选 codecs；面向互操作的结构化文本选 json。选择边界是数据的语义：字符文本、原始字节、固定二进制布局和 JSON 文本不能混为一种输入。

import struct

packet = struct.pack(">H", 513)

struct 格式中的字节序和字段宽度是协议的一部分，不能从本机字节序猜测。把 str 直接传给只接受 bytes 的接口，或未写明编码便读写文本，都会把数据边界留给环境默认值。

文件、路径与系统模块地图

路径计算和文件系统访问优先区分 pathlib.PurePath 与 pathlib.Path；流层级查 io，高层复制移动查 shutil，临时资源查 tempfile，启动外部程序才查 subprocess。模块选择的边界是“描述路径”还是“实际访问系统”，以及调用方是否拥有关闭流和处理进程状态的责任。

from pathlib import Path

suffix = Path("archive.tar.gz").suffix

这里仅计算路径字符串，不检查文件存在性；把 Path 的构造当作权限、存在性或可移植性验证是错误的。操作系统接口和命令行边界可进一步参照操作系统、命令行与子进程。

集合、迭代与函数工具地图

频次、双端队列和专用容器从 collections 选择；组合、分组和惰性迭代从 itertools 选择；缓存和高阶函数适配从 functools 选择；把标准运算符作为可调用对象才使用 operator。关键边界是容器是否需要物化、迭代器能否只消费一次，以及排序键还是比较规则是否更贴近任务。

from collections import Counter

counts = Counter("letter")

Counter 适合计数，不替代需要固定字段或关系约束的领域模型。也不要把迭代器当作可重复读取的序列：许多 itertools 结果被消费后不会自动重放。

数值、随机、统计与时间地图

基础数学查 math，十进制精确规则查 decimal，有理数语义查 fractions，描述性统计查 statistics，日历和时区语义查 datetime 与 zoneinfo。random 只用于模拟、抽样和非安全随机；秘密值必须按安全需求选专门接口。选择时先写明精度、舍入、时区、单调时间或安全性约束。

import statistics

average = statistics.mean([2, 4, 6])

该均值不定义业务上的缺失值、异常值或加权规则；把浮点结果视为十进制金额，或把朴素日期时间当作带时区的时刻，都会改变结果含义。数值与时间细节见数值、随机、统计与日期时间。

并发与网络模块地图

共享内存中的线程协调选 threading，进程隔离和 CPU 并行候选查 multiprocessing，大量等待型 I/O 的协程协议选 asyncio；传输和协议层从 socket、ssl 与相关互联网模块开始。模块名不是并发模型的承诺：先确定共享状态、取消传播、背压、资源所有权和协议层，再决定线程、进程还是协程。

import asyncio

lock = asyncio.Lock()

asyncio.Lock 只能在相应事件循环的协程协调中使用，不能替代线程锁或进程间同步。平台限制、事件循环和任务取消的具体边界见并发与 asyncio；网络协议选择见网络与互联网协议。

平台可用性与可移植性

标准库中某个模块或功能的可用性可以依赖平台和构建方式。可用性标记说明的是文档定义的适用范围，不是某个具体操作系统上的存在保证；例如受限运行时可能让进程、线程、网络或文件系统能力不可用、受限或行为不同。

import importlib.util

has_subprocess = importlib.util.find_spec("subprocess") is not None

即使模块可导入，底层能力仍可能不可用或调用失败；可发现性不能替代功能测试。不要将本机成功结果推广到其他操作系统、解释器构建、沙箱或浏览器运行时；把目标平台放进持续验证矩阵。

模块选择与验证工作流

先写下任务及输入输出约束，再按分区列出候选并阅读官方 API 与可用性合同；最小探针只检查当前环境，最终仍要用任务数据验证行为并记录不支持的平台边界。以下报告也只检查四个名称在当前导入机制中可发现，并不验证文件系统、统计输入、JSON 内容或 URL 解析的业务正确性。

library_map_report.py

import importlib.util


TASK_MODULES = {
    "filesystem": "pathlib",
    "statistics": "statistics",
    "structured-data": "json",
    "url-parsing": "urllib.parse",
}


for task in sorted(TASK_MODULES):
    print(f"{task}={TASK_MODULES[task]}")

verified = all(
    importlib.util.find_spec(module_name) is not None
    for module_name in TASK_MODULES.values()
)
print(f"verified={verified}")

filesystem=pathlib
statistics=statistics
structured-data=json
url-parsing=urllib.parse
verified=True

verified=True 只表示这些候选在该运行时有导入规格；它不说明每个 API 在所有输入、所有平台和所有构建中都满足任务。遇到异常、平台差异或性能约束时，回到任务边界重选模块，并为目标环境保留可重复的行为测试。