Docling 的 Dignified Python 决策检查清单Python 提交前审查的 10 个关键决策点【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文基于 Docling 仓库中.agents/skills/dignified-python/references/checklists.md这份提交前决策检查清单展开它把 LBYL 式异常处理、pathlib路径操作、typing.cast断言、ABC/Protocol 接口选择、默认参数设计等 10 类高频 Python 设计决策浓缩成可勾选的审查条目是 AI 编码代理与人工代码评审在提交 Python 代码前做最终把关的统一依据。读完后你不仅能掌握这份检查清单的每一条判定标准与默认结论还能看到 Docling 主代码库中is_relative_to、keyword-only 参数、cache延迟计算等对应的真实源码落点。检查清单的定位Dignified Python 技能体系的收口文件Docling 在仓库根目录维护了一套面向 AI 编码代理的开发技能包见 AGENTS.md 中的 Skills 章节贡献者技能位于.agents/skills/。其中dignified-python技能定位为面向 Python 3.10–3.13 的意见化生产级 Python 规范其入口文件 SKILL.md 明确说明了checklists.md的触发时机最终审查提交 Python 代码前的最终 review规则查漏不确定是否遵循了全部规则时快速查阅需要快速查询各项要求时。整个技能的阅读路由是分层设计的核心规范常驻加载dignified-python-core.md专题文档按需加载——写try/except时读 references/advanced/exception-handling.md定义接口时读 references/advanced/interfaces.md使用typing.cast()时读 references/advanced/typing-advanced.md设计函数签名时读 references/advanced/api-design.md。而 checklists.md 把这些专题文档中最关键的判定规则去上下文化压缩成一张可在几秒内过完的决策表——每个主题都给出勾选问题加一句加粗的Default默认结论避免审查者在细节文档间来回跳转。这份清单有一个贯穿性的哲学基调默认偏向 LBYLLook Before You Leap即当存在廉价且精确的前置条件检查时优先显式检查而不是用try/except兜底同时默认不保留向后兼容、默认模块级导入、默认要求显式传参。下面逐条解析。检查清单 1写try/except之前原文条目在错误边界吗CLI/API 层能否用廉价、精确的主动检查若不能围绕权威操作写一个小try/except是否更清晰是在添加有意义的上下文还是只是在掩盖是不是第三方 API 没有精确预检、迫使你用异常异常是否已被封装捕获的是具体异常而非宽泛异常若在错误边界捕获是否做了日志/警告绝不静默吞掉默认让异常向上冒泡。这条清单与专题文档 exception-handling.md 一一对应。该文档指出异常只在三种场景下是合适的工具错误边界CLI/API 层、调用本身就是权威判定的操作、以及重新抛出前补充上下文。核心判定法则是一条自问能否在调用 API 之前用一次廉价、精确的检查验证条件能就优先 LBYL如果操作本身就是权威验证器那么一个小的try/except往往更清晰。对应的反模式同样被明确禁止# WRONG: 静默吞掉异常即使在错误边界也不允许 try: optional_feature() except Exception: pass # 静默——问题将无法诊断 # CORRECT: 错误边界处至少记录日志 try: optional_feature() except Exception as e: logging.warning(Optional feature failed: %s, e)另一个高频细节是Ruff B904 异常链在except块内重新抛出时必须写from e保留原始 traceback或from None有意切断链例如异常信息已进入 CLI JSON 输出。Docling 的核心规范文档 dignified-python-core.md 给出的字典访问范式也属于这一条if key in mapping成员测试或.get(key, default)是正确写法而try: mapping[key] / except KeyError属于用异常做控制流的反模式。检查清单 2路径操作之前原文条目.exists()检查是否真的因文件系统存在性而必要若路径缺失应让.resolve()失败是否传了strictTrue是否把.is_relative_to()当作布尔判断而不是为它包一层ValueError捕获是否用了pathlib.Path而非os.path是否指定了encodingutf-8这条清单针对的是 pathlib 的三个常见误用核心文档 dignified-python-core.md 将其概括为黄金规则.exists()只在文件系统存在性构成操作前提时使用不要把它当作.resolve()或.is_relative_to()的盲目前置条件更不要用宽泛的except OSError包裹这些 API——那会掩盖意图而不是澄清意图。三条关键事实Python 3.11 的Path.resolve()对不存在的路径不会抛错除非显式传strictTruePath.is_relative_to()返回bool不抛ValueError——为它写try/except本身就是误解 APIread_text()/write_text()必须显式传encodingutf-8否则行为依赖平台默认编码。这一条在 Docling 源码中有大量真实落点。仓库多处路径安全校验都采用了清单认可的布尔式is_relative_to判断写法例如 HTML 后端判断资源路径是否越出本地基目录docling/backend/html_backend.pyreturn requested_path.is_relative_to(local_base_path.parent)LaTeX 宏处理器与 Tectonic 引擎用同样的模式防止相对路径逃逸出基准目录docling/backend/latex/handlers/macros.py、docling/backend/latex/engines/tectonic.py图片资源加载器 likewisedocling/backend/utils/image_resource_loader.py。这些代码全部是if not resolved.is_relative_to(base_dir): ...的布尔判断形式——正是清单第 3 问所要求的写法没有出现try/except ValueError包裹。同时docling/backend/xml/doclang_backend.py、docling/backend/latex/engines/tectonic.py 等文件中的文本读写均显式携带encodingutf-8与清单第 5 问一致。值得注意的是AGENTS.md 的 Code standards 章节把这条规则提升为项目级约定新代码或修改代码优先使用pathlib.Path除非 API 明确要求字符串路径——也就是说这份技能清单与 Docling 的官方贡献规范是相互印证的。检查清单 3使用typing.cast()之前原文条目是否为 cast 加了运行时断言来验证断言成本是否平凡O(1)若是始终加上。若跳过是否因为刚刚做过isinstance检查冗余若因性能跳过是否记录了实测开销默认成本平凡时cast 前始终加运行时断言。typing-advanced.md 对此的解释是typing.cast()是纯编译期构造运行期不做任何校验如果假设错了得到的是静默错误行为而不是清晰的报错。规范要求模式是先断言、再 castassert isinstance(doc, MutableMapping), fExpected MutableMapping, got {type(doc)} cast(dict[str, Any], doc)[key] value跳过断言只有两个正当理由一是在isinstance类型守卫刚刚执行完之后重复检查二是热路径上有实测的性能开销且必须用注释记录示例注释called 10M times/sec, isinstance adds 15% overhead。文档同时列出了三个不成立的跳过理由框架会验证取值集合、库保证类型、从上下文显然——这三种情况都应照常加断言因为断言本身就是给未来读者的文档也构成防御性纵深第三方库跨版本可能改变行为。检查清单 4定义接口ABC 或 Protocol之前原文条目是否拥有所有实现是 → 优先 ABC。是否在包装第三方库是 → 优先 Protocol。是否需要运行时isinstance()校验是 → 用 ABC。接口是否足够小1–2 个方法是 → Protocol 可能更简单。是否需要共享方法实现是 → 用 ABC。默认自己拥有的内部代码用 ABC外部库门面用 Protocol。interfaces.md 给出的完整决策矩阵是使用场景推荐原因自己控制的内部接口ABC显式强制、运行时校验、代码复用第三方库边界Protocol无需继承、松耦合需要isinstance检查的插件体系ABC可靠的运行时类型校验最小接口契约1–2 个方法Protocol样板更少、契约聚焦文档同时指出了 Protocol 的三点局限runtime_checkable只检查方法存在性、不校验签名Protocol 不应携带方法实现无法复用代码isinstance()检查比 ABC 弱。从 Docling 源码结构看项目内部基类走的是显式继承 共享实现路线——例如 OCR 模型基类BaseOcrModeldocling/models/base_ocr_model.py在基类中提供通用的 OCR 功能供各具体模型复用这正是清单第 5 问需要共享方法实现 → 用 ABC基类所对应的形态。检查清单 5保留向后兼容之前原文条目用户是否明确要求是否有外部消费者的公共 API是否已记录保留原因迁移成本是否高到无法承受默认破坏 API立即迁移所有调用点。这是清单中最激进的一条核心文档 dignified-python-core.md 给出的立场是默认不保留向后兼容反模式示例是一个legacy_format: bool False开关参数——正确做法是直接删除旧路径、一次性改完所有调用点。保留兼容只在三个条件下成立代码明确属于公共 API、用户显式要求、迁移成本高到无法承受罕见。宣称的收益是更干净的代码库、更快的迭代、不积累遗留代码、更简单的心智模型。需要说明的是这一条主要针对应用内部代码的演化策略对已经发布的库级公共 API 需按清单第 2 问谨慎评估。检查清单 6函数内联导入之前原文条目是为了打破循环依赖是为了TYPE_CHECKING是为了条件特性若为了启动时间是否测量过导入成本成本是否显著100ms是否在注释中记录了实测成本是否已记录内联导入的原因默认模块级导入。module-design.md 把合法的内联导入收敛到四类场景打破循环依赖典型如 CLI 命令注册函数体内导入避免双向依赖TYPE_CHECKING导入仅为类型提示避免运行时循环条件特性dry-run 模式包装器、平台相关实现等启动时间优化罕见——只针对确实重量级的包如大型 ML 框架且必须遵循无罪推定原则默认模块级导入只有在有实测证据表明导入显著拖慢启动100ms时才延迟并用注释记录实测成本示例# Heavy: 800ms import time。文档明确列出不应延迟导入的对象标准库、轻量内部模块、未测量过的模块、以及任何以防万一的优化。检查清单 7导入/再导出符号之前原文条目该符号是否已有规范位置是否在创建同一符号的第二条导入路径若这是 shim 模块是否只导入了本模块用途所需是否避免了__all__导出默认从规范位置导入绝不再导出。核心文档 dignified-python-core.md 的表述是每个符号恰好只有一条导入路径。反模式是在包的__init__.py里from myapp.core import Process并配__all__——这会制造重复导入路径正确做法是保持空__init__.py使用方直接from myapp.core import Process。唯一例外是插件入口点等必须再导出的场景此时要求显式import X as X语法from myapp.core.feature import my_function as my_function让再导出在代码中显式可见。检查清单 8声明局部变量之前原文条目变量是否被使用超过一次是否在使用点附近声明内联计算会不会损害可读性是否在把对象字段抽成只用一次的局部变量默认单次使用的计算内联到调用点对象属性直接访问。核心文档给出了两个配套反模式。其一是变量声明远离使用点——函数开头result_path compute_result_path(ctx)隔 20 行才用应改为save_to_path(transformed, compute_result_path(ctx))就地内联其二是把对象拆成单次使用的局部变量# WRONG: 无谓的字段抽取 result fetch_user(user_id) name result.name email result.email send_notification(name, email, role) # CORRECT: 直接访问字段 user fetch_user(user_id) send_notification(user.name, user.email, user.role)检查清单 9添加默认参数值之前原文条目95% 以上的调用者是否真的想要这个默认值忘记传参会不会引发隐蔽 bug是否有更安全的设计让选择显式化若默认值在任何地方都不被覆盖这个参数是否该存在默认要求显式传值消灭无人使用的默认值。api-design.md 将默认参数定性为重要的 bug 来源列出四个机理静默错误行为、隐藏的耦合默认值编码了未必对所有调用者成立的假设、难以审计所有调用点、重构风险新增带默认值的参数不会在旧调用点报错。其典型示例恰好与检查清单 2 呼应# DANGEROUS: 某些调用者可能用错的默认值 def process_file(path: Path, encoding: str utf-8) - str: return path.read_text(encodingencoding) # SAFER: 强制显式选择 def process_file(path: Path, encoding: str) - str: return path.read_text(encodingencoding)文档给出三个可接受的默认值用途默认值对 95% 以上调用者确实正确为既有 API 新增参数时的临时兼容测试辅助函数tests/test_utils/下的辅助器被明确豁免。最后一条操作指南是当发现某个默认值在所有调用点都从未被覆盖时直接删掉参数——例子里preserve_relative_pathTrue永远传True正确做法是删除该参数、把它变成函数固有行为。检查清单 10定义 5 个以上参数的函数之前原文条目是否在第一个参数或ctx后加了*是否只有self/ctx是位置参数这是否是 ABC/Protocol 方法豁免若使用ThreadPoolExecutor.submit()是否用了 lambda 包装默认第一个参数之后的所有参数都应为 keyword-only。api-design.md 的规则是参数 ≥5 的函数必须在语言层面强制 keyword-only在首个位置参数后放*使调用点自文档化。四个例外self语言要求、ctx/上下文对象约定上可作为首位位置参数、ABC/Protocol 方法避免迫使所有实现改签名、Click 回调Click 注入参数遵循 Click 约定。配套的ThreadPoolExecutor.submit()模式是submit()按位置传递参数对 keyword-only 函数必须用 lambda 包装# WRONG: submit() 按位置传参——keyword-only 函数会失败 future executor.submit(fetch_data, url, timeout, retries, headers, token) # CORRECT: lambda 使关键字参数可用 future executor.submit( lambda: fetch_data(url, timeouttimeout, retriesretries, headersheaders, auth_tokentoken) )这条规则在 Docling 源码中有直接体现服务客户端 docling/service_client/_async_client.py 中大量方法签名在首个参数后使用*分隔符L194、L205、L216、L226、L314 等十几处使后续选项参数只能以关键字方式传入——与清单第一个参数之后全部 keyword-only的默认结论一致。附加清单写模块级代码之前原文条目是否涉及任何计算哪怕Path()构造是否涉及 I/O文件、网络、环境变量是否可能失败或抛异常测试是否需要 mock 这个值任一回答为是就用cache装饰的函数包裹。module-design.md 解释的理由是导入时副作用的四个代价拖慢启动、测试脆弱难以 mock/控制行为、循环导入问题依赖被过早求值、执行顺序不可预测。它点名的三个反模式分别是导入时构造PathSESSION_ID_FILE Path(.app/scratch/current-session-id)、导入时加载配置CONFIG load_config()、导入时建立数据库连接DB_CLIENT DatabaseClient(os.environ[DB_URL])。推荐模式是functools.cache包裹的惰性求值函数from functools import cache # CORRECT: 延迟到首次调用 cache def _session_id_file_path() - Path: return Path(.app/scratch/current-session-id) cache def get_config() - Config: Load config on first call, cache result. return load_config()模块级代码只有简单静态常量是免检的DEFAULT_TIMEOUT 30、SUPPORTED_FORMATS frozenset({...})。Docling 的模型工厂模块正是这一模式的实践者docling/models/factories/init.py 中多个工厂函数使用lru_cache缓存将模型实例的创建延迟到首次调用L17、L25、L35此外 docling/datamodel/service/requests.py 与 docling/utils/pdf_outline.py 也使用了cache。结合 Docling 的 Python 基线pyproject.toml 中requires-python 3.10,4.0清单推荐的cache/lru_cache、X | None联合类型等语法均在 3.10 可用范围内。落地方法把检查清单嵌入提交前流程综合 SKILL.md 的使用说明与 checklists.md 自身的结构这套清单的标准用法是三步触发时机提交 Python 代码的最终审查、或怀疑自己遗漏某条规则时通读一遍 10 组清单——每组只需几秒因为问题都是二选一的判定句且组尾附有Default兜底结论深挖路由对某一组清单给出是的答案后按 SKILL.md 的When to Read Each Reference表跳转到对应专题文档异常 → exception-handling.md、接口 → interfaces.md、cast → typing-advanced.md、模块级代码/内联导入 → module-design.md、默认参数/多参数函数 → api-design.md获取完整正反例版本适配技能要求先探测项目最低 Python 版本依次查pyproject.toml的requires-python、setup.py/setup.cfg的python_requires、.python-version文件找不到则默认 3.12再加载对应的 versions/python-3.10.md 至 versions/python-3.13.md。对 Docling 而言requires-python 3.10,4.0意味着应按 3.10 为下限选用语法特性。需要强调的两个适用边界其一SKILL.md 明确声明这是通用 Python 风格指导而非某框架专属且捕获了一套显式、偏 LBYL 的约定——项目自身约定可以覆盖它例如 Docling 在 AGENTS.md 中额外要求避免hasattr/宽泛getattr探测、优先用 Pydantic 模型或 dataclass 承载跨模块的稳定数据这些项目级规则与清单并不冲突而是更严格的叠加其二清单中的默认破坏 API、立即迁移调用点、默认要求显式传值等条目是内部代码演化策略移植到已对外发布的库 API 时必须先过检查清单 5 的第 2 问是否存在外部消费者。小结这份 checklists.md 的价值在于把十类高频 Python 设计决策从散落在专题文档中的长文压缩成可在提交前 30 秒内过完的判定表且每一组都以一句加粗的Default结束——审查者无需在细节中权衡直接采用默认结论即可让异常冒泡、.exists()只为真实前提、cast 前加 O(1) 断言、内部代码用 ABC、默认破坏兼容、模块级导入、单一导入路径、单次使用即内联、消灭未使用的默认值、多参数强制 keyword-only、模块级计算改cache。这些默认值与 Docling 源码中的is_relative_to布尔校验html_backend.py、macros.py、keyword-only 签名_async_client.py、工厂lru_cachedocling/models/factories/init.py等实现相互印证构成了一套文档、技能清单与生产代码三层一致的 Python 工程规范。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Docling 的 Dignified Python 决策检查清单：Python 提交前审查的 10 个关键决策点
Docling 的 Dignified Python 决策检查清单Python 提交前审查的 10 个关键决策点【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文基于 Docling 仓库中.agents/skills/dignified-python/references/checklists.md这份提交前决策检查清单展开它把 LBYL 式异常处理、pathlib路径操作、typing.cast断言、ABC/Protocol 接口选择、默认参数设计等 10 类高频 Python 设计决策浓缩成可勾选的审查条目是 AI 编码代理与人工代码评审在提交 Python 代码前做最终把关的统一依据。读完后你不仅能掌握这份检查清单的每一条判定标准与默认结论还能看到 Docling 主代码库中is_relative_to、keyword-only 参数、cache延迟计算等对应的真实源码落点。检查清单的定位Dignified Python 技能体系的收口文件Docling 在仓库根目录维护了一套面向 AI 编码代理的开发技能包见 AGENTS.md 中的 Skills 章节贡献者技能位于.agents/skills/。其中dignified-python技能定位为面向 Python 3.10–3.13 的意见化生产级 Python 规范其入口文件 SKILL.md 明确说明了checklists.md的触发时机最终审查提交 Python 代码前的最终 review规则查漏不确定是否遵循了全部规则时快速查阅需要快速查询各项要求时。整个技能的阅读路由是分层设计的核心规范常驻加载dignified-python-core.md专题文档按需加载——写try/except时读 references/advanced/exception-handling.md定义接口时读 references/advanced/interfaces.md使用typing.cast()时读 references/advanced/typing-advanced.md设计函数签名时读 references/advanced/api-design.md。而 checklists.md 把这些专题文档中最关键的判定规则去上下文化压缩成一张可在几秒内过完的决策表——每个主题都给出勾选问题加一句加粗的Default默认结论避免审查者在细节文档间来回跳转。这份清单有一个贯穿性的哲学基调默认偏向 LBYLLook Before You Leap即当存在廉价且精确的前置条件检查时优先显式检查而不是用try/except兜底同时默认不保留向后兼容、默认模块级导入、默认要求显式传参。下面逐条解析。检查清单 1写try/except之前原文条目在错误边界吗CLI/API 层能否用廉价、精确的主动检查若不能围绕权威操作写一个小try/except是否更清晰是在添加有意义的上下文还是只是在掩盖是不是第三方 API 没有精确预检、迫使你用异常异常是否已被封装捕获的是具体异常而非宽泛异常若在错误边界捕获是否做了日志/警告绝不静默吞掉默认让异常向上冒泡。这条清单与专题文档 exception-handling.md 一一对应。该文档指出异常只在三种场景下是合适的工具错误边界CLI/API 层、调用本身就是权威判定的操作、以及重新抛出前补充上下文。核心判定法则是一条自问能否在调用 API 之前用一次廉价、精确的检查验证条件能就优先 LBYL如果操作本身就是权威验证器那么一个小的try/except往往更清晰。对应的反模式同样被明确禁止# WRONG: 静默吞掉异常即使在错误边界也不允许 try: optional_feature() except Exception: pass # 静默——问题将无法诊断 # CORRECT: 错误边界处至少记录日志 try: optional_feature() except Exception as e: logging.warning(Optional feature failed: %s, e)另一个高频细节是Ruff B904 异常链在except块内重新抛出时必须写from e保留原始 traceback或from None有意切断链例如异常信息已进入 CLI JSON 输出。Docling 的核心规范文档 dignified-python-core.md 给出的字典访问范式也属于这一条if key in mapping成员测试或.get(key, default)是正确写法而try: mapping[key] / except KeyError属于用异常做控制流的反模式。检查清单 2路径操作之前原文条目.exists()检查是否真的因文件系统存在性而必要若路径缺失应让.resolve()失败是否传了strictTrue是否把.is_relative_to()当作布尔判断而不是为它包一层ValueError捕获是否用了pathlib.Path而非os.path是否指定了encodingutf-8这条清单针对的是 pathlib 的三个常见误用核心文档 dignified-python-core.md 将其概括为黄金规则.exists()只在文件系统存在性构成操作前提时使用不要把它当作.resolve()或.is_relative_to()的盲目前置条件更不要用宽泛的except OSError包裹这些 API——那会掩盖意图而不是澄清意图。三条关键事实Python 3.11 的Path.resolve()对不存在的路径不会抛错除非显式传strictTruePath.is_relative_to()返回bool不抛ValueError——为它写try/except本身就是误解 APIread_text()/write_text()必须显式传encodingutf-8否则行为依赖平台默认编码。这一条在 Docling 源码中有大量真实落点。仓库多处路径安全校验都采用了清单认可的布尔式is_relative_to判断写法例如 HTML 后端判断资源路径是否越出本地基目录docling/backend/html_backend.pyreturn requested_path.is_relative_to(local_base_path.parent)LaTeX 宏处理器与 Tectonic 引擎用同样的模式防止相对路径逃逸出基准目录docling/backend/latex/handlers/macros.py、docling/backend/latex/engines/tectonic.py图片资源加载器 likewisedocling/backend/utils/image_resource_loader.py。这些代码全部是if not resolved.is_relative_to(base_dir): ...的布尔判断形式——正是清单第 3 问所要求的写法没有出现try/except ValueError包裹。同时docling/backend/xml/doclang_backend.py、docling/backend/latex/engines/tectonic.py 等文件中的文本读写均显式携带encodingutf-8与清单第 5 问一致。值得注意的是AGENTS.md 的 Code standards 章节把这条规则提升为项目级约定新代码或修改代码优先使用pathlib.Path除非 API 明确要求字符串路径——也就是说这份技能清单与 Docling 的官方贡献规范是相互印证的。检查清单 3使用typing.cast()之前原文条目是否为 cast 加了运行时断言来验证断言成本是否平凡O(1)若是始终加上。若跳过是否因为刚刚做过isinstance检查冗余若因性能跳过是否记录了实测开销默认成本平凡时cast 前始终加运行时断言。typing-advanced.md 对此的解释是typing.cast()是纯编译期构造运行期不做任何校验如果假设错了得到的是静默错误行为而不是清晰的报错。规范要求模式是先断言、再 castassert isinstance(doc, MutableMapping), fExpected MutableMapping, got {type(doc)} cast(dict[str, Any], doc)[key] value跳过断言只有两个正当理由一是在isinstance类型守卫刚刚执行完之后重复检查二是热路径上有实测的性能开销且必须用注释记录示例注释called 10M times/sec, isinstance adds 15% overhead。文档同时列出了三个不成立的跳过理由框架会验证取值集合、库保证类型、从上下文显然——这三种情况都应照常加断言因为断言本身就是给未来读者的文档也构成防御性纵深第三方库跨版本可能改变行为。检查清单 4定义接口ABC 或 Protocol之前原文条目是否拥有所有实现是 → 优先 ABC。是否在包装第三方库是 → 优先 Protocol。是否需要运行时isinstance()校验是 → 用 ABC。接口是否足够小1–2 个方法是 → Protocol 可能更简单。是否需要共享方法实现是 → 用 ABC。默认自己拥有的内部代码用 ABC外部库门面用 Protocol。interfaces.md 给出的完整决策矩阵是使用场景推荐原因自己控制的内部接口ABC显式强制、运行时校验、代码复用第三方库边界Protocol无需继承、松耦合需要isinstance检查的插件体系ABC可靠的运行时类型校验最小接口契约1–2 个方法Protocol样板更少、契约聚焦文档同时指出了 Protocol 的三点局限runtime_checkable只检查方法存在性、不校验签名Protocol 不应携带方法实现无法复用代码isinstance()检查比 ABC 弱。从 Docling 源码结构看项目内部基类走的是显式继承 共享实现路线——例如 OCR 模型基类BaseOcrModeldocling/models/base_ocr_model.py在基类中提供通用的 OCR 功能供各具体模型复用这正是清单第 5 问需要共享方法实现 → 用 ABC基类所对应的形态。检查清单 5保留向后兼容之前原文条目用户是否明确要求是否有外部消费者的公共 API是否已记录保留原因迁移成本是否高到无法承受默认破坏 API立即迁移所有调用点。这是清单中最激进的一条核心文档 dignified-python-core.md 给出的立场是默认不保留向后兼容反模式示例是一个legacy_format: bool False开关参数——正确做法是直接删除旧路径、一次性改完所有调用点。保留兼容只在三个条件下成立代码明确属于公共 API、用户显式要求、迁移成本高到无法承受罕见。宣称的收益是更干净的代码库、更快的迭代、不积累遗留代码、更简单的心智模型。需要说明的是这一条主要针对应用内部代码的演化策略对已经发布的库级公共 API 需按清单第 2 问谨慎评估。检查清单 6函数内联导入之前原文条目是为了打破循环依赖是为了TYPE_CHECKING是为了条件特性若为了启动时间是否测量过导入成本成本是否显著100ms是否在注释中记录了实测成本是否已记录内联导入的原因默认模块级导入。module-design.md 把合法的内联导入收敛到四类场景打破循环依赖典型如 CLI 命令注册函数体内导入避免双向依赖TYPE_CHECKING导入仅为类型提示避免运行时循环条件特性dry-run 模式包装器、平台相关实现等启动时间优化罕见——只针对确实重量级的包如大型 ML 框架且必须遵循无罪推定原则默认模块级导入只有在有实测证据表明导入显著拖慢启动100ms时才延迟并用注释记录实测成本示例# Heavy: 800ms import time。文档明确列出不应延迟导入的对象标准库、轻量内部模块、未测量过的模块、以及任何以防万一的优化。检查清单 7导入/再导出符号之前原文条目该符号是否已有规范位置是否在创建同一符号的第二条导入路径若这是 shim 模块是否只导入了本模块用途所需是否避免了__all__导出默认从规范位置导入绝不再导出。核心文档 dignified-python-core.md 的表述是每个符号恰好只有一条导入路径。反模式是在包的__init__.py里from myapp.core import Process并配__all__——这会制造重复导入路径正确做法是保持空__init__.py使用方直接from myapp.core import Process。唯一例外是插件入口点等必须再导出的场景此时要求显式import X as X语法from myapp.core.feature import my_function as my_function让再导出在代码中显式可见。检查清单 8声明局部变量之前原文条目变量是否被使用超过一次是否在使用点附近声明内联计算会不会损害可读性是否在把对象字段抽成只用一次的局部变量默认单次使用的计算内联到调用点对象属性直接访问。核心文档给出了两个配套反模式。其一是变量声明远离使用点——函数开头result_path compute_result_path(ctx)隔 20 行才用应改为save_to_path(transformed, compute_result_path(ctx))就地内联其二是把对象拆成单次使用的局部变量# WRONG: 无谓的字段抽取 result fetch_user(user_id) name result.name email result.email send_notification(name, email, role) # CORRECT: 直接访问字段 user fetch_user(user_id) send_notification(user.name, user.email, user.role)检查清单 9添加默认参数值之前原文条目95% 以上的调用者是否真的想要这个默认值忘记传参会不会引发隐蔽 bug是否有更安全的设计让选择显式化若默认值在任何地方都不被覆盖这个参数是否该存在默认要求显式传值消灭无人使用的默认值。api-design.md 将默认参数定性为重要的 bug 来源列出四个机理静默错误行为、隐藏的耦合默认值编码了未必对所有调用者成立的假设、难以审计所有调用点、重构风险新增带默认值的参数不会在旧调用点报错。其典型示例恰好与检查清单 2 呼应# DANGEROUS: 某些调用者可能用错的默认值 def process_file(path: Path, encoding: str utf-8) - str: return path.read_text(encodingencoding) # SAFER: 强制显式选择 def process_file(path: Path, encoding: str) - str: return path.read_text(encodingencoding)文档给出三个可接受的默认值用途默认值对 95% 以上调用者确实正确为既有 API 新增参数时的临时兼容测试辅助函数tests/test_utils/下的辅助器被明确豁免。最后一条操作指南是当发现某个默认值在所有调用点都从未被覆盖时直接删掉参数——例子里preserve_relative_pathTrue永远传True正确做法是删除该参数、把它变成函数固有行为。检查清单 10定义 5 个以上参数的函数之前原文条目是否在第一个参数或ctx后加了*是否只有self/ctx是位置参数这是否是 ABC/Protocol 方法豁免若使用ThreadPoolExecutor.submit()是否用了 lambda 包装默认第一个参数之后的所有参数都应为 keyword-only。api-design.md 的规则是参数 ≥5 的函数必须在语言层面强制 keyword-only在首个位置参数后放*使调用点自文档化。四个例外self语言要求、ctx/上下文对象约定上可作为首位位置参数、ABC/Protocol 方法避免迫使所有实现改签名、Click 回调Click 注入参数遵循 Click 约定。配套的ThreadPoolExecutor.submit()模式是submit()按位置传递参数对 keyword-only 函数必须用 lambda 包装# WRONG: submit() 按位置传参——keyword-only 函数会失败 future executor.submit(fetch_data, url, timeout, retries, headers, token) # CORRECT: lambda 使关键字参数可用 future executor.submit( lambda: fetch_data(url, timeouttimeout, retriesretries, headersheaders, auth_tokentoken) )这条规则在 Docling 源码中有直接体现服务客户端 docling/service_client/_async_client.py 中大量方法签名在首个参数后使用*分隔符L194、L205、L216、L226、L314 等十几处使后续选项参数只能以关键字方式传入——与清单第一个参数之后全部 keyword-only的默认结论一致。附加清单写模块级代码之前原文条目是否涉及任何计算哪怕Path()构造是否涉及 I/O文件、网络、环境变量是否可能失败或抛异常测试是否需要 mock 这个值任一回答为是就用cache装饰的函数包裹。module-design.md 解释的理由是导入时副作用的四个代价拖慢启动、测试脆弱难以 mock/控制行为、循环导入问题依赖被过早求值、执行顺序不可预测。它点名的三个反模式分别是导入时构造PathSESSION_ID_FILE Path(.app/scratch/current-session-id)、导入时加载配置CONFIG load_config()、导入时建立数据库连接DB_CLIENT DatabaseClient(os.environ[DB_URL])。推荐模式是functools.cache包裹的惰性求值函数from functools import cache # CORRECT: 延迟到首次调用 cache def _session_id_file_path() - Path: return Path(.app/scratch/current-session-id) cache def get_config() - Config: Load config on first call, cache result. return load_config()模块级代码只有简单静态常量是免检的DEFAULT_TIMEOUT 30、SUPPORTED_FORMATS frozenset({...})。Docling 的模型工厂模块正是这一模式的实践者docling/models/factories/init.py 中多个工厂函数使用lru_cache缓存将模型实例的创建延迟到首次调用L17、L25、L35此外 docling/datamodel/service/requests.py 与 docling/utils/pdf_outline.py 也使用了cache。结合 Docling 的 Python 基线pyproject.toml 中requires-python 3.10,4.0清单推荐的cache/lru_cache、X | None联合类型等语法均在 3.10 可用范围内。落地方法把检查清单嵌入提交前流程综合 SKILL.md 的使用说明与 checklists.md 自身的结构这套清单的标准用法是三步触发时机提交 Python 代码的最终审查、或怀疑自己遗漏某条规则时通读一遍 10 组清单——每组只需几秒因为问题都是二选一的判定句且组尾附有Default兜底结论深挖路由对某一组清单给出是的答案后按 SKILL.md 的When to Read Each Reference表跳转到对应专题文档异常 → exception-handling.md、接口 → interfaces.md、cast → typing-advanced.md、模块级代码/内联导入 → module-design.md、默认参数/多参数函数 → api-design.md获取完整正反例版本适配技能要求先探测项目最低 Python 版本依次查pyproject.toml的requires-python、setup.py/setup.cfg的python_requires、.python-version文件找不到则默认 3.12再加载对应的 versions/python-3.10.md 至 versions/python-3.13.md。对 Docling 而言requires-python 3.10,4.0意味着应按 3.10 为下限选用语法特性。需要强调的两个适用边界其一SKILL.md 明确声明这是通用 Python 风格指导而非某框架专属且捕获了一套显式、偏 LBYL 的约定——项目自身约定可以覆盖它例如 Docling 在 AGENTS.md 中额外要求避免hasattr/宽泛getattr探测、优先用 Pydantic 模型或 dataclass 承载跨模块的稳定数据这些项目级规则与清单并不冲突而是更严格的叠加其二清单中的默认破坏 API、立即迁移调用点、默认要求显式传值等条目是内部代码演化策略移植到已对外发布的库 API 时必须先过检查清单 5 的第 2 问是否存在外部消费者。小结这份 checklists.md 的价值在于把十类高频 Python 设计决策从散落在专题文档中的长文压缩成可在提交前 30 秒内过完的判定表且每一组都以一句加粗的Default结束——审查者无需在细节中权衡直接采用默认结论即可让异常冒泡、.exists()只为真实前提、cast 前加 O(1) 断言、内部代码用 ABC、默认破坏兼容、模块级导入、单一导入路径、单次使用即内联、消灭未使用的默认值、多参数强制 keyword-only、模块级计算改cache。这些默认值与 Docling 源码中的is_relative_to布尔校验html_backend.py、macros.py、keyword-only 签名_async_client.py、工厂lru_cachedocling/models/factories/init.py等实现相互印证构成了一套文档、技能清单与生产代码三层一致的 Python 工程规范。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考