--- slug: "python-toolkit" name: "python-toolkit" version: 1.0.1 displayName: "Python工具箱(专业版)" summary: "团队级Python规范套件,含类型系统、异步、测试金字塔、性能优化与CI治理。。Python工具箱(专业版)面向团队与企业,提供完整的Python编码规范、类型系统、异步优秀实践、测试金字塔" summary_zh: "团队级Python规范套件,含类型系统、异步、测试金字塔、性能优化与CI治理。。Python工具箱(专业版)面向团队与企业,提供完整的Python编码规范、类型系统、异步优秀实践、测试金字塔" license: "MIT" edition: "pro" description: |- Python工具箱(专业版)面向团队与企业,提供完整的Python编码规范、类型系统、异步优秀实践、测试金字塔、性能优化策略与CI/CD治理方案。核心能力: - 全规范覆盖:PEP 8 + 类型系统 + 异步 + 性能 + 安全 - 完整类型注解:泛型、Protocol、TypedDict、overload - asyncio异步优秀实践与并发控制 - 测试金字塔:单元/集成/E2E + 覆盖率门禁 - 性能优化:profiling、内存、并发模型 - CI/CD门禁与团队规则治理 适用场景: - 企业级Pytho... tags: - Development - Python - 代码规范 - 企业级 - 异步 - 性能优化 - 测试 - 工具 - 效率 - 集成 - integration - self - def - user_id - int - userdto tools: - read - exec - write homepage: "" category: "Automation" --- # Python工具箱(专业版) ## 付费版专享能力 | 能力 | 免费版 | 付费版 | |---|---|---| | 基础功能 | 支持 | 支持 | | 代码静态分析与质量评分 | 不支持 | 支持 | | 依赖漏洞检测与升级建议 | 不支持 | 支持 | | 批量代码审查与报告生成 | 不支持 | 支持 | | CI/CD流水线集成 | 不支持 | 支持 | | 代码复杂度可视化与重构建议 | 不支持 | 支持 | ## 核心能力 | 能力模块 | 说明 | 与免费版差异 | |:-----|:-----|:-----| | PEP 8 + Pythonic | 核心风格规范 | 与免费版一致 | | 类型系统 | 泛型、Protocol、TypedDict、overload、ParamSpec | 免费版仅基础注解 | | 异步优秀实践 | asyncio、并发控制、取消、超时、背压 | 免费版无 | | 测试金字塔 | 单元/集成/E2E + 覆盖率门禁 + fixture | 免费版仅基础pytest | | 性能优化 | profiling、内存、GIL、并发模型 | 免费版无 | | 安全审查 | 输入校验、密钥处理、依赖审计 | 免费版无 | | CI/CD门禁 | 流水线模板、预提交钩子、规则分级 | 免费版仅基础配置 | | 团队治理 | 规则分级、豁免、迁移指南 | 免费版无 | ### 能力模块 针对能力模块,自动解析输入参数、调度任务队列、格式化输出,返回结构化响应. **输入**: 用户提供能力模块相关的配置参数、输入数据和处理选项. **输出**: 返回能力模块的处理结果。- 验证返回数据的完整性和格式正确性 - 参考`能力模块`的配置文档进行参数调优 ### PEP 8 + Pythonic 针对PEP 8 + Pythonic,自动解析输入参数、调度任务队列、格式化输出,返回结构化响应. **输入**: 用户提供PEP 8 + Pythonic相关的配置参数、输入数据和处理选项. **输出**: 返回PEP 8 + Pythonic的处理结果。- 验证返回数据的完整性和格式正确性 - 参考`PEP 8 + Pythonic`的配置文档进行参数调优 ### 类型系统 针对类型系统,自动解析输入参数、调度任务队列、格式化输出,返回结构化响应. **输入**: 用户提供类型系统相关的配置参数、输入数据和处理选项. **输出**: 返回类型系统的处理结果。- 验证返回数据的完整性和格式正确性 - 参考`类型系统`的配置文档进行参数调优 # ## 快速开始 1. 确认运行环境满足依赖说明中的要求 2. 在AI Agent对话中调用本技能,提供必要的输入参数 3. 检查输出结果,根据需要进行后续处理 > 详细的输入输出格式请参考下方章节说明。 ## 适用场景 ### 场景一:企业级异步服务规范统一 团队需要为多个异步服务统一规范,并接入CI门禁. ```yaml # .github/workflows/python-quality.yml 企业级Python质量门禁 name: Python Quality Gate on: pull_request: branches: [main] jobs: quality: runs-on: ubuntu-latest strategy: matrix: python-version: ['3.11', '3.12', '3.13'] steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: $相关信息 - run: pip install uv && uv pip install -e ".[dev]" - run: ruff check . --max-warnings=0 - run: ruff format --check . - run: mypy src/ --strict - run: pytest --cov=src --cov-fail-under=85 - run: bandit -r src/ ``` ### 场景二:异步服务并发与性能调优 某异步服务在高并发下响应变慢,工具分析后给出符合规范的优化方案. ```python import asyncio from collections.abc import AsyncIterator # ... async def fetch_batch( ids: list[int], *, concurrency: int = 10, timeout: float = 5.0, ) -> AsyncIterator[dict]: """并发获取数据,限制并发数与超时. # ... Args: ids: 待获取的ID列表. concurrency: 最大并发数. timeout: 单次请求超时秒数. # ... Yields: 每个ID对应的结果. """ semaphore = asyncio.Semaphore(concurrency) # ... async def fetch_one(item_id: int) -> dict: async with semaphore: try: return await asyncio.wait_for(_do_fetch(item_id), timeout=timeout) except TimeoutError: return {"id": item_id, "error": "timeout"} # ... results = await asyncio.gather(*(fetch_one(i) for i in ids)) for result in results: yield result # ... async def _do_fetch(item_id: int) -> dict: # 实际的异步获取逻辑 ... ``` ### 场景三:完整类型系统的API设计 团队需要设计类型安全的公共API,工具输出符合规范的类型注解. ```python from typing import Protocol, TypedDict, overload, runtime_checkable from collections.abc import Sequence # ... class UserDTO(TypedDict): id: str name: str active: bool # ... @runtime_checkable class UserRepository(Protocol): """用户仓储协议,定义存储层契约。""" # ... def get(self, user_id: str) -> UserDTO | None: ... # ... def list(self, *, offset: int = 0, limit: int = 20) -> Sequence[UserDTO]: ... # ... class InMemoryUserRepository: """内存实现,用于测试与本地开发。""" # ... def __init__(self) -> None: self._store: dict[str, UserDTO] = {} # ... def get(self, user_id: str) -> UserDTO | None: return self._store.get(user_id) # ... def list(self, *, offset: int = 0, limit: int = 20) -> Sequence[UserDTO]: items = list(self._store.values()) return items[offset : offset + limit] # ... class UserService: def __init__(self, repo: UserRepository) -> None: self._repo = repo # ... @overload def find(self, user_id: str) -> UserDTO: ... @overload def find(self, user_id: list[str]) -> list[UserDTO]: ... # ... def find(self, user_id): if isinstance(user_id, str): return self._repo.get(user_id) return [u for uid in user_id if (u := self._repo.get(uid))] ``` ## 使用流程 ### 1. 平滑升级 已使用免费版的项目直接替换Skill文件即可,核心规范完全兼容. ```bash # 依赖说明 pip install uv ruff mypy pytest pytest-cov bandit pytest-asyncio ``` ### 2. 接入预提交钩子 ```bash pip install pre-commit pre-commit init ``` ```yaml # .pre-commit-config.yaml repos: - repo: local rev: v0.6.0 hooks: - id: ruff args: [--fix, --exit-non-zero-on-fix] - id: ruff-format - repo: local rev: v1.11.0 hooks: - id: mypy additional_dependencies: [types-requests] - repo: local rev: 1.7.9 hooks: - id: bandit args: [-r, src/] ``` ### 3. 团队规则分级 ```toml # pyproject.toml 企业级配置 [tool.ruff] line-length = 100 target-version = "py312" # ... [tool.ruff.lint] select = [ "E", "W", # pycodestyle "F", # pyflakes "I", # isort "B", # bugbear "UP", # pyupgrade "S", # bandit安全 "ASYNC", # async规范 "RUF", # ruff专属 ] ignore = [ "E501", # 行长由formatter处理 ] # ... [tool.ruff.lint.per-file-ignores] "tests/*" = ["S101"] # 测试允许assert [tool.mypy] python_version = "3.12" strict = true warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true # ... [[tool.mypy.overrides]] module = "tests.*" disallow_untyped_defs = false # ... [tool.pytest.ini_options] addopts = "--cov=src --cov-fail-under=85 --cov-report=html --cov-report=term" testpaths = ["tests"] asyncio_mode = "auto" ``` # ## 输入格式 | 参数名 | 类型 | 必填 | 说明 | |---:|---:|---:|---:| | content | string | 否 | python-toolkit处理的内容输入 |, 默认: 全部维度 | | strict_level | string | 否 | 审查严格度, 可选: strict/normal/loose, 默认: normal | ## 输出格式 ```json { "success": true, "data": { "overall_grade": "A", "total_score": 92, "max_score": 100, "summary": "处理完成", "details": [ { "item": "代码风格", "status": "pass", "score": 95, "comment": "符合规范" }, { "item": "安全合规", "status": "warn", "score": 80, "comment": "符合规范" } ], "improvements": [ { "priority": "high", "suggestion": "建议优化", "expected_gain": "+5分" }, { "priority": "medium", "suggestion": "建议优化", "expected_gain": "+3分" } ] }, "error": null } ``` ## 异常处理 | 错误场景 | 原因 | 处理方式 | |:---:|:---:|:---:| | 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 | | 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 | | 网络错误 | 连接超时或不可达 | ## 依赖说明 ### 运行环境 - **Agent平台**: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等) - **操作系统**: Windows / macOS / Linux - **Python版本**: 建议 3.12 及以上(用于match、类型语法、asyncio改进) - **包管理器**: uv(推荐) / pip / pdm ### 第三方依赖 | 依赖项 | 类型 | 是否必需 | 获取方式 | |:------|------:|:------|:------| | LLM API | API | 必需 | 由Agent内置LLM提供 | | Python | 运行时 | 必需 | python.org 下载 | | ruff | 命令行工具 | 推荐 | `pip install ruff` | | mypy | 类型检查 | 推荐 | `pip install mypy` | | pytest | 测试框架 | 推荐 | `pip install pytest` | | pytest-cov | 覆盖率 | 推荐 | `pip install pytest-cov` | | pytest-asyncio | 异步测试 | 推荐 | `pip install pytest-asyncio` | | bandit | 安全扫描 | 推荐 | `pip install bandit` | | pre-commit | 预提交钩子 | 推荐 | `pip install pre-commit` | | uv | 包管理器 | 可选 | astral.sh 下载 | ### API Key 配置 - . - CI/CD流水线若需上传覆盖率或安全扫描结果,按对应服务(Codecov / Snyk 等)文档配置令牌环境变量. ### 可用性分类 - **分类**: MD+EXEC() - **说明**: 基于Markdown的AI Skill,。PRO版面向团队与企业,提供类型系统、异步、测试金字塔、性能优化与CI治理能力,完全兼容免费版核心规范. ## 案例展示 ### 性能profiling脚本 ```python """性能分析脚本:定位热点函数。""" # ... import cProfile import pstats from io import StringIO from pathlib import Path # ... def profile_function(func, *args, **kwargs) -> str: """分析函数性能并返回报告。""" profiler = cProfile.Profile() profiler.enable() func(*args, **kwargs) profiler.disable() # ... stream = StringIO() stats = pstats.Stats(profiler, stream=stream) stats.sort_stats("cumulative") stats.print_stats(20) return stream.getvalue() # ... # 使用示例 if __name__ == "__main__": from myapp.batch_processor import process_large_dataset report = profile_function(process_large_dataset, "data/") Path("profile-report.txt").write_text(report, encoding="utf-8") print(report) ``` ### 异步测试fixture ```python import pytest # ... @pytest.fixture async def db_session(): """异步数据库会话fixture,自动清理。""" session = await create_session() try: yield session finally: await session.close() # ... @pytest.mark.asyncio async def test_concurrent_fetch(db_session): """测试并发获取,验证并发安全。""" results = await fetch_batch([1, 2, 3], concurrency=2) assert len(list(results)) == 3 ``` ## 常见问题 ### Q1:PRO版与免费版如何共存? 两者核心规范完全兼容,PRO版包含免费版全部能力。团队统一使用PRO版,个人项目可继续使用免费版。迁移时直接替换Skill文件,无需改动业务代码. ### Q2:mypy strict太严格怎么办? 建议渐进式开启:先在CI跑非strict的mypy,统计错误;再逐模块在 `[[tool.mypy.overrides]]` 中开启strict,避免一次性阻塞所有提交。参考"团队迁移指南". ### Q3:PRO版是否支持异步框架? 支持asyncio原生与主流框架(FastAPI、aiohttp等)。工具提供asyncio并发模型、取消传播、背压等优秀实践。深度框架调优建议结合对应框架专用工具. ### Q4:覆盖率门禁设多少合理? 新项目建议85%,成熟项目可逐步提升至90%以上。关键路径(支付、鉴权)建议95%+。`--cov-fail-under` 在CI中强制执行,未达标则阻断合并. ### Q5:支持Monorepo吗? 支持。建议用uv workspace或pdm workspace管理多包,ruff/mypy在根目录配置,各子包通过 `tool.ruff.extend` 继承. ### Q6:性能优化建议是否覆盖GIL场景? 覆盖。CPU密集型用多进程绕开GIL,I/O密集型用asyncio或线程池。工具会分析瓶颈类型给出对应方案,并提供cProfile profiling脚本模板. ## 错误处理 | 错误场景(续)| 原因 | 处理方式 | |----:|:----|----:| | LLM响应超时或无响应 | 网络延迟或模型负载过高 | ，请求；确认Agent平台LLM服务正常 | | 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求，参考示例章节 | | 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述，补充必要的上下文信息 | | 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求；检查命令权限设置 |