--- name: Python Dev slug: python-dev category: Quality description: Python Dev provides Python coding standards for style, type hints, error handling, logging, testing, and project structure. Use it when writing or reviewing Python code that should follow consistent conventions. github: "https://github.com/doccker/cc-use-exp/tree/main/skills/python-dev" language: Python stars: 1011 forks: 105 install: "npx degit https://github.com/doccker/cc-use-exp/tree/main/skills/python-dev ~/.claude/skills/python-dev" installs_to: ~/.claude/skills/python-dev source_path: skills/python-dev/SKILL.md collection_size: 23 category_size: 1354 collection_url: "https://dirskills.com/collections/doccker/cc-use-exp" added: 2026-08-21T05:14:35.020Z last_synced: 2026-08-21T05:14:35.020Z canonical_url: "https://dirskills.com/skills/python-dev" --- # Python Dev Python Dev provides Python coding standards for style, type hints, error handling, logging, testing, and project structure. Use it when writing or reviewing Python code that should follow consistent conventions. **Install:** ```bash npx degit https://github.com/doccker/cc-use-exp/tree/main/skills/python-dev ~/.claude/skills/python-dev ``` ## README # Python 开发规范 > 参考来源: PEP 8、Google Python Style Guide --- ## 工具链 ```bash # 格式化 black . # 代码格式化 isort . # import 排序 # 类型检查 mypy . # 静态类型检查 pyright . # 备选 # 代码检查 ruff check . # 快速 linter（推荐） flake8 . # 传统 linter # 测试 pytest -v # 运行测试 pytest --cov=src # 覆盖率 ``` --- ## 命名约定 | 类型 | 规则 | 示例 | |------|------|------| | 模块/包 | 小写下划线 | `user_service.py` | | 类名 | 大驼峰 | `UserService`, `HttpClient` | | 函数/变量 | 小写下划线 | `get_user_by_id`, `user_name` | | 常量 | 全大写下划线 | `MAX_RETRY_COUNT` | | 私有 | 单下划线前缀 | `_internal_method` | --- ## 类型注解 ```python from typing import Optional, List, Dict, Union from dataclasses import dataclass @dataclass class User: id: int name: str email: Optional[str] = None def find_user_by_id(user_id: int) -> Optional[User]: """根据 ID 查找用户""" ... def process_items(items: List[str]) -> Dict[str, int]: """处理项目列表""" return {item: len(item) for item in items} # Python 3.10+ 可用新语法 def greet(name: str | None = None) -> str: return f"Hello, {name or 'World'}" ``` --- ## 异常处理 ```python # ✅ 好：捕获具体异常 try: user = repository.find_by_id(user_id) except DatabaseError as e: logger.error(f"Failed to find user {user_id}: {e}") raise ServiceError(f"Database error: {e}") from e # ✅ 好：上下文管理器 with open("file.txt", "r") as f: content = f.read() # ❌ 差：裸 except try: do_something() except: # 永远不要这样做 pass ``` --- ## 自定义异常 ```python class ServiceError(Exception): """服务层异常基类""" def __init__(self, message: str, code: str = "UNKNOWN"): super().__init__(message) self.code = code class UserNotFoundError(ServiceError): """用户不存在""" def __init__(self, user_id: int): super().__init__(f"User {user_id} not found", "USER_NOT_FOUND") self.user_id = user_id ``` --- ## 日志规范 ```python import logging logger = logging.getLogger(__name__) # ✅ 好：使用参数化日志 logger.debug("Finding user by id: %s", user_id) logger.info("User %s logged in successfully", username) logger.error("Failed to process order %s", order_id, exc_info=True) # ❌ 差：f-string（即使不输出也会计算） logger.debug(f"Finding user by id: {user_id}") ``` --- ## 测试规范（pytest） ```python import pytest from unittest.mock import Mock, patch class TestUserService: @pytest.fixture def user_service(self): repository = Mock() return UserService(repository) def test_find_by_id_returns_user(self, user_service): # given expected = User(id=1, name="test") user_service.repository.find_by_id.return_value = expected # when result = user_service.find_by_id(1) # then assert result == expected user_service.repository.find_by_id.assert_called_once_with(1) def test_find_by_id_raises_when_not_found(self, user_service): # given user_service.repository.find_by_id.return_value = None # when/then with pytest.raises(UserNotFoundError): user_service.find_by_id(999) # 参数化测试 @pytest.mark.parametrize("input,expected", [ (1, 1), (2, 4), (3, 9), ]) def test_square(input, expected): assert square(input) == expected ``` --- ## 异步编程 ```python import asyncio from typing import List async def fetch_user(user_id: int) -> User: """异步获取用户""" async with aiohttp.ClientSession() as session: async with session.get(f"/api/users/{user_id}") as response: data = await response.json() return User(**data) async def fetch_all_users(user_ids: List[int]) -> List[User]: """并发获取多个用户""" tasks = [fetch_user(uid) for uid in user_ids] return await asyncio.gather(*tasks) # 限制并发数 async def fetch_with_limit(user_ids: List[int], limit: int = 10) -> List[User]: semaphore = asyncio.Semaphore(limit) async def fetch_one(uid: int) -> User: async with semaphore: return await fetch_user(uid) return await asyncio.gather(*[fetch_one(uid) for uid in user_ids]) ``` --- ## 项目结构 ``` project/ ├── src/ │ └── myproject/ │ ├── __init__.py │ ├── models/ │ ├── services/ │ ├── repositories/ │ └── utils/ ├── tests/ │ ├── __init__.py │ ├── conftest.py │ └── test_*.py ├── pyproject.toml ├── requirements.txt └── README.md ``` --- ## 依赖管理 ```toml # pyproject.toml (推荐) [project] name = "myproject" version = "1.0.0" dependencies = [ "fastapi>=0.100.0", "sqlalchemy>=2.0.0", ] [project.optional-dependencies] dev = [ "pytest>=7.0.0", "black>=23.0.0", "mypy>=1.0.0", ] ``` --- ## 性能优化 | 场景 | 方案 | |------|------| | 大数据处理 | 使用生成器 `yield` | | 字符串拼接 | 使用 `''.join()` | | 查找操作 | 使用 `set` 或 `dict` | | 并发 I/O | 使用 `asyncio` | | CPU 密集 | 使用 `multiprocessing` | ```python # ✅ 使用生成器 def read_large_file(file_path: str): with open(file_path, 'r') as f: for line in f: yield line.strip() # ✅ 高效字符串拼接 result = ''.join(strings) # 而不是 += 循环 ``` --- > 📋 本回复遵循：`python-dev` - [具体章节]