ECC Python 编码风格指南PEP 8、类型注解、不可变数据结构与 black/isort/ruff 工具链实战【免费下载链接】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本文是 ECCThe agent harness performance optimization system仓库中 Python 编码风格规则 的完整展开。它以该规则为骨架结合仓库内真实源码src/llm模块与工具链配置pyproject.toml进行纵深讲解帮助你在 Agent/LLM 协作开发场景下写出符合 ECC 标准、可被自动化检查的 Python 代码。读完本文你将掌握PEP 8 与全量类型注解的落地要求、不可变数据结构frozen dataclass与NamedTuple的正确用法、black/isort/ruff 三件套的配置与命令以及如何在真实项目中验证这些规范。规则文件与适用范围在 ECC 仓库中Python 编码风格由两层规则叠加构成rules/python/coding-style.mdPython 语言特有的编码风格规则声明其适用于**/*.py与**/*.pyi文件pyi为类型桩文件并从 rules/common/coding-style.md 继承通用约束。rules/common/coding-style.md跨语言的通用规范包含不变量Immutability标记为 CRITICAL、KISS/DRY/YAGNI 三原则、文件组织小文件优先源文件 800 行软上限、错误处理、输入校验、命名约定与代码质量检查清单。因此评估一段 Python 代码是否符合 ECC 标准需要同时满足通用规范 Python 特有规范两层要求。本文聚焦 Python 特有部分同时保留通用规范的落地点尤其是不可变性。标准PEP 8 与全量类型注解规则明确两条硬性标准遵循 PEP 8 规范包括 4 空格缩进、行宽建议 79/88 字符、命名风格snake_case函数与变量、UPPER_SNAKE_CASE常量、CamelCase类名、导入顺序等。所有函数签名使用类型注解不仅是公开 API内部函数、私有方法、回调函数同样需要标注参数与返回值类型。这两条标准在仓库中有直接实现证据。以 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: ... def supports_tools(self) - bool: return True def supports_vision(self) - bool: return False def get_default_model(self) - str: raise NotImplementedError(f{self.__class__.__name__} must implement get_default_model)可以看到每个方法都有完整签名注解连只有一条return True的supports_tools也不例外抽象方法体使用...Ellipsis占位返回值类型明确标注。这正是所有函数签名都带类型注解标准的实际样板。在工具链层面类型检查由 mypy 负责仓库在 pyproject.toml 中配置了[tool.mypy] python_version 3.11 mypy_path src warn_return_any true warn_unused_ignores truewarn_return_any true会强制要求函数不要隐式返回Any从类型层面倒逼写出精确的返回注解warn_unused_ignores则防止冗余的# type: ignore注释堆积。不可变性优先使用不可变数据结构规则将优先不可变数据结构列为 Python 特有要点而 rules/common/coding-style.md 更是将不可变性标记为CRITICAL级永远创建新对象绝不原地修改已有对象。错误写法modify(original, field, value)原地修改 original 正确写法update(original, field, value)返回带修改的新副本。理由不可变数据能阻止隐藏的副作用、让调试更简单、并支持安全的并发。规则给出的两种推荐实现from dataclasses import dataclass dataclass(frozenTrue) class User: name: str email: str from typing import NamedTuple class Point(NamedTuple): x: float y: floatfrozen dataclass 与 NamedTuple 的取舍dataclass(frozenTrue)自动生成__init__、__repr__、__eq__且实例创建后属性不可赋值赋值会抛出FrozenInstanceError。适合需要默认值、复杂字段或后续增加方法的场景。NamedTuple基于元组的不可变结构内存占用小、可解包、可与元组互通且天然支持哈希字段均为可哈希类型时。适合轻量、纯数据的结构。仓库中的真实实践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、LLMInput、LLMOutput、ToolDefinition、ToolCall、ToolResult、ModelInfo全部以dataclass(frozenTrue)定义。这意味着在多 ProviderClaude/OpenAI/Ollama 等切换、工具调用链传递的过程中数据结构不可能被某个环节意外修改——这正是不可变性对隐藏副作用的防御价值。同时注意Role与ProviderType使用(str, Enum)混入的StrEnum风格pyproject.toml 中特意忽略UP042规则并注释说明原因枚举成员必须跨 Provider 以纯字符串比较和序列化显式混入是有意为之。这说明编码风格规则并非死板教条工具链配置允许为合理的工程取舍显式豁免。与不可变结构配套的是更新即新建的惯例例如Message.to_dict()、LLMInput.to_dict()均返回新字典而不修改自身外部可通过result | self.metadata合并元数据生成新结构而不是原地变更。格式化工具链black isort ruff规则指定 Python 工程的三件套工具职责black代码格式化统一排版号称不可争辩的格式化器isort导入语句排序标准库 → 第三方 → 本地ruff代码检查lint超高速的 Rust 实现典型命令序列# 格式化 black . isort . # 检查 ruff check .isort 的导入分组约定在 skills/python-patterns/SKILL.md 中有示例——标准库、第三方包、本地模块三组组间空行分隔# stdlib import os import sys from pathlib import Path # third-party import requests from fastapi import FastAPI # local from mypackage.models import User from mypackage.utils import format_nameECC 仓库的实际 ruff 配置ECC 在 pyproject.toml 中给出了可直接照搬的 ruff 配置[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. ignore [E501, UP042]要点解读src [src]告知 ruff 项目的源根目录配合 src 布局避免本地导入被误判为第三方包。target-version py311与项目requires-python 3.11对齐让 ruff 只建议 Python 3.11 支持的语法。select启用Epycodestyle 错误、FPyflakes、Iisort 规则ruff 内置、NPEP 8 命名、Wpycodestyle 警告、UPpyupgrade升级为现代语法。其中I意味着 isort 的检查能力已被 ruff 覆盖可直接用ruff check --fix自动排序导入。ignore [E501, UP042]行宽交给 black 处理E501不强制(str, Enum)混入是有意设计UP042豁免。这种格式化归 black、检查归 ruff的分工是当前 Python 社区的主流实践。版本约束pyproject.toml的 dev 依赖中要求ruff0.16.1、mypy2.3.0。也就是说ECC 规则与配置面向的是较新的工具链版本使用时建议锁定不低于这些版本以保证select/ignore配置项如UP042都能被识别。规则落地的配套环节测试与类型检查编码风格不是孤立的排版问题ECC 将它与测试、类型检查绑定为一个完整的质量闭环测试框架rules/python/testing.md 规定使用 pytest并通过pytest.mark.unit/pytest.mark.integration对用例分类覆盖率命令为pytest --covsrc --cov-reportterm-missing。配置对齐pyproject.toml 中[tool.pytest.ini_options]设置testpaths [tests]、asyncio_mode auto[tool.coverage]配置source [src/llm]与分支覆盖、排除行pragma: no cover、if TYPE_CHECKING:等。测试佐证tests/test_types.py直接验证了不可变数据结构的可观察行为——例如断言Message的默认字段、to_dict()的序列化结果、ToolDefinition默认strict is True等。风格规则与测试共同保证了 LLM 抽象层的质量。深度参考python-patterns skill规则末尾将 skills/python-patterns/SKILL.md 作为综合参考。该 skill 覆盖了本文之外更广泛的 Python 习语与模式与编码风格规则互为补充值得按需查阅可读性优先与显式优于隐式清晰的命名与显式配置杜绝魔法行为EAFPEasier to Ask Forgiveness Than Permission优先try/except而非先判断再取值类型进阶Protocol鸭子类型、TypeVar泛型、dict[str, Any]等现代注解Python 3.9 直接用内置泛型仓库目标版本 3.11 完全支持错误处理模式捕获具体异常、raise ... from e异常链、自定义异常层级如仓库中LLMError派生AuthenticationError/RateLimitError/ContextLengthError等见 src/llm/core/interface.py资源管理上下文管理器with语句与自定义contextmanager数据结构带__post_init__校验的 dataclass、NamedTuple 方法、__slots__内存优化性能注意循环中避免字符串拼接用join/StringIO、大文件用生成器逐行处理反模式清单可变默认参数、type()类型判断、 None比较、import *、裸except等。实战检查清单将规则落实为提交前的自查动作类型每个函数签名都有参数与返回值注解没有隐式Any不可变数据容器是否优先使用frozen dataclass或NamedTuple是否避免了原地修改格式black .与isort .或ruff check --fix是否通过命名是否符合 PEP 8snake_case函数/变量、UPPER_SNAKE_CASE常量、CamelCase类文件规模源文件是否小于 800 行函数是否小于 50 行、嵌套不超过 4 层测试pytest --covsrc --cov-reportterm-missing是否通过新增逻辑是否有分类标记的测试这条路径——PEP 8 全量类型注解 不可变结构 black/isort/ruff 三件套 pytest 闭环——正是 ECC 对 Python 代码质量的定义也是本仓库src/llm模块实际遵循的工程基线。【免费下载链接】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），仅供参考