随着 Python 生态的快速演进，许多传统的工具（如 pip, virtualenv, flake8）正逐渐被更现代、更高效的工具所取代。本文将介绍一套现代化的 Python 开发环境配置方案，旨在提升开发效率、代码质量和运行性能。

1. 基础：IDE

1.1 VS Code 及其插件与配置

VS Code 是目前最流行的 Python 开发工具。首先，建议前往 VS Code 官网下载安装。

配置建议：建议去掉以下勾选，以避免与现代工具冲突：

推荐插件：安装以下插件以获得最佳开发体验：

1.2 AI 编程工具

Cursor：深度集成 AI 的智能编辑器，配置与 VS Code 兼容，强烈推荐。
Trae：字节跳动研发的国内 AI 编程工具，目前功能迭代中。

2. 底层：uv

2.1 uv 简介

uv 是一个速度极快的 Python 包安装器和解析器，由 Ruff 的作者 Charlie Marsh 开发，并由 Astral 公司提供支持。你可以把它看作是 pip 和 pip-tools 的一个高性能替代品，旨在解决 Python 包管理中长期存在的速度和性能问题。

安装方法（推荐使用 curl）：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

快速开始：

# 1. 创建并进入项目目录
mkdir my-python-project
cd my-python-project

# 2. 使用 uv 创建虚拟环境 (它会默认创建在 .venv 目录)
uv venv

# 3. 激活虚拟环境
source .venv/bin/activate
# Windows 用户: .venv\Scripts\activate

2.2 为什么会出现 uv

1. 统一的工具链 (Unified Toolchain)

uv 的核心理念是将过去分散的多个工具整合为一。在 uv 出现之前，一个典型的 Python 项目可能需要：

python -m venv .venv：创建虚拟环境
pip：安装包
pip-tools：从 requirements.in 解析和锁定依赖到 requirements.txt
pipx：安装和管理全局命令行工具

uv 将以上所有功能整合到了一个二进制文件中，你可以用 uv venv, uv pip install, uv pip compile, uv tool install 等子命令完成所有操作。这大大简化了工具管理和项目配置。

2. 全局缓存 (Global Cache)

这是 uv 速度的终极秘诀。当你第一次安装一个包（例如 pandas==2.2.0）时，uv 会：

下载 wheel 文件。
将其解压到一个全局共享的、与版本和平台相关的缓存目录中。

当你再次在任何项目中安装同一个版本的 pandas 时，uv 不会重新下载或解压，而是直接从缓存中创建硬链接（或在不支持的系统上进行复制）到你的虚拟环境。这个过程几乎是瞬时的。

关键点：缓存是全局的，所有由 uv 管理的项目共享这份福利。
相关命令：
- uv cache dir：查看缓存目录的位置。
- uv cache clean：清空缓存。

3. 高性能解析器 (High-Performance Resolver)

依赖解析是找出所有包（包括子依赖）的兼容版本集合的过程。pip 的传统解析器较慢，尤其是在依赖关系复杂时。

uv 使用一个用 Rust 编写的高性能解析器，其特点是：

大规模并行：它会同时获取所有顶层依赖的元数据。
高效的版本选择算法：能非常迅速地找到满足所有约束条件的版本组合。

这意味着，即使你有复杂的 pyproject.toml 或 requirements.in 文件，uv pip compile 也能在极短的时间内生成一个精确的、可复现的 requirements.txt 锁定文件。

2.3 常用操作

uv venv                     # 创建环境
uv venv my-env -p 3.11      # 指定环境名字和python版本
uv venv -p python@3.11      # 使用 python3.11 创建 .venv
source .venv/bin/activate   # 激活环境 (此步仍然需要)
uv init                     # 初始化uv项目
uv pip install              # 装包
uv add                      # 为项目加包
uv sync                     # 如果有拉取一个uv的项目，直接sync即可配置好环境
uv pip freeze > requirements.txt # 生成包含所有已安装包及其精确版本的列表

2.4 进阶内容

1. 依赖解析与锁定

代替 pip-tools，从一个 requirements.in 文件生成一个锁定的 requirements.txt。

uv pip compile requirements.in -o requirements.txt

2. 全局工具安装

代替 pipx：

# 安装工具
uv tool install ruff
uv tool install black --python python3.11  # 指定python版本

# 管理工具
uv tool list         # 列出所有已安装的工具
uv tool uninstall ruff # 卸载工具
uv tool run black .  # 在不激活环境的情况下运行工具

2.5 必知必会：pyproject.toml

一、pyproject.toml 是什么？

pyproject.toml 是一个由 PEP 518 引入并由后续多个 PEP 扩展的、统一的 Python 项目配置文件。

它的核心目标是解决过去配置混乱的问题。在它出现之前，一个项目可能同时包含 setup.py, setup.cfg, requirements.txt, MANIFEST.in, 以及各种工具的配置文件（如 .flake8, .coveragerc, mypy.ini 等）。

pyproject.toml 使用 TOML 格式，旨在成为这些配置的唯一入口和最终归宿，让项目结构更清晰、更标准化。

二、它解决了什么核心问题？

它主要解决了 setup.py 时代的两个痛点：

静态元数据的缺失：setup.py 是一个可执行的 Python 脚本。这意味着，如果不运行它，你无法确定构建项目需要哪些依赖（即 "build-time dependencies"）。这就产生了一个"先有鸡还是先有蛋"的悖论。
配置分散：项目配置散落在十几个不同的文件中，难以管理。

pyproject.toml 通过一个静态的、声明性的文件解决了这两个问题。

三、pyproject.toml 的结构

文件由多个"表"（table）组成，每个表用 [table_name] 表示。主要分为三大类：

[build-system]：定义项目的构建系统。
[project]：定义项目的核心元数据（包名、版本、依赖等）。
[tool.*]：用于配置各种第三方工具（如 uv, ruff, mypy, pytest 等）。

1. [build-system] 表

它告诉打包工具（如 pip）如何构建你的项目。

[build-system]
# --- 声明构建项目本身所需要的依赖 ---
requires = ["setuptools>=61.0"]
# --- 指定用于构建的 Python 后端对象 ---
build-backend = "setuptools.build_meta"

requires: 声明了构建你的包需要哪些依赖。常见的有 setuptools, hatchling, flit_core, poetry-core。
build-backend: 指向一个 Python 对象，这个对象知道如何构建你的包。

2. [project] 表

这是项目的"身份证"，由 PEP 621 标准化。

[project]
name = "my-package"
version = "0.1.0"
description = "A short description of my project."
readme = "README.md"
requires-python = ">=3.9"
license = { file = "LICENSE" }

authors = [
  { name = "Your Name", email = "your.email@example.com" },
]

keywords = ["packaging", "python", "example"]

# --- 核心依赖 ---
dependencies = [
  "httpx",
  "rich>=13.0.0",
  'tomli; python_version < "3.11"',
]

# --- 可选依赖 ---
[project.optional-dependencies]
test = ["pytest", "pytest-cov"]
dev = [
  "my-package[test]",
  "ruff",
  "mypy",
]

# --- 命令行脚本入口 ---
[project.scripts]
my-cli = "my_package.cli:main"

# --- 项目相关链接 ---
[project.urls]
Homepage = "https://github.com/user/my-package"
Repository = "https://github.com/user/my-package"

3. [tool.*] 表

这是 pyproject.toml 最强大的功能之一：统一配置所有开发工具。每个工具都可以定义自己的配置表，以 [tool.工具名] 的形式存在。

# --- uv 的配置 ---
[tool.uv.pip]
extra-index-url = "https://my-private-registry.com/simple"

# --- ruff (linter/formatter) 的配置 ---
[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I"]
ignore = ["E501"]

[tool.ruff.lint.isort]
known-first-party = ["my_package"]

# --- mypy (type checker) 的配置 ---
[tool.mypy]
python_version = "3.11"
warn_return_any = true
ignore_missing_imports = true

四、完整示例

# pyproject.toml

# 1. 构建系统配置
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

# 2. 项目核心元数据
[project]
name = "data-analyzer"
version = "1.0.0"
description = "A tool for analyzing data sets."
readme = "README.md"
requires-python = ">=3.9"
license = { text = "MIT" }
authors = [{ name = "Data Team", email = "data@example.com" }]

dependencies = [
  "pandas>=2.0.0",
  "numpy",
  "matplotlib",
]

[project.optional-dependencies]
dev = [
  "pytest",
  "ruff",
  "uv >= 0.1.0",
]

[project.scripts]
analyze = "data_analyzer.main:run"

[project.urls]
Repository = "https://github.com/example/data-analyzer"

# 3. 第三方工具配置
[tool.ruff]
line-length = 99
select = ["E", "F", "W", "I", "N", "D"]
ignore = ["D100", "D104"]

[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-ra -q"
testpaths = ["tests"]

总结

pyproject.toml 是现代 Python 项目的配置标准。
它使用 TOML 格式，结构清晰，声明式而非可执行。
[build-system] 定义了如何构建项目。
[project] 定义了项目是什么，是包的元数据中心。
[tool.*] 允许你将所有工具链的配置集中于一处。

对于任何新启动的 Python 项目，都应优先使用 pyproject.toml 作为唯一的配置文件。

2.6 和 Conda 的区别

特性	uv	Conda
速度	⚡ 极快	慢
生态	PyPI（Python 优先）	conda-forge（跨语言）
非 Python 依赖	❌	✅
CUDA/MKL 优化	依赖系统	内置支持
适合你吗？	✅ 大多数 AI/仿真项目	仅当需要 conda 特供包

🚀 趋势：随着 uv、pixi（conda 的 Rust 替代品）等工具出现，纯 Python 项目正快速转向 uv，而 conda 仍主导科学计算重依赖场景。

2.7 最佳实践

声明 (Declare)：在一个源文件中（推荐 pyproject.toml）声明你的项目直接依赖。这是你的"依赖源头"。
锁定 (Lock)：使用 uv pip compile 将你的声明性依赖解析为一个包含所有包（包括子依赖）精确版本的"锁定文件"。
同步 (Sync)：使用 uv pip sync 根据锁定文件来安装依赖。这个命令会确保你的虚拟环境与锁定文件完全一致。

场景	✅ 推荐做法	❌ 避免做法
依赖声明	在 `pyproject.toml` 中管理所有依赖	使用多个 `requirements.in` 或直接手写
安装依赖	使用 `uv pip sync -r <lockfile>`	使用 `pip install -r` 直接安装
更新依赖	修改 `pyproject.toml` → `uv pip compile` → `uv pip sync`	手动修改 `requirements.txt`
全局工具	使用 `uv tool install`	使用 `sudo pip install` 或 `pip install --user`
团队协作	将锁定文件 (`*.txt`) 提交到 Git	将 `.venv` 目录提交到 Git

3. 语法：Ruff

3.1 为什么会出现 Ruff

在 Ruff 出现之前，一个标准的项目可能需要配置以下工具：

Flake8：用于代码风格和逻辑错误检查。
pycodestyle, pyflakes：Flake8 的核心插件。
isort：用于 import 语句排序。
pylint：更严格的、可配置的 Linter。
pyupgrade：用于自动升级 Python 语法。
autoflake：用于移除未使用的导入。
black：用于代码格式化。

Ruff 的目标是替代以上所有工具。你只需要安装和配置 ruff 这一个依赖，就能获得上述大部分功能。这极大地简化了项目的依赖管理和配置文件。

3.2 Ruff 简介

Ruff 是一个用 Rust 编写的、速度极快的 Python Linter 和 Formatter。

它的核心使命是用一个工具替代过去 Python 开发中需要安装和配置的一大堆零散的工具。它将代码检查（Linting）、代码格式化（Formatting）、导入排序、语法升级等功能全部整合到了一个快如闪电的二进制文件中。

核心优势

1. 极致的速度 (Extreme Speed)

这是 Ruff 最引人注目的特点。因为它使用 Rust 编译，而不是作为 Python 脚本运行，所以它避免了 Python 解释器的启动开销，并且能更好地利用多核 CPU 进行并行处理。

量化对比：Ruff 的运行速度通常比它所替代的工具（如 Flake8 + 插件、isort、pylint）快 10 到 100 倍。
实际影响：
- 在 CI/CD 流程中，代码检查步骤从几分钟缩短到几秒钟。
- 在本地开发时，反馈都是瞬时的，毫无延迟感。

2. 内置自动修复 (--fix)

Ruff 不仅仅能发现问题，它还能自动修复大量问题。它的自动修复功能非常强大且安全，涵盖：

自动排序 import 语句。
移除未使用的导入和变量。
将代码自动升级到更现代的 Python 语法。
修复许多代码风格问题。

主要功能

1. Linter (ruff check)

这是 Ruff 的核心功能。它包含了数百条来自各种流行工具的规则，你可以通过规则代码来选择启用或禁用。

F 开头：来自 Pyflakes (逻辑错误)
E, W 开头：来自 pycodestyle (代码风格)
I 开头：来自 isort (导入排序)
D 开头：来自 pydocstyle (文档字符串)
UP 开头：来自 pyupgrade (语法升级)

2. Formatter (ruff format)

这是 Ruff 相对较新的功能，旨在成为 black 的高性能替代品。

兼容性目标：它致力于在默认配置下生成与 black 几乎完全相同的输出。
性能优势：同样，ruff format 的速度远超 black。

3.3 常用操作

任务	命令
格式化我的代码	`ruff format .`
检查代码问题并自动修复	`ruff check . --fix`
在 CI/CD 中验证格式	`ruff format . --check`
在 CI/CD 中检查代码质量	`ruff check .`
开发时实时检查	`ruff check . --watch`
搞不清某条规则是什么意思	`ruff rule <RULE_CODE>`
清理缓存	`ruff cache clean`
终极清理	`ruff format . && ruff check . --fix`

3.4 进阶内容

1. 启用预览功能（Preview Features）

Ruff 的许多强大功能目前处于 preview 模式，需显式启用：

[tool.ruff]
preview = true

或命令行启用：

ruff check --preview .
ruff format --preview .

💡 建议：在新项目中开启 preview = true，以获得最新规则和修复能力。

2. 类型感知 Lint（Type-Aware Linting）

Ruff 在 preview 模式下支持轻量级类型推断，用于增强规则判断。

RUF014: 冗余的 isinstance(x, str)（当 x: str 已知）
RUF015: 无效的 assert isinstance(...)（类型已确定）

⚠️ 注意：Ruff 不替代 Pyright/mypy，仅用类型信息增强 lint 规则。建议搭配 Pyright 做完整类型检查。

3. 细粒度规则控制（Per-File / Per-Line）

(a) 忽略特定文件/目录

[tool.ruff.lint]
extend-exclude = [
  "migrations/",
  "legacy_code.py",
  "scripts/temp_*.py"
]

(b) 为特定文件启用/禁用规则

[[tool.ruff.lint.per-file-ignores]]
"tests/**.py" = ["S101", "D"]  # 忽略 asserts 和 docstring 规则
"scripts/*.py" = ["T20"]       # 忽略 print 警告

(c) 行内忽略

x = 1  # noqa: E741  # 允许模糊变量名 'l', 'O', 'I'
print("debug")  # noqa: T201, T203

4. 自定义规则优先级与安全修复

[tool.ruff]
fix = true
unsafe-fixes = false  # 默认不应用可能改变语义的修复

安全修复：重命名、格式调整、删除无用导入等
不安全修复：修改逻辑（如 == → is）、重写表达式等

🛡️ 在 CI 中建议保持 unsafe-fixes = false，避免意外行为变更。

5. 与编辑器深度集成（VS Code）

推荐 VS Code 设置（settings.json）：

{
  "python.linting.enabled": false,
  "ruff.enable": true,
  "ruff.args": ["--preview"],
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

✅ 启用后，Ruff 同时提供 linting + formatting，无需 Black 或 Flake8。

6. CI/CD 集成最佳实践

GitHub Actions 示例：

- name: Run Ruff
  run: |
    pip install ruff
    ruff check . --output-format=github
    ruff format . --check  # 检查是否已格式化

--output-format=github：在 PR 中直接显示注释
ruff format --check：确保代码已格式化（不修改文件）

7. 迁移现有项目（从 Black + Flake8 + isort）

原工具	Ruff 对应能力
Black	`ruff format`
Flake8	`ruff check`（E/W/F）
isort	`ruff check`（I）
pyupgrade	`ruff check`（UP）
autoflake	`ruff check --fix`

迁移步骤：

安装 Ruff：pip install ruff
生成初始配置：ruff migrate（实验性命令，或手动配置）
一键格式化+修复：ruff check --fix . && ruff format .
移除旧工具依赖

3.5 pyproject.toml 配置

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_project"
version = "0.1.0"
description = "A modern Python project"
dependencies = []
requires-python = ">=3.10"

# ==============================
# 🛠️ Ruff 配置（Lint + Format）
# ==============================
[tool.ruff]
preview = true
target-version = "py310"
fix = true
unsafe-fixes = false
line-length = 88

extend-exclude = [
  ".git",
  "__pycache__",
  "venv",
  ".venv",
  "build",
  "dist",
  "notebooks",
]

# ==============================
# 🔍 Lint 规则配置
# ==============================
[tool.ruff.lint]
select = [
  "E", "W", "F",
  "I",
  "UP",
  "C4",
  "TID",
  "ARG",
  "PTH",
]

ignore = [
  "E501",
  "D",
]

[[tool.ruff.lint.per-file-ignores]]
"tests/**.py" = ["S101", "ARG", "PLR0913"]
"scripts/*.py" = ["T20"]

# ==============================
# 🧹 isort 配置（Ruff 内置）
# ==============================
[tool.ruff.lint.isort]
known-first-party = ["my_project"]
combine-as-imports = true
force-sort-within-sections = true

# ==============================
# ✨ Formatter 配置（替代 Black）
# ==============================
[tool.ruff.format]
preview = true
quote-style = "single"
skip-magic-trailing-comma = false
line-length = 88
indent-width = 4

# ==============================
# 🔤 Pyright 配置（类型检查）
# ==============================
[tool.pyright]
typeCheckingMode = "basic"
pythonVersion = "3.10"
include = ["src", "tests"]
exclude = [
  "**/node_modules",
  "**/__pycache__",
  ".venv",
  "venv",
  "build",
  "dist",
  "notebooks",
]
reportMissingTypeStubs = "none"
reportUnusedImport = "warning"
reportUnusedVariable = "warning"

3.6 最佳实践

统一使用 pyproject.toml 进行配置
放弃所有独立的配置文件（如 .isort.cfg, .flake8），将 Ruff 的所有配置集中在 pyproject.toml 的 [tool.ruff] 表中。
明确目标 Python 版本 (target-version)
这是最重要却也最容易被忽略的配置项。设定它能确保 Ruff 应用的规则与你的项目环境相匹配。
```
[tool.ruff]
target-version = "py311"
```
从一个稳健的基础规则集开始
不要一开始就想着启用所有规则。一个理智的起点是启用那些被广泛接受、能显著提升代码质量的核心规则集。
```
[tool.ruff]
# E: pycodestyle 错误, F: Pyflakes 逻辑错误, I: isort 导入排序, UP: pyupgrade 语法升级
select = ["E", "F", "I", "UP"]
```
拥抱自动修复 (--fix)
将 ruff check . --fix 作为你的常规操作。Ruff 的自动修复非常安全可靠。

4. 类型：Pyright

4.1 Pyright 简介

Pyright 是由微软开发的 静态类型检查器，专门针对 Python 的类型注解（PEP 484, PEP 561 等）。
用 TypeScript 编写，运行速度非常快（比 mypy 快很多）。
集成在 VS Code 的 Pylance 插件里，所以如果你用 VS Code，大概率已经在用 Pyright 了。

4.2 Pyright 特点

超快 —— 增量分析大项目时比 mypy 快数倍
类型推断更强 —— 能根据代码上下文自动推导类型
支持 strict mode —— 强制要求类型标注，避免漏网之鱼
跨平台集成 —— 可单独作为 CLI 工具运行 (pyright)，也能集成到 CI/CD

4.3 安装

1. 全局安装（npm 提供）

npm install -g pyright

2. 项目内配置

在项目根目录添加 pyrightconfig.json：

{
  "include": ["src"],
  "exclude": ["tests", "build"],
  "reportMissingImports": true,
  "reportUnusedVariable": "warning",
  "typeCheckingMode": "strict"
}

4.4 Pyright vs Mypy

特性	Pyright	Mypy
性能	🚀 极快	🐢 慢
IDE 集成	VS Code/Pylance 完美集成	PyCharm 较好
类型推断	更智能	依赖显式注解多
社区生态	新但发展快	历史悠久、兼容性好
配置	简单	灵活但复杂

5. 守门：pre-commit

5.1 介绍

首先要明白，"pre-commit"这个词有两个含义：

Git 自身的钩子 (Hook): Git 本身提供了一种"钩子"机制，允许你在特定的 Git 事件发生时自动执行自定义脚本。pre-commit 就是其中一个钩子，它在你输入 git commit 命令之后，但在正式生成 commit 对象之前触发。如果这个钩子脚本以非零状态码退出，那么整个 commit 过程就会被中止。
pre-commit 框架: 一个名为 pre-commit 的 Python 工具（框架）。通常我们所说的 pre-commit，指的就是这个框架。它极大地简化了管理和使用 Git 钩子的过程。

简单来说：pre-commit 框架利用了 Git 的 pre-commit 钩子功能，并将其变得极其强大和易于管理。

5.2 好处

自动化代码质量保障: 将代码检查（Linting）、格式化（Formatting）等任务从"需要开发者记住去做"变成了"自动强制执行"。再也不会有人忘记运行 ruff 就提交代码了。
保持团队一致性: 配置文件（.pre-commit-config.yaml）被提交到版本库中。这保证了团队中的每一个人都使用完全相同版本的工具进行检查。
提前发现问题 (Shift Left): 它在问题进入代码库之前就将其拦截。这远比在 Code Review 阶段或 CI/CD 流程中才发现问题要高效得多。
简化新成员的配置: 新加入的成员不需要手动安装一系列工具。他们只需要安装 pre-commit 这一个工具，然后运行 pre-commit install。

5.3 常用操作

操作目的	常用命令	说明
首次安装钩子	`pre-commit install`	每个开发者/每个项目只需一次
日常提交	`git commit`	自动触发，无需额外命令
检查所有文件	`pre-commit run --all-files`	初始化项目或在 CI 中使用
检查暂存文件	`pre-commit run`	手动触发对暂存区的检查
更新工具版本	`pre-commit autoupdate`	保持钩子配置为最新
修复损坏的环境	`pre-commit clean`	清理缓存，解决疑难杂症
紧急时跳过检查	`git commit --no-verify`	谨慎使用！临时绕过钩子

5.4 .pre-commit-config.yaml 配置

一、文件的核心作用

.pre-commit-config.yaml 是一个使用 YAML 格式的声明式配置文件。它的核心作用是告诉 pre-commit 框架：

从哪里 (Where): 从哪个代码仓库获取要运行的工具。
是什么 (What): 要运行的具体是哪个钩子（hook）。
怎么做 (How): 以何种方式、带何种参数来运行这个钩子。

二、文件的顶级结构

# 最核心的内容：一个包含多个仓库配置的列表
repos:
  # ... 第一个仓库的配置 ...
  # ... 第二个仓库的配置 ...

三、repos：核心配置块

repos 是一个列表，每个仓库配置包含以下关键字段：

repo: (必需) 包含钩子的代码仓库地址。
rev: (必需) 指定要使用的仓库的 Git 修订版本。必须使用一个固定的版本号。
hooks: (必需) 一个列表，定义了你希望从这个 repo 中启用哪些钩子。

四、完整示例

# .pre-commit-config.yaml

minimum_pre_commit_version: '2.9.0'

repos:
-   # 仓库 1: pre-commit 官方提供的通用钩子
    repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
    -   id: trailing-whitespace      # 移除行尾多余空格
    -   id: end-of-file-fixer        # 保证文件末尾有空行
    -   id: check-yaml               # 检查 YAML 文件语法
    -   id: check-json               # 检查 JSON 文件语法
    -   id: check-toml               # 检查 TOML 文件语法
    -   id: check-added-large-files  # 防止提交大于 5MB 的大文件
        args: ['--maxkb=5120']

-   # 仓库 2: Ruff - 高性能的 Linter 和 Formatter
    repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.0
    hooks:
    -   id: ruff
        args: [--fix]
    -   id: ruff-format

-   # 仓库 3: 防止密钥泄露的 trufflehog
    repo: https://github.com/trufflesecurity/trufflehog
    rev: v3.77.1
    hooks:
    -   id: trufflehog
        name: TruffleHog - Scan for secrets

-   # 仓库 4: 本地钩子，用于运行项目自身的 Mypy
    repo: local
    hooks:
    -   id: mypy
        name: mypy
        entry: mypy .
        language: system
        types: [python]
        args: ["--ignore-missing-imports"]
        require_serial: true

解析：

第一个 repo: 引入了一系列与语言无关的、通用的文件检查工具。
第二个 repo: 引入了 ruff，配置了自动修复 (--fix)。
第三个 repo: 使用 TruffleHog 防止密钥泄露。
第四个 repo (local): repo: local 表示这个钩子运行的命令来自本地环境。language: system 告诉 pre-commit 直接使用当前激活的虚拟环境中的 mypy。

6. 美化：Rich

6.1 Rich 简介

rich 是一个用于在终端中创建富文本和精美格式化输出的 Python 库。它可以让你的命令行界面（CLI）应用程序变得更加美观和易于阅读。

核心优势

易用性：rich 的 API 设计非常直观和 "Pythonic"，很容易上手。
功能强大：支持颜色、样式、表格、进度条、Markdown、语法高亮、漂亮的 Traceback 等多种功能。
跨平台：在 Windows, macOS 和 Linux 上表现良好。
自动化：能自动检测终端宽度并换行，智能处理文本溢出。

6.2 安装

uv pip install rich

6.3 核心功能详解

1. Console 对象与 print 函数

rich 的核心是 Console 对象。你可以使用类似 BBCode 的标记语法来轻松添加样式。

代码解释:

Console() 创建一个控制台对象。

console.print() 是 rich 版的 print。

[style]...[/style] 是 rich 的标记语法，用于包裹你想要添加样式的文本。

2. 精美的表格 (Table)

在终端中手动创建对齐的表格是一件很痛苦的事，但 rich 的 Table 类让这一切变得异常简单。

代码解释:

Table(title="...") 创建一个带标题的表格。

table.add_column(...) 定义每一列的标题和样式。

table.add_row(...) 添加一行数据。rich 会自动处理对齐和宽度。

3. 进度条 (Progress)

对于长时间运行的任务，提供一个进度条可以极大地提升用户体验。

代码解释:

with Progress() as progress: 创建一个进度条上下文管理器。

progress.add_task(...) 添加一个新的跟踪任务。

progress.update(task_id, advance=...) 更新指定任务的进度。

4. Markdown 渲染

你甚至可以在终端里直接渲染 Markdown 文本。

5. 语法高亮 (Syntax)

rich 可以对代码进行语法高亮显示，支持多种语言。

6. 漂亮的 Traceback

当程序出错时，rich 可以自动格式化这些错误信息，使其更加清晰易读。

from rich.traceback import install

install()

# 下面这段代码会故意触发一个错误
def faulty_function():
    result = 1 / 0
    return result

faulty_function()

运行这段代码，你将看到一个经过语法高亮、代码上下文清晰、变量值明确的错误报告，定位问题会快得多。

6.4 总结

rich 是一个现代化、功能全面且易于使用的 Python 库，它极大地改善了命令行应用的开发体验和最终用户的视觉体验。无论你是想为你的脚本添加一些简单的彩色输出，还是构建一个复杂的、专业的 CLI 工具，rich 都是一个非常值得学习和使用的选择。

7. 总结

通过组合使用 VS Code/Cursor + uv + Ruff + Pyright + pre-commit + Rich，我们可以构建一个既快速又标准化的现代 Python 开发环境。这些工具不仅提高了代码质量，更重要的是在日常开发、安装依赖和调试问题时节省了大量时间。

能力	说明
一体化工具链	uv 替代 pip + pip-tools + pipx
统一代码检查	Ruff 替代 Black + Flake8 + isort + pyupgrade
极速性能	比传统工具快 10–100 倍
类型检查	Pyright 提供智能类型推断
自动化守门	pre-commit 在提交前自动检查
终端美化	Rich 让 CLI 输出更专业

搬运自：【Python/uv】迈向AI的第零步！现代化Python工具指南（作者：木乔_Mokio）

Python uv Ruff Pyright pre-commit Rich 技术教程

现代化 Python 开发环境配置指南

1. 基础：IDE

1.1 VS Code 及其插件与配置

1.2 AI 编程工具

2. 底层：uv

2.1 uv 简介

2.2 为什么会出现 uv

1. 统一的工具链 (Unified Toolchain)

2. 全局缓存 (Global Cache)

3. 高性能解析器 (High-Performance Resolver)

2.3 常用操作

2.4 进阶内容

1. 依赖解析与锁定

2. 全局工具安装

2.5 必知必会：pyproject.toml

一、pyproject.toml 是什么？

二、它解决了什么核心问题？

三、pyproject.toml 的结构

1. [build-system] 表

2. [project] 表

3. [tool.*] 表

四、完整示例

总结

2.6 和 Conda 的区别

2.7 最佳实践

3. 语法：Ruff

3.1 为什么会出现 Ruff

3.2 Ruff 简介

核心优势

主要功能

3.3 常用操作

3.4 进阶内容

1. 启用预览功能（Preview Features）

2. 类型感知 Lint（Type-Aware Linting）

3. 细粒度规则控制（Per-File / Per-Line）

4. 自定义规则优先级与安全修复

5. 与编辑器深度集成（VS Code）

6. CI/CD 集成最佳实践

7. 迁移现有项目（从 Black + Flake8 + isort）

3.5 pyproject.toml 配置

3.6 最佳实践

4. 类型：Pyright

4.1 Pyright 简介

4.2 Pyright 特点

4.3 安装

1. 全局安装（npm 提供）

2. 项目内配置

4.4 Pyright vs Mypy

5. 守门：pre-commit

5.1 介绍

5.2 好处

5.3 常用操作

5.4 .pre-commit-config.yaml 配置

一、文件的核心作用

二、文件的顶级结构

三、repos：核心配置块

四、完整示例

解析：

6. 美化：Rich

6.1 Rich 简介

核心优势

6.2 安装

6.3 核心功能详解

1. Console 对象与 print 函数

2. 精美的表格 (Table)

3. 进度条 (Progress)

4. Markdown 渲染

5. 语法高亮 (Syntax)

6. 漂亮的 Traceback

6.4 总结

7. 总结