Conductor Python 风格指南解析把 PEP 8 与现代最佳实践固化为项目可复用的工程规范【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents导读本篇文章围绕 Claude Code 生态的 ConductorContext-Driven Development插件所附带的 Python 代码风格模板展开。该模板位于本仓库 plugins/conductor/templates/code_styleguides/python.md是一份以 PEP 8 为根基、融合类型标注、文档字符串、虚拟环境、pytest 测试、错误处理与代码质量工具的现代 Python 工程规范。读完本文你将掌握Conductor 如何在初始化与实现阶段把这份风格指南注入你的项目setup.md、implement.md以及该模板每一章的可执行细节如何落地为可复制、可通过 ruff/mypy 校验的真实代码。一、这份风格指南在 Conductor 体系中的角色Conductor 将「项目上下文」视为与代码同等重要的受管产物其核心理念是Context → Spec Plan → Implement详见 plugins/conductor/README.md。在/conductor:setup交互式初始化时它会根据你选择的语言生成代码风格指南写入项目内的conductor/code_styleguides/目录。依据 setup.md 第 7 步的说明Generate selected style guides from$CLAUDE_PLUGIN_ROOT/templates/code_styleguides/即模板目录code_styleguides/含 python.md、typescript.md、go.md 等共 8 份是生成动作的源头conductor/code_styleguides/是产物。生成后导航中心 templates/index.md 会以 Python standards 的身份把该指南登记进 Style Guides 区段。真正让这份指南「被强制执行」的环节在/conductor:implementimplement.md 的「Context Loading」第 3 步明确规定在实现每个任务前要加载代码风格约束——conductor/code_styleguides/{language}.md。换句话说当 Claude Code 依照 plan 展开实现时这份 Python 风格指南是上下文的一部分决定了 Agent 生成的代码长什么样。二、PEP 8 基础命名、缩进与导入2.1 命名约定Naming Conventions模板给出了五层命名规则覆盖变量到「私有成员」的全部粒度对象约定示例变量 / 函数snake_caseuser_name、calculate_total(items)常量SCREAMING_SNAKE_CASEMAX_CONNECTIONS 100、DEFAULT_TIMEOUT 30类名PascalCaseclass UserAccount实例私有属性单下划线前缀约定私有self._internal_state {}类内「真正私有」双下划线前缀名称改写self.__private truly private模块级私有单下划线前缀_module_cache {}需要特别区分单下划线与双下划线的语义差异_internal_state仅表示「内部实现细节外部勿直接访问」的团队约定仍可被外部读取而self.__private会触发 Python 的名称改写name mangling机制被改写为_Base__private避免子类意外覆盖因此模板注释称其为 truly private。模块级_module_cache则主要影响from module import *的导出边界。2.2 缩进与行长Indentation and Line Length每一级缩进固定为4 个空格严禁混用 Tab。行长默认88 字符Black 默认或 79 字符PEP 8 严格值模板注释将 88 作为首选。超长行通过括号内的隐式续行优雅换行而非反斜杠result some_function( argument_one, argument_two, argument_three, ) users [ alice, bob, charlie, ]注意尾随逗号的保留多行参数/元素列表保留最后一个逗号能让后续 diff 更干净每增删一行只影响一行 diff。这也与本仓库内真实 Python 子项目的 ruff 配置取向一致——见下文第八节。2.3 导入分组Imports标准的三段式导入分组组间以空行分隔# Standard library import os import sys from pathlib import Path from typing import Optional, List # Third-party import requests from pydantic import BaseModel # Local application from myapp.models import User from myapp.utils import format_date规则要点标准库 → 第三方 → 本地应用顺序固定、组间空行同组内建议按字母序isort/ruff 的I规则可自动维护禁止通配符导入from module import *它会让命名空间被污染、静态分析失效正确写法是显式导入具体名字。该三段式约定在当前仓库的 Python 实现中得到真实应用例如 plugins/plugin-eval/src/plugin_eval/models.py 顶部正是先from __future__ import annotations、from enum import StrEnum、from typing import Any再单独导入pydantic依赖。三、类型标注从基础到进阶3.1 基础标注变量标注给出契约语义函数标注则说明输入输出from typing import Optional, List, Dict, Tuple, Union, Any name: str John age: int 30 active: bool True scores: List[int] [90, 85, 92] def greet(name: str) - str: return fHello, {name}! def find_user(user_id: int) - Optional[User]: Returns User or None if not found. pass def process_items(items: List[str]) - Dict[str, int]: Returns count of each item. pass注意模板对「可能为空」的返回值统一使用Optional[User]并配套说明性 docstring让调用方明确感知空值分支。需要说明的是在现代 Python3.10中Optional[X]等价于X | None的 PEP 604 写法后者更简洁。本仓库真实代码已采用新写法如 models.py 中corpus_path: str | None None并搭配from __future__ import annotations。模板作为兼容更老 Python 版本的基准约定保留了经典形式。3.2 进阶标注工具模板集中展示了 5 个高频进阶构造from typing import ( TypeVar, Generic, Protocol, Callable, Literal, TypedDict, Final ) # TypeVar泛型 T TypeVar(T) def first(items: List[T]) - Optional[T]: return items[0] if items else None # Protocol结构化类型鸭子类型的静态化 class Renderable(Protocol): def render(self) - str: ... def display(obj: Renderable) - None: print(obj.render()) # Literal限定具体取值 Status Literal[pending, active, completed] def set_status(status: Status) - None: pass # TypedDict描述 dict 的形状 class UserDict(TypedDict): id: int name: str email: Optional[str] # Final标记常量 MAX_SIZE: Final 100逐个说明其适用场景TypeVar是编写类型安全的泛型函数如first()对任意元素类型的列表取首项并保持类型不丢失的基础Protocol实现结构化子类型让display可接受任何实现了render()方法的类无需继承关系即可满足类型检查——是「面向接口而非实现」的静态化表达Literal把「魔法字符串」收敛为编译期可校验的字面量联合配合枚举可显著降低拼写错误TypedDict为真正需要字典如 JSON 边界的场景提供键值形状约束比裸Dict[str, Any]更安全Final防止常量被意外重赋值。这些工具与Generic、Callable等组合几乎可以精确表达日常业务代码的九成类型需求。3.3 类中的类型标注from dataclasses import dataclass from typing import ClassVar, Self dataclass class User: id: int name: str email: str active: bool True # Class variable _instances: ClassVar[Dict[int, User]] {} def deactivate(self) - Self: self.active False return self class Builder: def __init__(self) - None: self._value: str def append(self, text: str) - Self: self._value text return self模板通过ClassVar区分「类级变量」与「实例字段」否则 dataclass 会误把_instances当实例字段并用Self作为链式调用 / 返回自身方法的返回类型。- Self相比直接写类名更优在继承场景下返回类型会自动跟随子类避免类型检查误报。四、Docstrings让文档字符串可执行化4.1 函数 Docstring模板给出了一个完整、可被 doctest / IDE 直接消费的范例def calculate_discount( price: float, discount_percent: float, min_price: float 0.0 ) - float: Calculate the discounted price. Args: price: Original price of the item. discount_percent: Discount percentage (0-100). min_price: Minimum price floor. Defaults to 0.0. Returns: The discounted price, not less than min_price. Raises: ValueError: If discount_percent is not between 0 and 100. Example: calculate_discount(100.0, 20.0) 80.0 if not 0 discount_percent 100: raise ValueError(Discount must be between 0 and 100) discounted price * (1 - discount_percent / 100) return max(discounted, min_price)该范例同时示范了三件事结构要素齐全Args、Returns、Raises、Example四段式缺失任何一个都可能让调用方踩坑例如不知道会抛ValueError。示例可直接运行前缀的示例即为 doctest可被测试框架执行校验做到「示例永不撒谎」。实现与文档一致Raises声明的异常在实际代码中被真实raise边界校验0 discount_percent 100与参数描述互为印证。4.2 类 Docstringclass UserService: Service for managing user operations. This service handles user CRUD operations and authentication. It requires a database connection and optional cache. Attributes: db: Database connection instance. cache: Optional cache for user lookups. Example: service UserService(db_connection) user service.get_user(123) def __init__( self, db: DatabaseConnection, cache: Optional[Cache] None ) - None: Initialize the UserService. Args: db: Active database connection. cache: Optional cache instance for performance. self.db db self.cache cache类级 docstring 强调职责描述 依赖声明 Attributes 清单让读者无需读构造器就能判断该类是否适合当前场景构造器内部再对每个参数展开说明。这种「外层总览、内层细节」的两级文档分工是大型类文档组织的推荐做法。此外注意__init__的每个参数都做了类型标注便于 IDE 自动补全。五、虚拟环境与项目结构5.1 经典 venv pip 工作流# Create virtual environment python -m venv .venv # Activate (Unix/macOS) source .venv/bin/activate # Activate (Windows) .venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Freeze dependencies pip freeze requirements.txt要点环境目录统一命名为.venvgitignore 惯例激活命令区分 Unix/macOS 与 Windows 两种 shell。5.2 现代工具链模板将uv标注为 recommended并附 Poetry、Pipenv 备选# Using uv (recommended) uv venv uv pip install -r requirements.txt # Using poetry poetry init poetry add requests poetry install # Using pipenv pipenv install pipenv install requests在本仓库中 uv 已被真实采用插件 plugin-eval/pyproject.toml 与 tools/yt-design-extractor/pyproject.toml 都带uv.lock锁定文件作为项目级依赖的权威版本来源。若团队认可「可复现构建」那么模板「uv 优先」的取向与本仓库实践是一致的。5.3 推荐的 src-layout 项目结构project/ ├── .venv/ # Virtual environment (gitignored) ├── src/ │ └── myapp/ │ ├── __init__.py │ ├── main.py │ └── utils.py ├── tests/ │ ├── __init__.py │ └── test_main.py ├── pyproject.toml # Modern project config ├── requirements.txt # Pinned dependencies └── README.md该src/布局src-layout能避免「从仓库根目录误导入包」的经典问题并将实现与测试清晰隔离。注意两套清单的并存定位pyproject.toml承载现代项目元数据与工具配置requirements.txt记录锁定pinned后的直接依赖。本仓库 plugin-eval 即完全遵循此模式src/plugin_eval/存放实现、tests/存放测试、pyproject.toml统管 ruff/pytest/构建。六、测试pytest 三件套6.1 基础断言与参数化import pytest from myapp.calculator import add, divide def test_add_positive_numbers(): assert add(2, 3) 5 def test_add_negative_numbers(): assert add(-1, -1) -2 def test_divide_by_zero_raises(): with pytest.raises(ZeroDivisionError): divide(10, 0) # Parametrized tests pytest.mark.parametrize(a,b,expected, [ (1, 1, 2), (0, 0, 0), (-1, 1, 0), ]) def test_add_parametrized(a, b, expected): assert add(a, b) expected模板刻意覆盖三类断言风格正向值断言、异常断言pytest.raises、以及参数化——用一组(输入, 输入, 期望)元组驱动同一测试逻辑跑多组用例从而消灭「复制粘贴式」的同构测试函数。6.2 Fixtures测试间依赖的解耦与复用import pytest from myapp.database import Database from myapp.models import User pytest.fixture def db(): Provide a clean database for each test. database Database(:memory:) database.create_tables() yield database database.close() pytest.fixture def sample_user(db): Create a sample user in the database. user User(nameTest User, emailtestexample.com) db.save(user) return user def test_user_creation(db, sample_user): found db.find_user(sample_user.id) assert found.name Test Userfixture 的精髓是通过函数参数声明依赖、由 pytest 负责注入从而让每个测试只关心自己的行为。dbfixture 的yield前是 setup、后是 teardown关闭连接保证测试相互隔离sample_user又依赖db形成 fixture 链。测试函数通过(db, sample_user)参数名即可获得全部依赖无需在函数体内手工初始化。6.3 Mocking隔离外部依赖from unittest.mock import Mock, patch, MagicMock import pytest def test_api_client_with_mock(): # Create mock mock_response Mock() mock_response.json.return_value {id: 1, name: Test} mock_response.status_code 200 with patch(requests.get, return_valuemock_response) as mock_get: result fetch_user(1) mock_get.assert_called_once_with(/users/1) assert result[name] Test patch(myapp.service.external_api) def test_with_patch_decorator(mock_api): mock_api.get_data.return_value {status: ok} result process_data() assert result[status] ok模板同时展示patch的两种用法上下文管理器形式with patch(...)作用域受限与装饰器形式patch(...)作用于整个测试函数。核心断言工具包括mock_response.json.return_value {...}预置返回值mock_get.assert_called_once_with(/users/1)校验「以正确参数恰好调用一次」patch(myapp.service.external_api)中的路径必须指向被测代码中实际引用外部对象的模块路径而非其定义处——这是 patch 最常见的踩坑点。七、错误处理与常见模式7.1 异常分层业务异常体系模板强调先建立自己的异常继承树再在业务代码中抛出class AppError(Exception): Base exception for application errors. pass class ValidationError(AppError): Raised when validation fails. def __init__(self, field: str, message: str): self.field field self.message message super().__init__(f{field}: {message}) class NotFoundError(AppError): Raised when a resource is not found. def __init__(self, resource: str, identifier: Any): self.resource resource self.identifier identifier super().__init__(f{resource} {identifier} not found)分层价值体现在顶层AppError让调用方只需except AppError即可统一兜底业务失败ValidationError/NotFoundError让上层可按类型精细化处理同时每个子类通过super().__init__(格式化消息)保留可读性良好的人类消息。7.2 异常的捕获、包装与资源清理def get_user(user_id: int) - User: try: user db.find_user(user_id) if user is None: raise NotFoundError(User, user_id) return user except DatabaseError as e: logger.error(fDatabase error: {e}) raise AppError(Unable to fetch user) from e其中raise ... from e异常链是模板的隐藏知识点它显式保留原始异常为__cause__让上层看到业务化消息的同时仍能追溯底层根因是「既不吞异常、又给上层友好语义」的标准手法。基于contextlib.contextmanager的事务型上下文管理器示范了「成功提交、失败回滚」的经典骨架from contextlib import contextmanager contextmanager def database_transaction(db): try: yield db db.commit() except Exception: db.rollback() raise7.3 常用模式dataclass / 上下文管理器 / 装饰器Dataclass 进阶用法——关注field(default_factory...)与__post_init__from dataclasses import dataclass, field from typing import List, Optional from datetime import datetime dataclass class User: id: int name: str email: str active: bool True created_at: datetime field(default_factorydatetime.now) tags: List[str] field(default_factorylist) def __post_init__(self): self.email self.email.lower() dataclass(frozenTrue) class Point: Immutable point. x: float y: float def distance_to(self, other: Point) - float: return ((self.x - other.x)**2 (self.y - other.y)**2) ** 0.5两个反直觉的坑模板均已规避一是可变默认值必须用default_factory直接写[]或datetime.now()会共享实例导致数据污染二是初始化后处理用__post_init__此处统一小写 email。frozenTrue则把Point变成不可变值对象。上下文管理器的contextmanager与类式两种实现模板都已给出前者适合简单计时场景后者实现__enter__/__exit__适合持有真实资源如连接的复杂对象。__exit__返回False表示不吞异常——这是必须保持的默认行为。装饰器模板给出了保留类型签名的泛型 retry 装饰器含指数退避from functools import wraps from typing import Callable, TypeVar, ParamSpec import time P ParamSpec(P) R TypeVar(R) def retry(max_attempts: int 3, delay: float 1.0): Retry decorator with exponential backoff. def decorator(func: Callable[P, R]) - Callable[P, R]: wraps(func) def wrapper(*args: P.args, **kwargs: P.kwargs) - R: last_exception None for attempt in range(max_attempts): try: return func(*args, **kwargs) except Exception as e: last_exception e if attempt max_attempts - 1: time.sleep(delay * (2 ** attempt)) raise last_exception return wrapper return decorator retry(max_attempts3, delay0.5) def fetch_data(url: str) - dict: response requests.get(url) response.raise_for_status() return response.json()这里的ParamSpecTypeVar是「编写装饰器却不让类型信息丢失」的现代标准解法wraps保证被装饰函数的元数据__name__、docstring不被破坏time.sleep(delay * (2 ** attempt))实现失败后逐次翻倍的指数退避。八、代码质量工具Ruff mypy 双闸门8.1 Ruff 配置# pyproject.toml [tool.ruff] line-length 88 target-version py311 [tool.ruff.lint] select [ E, # pycodestyle errors W, # pycodestyle warnings F, # Pyflakes I, # isort B, # flake8-bugbear C4, # flake8-comprehensions UP, # pyupgrade ] ignore [E501] # Line too long (handled by formatter) [tool.ruff.lint.isort] known-first-party [myapp]模板选用的规则集与每条的定位E/W覆盖 PEP 8 风格错误与警告F负责未使用导入等 Pyflakes 检测I自动整理导入顺序Bflake8-bugbear与C4comprehension 优化、UPpyupgrade自动升级到新语法则偏向「隐患与现代化」——其中UP与模板第三节推荐X | None新写法、Self返回类型的方向一脉相承。ignore [E501]是刻意的取舍行长度交由格式化器统一处理避免 lint 与 formatter 在换行策略上打架。known-first-party让 isort 能正确识别本地包myapp从而把「本地导入」排在第三方库之后。值得对照的是本仓库真实子项目 plugin-eval/pyproject.toml 采用了同一哲学的不同参数值line-length 100select [E4, E7, E9, F, B, I, UP, SIM]同样ignore [E501]。这说明模板给出的是可调参的基线而非铁律——团队可以依据自身偏好调整行长、增删规则例如SIM是 plugin-eval 额外启用的 flake8-simplify。8.2 mypy 严格模式# pyproject.toml [tool.mypy] python_version 3.11 strict true warn_return_any true warn_unused_configs true ignore_missing_imports truemypy 配置的五个开关含义strict true一键开启全部严格检查含 no-untyped-def、disallow-any-* 等是保证类型标注真正起效的门槛warn_return_any true禁止函数在标注了返回类型的情况下悄悄返回Any防止类型检查形同虚设warn_unused_configs true提醒清理无效配置项ignore_missing_imports true对无类型桩的第三方包放行避免外部依赖阻塞检查这是一种务实的妥协代价是该包失去类型安全建议配合stub包逐步消除。这两道闸门ruff 管风格与静态隐患、mypy 管类型正确性与模板前三节命名/导入/标注形成闭环写代码时遵守命名与标注约定提交前由工具自动验证。九、把模板落到 Conductor 驱动的日常迭代里综合全仓库证据这份python.md模板的使用闭环可以概括为四条初始化注入运行/conductor:setup在 Step 7 由 setup.md 从$CLAUDE_PLUGIN_ROOT/templates/code_styleguides/复制所选语言指南至项目conductor/code_styleguides/产物目录布局可参见 README.md 的 Generated Artifacts。上下文导航conductor/index.md模板见 templates/index.md把 Python 指南登记为 Python standards团队新成员可在此总览全部规范。实现时强制执行每次/conductor:implement执行任务前implement.md 的上下文加载步骤会把code_styleguides/{language}.md与product.md、tech-stack.md、workflow.md一并读入——这意味着Agent 生成的每一行 Python 代码都应以本文档为默认风格基准。人工可审查风格指南作为受版本控制的上下文产物随代码一起提交Conductor 的 workflow 规则代码评审时可将「是否符合项目风格指南」作为明确的评审维度。对使用 Conductor 管理 Python 项目的团队落地顺序建议是用模板生成conductor/code_styleguides/python.md→ 依据团队偏好微调行长与 ruff 规则集 → 把对应 ruff/mypy 配置写入pyproject.toml→ 之后所有实现任务的代码生成与评审均以此为准。若你的代码库需要跨语言治理可参照同目录下 general.md、typescript.md 等其余 7 份指南保持多语言风格一致。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
