ECC 项目 Python 代码风格指南：PEP 8、不可变数据结构与工程化格式化实践

ECC 项目 Python 代码风格指南PEP 8、不可变数据结构与工程化格式化实践【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本篇技术指南基于 docs/es/rules/python/coding-style.md及其英文版 rules/python/coding-style.md展开是 ECCThe agent harness performance optimization system面向 Claude Code、Codex、Opencode、Cursor 等 agent harness 的性能优化系统中 Python 语言规则的完整实践解读。它在 ECC 的编码规则体系中扮演Python 语言专属补充的角色凡是**/*.py与**/*.pyi文件都要在本规则约束下开发。读完本文你将掌握 ECC 对 Python 代码的三大硬性要求——PEP 8 规范与全量类型注解、以冻结 dataclass 与 NamedTuple 为核心的不可变数据结构、以 black / isort / ruff 组成的一体化格式化与 lint 工具链并能结合仓库源码与配置看到这些规则在实际项目中的落地形态。规则定位Python 专属扩展与通用编码规范的边界ECC 的编码规则采用通用规则 语言专属规则的分层结构。本文主角 docs/es/rules/python/coding-style.md 的第一行 front matter 明确声明其生效范围paths: - **/*.py - **/*.pyi即该规则只对 Python 源码文件与类型桩文件生效。同时文档开头明确指出Este archivo extiende common/coding-style.md con contenido específico de Python本文件以 Python 专属内容扩展 common/coding-style.md。因此Python 代码必须同时满足两层约束通用层common/coding-style.md不可变性CRÍTICO永远创建新对象绝不原地修改已有对象KISS / DRY / YAGNI三大原则优先最简单可行的方案、抽取真实重复逻辑、不做投机性抽象文件组织多小文件优于少大文件单文件典型 200–400 行、上限 800 行按 feature/domain 而非类型组织错误处理每一层显式处理错误UI 侧给友好提示、服务端记详细上下文绝不静默吞错输入校验在系统边界校验全部输入优先 schema 化校验、快速失败、绝不信任外部数据命名约定变量/函数camelCase、布尔量用is/has/should/can前缀、接口与类型PascalCase、常量UPPER_SNAKE_CASECode Smells避免深度嵌套优先提前 return、消灭魔法数字用命名常量、拆分长函数质量检查清单函数 50 行、文件 800 行、嵌套 ≤4 层、无硬编码值、无原地突变。Python 专属层本文档在通用层之上追加 PEP 8、全量类型注解、不可变数据结构的首选写法以及 black/isort/ruff 工具链约定。从代码结构看rules/ 目录下的每个语言子目录python、rust、golang、java 等都遵循同样的coding-style / testing / security / patterns / hooks文件骨架而common子目录提供跨语言共享基准这套分层设计正是 ECC 规则体系RULES.md的可复用单元。标准PEP 8 与全量类型注解文档在 Estándares 一节给出两条不可妥协的标准遵循 PEP 8 约定包括 4 空格缩进、每行 79 字符或团队约定的 88 字符、import 顺序、命名风格等官方约定所有函数签名必须带类型注解这是比 PEP 8 更严格的要求意味着每个函数的参数与返回值都应有明确的类型标注。仓库中的src/llm模块是这套标准的直接体现。src/llm/core/types.py 中枚举与数据类全部带完整注解例如class Role(str, Enum): SYSTEM system USER user ASSISTANT assistant TOOL tool而 src/llm/core/interface.py 的抽象基类则示范了抽象方法 类型注解的组合class LLMProvider(ABC): provider_type: ProviderType abstractmethod def generate(self, input: LLMInput) - LLMOutput: ... abstractmethod def list_models(self) - list[ModelInfo]: ... abstractmethod def validate_config(self) - bool: ...值得注意的是 pyproject.toml 中requires-python 3.11因此list[ModelInfo]这类内置泛型写法PEP 585与str | None联合类型写法PEP 604在整个项目中都是合法且推荐的这是类型注解标准在当前仓库中的具体版本语义。不可变性冻结 dataclass 与 NamedTuple 的首选写法为什么强调不可变common/coding-style.md 将不可变性列为 CRÍTICO 级要求理由是不可变数据能杜绝隐藏的副作用、简化调试、并支撑安全并发。Python 专属文档则给出了落地这种思想的两个具体工具。首选一dataclass(frozenTrue)from dataclasses import dataclass dataclass(frozenTrue) class User: name: str email: strfrozenTrue使 dataclass 实例在创建后不可修改任何赋值都会抛出FrozenInstanceError从机制上保证了不可变性。首选二typing.NamedTuplefrom typing import NamedTuple class Point(NamedTuple): x: float y: floatNamedTuple 兼具元组的轻量与命名字段的可读性且天然不可变不可重新赋值字段。源码级印证ECC 的 LLM 抽象层完全贯彻了这一模式。src/llm/core/types.py 中几乎所有数据传输对象都是frozenTrue的 dataclassdataclass(frozenTrue) class Message: role: Role content: str name: str | None None tool_call_id: str | None None tool_calls: list[ToolCall] | None NoneMessage、ToolDefinition、ToolCall、ToolResult、LLMInput、LLMOutput、ModelInfo全部为冻结数据类。这类对象在跨 provider 传递时被多个模块共享如 src/llm/providers/claude.py 将其转换为 Anthropic 请求格式不可变性保证它们不会被某个 provider 适配器意外篡改这正是防止隐藏副作用的工程价值所在。同时这些数据类遵循创建新对象而非修改旧对象的约定需要变化时通过to_dict()如 src/llm/core/types.py 中Message.to_dict、LLMInput.to_dict生成新的字典表示或在调用侧构造新实例而不是原地修改。实践建议表示值/数据传输DTO的类优先dataclass(frozenTrue)需要元组语义或哈希性能的小型值对象用NamedTuple避免在冻结 dataclass 中持有list/dict等可变字段值而误以为不可变——应搭配元组或深拷贝可参考LLMInput.metadata使用field(default_factorydict)的写法需要在初始化时校验/派生字段使用__post_init__frozen 模式下配合object.__setattr__或dataclasses.replace创建新实例。工具链black isort ruff 的一体化工作流文档在 Formateo 一节明确了三项工具分工工具职责black代码格式化无争议风格、自动统一isortimport 语句排序rufflint 检查静态问题、未用 import、命名等仓库中的真实配置pyproject.toml 给出了这些工具的落地配置可作为直接可用的参考[tool.ruff] src [src] target-version py311 [tool.ruff.lint] select [E, F, I, N, W, UP] # E501: line length is handled by the formatter, not enforced here. # UP042: the (str, Enum) mixin is intentional — enum members must compare # and serialize as plain strings across providers. StrEnum changes # str() semantics, so the explicit mixin is kept deliberately. ignore [E501, UP042]其中select启用了Epycodestyle 错误、FPyflakes、Iisort import 排序、NPEP 8 命名、W警告、UPpyupgrade 现代化写法E501行长度被显式忽略注释说明行长度交给格式化器处理——这正是 black/isort/ruff 各自边界划分的体现black 负责换行ruff 不重复报行长度UP042(str, Enum)混合类被有意保留注释解释了理由枚举成员必须跨 provider 以纯字符串比较与序列化StrEnum会改变str()语义因此刻意保留显式混合类。这展示了一条重要工作流工具规则遇到合理例外时应通过配置忽略并写注释说明原因而非盲目遵循。建议的命令组合在项目根目录含pyproject.toml的位置执行# 1. 排序 imports isort src tests # 2. 格式化代码 black src tests # 3. lint 检查 ruff check src tests # 4. 静态类型检查与全量类型注解标准配套 mypy src也可以将isort交由 ruff 的I规则统一处理本仓库即如此此时只需ruff check --fix即可完成 import 排序。仓库的 dev 依赖声明pyproject.toml 的[project.optional-dependencies] dev中同时包含ruff0.16.1与mypy2.3.0而[tool.mypy]配置了python_version 3.11、mypy_path src、warn_return_any true、warn_unused_ignores true说明类型检查是这条工具链的第四环与所有函数签名带注解的标准闭环。CI 与测试中的联动工具链不仅是本地习惯。仓库的测试体系tests/与配置表明[tool.pytest.ini_options]设置了testpaths [tests]、asyncio_mode auto覆盖率配置[tool.coverage.run]以src/llm为统计源并开启分支覆盖。测试文件本身也遵循同样的类型注解与不可变风格例如 tests/test_types.py 中直接构造Message(roleRole.USER, contentHello)断言其字段与to_dict()输出——这些测试同时充当了编码规范的活文档。与其他规则的衔接与深度阅读入口文档末尾给出参考指引完整的 Python 惯用法与模式参见python-patternsskill。在 ECC 仓库中围绕 Python 语言还有一整套配套规则与资源可供继续深入rules/python/patterns.mdPython 惯用法与设计模式rules/python/testing.mdpytest 框架、覆盖率命令与pytest.mark分类组织rules/python/security.mdPython 安全编码要求rules/python/fastapi.mdFastAPI 专属约定rules/python/hooks.mdPython 相关 harness hooks 规则skills/python-patterns/对应 skill 的完整内容src/llm/本仓库中践行上述规范的 Python 实现示例tests/ 下的 Python 测试如 tests/test_types.py规范的可验证用例。小结一条可立即执行的 Python 编码基线把 ECC 的 Python 编码风格规则压缩成一份可执行清单规范层所有.py/.pyi文件遵循 PEP 8所有函数签名必须带完整类型注解str | None、list[T]等现代写法在 Python ≥3.11 下优先数据结构层优先dataclass(frozenTrue)与NamedTuple遵循创建新对象、绝不原地突变的不可变原则通用规则中的 CRÍTICO 项工具层black 格式化、isort或 ruffI规则排序 imports、ruff lint、mypy 类型检查四件套规则例外通过配置忽略并注释说明质量底线函数 50 行、文件 800 行、嵌套 ≤4 层、无魔法数字、显式错误处理、边界输入校验。这套基线直接复用了 ECC 自身 LLM 抽象层src/llm/core/types.py的工程实践——当你为 agent harness 编写 Python 代码时照着这份清单写代码风格、可维护性与团队一致性都不会偏离仓库的既有标准。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考