⚡

Python开发技能Skill python

此技能提供现代Python开发的全面指南，涵盖从简单脚本到生产系统的所有方面，包括安装、代码风格、项目结构、依赖管理、测试、类型提示、代码质量、安全、性能优化和打包。适用于Python开发者、团队项目和长期维护的代码，关键词包括Python开发、PEP-8、Ruff、pytest、mypy、uv、项目结构、测试、打包、安全、性能。

后端开发 0 次安装 0 次浏览 更新于 3/11/2026

名称: python 描述: 自适应Python开发指南，具有分级复杂度级别（最小/标准/完整）。根据项目上下文自动选择适当的指导 - 从简单脚本（仅干净Python代码）到完整生产系统（完整工具生态系统）。涵盖现代约定、测试、工具、安全和最佳实践。在编写Python代码、转换脚本、设置项目或构建生产系统时使用。关键词: PEP-8, Ruff, pytest, mypy, 简单脚本, 项目结构, PyPI, 打包, 类型提示, 干净代码 允许工具: Read, Bash, Glob, Grep

Python开发技能

全面指南，涵盖现代Python开发，包括约定、测试、工具、安全、性能和生态系统最佳实践（2024-2025标准）。

第2层快速开始

适用于多文件项目、团队协作和维护的代码：

# 安装Python 3.12和uv（参见安装指南）
# Windows: winget install Python.Python.3.12 && winget install astral-sh.uv
# macOS: brew install python@3.13 uv
# Linux: apt install python3.13 && curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用现代结构创建新项目
uv init my-project
cd my-project

# 添加依赖项
uv add requests httpx pydantic

# 添加开发依赖项
uv add --dev pytest pytest-cov ruff mypy

# 设置代码质量（创建pyproject.toml配置 - 参见assets/pyproject-toml-template.toml）
# 配置Ruff、mypy、pytest

# 编写测试（pytest）
# tests/test_example.py - 镜像src/结构

# 运行质量检查
uv run ruff check .          # 代码检查
uv run ruff format .         # 格式化
uv run mypy .                # 类型检查
uv run pytest                # 运行测试
uv run pytest --cov          # 带覆盖率

何时使用此技能

在需要以下指导时调用此技能：

  • 安装与设置：安装Python 3.12/3.14、uv，设置开发环境
  • 代码风格：遵循PEP-8，配置Ruff/Black，命名约定
  • 项目结构：使用src/布局组织代码，导入，包结构
  • 依赖管理：使用uv、Poetry、pip、虚拟环境、pyproject.toml
  • 测试：编写pytest测试、夹具、参数化、覆盖率、模拟
  • 类型提示：现代类型模式、mypy配置、协议、泛型
  • 代码质量：设置Ruff、mypy、Bandit、预提交钩子、CI/CD
  • 异步编程：asyncio模式、async/await、TaskGroup、结构化并发
  • 安全：OWASP最佳实践、输入验证、依赖扫描
  • 性能：性能分析、优化模式、Cython
  • 打包：pyproject.toml、PyPI发布、版本控制、分发
  • 常用库：标准库要点、生态系统概述
  • 文档：文档字符串（PEP-257）、Sphinx、文档生成

概述

此技能提供符合当前最佳实践（2024-2025）的现代Python开发指导：

核心标准：

  • 风格：PEP-8（通过Ruff强制执行）
  • 类型提示：PEP-484、PEP-526、现代语法（PEP-604：str | None）
  • 打包：PEP-517、PEP-518（pyproject.toml）
  • 文档字符串：PEP-257
  • 测试：pytest（行业标准）
  • 依赖管理：uv（最快）或Poetry（功能丰富）

现代工具（2024-2025）：

  • 代码检查器/格式化器：Ruff（替代flake8、isort，可选Black）
  • 类型检查器：mypy带严格模式
  • 测试框架：pytest
  • 依赖管理器：uv或Poetry
  • 安全扫描器：Bandit + pip-audit
  • 项目配置：pyproject.toml（通用）

项目结构：

  • src/布局（现代标准，非扁平布局）
  • 绝对导入优于相对导入
  • 测试镜像src/结构
  • pyproject.toml用于所有配置

官方来源： 所有指导基于官方Python文档、PEP和工具文档：

快速层级选择

选择您的复杂度级别：

🎯 第1层：最小（简单脚本）

→ 单文件实用程序、转换脚本、一次性自动化 → 仅Python代码 - 无工具开销 → 跳转到最小指导

📦 第2层：标准（组织化项目）

→ 多文件模块、团队项目、维护的代码 → 现代项目结构 + 测试 → 跳转到标准指导

🚀 第3层：完整（生产系统）

→ PyPI包、企业系统、生产部署 → 完整工具生态系统 → 跳转到完整指导

不确定？ 默认使用第2层（标准） - 它覆盖大多数用例。

第1层：最小（简单脚本）

适用于： 单文件实用程序、脚本转换和简单自动化。

设置

仅Python 3.12+ - 无需额外工具：

  • ✅ 无需uv，无需虚拟环境
  • ✅ 无需pyproject.toml，无需src/布局
  • ✅ 可选：安装Ruff进行快速代码检查（pip install ruff）

代码标准

遵循这些简单原则：

  • PEP-8命名：函数/变量使用snake_case，类使用PascalCase
  • 类型提示：为清晰度添加（帮助读者理解代码）
  • 文档字符串：函数的简单描述
  • pathlib：使用pathlib.Path进行文件操作（非os.path）
  • 内置功能：使用Python的内置json、datetime、sys模块

示例：简单日志脚本

#!/usr/bin/env python3
"""简单日志实用程序 - 将事件转换为JSON。"""

import json
import sys
from datetime import datetime, timezone
from pathlib import Path


def log_event(event_name: str, data: dict) -> None:
    """
    将事件记录到每日JSONL文件。

    参数:
        event_name: 事件名称
        data: 要记录的事件数据
    """
    log_dir = Path(__file__).parent / "logs"
    log_dir.mkdir(exist_ok=True)

    now = datetime.now(timezone.utc)
    log_file = log_dir / f"{now:%Y-%m-%d}.jsonl"

    entry = {
        "timestamp": now.isoformat(),
        "event": event_name,
        "data": data
    }

    with open(log_file, "a", encoding="utf-8") as f:
        f.write(json.dumps(entry) + "
")


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: script.py <event_name>", file=sys.stderr)
        sys.exit(1)
    event_name = sys.argv[1]
    data = json.loads(sys.stdin.read())
    log_event(event_name, data)

可选：快速代码检查

如果您想检查代码风格：

# 安装Ruff（可选）
pip install ruff

# 检查代码
ruff check script.py

# 格式化代码
ruff format script.py

何时升级到第2层

考虑升级到第2层（标准）当：

  • ✅ 脚本增长到3个以上文件
  • ✅ 多人在代码上工作
  • ✅ 需要自动化测试
  • ✅ 管理外部依赖项
  • ✅ 代码将长期维护

第2层：标准（组织化项目）

适用于： 多文件模块、团队项目和维护的代码。

现代Python项目设置，具有适当的结构、测试和质量工具。

安装

安装Python 3.12+和uv（现代依赖管理器）。参见平台特定指南：

项目设置和组织

约定和风格 - 遵循PEP-8，使用Ruff进行代码检查和格式化：

项目结构 - 使用现代src/布局进行适当打包：

依赖管理 - 在uv（最快）、Poetry（功能丰富）或pip+venv之间选择：

测试和质量

测试 - 使用pytest与夹具、参数化和覆盖率：

类型提示 - 现代类型化与mypy、协议和泛型：

代码质量 - 设置Ruff、mypy、Bandit和预提交钩子：

高级开发

异步编程 - asyncio模式、TaskGroup、结构化并发：

安全 - OWASP最佳实践、输入验证、密钥管理：

性能 - 性能分析、优化模式、内存效率：

打包 - 使用pyproject.toml和语义版本控制发布到PyPI：

库 - 标准库要点和生态系统概述：

文档 - PEP-257文档字符串、Sphinx、ReadTheDocs：

第3层：完整（生产系统）

适用于： PyPI包、企业系统和生产部署。

第2层（标准）中的所有内容加上：

安全和质量

  • 安全扫描：Bandit用于代码安全，pip-audit用于依赖漏洞
  • 预提交钩子：每次提交前的自动化检查
  • 全面类型覆盖：mypy严格模式覆盖整个代码库
  • 代码覆盖率执行：CI/CD中的最低覆盖率要求

分发

  • PyPI打包：构建并发布Python包到PyPI
  • 语义版本控制：遵循semver进行版本管理
  • 二进制分发：创建wheel以加速安装
  • 多平台支持：测试和构建Windows/macOS/Linux

CI/CD

  • GitHub Actions / GitLab CI：每次推送的自动化测试
  • 多版本测试：针对Python 3.12、3.13、3.14测试
  • 覆盖率跟踪：自动化覆盖率报告和执行
  • 发布自动化：标签上的自动PyPI发布

文档

  • Sphinx：从文档字符串生成API文档
  • ReadTheDocs：托管带版本控制的文档
  • 全面文档字符串：所有公共API的Google或NumPy风格
  • 示例和教程：面向用户的文档带示例

详细指南

参见这些参考文件以获取全面的生产指导：

参考文件

所有详细指导都在references/目录中：

安装：

核心开发：

高级主题：

资产

模板文件：

测试和评估

此技能包括正式评估场景以验证有效性：

  • 参见技能评估场景 覆盖的测试案例：
    • 最小层（简单脚本）
    • 标准层（新项目、代码质量工具）
    • 完整层（生产系统）
    • 替代工作流（Poetry vs uv）
    • 成功标准和测试方法

相关技能

  • git-commit：Git提交工作流（补充Python项目工作流）
  • git:git-config：Git配置（Python项目使用Git）
  • code-quality:markdown-linting：通过插件的Markdown代码检查（Python项目有README）

版本历史

  • 1.1.2 (2025-11-25): 全面改进
    • 修复了示例代码中已弃用的datetime.utcnow()（使用datetime.now(timezone.utc)）
    • 添加了Python 3.13覆盖（原在3.12和3.14之间缺失）
    • 更新了PEP URL到现代格式（peps.python.org替代python.org/dev/peps/）
    • 在示例代码中添加了UTF-8编码到文件打开
    • 在示例中添加了缺失CLI参数的错误处理
  • 1.1.1 (2025-11-25): 版本审计更新
    • 更新了工具版本引用（Ruff 0.14.x、mypy 1.18.x、pytest 9.x）
    • 验证了所有参考文件链接存在且正确
    • 根据官方要求验证了YAML前言
  • 1.1.0 (2025-11-18): 自适应分层指导
    • 添加了三层复杂度系统（最小/标准/完整）
    • 第1层：最小指导用于简单脚本（无工具开销）
    • 第2层：标准指导用于组织化项目（原始快速开始）
    • 第3层：完整指导用于生产系统（全面工具）
    • 上下文感知技能根据查询自动选择适当层级
    • 防止“大爆炸”过度工程用于简单场景
  • 1.0.0 (2025-11-17): 初始发布
    • 全面现代Python指导（2024-2025标准）
    • 从docs/python/迁移了安装文档
    • 添加了12个详细参考文件
    • 现代工具：Ruff、uv、pytest、mypy
    • pyproject.toml模板

官方文档

Python：

工具：

PEPs（Python增强提案）：

最后更新

日期： 2025-11-28 模型： claude-opus-4-5-20251101