docling dignified-python 技能一套带自动版本检测3.10–3.13的生产级 Python 编码规范【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文解析 docling 仓库中随仓库分发的dignified-pythonAgent 技能它是一套有明确立场opinionated的现代 Python 生产规范覆盖 LBYL 异常处理、pathlib 路径操作、导入组织、接口设计与 API 设计等核心主题并内置按项目requires-python自动路由到 3.10–3.13 各版本特性文件的机制。读完本文你可以理解该技能的文档组织结构与按需加载逻辑掌握其核心编码规则与反模式清单并能将同样的版本探测流程与决策检查表套用到任何 Python 项目上。一、这是什么docling 内置的 Agent 编码标准技能dignified-python是存放在仓库根目录.agents/skills/dignified-python/下的一组 Markdown 技能文件。根据 AGENTS.md 对仓库结构的说明.agents/skills/存放的是开发技能development skills面向参与开发 Docling 本身的 AI 编码 Agent与之相对真正供使用方 Agent 的用法技能则打包在docling/.agents/skills/docling/内并随 wheel 分发。两者定位不同dignified-python属于前者。技能入口文件 SKILL.md 的 YAML frontmatter 声明了技能元数据与引用清单--- name: dignified-python description: Opinionated production Python standards with automatic version detection (3.10-3.13). Use when writing, reviewing, or refactoring Python in repos that want modern type syntax, explicit condition checks where practical, pathlib operations, interface guidance, and pragmatic production patterns. references: - dignified-python-core - cli-patterns - versions/python-3.10 - versions/python-3.11 - versions/python-3.12 - versions/python-3.13 - references/advanced/api-design - references/advanced/exception-handling - references/advanced/interfaces - references/advanced/typing-advanced ---目录中的完整文件布局与 SKILL.md 的引用清单一一对应文件职责加载策略dignified-python-core.md核心规范80% 代码模式始终加载cli-patterns.mdCLI 模式click、argparse检测到 click/CLI 时加载subprocess.md子进程操作模式检测到 subprocess 时加载versions/python-3.10.md 至 python-3.13.md各版本可用特性版本探测后按最低版本加载对应文件references/advanced/exception-handling.mdLBYL 模式、错误边界、B904 链式异常按需references/advanced/interfaces.mdABC 与 Protocol 模式按需references/advanced/typing-advanced.md高级 typing 模式按需references/advanced/api-design.mdAPI 设计原则按需references/module-design.md模块级代码、导入期副作用、cache按需references/checklists.md提交前决策检查表合集按需SKILL.md 特别强调了两点边界该技能是通用 Python 风格指南刻意只捕获一套显式、偏 LBYL的约定当项目自身约定冲突时以项目约定为准项目约定可以覆盖它。它不用于 Dagster 专属问题——SKILL.md 中的对照表明确best practices for dagster、implement X pipeline、which integration to use应交给/dagster-best-practices、/dg、/dagster-expert而make this pythonic、type hints、LBYL vs EAFP、pathlib vs os.path、CLI argument parsing、code review等属于本技能射程。二、自动版本探测技能的核心机制SKILL.md 的 Version Detection 小节定义了一个确定性的四步探测顺序用于判断项目的最低Python 版本查pyproject.toml的requires-python字段例如requires-python 3.12查setup.py/setup.cfg的python_requires查.python-version文件内容为3.12或3.12.0之类均未找到时默认按 Python 3.12 处理。确定版本后仅加载对应的版本文件3.10 →versions/python-3.10.md3.11 →versions/python-3.11.md3.12 →versions/python-3.12.md3.13 →versions/python-3.13.md。这一机制可以直接在 docling 自身仓库上验证pyproject.toml 第 46 行声明requires-python 3.10,4.0按探测规则第 1 步即命中最低版本为 3.10因此针对本仓库的任务应加载 versions/python-3.10.md结构化模式匹配match/case、X | Y类型联合、括号化上下文管理器等 3.10 特性而不应建议使用 3.11 的except*异常组、3.12 的type语法或 3.13 的实验性 free-threading 特性。参考目录的 references/README.md 中列出的各版本特性摘要与之一致。三、核心规范始终加载的 80% 模式dignified-python-core.md 是每次调用都加载的核心文件覆盖六类规则。3.1 默认立场优先显式前置条件LBYL技能对 LBYLLook Before You Leap/ EAFPEasier to Ask for Forgiveness than Permission采取明确立场当日常分支的前置条件廉价且精确时默认 LBYL当操作本身就是权威判据、或在边界处翻译错误时才用 EAFP。字典访问的标准写法# CORRECT: Membership testing if key in mapping: value mapping[key] process(value) else: handle_missing() # ALSO CORRECT: .get() with default value mapping.get(key, default_value) process(value) # CORRECT: Check before nested access if config in data and timeout in data[config]: timeout data[config][timeout] # WRONG: KeyError as control flow try: value mapping[key] except KeyError: handle_missing()例外异常仍然合适的三类场景错误边界CLI/API 层、调用本身即权威测试的操作、以及补充上下文后重新抛出。其余情况默认让异常继续向上传播而不是到处捕获。3.2 路径操作pathlib黄金法则核心文件给出了三条关键事实依据解释了为什么不应该给resolve()/is_relative_to()套宽泛的try/exceptPython 3.11 起Path.resolve()对不存在的路径不会抛错除非显式传strictTruePath.is_relative_to()返回bool路径不在子树内时返回False不抛ValueError给这些 API 包宽异常通常是在掩盖意图而不是澄清意图。正确模式from pathlib import Path # CORRECT: Check existence only when you need a real filesystem entry for wt_path in worktree_paths: wt_path_resolved wt_path.resolve() if not wt_path_resolved.exists(): continue if current_dir.is_relative_to(wt_path_resolved): current_worktree wt_path_resolved break # ALSO CORRECT: Ask resolve() to fail when absence is an error config_dir config_path.resolve(strictTrue)同时要求永远用pathlib.Path而非os.path读写文本时永远显式指定编码read_text(encodingutf-8)避免平台相关默认编码。这一条与 docling 仓库自身的约定完全一致——AGENTS.md 的 Code standards 一节明确要求Prefer pathlib.Path for path-handling code. Use Path operations instead of os.path in new or edited code unless an API explicitly requires string paths。3.3 导入组织三条核心规则默认所有导入放在模块级只用绝对导入禁止from .config import ...相对导入行内导入仅限特定例外打破循环依赖、TYPE_CHECKING、条件功能。模块级细节何时可用行内导入、启动耗时优化必须先测量后延迟、cache延迟计算、模块级常量的合法边界在 references/module-design.md 中展开例如把导入期的 I/O 反模式DB_CLIENT DatabaseClient(os.environ[DB_URL])改写为cache装饰的get_db_client()。3.4 性能约束property 与魔术方法必须 O(1)# WRONG: Property doing I/O property def size(self) - int: return self._fetch_from_db() # CORRECT: Explicit method name def fetch_size_from_db(self) - int: return self._fetch_from_db()__len__同样禁止内部迭代计数应维护_count后 O(1) 返回。3.5 反模式清单核心文件列出六类必须避免的写法每条都配有 WRONG/CORRECT 对照反模式规则要点默认不保留向后兼容不要留legacy_format: bool False之类的旧 API 分支仅当代码确属公共 API、用户明确要求、或迁移成本过高时才保留禁止再导出每个符号只有一条规范导入路径__init__.py保持空不要__all__式导出。确需插件入口时显式写import X as X变量声明贴近使用点声明与使用相距 20 行的局部变量应内联到调用处不要解构单次使用的对象result.name/result.email各只用一次时直接send_notification(user.name, user.email, user.role)缩进深度上限 4 层超过即抽取辅助函数上下文管理器保持内联with (cm_a if condition else nullcontext()):优于先抽成中间变量因为__enter__/__exit__生命周期在with语句中才显式可见3.6 现代类型语法references/README.md 的 Philosophy 一节把这一点列为首要原则全量使用 3.10 语法——list[str]、dict[str, int]、str | None而不是List[str]/Optional[str]。docling 源码本身即是这种风格的实例例如 docling/backend/iwork/pages_backend.py、docling/backend/msword_backend.py 等大量模块直接使用str | None联合类型AGENTS.md 也要求 Keep public APIs typed and compatible with Python 3.10。四、进阶参考按需加载的四个专题SKILL.md 的 When to Read Each Reference 小节为每个进阶文件定义了触发条件这是该技能渐进式加载设计的关键——核心文件覆盖 80% 场景其余文件只在检测到特定模式时才读取。4.1 异常处理写 try/except、包第三方 API、见到from e/from None时读取references/advanced/exception-handling.md 的增量内容包括B904 异常链Ruff lint 合规在except块内raise必须显式声明链。from e用于保留原始 traceback 便于调试from None用于有意切断链如异常信息已经进了 CLI 的 JSON 输出traceback 对终端用户无意义。裸raise SystemExit(1)而不写from e会被 B904 判为违规。用真实解析器替代脆弱的预检查不要用手搓的str.isdigit()或 ISO 日期形状检查去替代解析调用——这类检查经常拒绝合法输入、放行非法输入。当try / parse / default模式反复出现时抽取通用助手from typing import TypeVar, Callable T TypeVar(T) def try_parse(parse: Callable[[str], T], value: str, default: T) - T: Parse *value* with *parse*, returning *default* on ValueError. try: return parse(value) except ValueError: return default port try_parse(int, user_input, 80) ts try_parse(datetime.fromisoformat, timestamp_str, None)两条硬性禁令永远不要静默吞异常即使错误边界也要logging.warning至少留痕永远不要用静默降级except Exception: return regex_parse_fallback(...)会掩盖真实故障应让错误冒泡到边界。docling 的 CLI 入口 docling/cli/main.py 展示了与错误边界原则相符的结构文件系统类错误FileNotFoundError、IsADirectoryError、PermissionError等在命令执行层被分类捕获并转成用户可读的提示而不是散落在业务深处见 docling/cli/main.py#L1242-L1265。4.2 接口设计创建 ABC/Protocol、写abstractmethod时读取references/advanced/interfaces.md 给出选择矩阵与两条默认使用场景推荐理由自己掌控的内部接口ABC显式强制、运行时校验、可复用具体方法第三方库边界Protocol无需继承、松耦合需要isinstance校验的插件系统ABC可靠的运行时类型校验1–2 个方法的最小契约Protocol样板代码更少即内部自持代码默认 ABC外部库门面默认 Protocol。参考文档还给出了完整的依赖注入示例DataStoreABC RedisStore实现 FakeStore测试替身 dataclass Service依赖抽象以及 Protocol 的三条局限runtime_checkable只查方法存在性不查签名、不能承载共享实现、isinstance校验较弱。4.3 模块设计新建模块、模块级代码、cache时读取references/module-design.md 的核心规则是避免导入期的计算与副作用延迟到函数调用。导入期副作用的四个代价启动更慢、测试脆弱难以 mock、循环导入风险、行为依赖导入顺序。合法模块级代码仅限静态常量DEFAULT_TIMEOUT 30、SUPPORTED_FORMATS frozenset({...})。行内导入的四个合法场景——打破循环依赖、条件功能、TYPE_CHECKING、有测量证据的启动耗时优化且成本需 100ms 并在注释中记录实测值——各配有代码示例与 When NOT to defer 清单。4.4 API 设计与高级 typing审查函数签名时读取references/advanced/api-design.md 的触发条件给函数加默认参数值、定义 5 参数函数、使用ThreadPoolExecutor.submit()、审查函数签名。references/advanced/typing-advanced.md 的触发条件使用typing.cast()、创建Literal类型别名、在条件块中做类型收窄。五、决策检查表提交前的最后一道闸references/checklists.md 把全文规则压缩成九组动手前自问清单每组以加粗一行给出默认立场。摘录最能代表该技能哲学的一组写try/except之前是否在错误边界能否用廉价精确的检查前置是否在捕获具体异常而非宽泛异常边界处是否记录了日志永不静默吞默认让异常冒泡。路径操作之前.exists()是否因文件系统存在性确实是需求缺路径应报错时是否传了strictTrue.is_relative_to()是否当布尔用而非包ValueError是否指定了encodingutf-8用typing.cast()之前是否加了运行时断言断言成本 O(1) 时必须加。默认成本可忽略就永远加断言。保留向后兼容之前用户是否明确要求是否公共 API默认直接破坏 API 并立即迁移调用点。行内导入之前若为启动耗时是否实测过、是否 100ms、是否在注释中记录默认模块级导入。声明局部变量之前是否只用一次是否贴近声明点默认单次计算内联到调用点。六、技能的使用流程与 docling 仓库的落地验证SKILL.md 的 How to Use This Skill 定义了五步工作流核心知识自动加载默认立场、pathlib、导入、反模式版本探测只做一次——确定最低 Python 版本并加载对应版本文件参考文档按需加载依据上文各小节的触发模式附加模式按需额外加载CLI 模式、subprocess每个文件自包含其领域内的指导完整独立。放到 docling 仓库的实际开发场景中这套流程与仓库既有约定形成闭环版本探测pyproject.toml 中requires-python 3.10,4.0→ 加载 python-3.10 特性文件AGENTS.md 同步要求公共 API 保持 3.10 类型兼容。pathlib 优先、避免属性探测AGENTS.md 的 Code standards 与技能核心文件互相印证甚至更严格地补充了一条避免hasattr(...)、宽泛getattr(...)之类的属性探测这类检查通常掩盖了接口上的不确定性。数据模型AGENTS.md 要求跨模块边界、被序列化或作为稳定契约的数据优先用 Pydantic 模型或 dataclass 而非松散字典——这与 references/advanced/interfaces.md 中 DI 示例使用dataclass Service依赖抽象的思路一致。验证手段仓库提供的make setup/make test/make check只读校验/make validate变更钩子命令见 AGENTS.md 的 Key commands 与 Makefile构成完成前必跑的落地检查而技能中 B904 异常链、编码显式化等规则正是这类静态检查会捕获的类别。七、小结dignified-python的价值不在于罗列零散技巧而在于把何时查条件、何时抛异常、何时延迟、何时断言这类判断固化成了带默认立场的规则集并用始终加载核心 版本探测 触发式按需加载的结构控制 Agent 的上下文开销。对 docling 这类要求 3.10 类型兼容、pathlib 优先、边界处处理异常的 Python 仓库而言它与 AGENTS.md 中的项目级约定共同构成了 AI 辅助编码时的可执行质量基线。主要参考文件SKILL.md、dignified-python-core.md、references/README.md、references/checklists.md、references/module-design.md、references/advanced/exception-handling.md、references/advanced/interfaces.md、AGENTS.md、pyproject.toml、docling/cli/main.py。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
docling dignified-python 技能一套带自动版本检测3.10–3.13的生产级 Python 编码规范【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文解析 docling 仓库中随仓库分发的dignified-pythonAgent 技能它是一套有明确立场opinionated的现代 Python 生产规范覆盖 LBYL 异常处理、pathlib 路径操作、导入组织、接口设计与 API 设计等核心主题并内置按项目requires-python自动路由到 3.10–3.13 各版本特性文件的机制。读完本文你可以理解该技能的文档组织结构与按需加载逻辑掌握其核心编码规则与反模式清单并能将同样的版本探测流程与决策检查表套用到任何 Python 项目上。一、这是什么docling 内置的 Agent 编码标准技能dignified-python是存放在仓库根目录.agents/skills/dignified-python/下的一组 Markdown 技能文件。根据 AGENTS.md 对仓库结构的说明.agents/skills/存放的是开发技能development skills面向参与开发 Docling 本身的 AI 编码 Agent与之相对真正供使用方 Agent 的用法技能则打包在docling/.agents/skills/docling/内并随 wheel 分发。两者定位不同dignified-python属于前者。技能入口文件 SKILL.md 的 YAML frontmatter 声明了技能元数据与引用清单--- name: dignified-python description: Opinionated production Python standards with automatic version detection (3.10-3.13). Use when writing, reviewing, or refactoring Python in repos that want modern type syntax, explicit condition checks where practical, pathlib operations, interface guidance, and pragmatic production patterns. references: - dignified-python-core - cli-patterns - versions/python-3.10 - versions/python-3.11 - versions/python-3.12 - versions/python-3.13 - references/advanced/api-design - references/advanced/exception-handling - references/advanced/interfaces - references/advanced/typing-advanced ---目录中的完整文件布局与 SKILL.md 的引用清单一一对应文件职责加载策略dignified-python-core.md核心规范80% 代码模式始终加载cli-patterns.mdCLI 模式click、argparse检测到 click/CLI 时加载subprocess.md子进程操作模式检测到 subprocess 时加载versions/python-3.10.md 至 python-3.13.md各版本可用特性版本探测后按最低版本加载对应文件references/advanced/exception-handling.mdLBYL 模式、错误边界、B904 链式异常按需references/advanced/interfaces.mdABC 与 Protocol 模式按需references/advanced/typing-advanced.md高级 typing 模式按需references/advanced/api-design.mdAPI 设计原则按需references/module-design.md模块级代码、导入期副作用、cache按需references/checklists.md提交前决策检查表合集按需SKILL.md 特别强调了两点边界该技能是通用 Python 风格指南刻意只捕获一套显式、偏 LBYL的约定当项目自身约定冲突时以项目约定为准项目约定可以覆盖它。它不用于 Dagster 专属问题——SKILL.md 中的对照表明确best practices for dagster、implement X pipeline、which integration to use应交给/dagster-best-practices、/dg、/dagster-expert而make this pythonic、type hints、LBYL vs EAFP、pathlib vs os.path、CLI argument parsing、code review等属于本技能射程。二、自动版本探测技能的核心机制SKILL.md 的 Version Detection 小节定义了一个确定性的四步探测顺序用于判断项目的最低Python 版本查pyproject.toml的requires-python字段例如requires-python 3.12查setup.py/setup.cfg的python_requires查.python-version文件内容为3.12或3.12.0之类均未找到时默认按 Python 3.12 处理。确定版本后仅加载对应的版本文件3.10 →versions/python-3.10.md3.11 →versions/python-3.11.md3.12 →versions/python-3.12.md3.13 →versions/python-3.13.md。这一机制可以直接在 docling 自身仓库上验证pyproject.toml 第 46 行声明requires-python 3.10,4.0按探测规则第 1 步即命中最低版本为 3.10因此针对本仓库的任务应加载 versions/python-3.10.md结构化模式匹配match/case、X | Y类型联合、括号化上下文管理器等 3.10 特性而不应建议使用 3.11 的except*异常组、3.12 的type语法或 3.13 的实验性 free-threading 特性。参考目录的 references/README.md 中列出的各版本特性摘要与之一致。三、核心规范始终加载的 80% 模式dignified-python-core.md 是每次调用都加载的核心文件覆盖六类规则。3.1 默认立场优先显式前置条件LBYL技能对 LBYLLook Before You Leap/ EAFPEasier to Ask for Forgiveness than Permission采取明确立场当日常分支的前置条件廉价且精确时默认 LBYL当操作本身就是权威判据、或在边界处翻译错误时才用 EAFP。字典访问的标准写法# CORRECT: Membership testing if key in mapping: value mapping[key] process(value) else: handle_missing() # ALSO CORRECT: .get() with default value mapping.get(key, default_value) process(value) # CORRECT: Check before nested access if config in data and timeout in data[config]: timeout data[config][timeout] # WRONG: KeyError as control flow try: value mapping[key] except KeyError: handle_missing()例外异常仍然合适的三类场景错误边界CLI/API 层、调用本身即权威测试的操作、以及补充上下文后重新抛出。其余情况默认让异常继续向上传播而不是到处捕获。3.2 路径操作pathlib黄金法则核心文件给出了三条关键事实依据解释了为什么不应该给resolve()/is_relative_to()套宽泛的try/exceptPython 3.11 起Path.resolve()对不存在的路径不会抛错除非显式传strictTruePath.is_relative_to()返回bool路径不在子树内时返回False不抛ValueError给这些 API 包宽异常通常是在掩盖意图而不是澄清意图。正确模式from pathlib import Path # CORRECT: Check existence only when you need a real filesystem entry for wt_path in worktree_paths: wt_path_resolved wt_path.resolve() if not wt_path_resolved.exists(): continue if current_dir.is_relative_to(wt_path_resolved): current_worktree wt_path_resolved break # ALSO CORRECT: Ask resolve() to fail when absence is an error config_dir config_path.resolve(strictTrue)同时要求永远用pathlib.Path而非os.path读写文本时永远显式指定编码read_text(encodingutf-8)避免平台相关默认编码。这一条与 docling 仓库自身的约定完全一致——AGENTS.md 的 Code standards 一节明确要求Prefer pathlib.Path for path-handling code. Use Path operations instead of os.path in new or edited code unless an API explicitly requires string paths。3.3 导入组织三条核心规则默认所有导入放在模块级只用绝对导入禁止from .config import ...相对导入行内导入仅限特定例外打破循环依赖、TYPE_CHECKING、条件功能。模块级细节何时可用行内导入、启动耗时优化必须先测量后延迟、cache延迟计算、模块级常量的合法边界在 references/module-design.md 中展开例如把导入期的 I/O 反模式DB_CLIENT DatabaseClient(os.environ[DB_URL])改写为cache装饰的get_db_client()。3.4 性能约束property 与魔术方法必须 O(1)# WRONG: Property doing I/O property def size(self) - int: return self._fetch_from_db() # CORRECT: Explicit method name def fetch_size_from_db(self) - int: return self._fetch_from_db()__len__同样禁止内部迭代计数应维护_count后 O(1) 返回。3.5 反模式清单核心文件列出六类必须避免的写法每条都配有 WRONG/CORRECT 对照反模式规则要点默认不保留向后兼容不要留legacy_format: bool False之类的旧 API 分支仅当代码确属公共 API、用户明确要求、或迁移成本过高时才保留禁止再导出每个符号只有一条规范导入路径__init__.py保持空不要__all__式导出。确需插件入口时显式写import X as X变量声明贴近使用点声明与使用相距 20 行的局部变量应内联到调用处不要解构单次使用的对象result.name/result.email各只用一次时直接send_notification(user.name, user.email, user.role)缩进深度上限 4 层超过即抽取辅助函数上下文管理器保持内联with (cm_a if condition else nullcontext()):优于先抽成中间变量因为__enter__/__exit__生命周期在with语句中才显式可见3.6 现代类型语法references/README.md 的 Philosophy 一节把这一点列为首要原则全量使用 3.10 语法——list[str]、dict[str, int]、str | None而不是List[str]/Optional[str]。docling 源码本身即是这种风格的实例例如 docling/backend/iwork/pages_backend.py、docling/backend/msword_backend.py 等大量模块直接使用str | None联合类型AGENTS.md 也要求 Keep public APIs typed and compatible with Python 3.10。四、进阶参考按需加载的四个专题SKILL.md 的 When to Read Each Reference 小节为每个进阶文件定义了触发条件这是该技能渐进式加载设计的关键——核心文件覆盖 80% 场景其余文件只在检测到特定模式时才读取。4.1 异常处理写 try/except、包第三方 API、见到from e/from None时读取references/advanced/exception-handling.md 的增量内容包括B904 异常链Ruff lint 合规在except块内raise必须显式声明链。from e用于保留原始 traceback 便于调试from None用于有意切断链如异常信息已经进了 CLI 的 JSON 输出traceback 对终端用户无意义。裸raise SystemExit(1)而不写from e会被 B904 判为违规。用真实解析器替代脆弱的预检查不要用手搓的str.isdigit()或 ISO 日期形状检查去替代解析调用——这类检查经常拒绝合法输入、放行非法输入。当try / parse / default模式反复出现时抽取通用助手from typing import TypeVar, Callable T TypeVar(T) def try_parse(parse: Callable[[str], T], value: str, default: T) - T: Parse *value* with *parse*, returning *default* on ValueError. try: return parse(value) except ValueError: return default port try_parse(int, user_input, 80) ts try_parse(datetime.fromisoformat, timestamp_str, None)两条硬性禁令永远不要静默吞异常即使错误边界也要logging.warning至少留痕永远不要用静默降级except Exception: return regex_parse_fallback(...)会掩盖真实故障应让错误冒泡到边界。docling 的 CLI 入口 docling/cli/main.py 展示了与错误边界原则相符的结构文件系统类错误FileNotFoundError、IsADirectoryError、PermissionError等在命令执行层被分类捕获并转成用户可读的提示而不是散落在业务深处见 docling/cli/main.py#L1242-L1265。4.2 接口设计创建 ABC/Protocol、写abstractmethod时读取references/advanced/interfaces.md 给出选择矩阵与两条默认使用场景推荐理由自己掌控的内部接口ABC显式强制、运行时校验、可复用具体方法第三方库边界Protocol无需继承、松耦合需要isinstance校验的插件系统ABC可靠的运行时类型校验1–2 个方法的最小契约Protocol样板代码更少即内部自持代码默认 ABC外部库门面默认 Protocol。参考文档还给出了完整的依赖注入示例DataStoreABC RedisStore实现 FakeStore测试替身 dataclass Service依赖抽象以及 Protocol 的三条局限runtime_checkable只查方法存在性不查签名、不能承载共享实现、isinstance校验较弱。4.3 模块设计新建模块、模块级代码、cache时读取references/module-design.md 的核心规则是避免导入期的计算与副作用延迟到函数调用。导入期副作用的四个代价启动更慢、测试脆弱难以 mock、循环导入风险、行为依赖导入顺序。合法模块级代码仅限静态常量DEFAULT_TIMEOUT 30、SUPPORTED_FORMATS frozenset({...})。行内导入的四个合法场景——打破循环依赖、条件功能、TYPE_CHECKING、有测量证据的启动耗时优化且成本需 100ms 并在注释中记录实测值——各配有代码示例与 When NOT to defer 清单。4.4 API 设计与高级 typing审查函数签名时读取references/advanced/api-design.md 的触发条件给函数加默认参数值、定义 5 参数函数、使用ThreadPoolExecutor.submit()、审查函数签名。references/advanced/typing-advanced.md 的触发条件使用typing.cast()、创建Literal类型别名、在条件块中做类型收窄。五、决策检查表提交前的最后一道闸references/checklists.md 把全文规则压缩成九组动手前自问清单每组以加粗一行给出默认立场。摘录最能代表该技能哲学的一组写try/except之前是否在错误边界能否用廉价精确的检查前置是否在捕获具体异常而非宽泛异常边界处是否记录了日志永不静默吞默认让异常冒泡。路径操作之前.exists()是否因文件系统存在性确实是需求缺路径应报错时是否传了strictTrue.is_relative_to()是否当布尔用而非包ValueError是否指定了encodingutf-8用typing.cast()之前是否加了运行时断言断言成本 O(1) 时必须加。默认成本可忽略就永远加断言。保留向后兼容之前用户是否明确要求是否公共 API默认直接破坏 API 并立即迁移调用点。行内导入之前若为启动耗时是否实测过、是否 100ms、是否在注释中记录默认模块级导入。声明局部变量之前是否只用一次是否贴近声明点默认单次计算内联到调用点。六、技能的使用流程与 docling 仓库的落地验证SKILL.md 的 How to Use This Skill 定义了五步工作流核心知识自动加载默认立场、pathlib、导入、反模式版本探测只做一次——确定最低 Python 版本并加载对应版本文件参考文档按需加载依据上文各小节的触发模式附加模式按需额外加载CLI 模式、subprocess每个文件自包含其领域内的指导完整独立。放到 docling 仓库的实际开发场景中这套流程与仓库既有约定形成闭环版本探测pyproject.toml 中requires-python 3.10,4.0→ 加载 python-3.10 特性文件AGENTS.md 同步要求公共 API 保持 3.10 类型兼容。pathlib 优先、避免属性探测AGENTS.md 的 Code standards 与技能核心文件互相印证甚至更严格地补充了一条避免hasattr(...)、宽泛getattr(...)之类的属性探测这类检查通常掩盖了接口上的不确定性。数据模型AGENTS.md 要求跨模块边界、被序列化或作为稳定契约的数据优先用 Pydantic 模型或 dataclass 而非松散字典——这与 references/advanced/interfaces.md 中 DI 示例使用dataclass Service依赖抽象的思路一致。验证手段仓库提供的make setup/make test/make check只读校验/make validate变更钩子命令见 AGENTS.md 的 Key commands 与 Makefile构成完成前必跑的落地检查而技能中 B904 异常链、编码显式化等规则正是这类静态检查会捕获的类别。七、小结dignified-python的价值不在于罗列零散技巧而在于把何时查条件、何时抛异常、何时延迟、何时断言这类判断固化成了带默认立场的规则集并用始终加载核心 版本探测 触发式按需加载的结构控制 Agent 的上下文开销。对 docling 这类要求 3.10 类型兼容、pathlib 优先、边界处处理异常的 Python 仓库而言它与 AGENTS.md 中的项目级约定共同构成了 AI 辅助编码时的可执行质量基线。主要参考文件SKILL.md、dignified-python-core.md、references/README.md、references/checklists.md、references/module-design.md、references/advanced/exception-handling.md、references/advanced/interfaces.md、AGENTS.md、pyproject.toml、docling/cli/main.py。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
知识建站
内容驱动
阅读友好版式
SEO 精细化
线索转化