Python 3.14 标准库 → mystx 主题优化机会映射笔记#
一句话摘要：本笔记将
python314-stdlib-wiki六个模块（contextlib/contextvars/sys.monitoring/annotationlib/dataclasses/traceback）的系统学习成果，映射到mystxSphinx 主题（d:\spaces\SpecWeave\playground\books\libs\mystx\src\mystx）的具体优化机会，明确每项 stdlib 能力在 mystx 代码中的落点、优化动作与量化收益预判，并诚实标注「暂无收益明确落点」的模块，避免为凑齐六模块而强行引入无收益改造。
一、六模块 → mystx 落点总览#
stdlib 能力 |
wiki 章节 |
mystx 落点（文件 / 类 / 函数） |
优化动作 |
落点类型 |
|---|---|---|---|---|
|
|
增加 |
代码落点 |
|
|
|
|
代码落点 |
|
|
|
文件资源已由 |
诚实记录 |
|
|
无 |
Sphinx 扩展为同步配置加载，无跨协程任务级状态隔离需求 |
诚实记录 |
|
|
全模块 |
无 |
诚实记录 |
|
|
无 |
暂无收益明确的代码落点，记录为条件性未来落点（性能剖析/测试插桩） |
诚实记录 |
二、代码落点两个模块（已落地，有量化基线）#
2.1 dataclasses：slots=True 省内存、修正字段类型一致性#
事实（06-dataclasses）：
slots参数在 Python 3.10 加入，为数据类生成__slots__，消除每实例的__dict__，减少内存占用并加速属性访问；field(doc=...)是 Python 3.14 新增参数，为字段附加文档字符串。落点：
config.py的ConfigManager（3 个字段：app/config/logger），theme.py的MySTX（3 个字段：app/name/theme_dir）。优化动作：
两个
@dataclass增加slots=True。ConfigManager.logger由「无类型标注、默认为None、__post_init__内赋值」修正为Optional[logging.SphinxLoggerAdapter] = None，消除类型标注与默认值不一致，构造签名与__post_init__赋值语义不变。
量化收益预判（已实测）：
hasattr(instance, "__dict__")由True变False；sys.getsizeof(instance)收敛为 56 字节（无独立__dict__），对比同字段无 slots 数据类「56 +__dict__」的内存占用显著下降。field(doc=...)落点评估（诚实记录）：mystx的requires-python已为>=3.14，field(doc=...)可用；但ConfigManager/MySTX的关键字段已通过类 docstring 的Attributes:段清晰文档化，引入field(doc=...)的边际收益有限，故暂不引入，保留为条件性未来落点（当字段文档需要被dataclasses.fields()/help()内省时启用）。
2.2 traceback：exc_info=True 结构化诊断 + 异常链保留#
事实（07-traceback）：
TracebackException.from_exception(exc)轻量捕获异常对象（不持帧引用），traceback.format_exc()输出含异常类型、消息与逐帧定位（文件名/行号）的完整回溯。落点：
config.py的load_custom_config（tomllib.TOMLDecodeError与通用Exception两处）、config_inited_handler。theme.py的MySTX.__post_init__（主题注册异常路径）。
优化动作：各异常捕获处由「单行
str(e)」升级为logger(..., exc_info=True)，日志附带完整回溯（类型 + 消息 + 文件名/行号）；重抛处保留原始异常（raise维持__context__与完整 traceback），异常链不丢失。量化收益预判（已实测）：
_config.toml解析错误时，日志输出不再是「一行摘要」，而是含tomllib.TOMLDecodeError类型、行号定位的完整堆栈，便于快速定位格式错误。
三、诚实记录落点四个模块（不强行改造）#
3.1 contextlib：文件资源已由 with 正确管理#
事实（02-contextlib）：上下文管理器协议的核心是
__enter__/__exit__，with语句在进入/退出时自动调用，__exit__无论正常结束还是抛异常都会执行，用于确定性资源回收。落点与结论（满足，无需改动）：
config.py的load_custom_config已使用with open(custom_toml, "rb") as f:管理文件句柄；version_switcher.py/theme.py无其他文件/资源句柄。无需额外引入contextlib，仅在笔记中确认该模式已正确应用。
3.2 contextvars：无任务级状态隔离需求#
事实（03-contextvars）：
contextvars（PEP 567）提供并发执行单元的取值映射，用于任务级状态隔离，ContextVar/Token在异步/多线程场景跨边界传播上下文。为何无落点：
mystx是 Sphinx HTML 主题扩展，setup(app)/config_inited_handler/ 指令run()均为同步配置加载与文档构建流程，不存在跨协程/跨线程隐式传值需求，Sphinx 自身的app/config对象即承载所需上下文。条件性未来落点：若未来为主题引入异步构建钩子或并发预加载，需跨任务边界传播触发上下文时，可引入
ContextVar；当前不满足触发条件。
3.3 annotationlib：3.14 惰性求值 + 无 future import 遗留#
事实（05-annotationlib）：3.14 起 PEP 649/749 使注解惰性求值成为默认，
annotationlib.get_annotations(..., format=...)提供内省入口。现状与结论（无需改动）：
src/mystx全部模块均未使用from __future__ import annotations，类型标注（如Optional[logging.SphinxLoggerAdapter]、Dict[str, Any]）直接随 3.14 默认惰性求值语义生效，无 PEP 563 遗留需要清理。后续推荐入口：若未来需要注解内省，优先用
annotationlib.get_annotations(..., format=...)（PEP 649 原生），而非typing.get_type_hints()。
3.4 sys.monitoring：暂无收益明确的代码落点#
事实（04-sys-monitoring）：PEP 669 低开销事件监控，不是可独立
import的模块；三要素为工具 ID + 事件集合 + 回调，set_local_events可实现局部近零开销。为何暂无落点：
mystx是零运行时依赖的 Sphinx 主题库，负责主题注册、配置合并与 URL 生成，运行时不做性能事件采集或执行流追踪，引入sys.monitoring无对应收益。条件性未来落点：若未来需要为主题启动过程做低开销性能剖析或测试分支覆盖追踪，可用
sys.monitoring+ 局部事件开关实现近零开销观测。当前测试覆盖以pytest --cov实现，未引入运行时插桩。
四、小结#
六模块中，dataclasses、traceback 两项有明确且已落地的代码改造（内存、诊断两方面可量化提升）；contextlib 经核实为「已满足」落点（with 已正确使用，无需改动）；contextvars、annotationlib、sys.monitoring 三项经第一性原理评估后判定当前无收益明确的改造必要，其中 annotationlib 记录了「3.14 默认惰性求值 + 无 future import 遗留」结论，sys.monitoring 记录了未来剖析场景落点，contextvars 记录了同步流程无需任务级隔离的结论。所有结论均以「不强行引入无收益改动」为原则，量化对比见 15-mystx-optimization-report。