常用库 on 扎塔-Zata

Typer + Rich 入门教程

Tue, 09 Jun 2026 15:30:00 +0800

最近在写一个运维工具,翻了一圈 Python 写 CLI 的库,最后选了 Typer + Rich。这套组合的好处是:用类型注解写 CLI,自动拿到漂亮的 help 页面、参数解析、子命令,基本不用自己处理模板代码。这篇把学习过程整理一下,适合第一次用 Typer 的同学。

为什么是 Typer + Rich

Typer:基于 Click,用 Python 类型注解构建 CLI。help 文本、参数解析、子命令、shell completion 都是开箱即用。
Rich:终端美化库。Typer 内置 Rich 集成,所以你看到的 ╭─╮ 框线、分组的 Options/Commands 面板、错误高亮全是 Rich 自动渲染的,不用自己写一行 Rich 代码。Rich 自己还能画表格、进度条、Markdown、JSON 语法高亮等。

两个库配合,Python 写 CLI 的体验接近 cargo / npm 这种专业工具。

五分钟上手

最小可运行的 CLI,五行就够:

import typer

app = typer.Typer()

@app.command()
def hello(name: str):
 """Say hello to NAME."""
 typer.echo(f"Hello, {name}!")

if __name__ == "__main__":
 app()

保存为 demo.py,运行 python demo.py Alice → Hello, Alice!。加 --help 就能看到 Rich 渲染的 help 页面,零额外配置。

核心概念

Arguments:必填位置参数

@app.command()
def deploy(env: str, version: str):
 """Deploy VERSION to ENV."""
 ...

调用:deploy prod v1.2.0。少传任何一个,Typer 都会报错并提示。

Options:可选命名参数

@app.command()
def deploy(
 env: str,
 version: str,
 region: str = typer.Option("us-east-1", help="AWS region."),
 dry_run: bool = typer.Option(False, "--dry-run", help="Preview only."),
 verbose: int = typer.Option(0, "-v", count=True, help="Verbosity level."),
):
 ...

调用:

deploy prod v1.2.0 --region eu-west-1 --dry-run -vvv

几个关键点:

写法	含义
`param: str`	必填位置参数
`param: str = typer.Option("default")`	有默认值的 option
`param: bool = typer.Option(False, "--dry-run")`	flag,出现即 True
`param: int = typer.Option(0, "-v", count=True)`	短选项,支持 `-v -v -v` 累加
`typer.Option(..., help="...")`	参数的 help 文本
函数 docstring 第一段	命令的简介

类型注解决定一切 — str 收字符串,int 收整数,bool 自动变 flag,Path 自动转 pathlib.Path,Literal["a","b"] 限制枚举。

错误处理

@app.command()
def deploy(env: str):
 if env not in {"dev", "staging", "prod"}:
 raise typer.BadParameter(f"unknown env: {env}")
 ...

typer.BadParameter 和 typer.Exit(code=1) 是 Typer 的标准错误出口,会自动用红色打印并以非零码退出。

子命令:嵌套 Typer 应用

复杂 CLI 一般会拆成多个子命令,像 git 那样:

mycli db backup
mycli db list
mycli env provision
mycli logs tail

实现方式是 每个子域一个 Typer 应用,再挂到主应用上。

# mycli/cli.py
import typer
from mycli.db import cli as db_cli
from mycli.env import cli as env_cli
from mycli.logs import cli as logs_cli

app = typer.Typer(
 name="mycli",
 no_args_is_help=True, # 不带子命令时显示 help
 add_completion=False, # 关闭自动安装 shell completion 的提示
)

app.add_typer(db_cli.app, name="db", help="Database operations.")
app.add_typer(env_cli.app, name="env", help="Environment provisioning.")
app.add_typer(logs_cli.app, name="logs", help="Log utilities.")

# mycli/db/cli.py
import typer
app = typer.Typer(no_args_is_help=True, add_completion=False)

@app.command("backup")
def backup_command(...):
 """Back up the database."""
 ...

@app.command("list")
def list_command(...):
 """List recent backup runs."""
 ...

模式要点:

子命令文件独立,各自定义一个 app = typer.Typer(...)。
add_typer(..., name="db") 决定子命令的拼写。
add_completion=False 在子应用里也建议加上,避免每个子命令都重复提示装 completion。

Rich 怎么用

自动部分(零配置)

--help、参数错误、未识别命令 — Typer 自动用 Rich 渲染,免费拿到好看的 help 和红字报错。

手动部分:画表格

from rich.console import Console
from rich.table import Table

console = Console()

@app.command()
def status():
 """Show service status."""
 table = Table(title="Service Status")
 table.add_column("Name", style="cyan")
 table.add_column("State", style="green")
 table.add_column("Uptime", justify="right")
 table.add_row("api", "running", "12d 4h")
 table.add_row("worker", "stopped", "—")
 console.print(table)

效果:

 Service Status
┏━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name ┃ State ┃ Uptime ┃
┡━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━┩
│ api │ running │ 12d 4h │
│ worker │ stopped │ — │
└────────┴───────────┴─────────┘

column 的 style= 可以指定颜色,justify="right" 控制对齐,add_row 一行行加数据。

进度条 / JSON / Markdown

from rich.progress import track
from rich.json import JSON
from rich.markdown import Markdown

for item in track(items, description="Processing..."):
 do_work(item)

console.print(JSON('{"a": 1}'))
console.print(Markdown("# title\n*body*"))

实战里常用的几个模式

eager `--version`

--version 需要在子命令参数解析前就生效,否则 mycli --version db backup 会被当成"先解析 db backup,再回头看 –version"。

写法是 is_eager=True + callback 抛 typer.Exit():

def _print_version_and_exit(value: bool) -> None:
 if value:
 typer.echo(f"mycli {__version__}")
 raise typer.Exit()

@app.callback()
def _main(
 version: Optional[bool] = typer.Option(
 None, "--version", "-V",
 is_eager=True,
 callback=_print_version_and_exit,
 help="Show version and exit.",
 ),
) -> None:
 return None

配置默认值 + flag 覆盖

CLI 工具经常要从 .env 读配置,又要允许 flag 显式覆盖。最简单的写法是用一个 _resolve 辅助函数:

def _resolve(value: Optional[str], default: str) -> str:
 return value if value is not None and value != "" else default

然后每个 Option 都写成 Optional[str] = typer.Option(None, ...),命令体里统一用 _resolve(cli_flag, settings.field) 决定最终值:

没传 flag → 用 .env 里的配置
传了 flag → 覆盖配置
.env 也没设 → 用代码里的 default

坑提醒:别把 default=settings.field 写到 Option 上 — Python 的默认参数是在 import 时求值的,不在运行命令的工作目录,容易踩到。

`--dry-run` 模式

dry_run: bool = typer.Option(False, "--dry-run", help="...")

def run(plan, dry_run: bool):
 if dry_run:
 console.print("[yellow]DRY RUN[/yellow] — no network calls")
 console.print(plan)
 return
 do_real_work(plan)

CI / smoke test 里非常有用 — --dry-run 不打网络也能验证命令链路。

排错小抄

现象	原因 / 修法
`--help` 显示一坨不分组	老版本 Typer;升级到 0.12+ 并装 Rich
中文 help 乱码	终端编码不是 UTF-8;`export LANG=en_US.UTF-8`
`typer.Option(None, ...)` 拿不到 None	漏 `from __future__ import annotations` 或没标注 `Optional`
子命令 help 不显示	子 `Typer()` 没设 `no_args_is_help=True`
`--version` 在子命令里被吞	缺 `is_eager=True` + `callback` 抛 `typer.Exit()`
default 用配置项不生效	Python 默认参数在 import 时求值,改用 `_resolve` 模式

一页速查代码

import typer
from typing import Optional
from rich.console import Console

app = typer.Typer(no_args_is_help=True, add_completion=False)
console = Console()

@app.command()
def greet(
 name: str, # 必填位置参数
 greeting: str = typer.Option("Hi", "-g", help="..."), # 可选 option
 repeat: int = typer.Option(1, "-r", help="..."), # 数字
 loud: bool = typer.Option(False, "--loud", help="..."), # flag
):
 """Say GREETING to NAME."""
 msg = f"{greeting}, {name}!"
 if loud:
 msg = msg.upper()
 console.print(msg * repeat)

if __name__ == "__main__":
 app()

练习题

学完上面这些,推荐按顺序做四道题,做完基本就掌握了:

写一个 notes add <text> / notes list 的小型 CLI(用 JSON 文件存)。
给 notes list 加一个 --tag 过滤 option,类型用 Optional[str]。
用 rich.table.Table 把 notes list 渲染成表格。
加一个 --export json|csv option,用 rich.json.JSON 或自己拼 CSV。

参考资料

Typer 官方文档: https://typer.tiangolo.com/
Rich 官方文档: https://rich.readthedocs.io/
实战参考:可以找一个真实的 Python CLI 项目翻一翻,比如 pipx、httpie、poetry 这些开源工具的源码,看它们怎么组织子命令、怎么用 Rich 画表格,比自己闭门造车快得多。

python开发环境配置指南

Sun, 25 Jan 2026 19:39:45 +0800

最快安装命令合集如下

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
scoop install git ## 注意要按指示执行几个命令
scoop install uv
scoop install just
scoop install nvm

🚀 2026 现代化 Python 开发环境配置指南：拥抱 uv 与 Just

换了新电脑，最让人头疼也最令人兴奋的事情莫过于重新配置开发环境。

作为一个 Python 开发者，过去我们可能需要安装 pyenv 管理版本，用 virtualenv 或 conda 管理环境，用 poetry 管理依赖，再写一个臃肿的 Makefile 来跑任务。

但时代变了。在 Rust 重写万物的浪潮下，我们的工具链已经可以极致精简且飞快。

今天这篇由零开始的指南，将带你用最现代的工具栈——uv, Git, 和 Just——打造一台高效的 Python 开发机器。

🛠️ 第一步：准备包管理器 (Windows 特别篇)

对于 macOS 和 Linux 用户，系统通常自带或很容易安装包管理器。但对于 Windows 用户，系统自带的 winget 往往因为缺少组件或版本问题（比如 LTSC 版本）导致无法使用。

因此，强烈推荐 Windows 开发者安装 Scoop。它类似于 Mac 的 Homebrew，将软件安装在用户目录下，无需管理员权限，干净又卫生。

🪟 Windows (安装 Scoop) 打开 PowerShell，运行以下两行命令：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

安装完 Scoop 后，接下来的工具安装将变得丝般顺滑。

🍎 macOS 确保安装了 Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

🐧 Linux 使用系统自带的 apt, dnf 或 pacman 即可。

1. Git：基石配置

在新电脑上，Git 是第一个需要就位的工具。

安装 Git

🪟 Windows: scoop install git (推荐) 或下载安装包，注意的是安装完成之后会提示执行三条命，然后还要把"C:\Users\zata\scoop\apps\git\current\usr\bin"粘贴到path环境变量,因为涉及到cygpath,不配置环境变量用不了
🍎 macOS: brew install git
🐧 Linux: sudo apt install git (Ubuntu/Debian)

基础配置

安装完成后，记得执行以下配置，让 git pull 和 diff 更符合现代习惯：

# 1. 身份认证
git config --global user.name "Zata"
git config --global user.email "your_email@example.com"

# 2. 现代化默认设置
git config --global init.defaultBranch main
git config --global pull.rebase true # 保持提交线整洁，避免无意义的 merge commit

# 3. (可选) 安装 Delta 让 diff 界面更漂亮
# Windows: scoop install delta
# Mac: brew install git-delta

2. uv：极速的 Python 全能管家

如果你还在纠结是用 conda 还是 poetry，请直接尝试 uv。它由 Astral 团队构建，集成了 Python 版本管理、虚拟环境管理和包依赖管理。

这意味着：你甚至不需要去 Python 官网下载安装包，uv 会帮你搞定一切。

安装 uv

🪟 Windows:

scoop install uv
# 或者: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

🍎 macOS & 🐧 Linux:

curl -lsSf https://astral.sh/uv/install.sh | sh

核心工作流

在空文件夹中启动一个新项目，以前需要好几步，现在只需要：

# 1. 初始化项目 (自动创建 pyproject.toml)
uv init my-project
cd my-project

# 2. 指定 Python 版本 (uv 会自动下载并安装该版本，无需系统预装)
uv python install 3.12

# 3. 添加依赖 (极速解析并同步)
uv add fastapi uvicorn

# 4. 运行命令 (自动使用虚拟环境，不用手动 activate)
uv run uvicorn main:app --reload

3. Just：比 Make 更现代的任务运行器

以前我们常在项目里放一个 Makefile 来记录常用命令。但 Make 对 Windows 支持极差，且语法古老。

Just 是一个跨平台的任务运行器。它使用 Justfile，语法清晰，且在 Windows/Mac/Linux 上表现完全一致。

安装 Just

🪟 Windows: scoop install just (最稳健)
🍎 macOS: brew install just
🐧 Linux:

sudo apt install just

配置你的第一个 Justfile

在项目根目录创建一个名为 Justfile 的文件（注意大小写）：

# 列出所有可用命令
default:
 @just --list

# 安装依赖
install:
 uv sync

# 运行格式化工具 (集成 ruff)
fmt:
 uv run ruff format .

# 运行本地开发服务器
dev:
 uv run uvicorn src.main:app --reload --port 8000

# 清理缓存
clean:
 rm -rf .ruff_cache .venv

现在，无论你在哪个系统上，只需要在终端输入 just dev 就能启动服务，再也不用去记那些冗长的 CLI 参数了。

4. 终端美化 (Optional)

无论你用什么系统，一个好的 Prompt 能让你心情愉悦。强烈推荐 Starship。它能用极简的图标显示当前的 Python 版本、Git 分支状态、执行时长等。

安装:
Windows: scoop install starship
Mac/Linux: curl -sS https://starship.rs/install.sh | sh
配置: 在你的 Shell 配置文件（如 .zshrc 或 PowerShell profile）中加入初始化脚本即可。

总结

对于 2026 年的 Python 开发环境，我的建议非常简单：

Git 管理代码。
uv 管理 Python 生命周期（版本+依赖）。
Just 管理项目指令。
(Windows用户) 使用 Scoop 来安装上述工具。

这套 “黄金三角” 组合拳不仅安装简单，迁移方便，而且完全跨平台。把时间花在写代码上，而不是等待环境配置的进度条上。

toml_usage_tutorial

Tue, 05 Aug 2025 15:26:51 +0800

什么是 TOML？

TOML (Tom’s Obvious, Minimal Language) 是一种专为配置文件设计的、语义清晰且易于阅读的格式。它的目标是成为一个优秀的“最小化”语言，能够无歧义地映射到哈希表（在 Python 中即字典）。

由于其出色的可读性，TOML 已被 Python 社区广泛采用，最著名的应用就是 pyproject.toml 文件，用于管理项目的构建和依赖。

一个简单的 TOML 文件 config.toml 看起来是这样的：

# 这是一个 TOML 文件的注释
title = "TOML 示例"

[database]
server = "192.168.1.1"
ports = [ 8001, 8002, 8003 ]
connection_max = 5000
enabled = true

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # 日期时间格式

为什么使用 TOML？

可读性强：语法直观，对人类友好。
结构清晰：通过 [table] 和 [[array of tables]] 能够清晰地表达数据结构。
强类型：支持字符串、整数、浮点数、布尔值、日期时间、数组和表（字典）等明确的数据类型。
官方推荐：pyproject.toml (PEP 518) 的采用使其成为 Python 项目配置的事实标准。

在 Python 中使用 TOML

在 Python 中处理 TOML 文件主要有两种方式：

tomllib (标准库, Python 3.11+)：用于读取 TOML 文件。这是 Python 官方内置的库，但功能仅限于解析（读取），不能写入。
toml (第三方库)：用于 读取和写入 TOML 文件。在 Python 3.11 之前，这是最流行的选择。即使在 3.11+，当你需要写入 TOML 文件时，它仍然是必需的。

安装第三方库

如果你使用的 Python 版本低于 3.11，或者你需要写入 TOML 文件，首先需要安装 toml 库：

pip install toml

1. 读取 TOML 文件

假设我们有以下 config.toml 文件：

# 配置文件示例
title = "我的应用"
version = "1.2.0"

[database]
host = "localhost"
port = 5432
user = "admin"
enabled = true

[users]
roles = ["admin", "editor", "viewer"]

# 数组表，用于表示一组复杂的对象
[[servers]]
name = "alpha"
ip = "10.0.0.1"
role = "database"

[[servers]]
name = "beta"
ip = "10.0.0.2"
role = "web"

使用 `tomllib` (Python 3.11+)

tomllib 的用法非常简单，和 json 模块类似。

tomllib.load(): 从一个二进制文件流中读取 TOML。
tomllib.loads(): 从一个字符串中读取 TOML。

# --- 使用 tomllib (Python 3.11+) ---

import tomllib
import pprint # 用于美化输出

try:
 # 注意：必须以二进制模式 ('rb') 打开文件
 with open('config.toml', 'rb') as f:
 config = tomllib.load(f)

 # 打印解析后的数据
 pprint.pprint(config)

 # 访问数据
 print("\n--- 访问数据 ---")
 print(f"应用标题: {config['title']}")
 print(f"数据库主机: {config['database']['host']}")
 print(f"第一个服务器的名字: {config['servers'][0]['name']}")

except FileNotFoundError:
 print("错误：config.toml 文件未找到。")
except tomllib.TOMLDecodeError as e:
 print(f"错误：解析 TOML 文件失败: {e}")

输出结果：

{'database': {'enabled': True, 'host': 'localhost', 'port': 5432, 'user': 'admin'},
 'servers': [{'ip': '10.0.0.1', 'name': 'alpha', 'role': 'database'},
 {'ip': '10.0.0.2', 'name': 'beta', 'role': 'web'}],
 'title': '我的应用',
 'users': {'roles': ['admin', 'editor', 'viewer']},
 'version': '1.2.0'}

--- 访问数据 ---
应用标题: 我的应用
数据库主机: localhost
第一个服务器的名字: alpha

使用 `toml` (所有 Python 版本)

toml 库的用法几乎与 tomllib 完全相同。

toml.load(): 从一个文本文件流中读取 TOML。
toml.loads(): 从一个字符串中读取 TOML。

# --- 使用 toml (第三方库) ---

import toml
import pprint

try:
 # 注意：使用文本模式 ('r') 打开文件
 with open('config.toml', 'r', encoding='utf-8') as f:
 config = toml.load(f)

 pprint.pprint(config)

except FileNotFoundError:
 print("错误：config.toml 文件未找到。")
except toml.TomlDecodeError as e:
 print(f"错误：解析 TOML 文件失败: {e}")

关键区别：tomllib.load() 需要以二进制模式 ('rb') 打开文件，而 toml.load() 通常以文本模式 ('r') 打开。

2. 写入 TOML 文件

如前所述，标准库 tomllib 不支持写入。因此，我们必须使用 toml 第三方库来将 Python 对象（通常是字典）序列化为 TOML 格式。

toml.dump(): 将 Python 对象写入到文件流。
toml.dumps(): 将 Python 对象转换为 TOML 格式的字符串。

示例：创建并写入 TOML 文件

假设我们有一个 Python 字典，并想将其保存为 new_config.toml。

import toml
from datetime import datetime

# 1. 定义一个 Python 字典
new_config_data = {
 'app_name': 'SuperApp',
 'version': '2.0.0',
 'debug_mode': False,
 'last_updated': datetime.now(), # toml库支持datetime对象

 'database': {
 'host': 'db.example.com',
 'port': 8080,
 'credentials': {
 'user': 'new_user',
 'pass': 's3cr3t'
 }
 },

 'features_enabled': ['feature1', 'feature2', 'feature3'],

 'nodes': [
 {'name': 'primary', 'ip': '192.168.1.100'},
 {'name': 'replica', 'ip': '192.168.1.101'}
 ]
}

# 2. 将字典写入文件
try:
 with open('new_config.toml', 'w', encoding='utf-8') as f:
 toml.dump(new_config_data, f)
 print("成功将配置写入 new_config.toml 文件。")

except Exception as e:
 print(f"写入文件时出错: {e}")

# 3. (可选) 将字典转换为字符串
config_string = toml.dumps(new_config_data)
print("\n--- TOML 格式字符串 ---")
print(config_string)

执行后，会生成一个 new_config.toml 文件，内容如下：

app_name = "SuperApp"
version = "2.0.0"
debug_mode = false
last_updated = 2025-08-05T07:21:54.123456 # 具体时间取决于运行时间
features_enabled = [ "feature1", "feature2", "feature3" ]

[database]
host = "db.example.com"
port = 8080

[database.credentials]
user = "new_user"
pass = "s3cr3t"

[[nodes]]
name = "primary"
ip = "192.168.1.100"

[[nodes]]
name = "replica"
ip = "192.168.1.101"

综合示例：读取、修改、再写入

这是一个更实际的流程，模拟了从配置文件加载设置，进行修改，然后保存回去的场景。

import toml
import pprint

CONFIG_FILE = 'config.toml'

# --- 1. 读取现有配置 ---
try:
 with open(CONFIG_FILE, 'r', encoding='utf-8') as f:
 config = toml.load(f)
 print("--- 原始配置 ---")
 pprint.pprint(config)
except FileNotFoundError:
 print(f"配置文件 {CONFIG_FILE} 未找到，将使用空配置。")
 config = {}

# --- 2. 修改配置 ---
# 更新版本号
config['version'] = '1.3.0'

# 禁用数据库
config['database']['enabled'] = False

# 添加一个新的服务器
new_server = {'name': 'gamma', 'ip': '10.0.0.3', 'role': 'monitoring'}
if 'servers' in config:
 config['servers'].append(new_server)
else:
 config['servers'] = [new_server]

print("\n--- 修改后的配置 ---")
pprint.pprint(config)

# --- 3. 写入到新文件 ---
try:
 with open('config_updated.toml', 'w', encoding='utf-8') as f:
 toml.dump(config, f)
 print(f"\n成功将更新后的配置写入 config_updated.toml")
except Exception as e:
 print(f"写入文件时出错: {e}")

高级话题与注意事项

pyproject.toml：这是现代 Python 项目中最重要的 TOML 应用。它用于定义项目元数据、构建系统（如 setuptools, poetry, flit）和工具配置（如 black, ruff, pytest）。TOML 的清晰结构使这个复杂的配置文件易于管理。
注释和格式保留：toml 和 tomllib 在解析时会丢弃文件中的注释和原有格式。如果你需要读取一个 TOML 文件，修改其中的值，然后写回并保留原始的注释和排版，你需要使用一个更强大的库，比如 tomlkit。tomlkit 专为这种“往返”场景设计，对于自动化修改 pyproject.toml 文件的工具来说至关重要。
- 安装：pip install tomlkit
- 用法与 toml 类似，但它会将 TOML 文档解析为一个特殊的、保留格式信息的对象。
错误处理：在实际应用中，务必使用 try...except 块来捕获 FileNotFoundError（文件不存在）和 TOMLDecodeError（文件格式错误），以增强程序的健壮性。

总结

功能	库	方法	描述
读取	`tomllib` (Python 3.11+)	`load(file_stream)`	从二进制文件流解析
		`loads(string)`	从字符串解析
读取/写入	`toml` (第三方)	`load(file_stream)`	从文本文件流解析
		`loads(string)`	从字符串解析
		`dump(data, file_stream)`	将 Python 字典写入文件
		`dumps(data)`	将 Python 字典转换为字符串
保留格式读写	`tomlkit` (第三方)	(类似 `toml`)	用于需要保留注释和格式的场景

希望这个详细的教程能帮助你熟练地在 Python 项目中使用 TOML！

pytest测试用例使用教程

Thu, 31 Jul 2025 10:38:04 +0800

基础概念

什么是 Pytest？

Pytest 是一个成熟、功能丰富的 Python 测试框架。与 Python 内置的 unittest 框架相比，Pytest 具有以下核心优势：

更少的样板代码：测试用例就是函数，不需要继承任何类。
更强大的断言：直接使用 Python 的 assert 语句，失败时能提供详细的上下文信息，无需记忆 assertEqual, assertTrue 等方法。
强大的 Fixture (夹具)：以一种优雅、模块化的方式管理测试的依赖和状态（如数据库连接、临时文件等）。
丰富的插件生态：拥有数百个高质量的插件，如 pytest-cov (测试覆盖率)、pytest-xdist (分布式测试)、pytest-django (Django集成) 等。
灵活的测试发现：自动发现并执行项目中的测试文件和测试函数。
清晰的输出信息：默认提供简洁明了的测试报告。

1. 安装

首先，你需要通过 pip 安装 pytest：

pip install pytest

2. 你的第一个测试

Pytest 的测试发现机制遵循一些简单的规则：

文件名以 test_*.py 或 *_test.py 格式命名。
文件内，以 test_ 开头的函数会被识别为测试函数。
文件内，包含以 test_ 开头的方法的 Test 开头的类（不能有 __init__ 方法）会被识别为测试类。

示例：

假设我们有一个简单的函数需要测试。

project/calculator.py

# 一个简单的计算器模块
def add(a, b):
 return a + b

def subtract(a, b):
 return a - b

现在，在同一个目录下创建一个测试文件。

project/test_calculator.py

# 导入需要测试的函数
from calculator import add

# 这是一个测试函数
def test_add():
 # 使用 assert 语句进行断言
 assert add(2, 3) == 5
 assert add(-1, 1) == 0
 assert add(-1, -1) == -2

def test_add_strings():
 # 这个测试预期会失败,因为 add 函数不支持字符串
 assert add('a', 'b') == 'ab'

3. 运行测试

在你的终端中，切换到 project 目录，然后执行 pytest 命令。

cd project
pytest

你会看到类似以下的输出：

============================= test session starts ==============================
platform linux -- Python 3.9.5, pytest-8.2.2, pluggy-1.5.0
rootdir: /path/to/project
collected 2 items

test_calculator.py .F [100%]

=================================== FAILURES ===================================
______________________________ test_add_strings ______________________________

 def test_add_strings():
 # 这个测试预期会失败,因为 add 函数不支持字符串
> assert add('a', 'b') == 'ab'
E TypeError: unsupported operand type(s) for +: 'int' and 'str'

test_calculator.py:14: TypeError
=========================== short test summary info ============================
FAILED test_calculator.py::test_add_strings - TypeError: unsupported operand...
========================= 1 failed, 1 passed in 0.02s ==========================

输出解读：

. (点) 代表一个通过的测试 (test_add)。
F 代表一个失败的测试 (test_add_strings)。
Pytest 详细地展示了 test_add_strings 失败的原因 (TypeError) 和失败发生在哪一行代码，这就是 assert 的强大之处。

常用运行选项：

详细模式 (-v)：显示每个测试函数的全名和结果。
```
pytest -v
```
运行指定文件：
```
pytest test_calculator.py
```
使用关键字 (-k) 运行特定测试：运行函数名中包含 “add” 的测试。
```
pytest -k "add"
```
遇到第一个失败就停止 (-x)：
```
pytest -x
```

Fixture (夹具)：管理测试依赖

Fixture 是 Pytest 的核心功能，用于为测试提供一个固定的基线状态。它们是管理 setup 和 teardown 逻辑的首选方式。

使用场景

创建一个数据库连接。
创建一个临时目录或文件。
提供一个可复用的数据对象。

基本用法

假设我们需要一个临时文件来进行测试。

# test_file.py
import pytest
import os

# 定义一个 fixture
@pytest.fixture
def temp_file(tmp_path): # tmp_path 是 pytest 内置的更现代的 fixture
 # Setup: 创建一个临时文件并写入内容
 file_path = tmp_path / "test.txt"
 file_path.write_text("hello pytest")

 # yield 关键字返回资源,测试函数会在这里执行
 yield file_path

 # Teardown: 这里可以写清理代码,但 tmp_path 会自动清理
 # print("\nCleaning up the file")

# 在测试函数中,把 fixture 的名字作为参数传入
def test_read_from_temp_file(temp_file):
 with open(temp_file, "r") as f:
 content = f.read()
 assert content == "hello pytest"

@pytest.fixture 装饰器定义了一个 fixture。
测试函数 test_read_from_temp_file 通过参数名 temp_file 来声明它需要使用这个 fixture。
yield 之前是 setup 代码，yield 之后是 teardown (清理) 代码。
tmp_path 是 Pytest 内置的一个 fixture，用于创建临时目录，是比 tmpdir 更推荐的方式。

Fixture 的作用域 (`scope`)

Fixture 可以在多个测试之间共享，以提高效率。scope 参数控制其生命周期：

function (默认): 每个测试函数都运行一次。
class: 每个测试类只运行一次。
module: 每个模块只运行一次。
session: 整个测试会话只运行一次（所有测试开始前创建，结束后销毁）。

@pytest.fixture(scope="session")
def db_connection():
 # 假设这里是连接数据库的昂贵操作
 print("\nSetting up DB connection for the session")
 conn = ... # connect_to_db()
 yield conn
 print("\nTearing down DB connection for the session")
 conn.close()

Pytest 常用内置 Fixtures

Pytest 提供了许多强大的内置 fixtures，它们可以直接在测试函数中使用，无需额外定义。这些 fixtures 覆盖了从临时文件管理到输出捕获、对象 Mock 等常见测试场景。

1. `tmp_path`: 临时目录管理

tmp_path 是一个 function 级别的 fixture，它为每个测试函数提供一个独立的临时目录（pathlib.Path 对象）。测试结束后，该目录会被自动清理。

使用场景：

需要创建临时文件或目录
测试文件读写操作
隔离每个测试的文件系统状态

示例：

import pytest
from pathlib import Path

def test_create_file(tmp_path):
 """测试在临时目录中创建文件"""
 # tmp_path 是一个 pathlib.Path 对象
 assert tmp_path.is_dir()

 # 创建一个临时文件
 test_file = tmp_path / "test.txt"
 test_file.write_text("Hello, pytest!")

 # 验证文件内容
 assert test_file.read_text() == "Hello, pytest!"
 assert test_file.exists()

def test_create_nested_directories(tmp_path):
 """测试创建嵌套目录结构"""
 # 创建嵌套目录
 nested_dir = tmp_path / "level1" / "level2" / "level3"
 nested_dir.mkdir(parents=True)

 # 在嵌套目录中创建文件
 data_file = nested_dir / "data.json"
 data_file.write_text('{"key": "value"}')

 assert data_file.exists()
 assert data_file.parent == nested_dir

def test_multiple_files(tmp_path):
 """测试处理多个文件"""
 # 创建多个测试文件
 for i in range(5):
 file = tmp_path / f"file_{i}.txt"
 file.write_text(f"Content {i}")

 # 验证所有文件都被创建
 files = list(tmp_path.glob("*.txt"))
 assert len(files) == 5

最佳实践：

优先使用 tmp_path 而不是旧的 tmpdir fixture（tmp_path 返回 pathlib.Path 对象，更现代化）
不需要手动清理临时文件，Pytest 会自动处理
每个测试函数获得独立的临时目录，避免测试间相互影响

2. `tmp_path_factory`: 跨测试会话的临时目录

tmp_path_factory 是一个 session 级别的 fixture，用于创建可以在多个测试之间共享的临时目录。它特别适合需要在整个测试会话中持久化某些数据的场景。

使用场景：

创建昂贵的测试数据（如大型数据集）并在多个测试中复用
需要跨多个测试共享文件系统状态
生成测试报告或日志文件

示例：

import pytest
from pathlib import Path

# 使用 tmp_path_factory 创建 session 级别的共享临时目录
@pytest.fixture(scope="session")
def shared_data_dir(tmp_path_factory):
 """创建一个会话级别的共享数据目录"""
 # 使用 mktemp 方法创建临时目录
 data_dir = tmp_path_factory.mktemp("shared_data")

 # 在这里可以生成一些昂贵的测试数据
 config_file = data_dir / "config.json"
 config_file.write_text('{"db": "test_db", "port": 5432}')

 return data_dir

def test_read_shared_config(shared_data_dir):
 """从共享目录读取配置"""
 config_file = shared_data_dir / "config.json"
 assert config_file.exists()
 content = config_file.read_text()
 assert "test_db" in content

def test_add_to_shared_dir(shared_data_dir):
 """向共享目录添加新文件"""
 new_file = shared_data_dir / "test_results.txt"
 new_file.write_text("Test passed")

 assert new_file.exists()

# 在 conftest.py 中使用 tmp_path_factory 的高级示例
@pytest.fixture(scope="session")
def test_dataset(tmp_path_factory):
 """生成一个大型测试数据集（仅生成一次）"""
 dataset_dir = tmp_path_factory.mktemp("dataset")

 # 模拟生成大量数据文件
 for i in range(100):
 data_file = dataset_dir / f"data_{i}.csv"
 data_file.write_text(f"id,value\n{i},{i*10}")

 return dataset_dir

def test_dataset_exists(test_dataset):
 """验证数据集已生成"""
 files = list(test_dataset.glob("*.csv"))
 assert len(files) == 100

def test_dataset_content(test_dataset):
 """验证数据集内容"""
 first_file = test_dataset / "data_0.csv"
 assert first_file.read_text() == "id,value\n0,0"

最佳实践：

用于创建昂贵的、可复用的测试资源
结合 scope="session" 或 scope="module" 的 fixture 使用
注意：共享状态可能导致测试间的依赖，需谨慎使用

3. `capsys` / `capfd`: 捕获输出

capsys 和 capfd fixtures 用于捕获测试期间产生的标准输出（stdout）和标准错误（stderr）。

capsys: 捕获 sys.stdout 和 sys.stderr（Python 级别）
capfd: 捕获文件描述符 1 和 2 的输出（系统级别，包括 C 扩展的输出）

使用场景：

测试打印输出的函数
验证日志信息
测试命令行工具的输出

示例：

import pytest
import sys

def greet(name):
 """打印问候信息"""
 print(f"Hello, {name}!")
 return True

def warn_user(message):
 """向 stderr 输出警告"""
 print(f"WARNING: {message}", file=sys.stderr)

# 使用 capsys 捕获输出
def test_greet_output(capsys):
 """测试问候函数的输出"""
 result = greet("Alice")

 # 捕获输出
 captured = capsys.readouterr()

 # 验证标准输出
 assert captured.out == "Hello, Alice!\n"
 assert captured.err == ""
 assert result is True

def test_warning_output(capsys):
 """测试警告输出"""
 warn_user("Low disk space")

 captured = capsys.readouterr()

 # 验证标准错误输出
 assert "WARNING: Low disk space" in captured.err
 assert captured.out == ""

def test_multiple_outputs(capsys):
 """测试多次输出"""
 print("First line")
 print("Second line")

 # 第一次读取
 captured = capsys.readouterr()
 assert "First line\nSecond line\n" == captured.out

 # 读取后输出会被清空
 print("Third line")
 captured = capsys.readouterr()
 assert captured.out == "Third line\n"

# 使用 disabled() 临时禁用捕获
def test_with_disabled_capture(capsys):
 """在测试中临时禁用输出捕获"""
 print("This will be captured")

 with capsys.disabled():
 # 这段输出不会被捕获,会直接显示在控制台
 print("This will be shown in the console")

 print("This will be captured again")

 captured = capsys.readouterr()
 assert "This will be captured" in captured.out
 assert "This will be captured again" in captured.out
 assert "This will be shown in the console" not in captured.out

高级用法：

import subprocess

def test_subprocess_output(capfd):
 """测试子进程的输出（需要使用 capfd）"""
 # capfd 可以捕获 C 级别的输出
 subprocess.run(["echo", "Hello from subprocess"])

 captured = capfd.readouterr()
 assert "Hello from subprocess" in captured.out

最佳实践：

大多数情况下使用 capsys 即可
只有在需要捕获 C 扩展或子进程输出时才使用 capfd
使用 readouterr() 后，输出缓冲区会被清空
使用 disabled() 上下文管理器可以临时禁用捕获，方便调试

4. `monkeypatch`: Mock 和修改对象

monkeypatch fixture 是一个强大的工具，用于在测试期间安全地修改对象、字典、环境变量等。所有修改会在测试结束后自动恢复，不会影响其他测试。

使用场景：

Mock 函数或类方法
修改环境变量
修改对象属性
临时更改字典内容
修改 sys.path 或其他系统配置

示例：

import pytest
import os
import requests

# 示例模块代码
class APIClient:
 def get_data(self):
 """从远程 API 获取数据"""
 response = requests.get("https://api.example.com/data")
 return response.json()

def get_env_config():
 """从环境变量读取配置"""
 return {
 "host": os.getenv("DB_HOST", "localhost"),
 "port": int(os.getenv("DB_PORT", "5432")),
 "debug": os.getenv("DEBUG", "False") == "True"
 }

# 测试：Mock 函数
def test_mock_function(monkeypatch):
 """使用 monkeypatch 替换函数"""
 def mock_get(*args, **kwargs):
 """模拟 requests.get 的返回值"""
 class MockResponse:
 def json(self):
 return {"status": "success", "data": [1, 2, 3]}
 return MockResponse()

 # 替换 requests.get 函数
 monkeypatch.setattr(requests, "get", mock_get)

 # 现在调用 API 会使用我们的 mock 函数
 client = APIClient()
 result = client.get_data()

 assert result["status"] == "success"
 assert result["data"] == [1, 2, 3]

# 测试：修改环境变量
def test_modify_env_vars(monkeypatch):
 """修改环境变量"""
 # 设置环境变量
 monkeypatch.setenv("DB_HOST", "test-server")
 monkeypatch.setenv("DB_PORT", "9999")
 monkeypatch.setenv("DEBUG", "True")

 config = get_env_config()

 assert config["host"] == "test-server"
 assert config["port"] == 9999
 assert config["debug"] is True

# 测试：删除环境变量
def test_delete_env_var(monkeypatch):
 """删除环境变量"""
 # 先设置一个环境变量
 monkeypatch.setenv("TEMP_VAR", "value")
 assert os.getenv("TEMP_VAR") == "value"

 # 删除它
 monkeypatch.delenv("TEMP_VAR")
 assert os.getenv("TEMP_VAR") is None

# 测试：修改对象属性
def test_modify_object_attr(monkeypatch):
 """修改对象属性"""
 class Config:
 timeout = 30
 retries = 3

 # 修改类属性
 monkeypatch.setattr(Config, "timeout", 60)
 monkeypatch.setattr(Config, "retries", 5)

 assert Config.timeout == 60
 assert Config.retries == 5

# 测试：修改字典
def test_modify_dict(monkeypatch):
 """修改字典内容"""
 cache = {"user": "admin", "token": "abc123"}

 # 修改字典项
 monkeypatch.setitem(cache, "user", "test_user")
 monkeypatch.setitem(cache, "role", "tester")

 assert cache["user"] == "test_user"
 assert cache["role"] == "tester"

 # 删除字典项
 monkeypatch.delitem(cache, "token")
 assert "token" not in cache

# 测试：修改 sys.path
def test_modify_syspath(monkeypatch):
 """临时修改 sys.path"""
 import sys

 original_length = len(sys.path)

 # 添加路径
 monkeypatch.syspath_prepend("/custom/path")

 assert sys.path[0] == "/custom/path"
 assert len(sys.path) == original_length + 1
 # 测试结束后 sys.path 会自动恢复

# 测试：修改当前工作目录
def test_change_directory(monkeypatch, tmp_path):
 """临时修改当前工作目录"""
 # 创建一个临时目录
 test_dir = tmp_path / "test_workspace"
 test_dir.mkdir()

 # 修改当前工作目录
 monkeypatch.chdir(test_dir)

 assert os.getcwd() == str(test_dir)
 # 测试结束后会自动恢复到原始目录

常用方法总结：

方法	说明	示例
`setattr(obj, name, value)`	设置对象属性	`monkeypatch.setattr(os, "getcwd", lambda: "/fake")`
`delattr(obj, name)`	删除对象属性	`monkeypatch.delattr(os, "environ")`
`setitem(dict, key, value)`	设置字典项	`monkeypatch.setitem(os.environ, "USER", "test")`
`delitem(dict, key)`	删除字典项	`monkeypatch.delitem(os.environ, "USER")`
`setenv(name, value)`	设置环境变量	`monkeypatch.setenv("DEBUG", "1")`
`delenv(name)`	删除环境变量	`monkeypatch.delenv("DEBUG")`
`syspath_prepend(path)`	在 sys.path 开头添加路径	`monkeypatch.syspath_prepend("/path")`
`chdir(path)`	修改当前工作目录	`monkeypatch.chdir("/tmp")`

最佳实践：

所有修改会在测试结束后自动撤销，无需手动清理
优先使用 monkeypatch 而不是直接修改全局状态
适合替代复杂的 mock 库（如 unittest.mock）进行简单的 mock 操作

5. `request`: 访问测试请求信息

request fixture 提供了关于当前测试请求的信息，包括测试函数、模块、参数等元数据。它在创建高级 fixtures 时特别有用。

使用场景：

在 fixture 中访问测试函数的信息
根据测试参数动态配置 fixture
实现 fixture 的终结器（finalizer）
访问测试的 markers 和配置

示例：

import pytest

# 基础用法：访问测试信息
@pytest.fixture
def show_test_info(request):
 """显示当前测试的信息"""
 print(f"\n测试函数名: {request.node.name}")
 print(f"测试模块: {request.module.__name__}")
 print(f"测试文件路径: {request.fspath}")

def test_example(show_test_info):
 """一个示例测试"""
 assert True

# 使用 request.param 访问参数化数据
@pytest.fixture
def db_connection(request):
 """根据参数创建不同类型的数据库连接"""
 db_type = request.param # 获取参数化的值

 print(f"\n正在连接到 {db_type} 数据库")

 # 根据数据库类型创建不同的连接
 connections = {
 "sqlite": {"type": "sqlite", "path": ":memory:"},
 "postgres": {"type": "postgres", "host": "localhost"},
 "mysql": {"type": "mysql", "host": "localhost"}
 }

 conn = connections.get(db_type)
 yield conn

 print(f"\n关闭 {db_type} 数据库连接")

@pytest.mark.parametrize("db_connection", ["sqlite", "postgres", "mysql"], indirect=True)
def test_database_operations(db_connection):
 """测试不同数据库的操作"""
 assert db_connection["type"] in ["sqlite", "postgres", "mysql"]
 print(f"当前使用的数据库: {db_connection['type']}")

# 使用 request.addfinalizer 注册清理函数
@pytest.fixture
def resource_with_finalizer(request):
 """使用 finalizer 进行资源清理"""
 print("\n设置资源")
 resource = {"status": "active", "data": []}

 def cleanup():
 """清理函数"""
 print("\n清理资源（使用 finalizer）")
 resource["status"] = "closed"

 # 注册清理函数
 request.addfinalizer(cleanup)

 return resource

def test_use_resource(resource_with_finalizer):
 """使用带 finalizer 的资源"""
 assert resource_with_finalizer["status"] == "active"
 resource_with_finalizer["data"].append("test")

# 访问测试的 markers
@pytest.fixture
def config_from_marker(request):
 """根据测试的 marker 提供不同配置"""
 # 检查测试是否有 slow marker
 if request.node.get_closest_marker("slow"):
 return {"timeout": 60, "retries": 5}
 else:
 return {"timeout": 10, "retries": 1}

@pytest.mark.slow
def test_slow_operation(config_from_marker):
 """慢速测试会获得更长的超时时间"""
 assert config_from_marker["timeout"] == 60
 assert config_from_marker["retries"] == 5

def test_fast_operation(config_from_marker):
 """快速测试使用默认配置"""
 assert config_from_marker["timeout"] == 10
 assert config_from_marker["retries"] == 1

# 在 conftest.py 中使用 request 创建灵活的 fixture
@pytest.fixture
def test_data_dir(request, tmp_path):
 """为每个测试创建独立的数据目录"""
 # 使用测试函数名创建目录
 test_name = request.node.name
 data_dir = tmp_path / test_name
 data_dir.mkdir()

 print(f"\n为测试 {test_name} 创建数据目录: {data_dir}")

 return data_dir

def test_first(test_data_dir):
 """第一个测试"""
 assert test_data_dir.name == "test_first"
 (test_data_dir / "file1.txt").write_text("data1")

def test_second(test_data_dir):
 """第二个测试"""
 assert test_data_dir.name == "test_second"
 (test_data_dir / "file2.txt").write_text("data2")

# 访问测试配置
@pytest.fixture
def check_config(request):
 """访问 pytest 配置"""
 config = request.config

 # 获取命令行选项
 verbose = config.getoption("verbose")
 print(f"\n详细模式: {verbose}")

 # 访问 pytest.ini 中的配置
 ini_value = config.getini("testpaths")
 print(f"测试路径配置: {ini_value}")

def test_with_config(check_config):
 """测试配置访问"""
 pass

常用属性和方法：

属性/方法	说明	示例
`request.node`	当前测试节点对象	`request.node.name`
`request.module`	测试所在的模块	`request.module.__name__`
`request.function`	测试函数对象	`request.function.__doc__`
`request.fspath`	测试文件路径	`str(request.fspath)`
`request.param`	参数化的当前值	`request.param`
`request.config`	pytest 配置对象	`request.config.getoption("verbose")`
`request.addfinalizer(func)`	注册清理函数	`request.addfinalizer(cleanup)`
`request.node.get_closest_marker(name)`	获取 marker	`request.node.get_closest_marker("slow")`

最佳实践：

使用 request.param 结合 indirect=True 实现参数化 fixture
使用 addfinalizer() 代替 yield 进行清理（当需要多个清理步骤时）
通过 request.node 访问测试元数据，实现动态行为
在创建通用的、可配置的 fixtures 时特别有用

使用 `conftest.py` 共享 Fixture

当多个测试文件需要使用同一个 Fixture 时，我们不应该在每个文件里都写一遍。这时，conftest.py 就派上用场了。

conftest.py 是一个特殊的文件，它的作用是：

共享 Fixtures: 定义在 conftest.py 中的 Fixture 可以在其所在的目录及所有子目录的测试文件中直接使用，无需导入。
存放 Hooks: 可以用来自定义 Pytest 的行为。
本地插件库: conftest.py 本质上就是一个本地的插件。

示例：

假设我们的项目结构如下：

project/
├── app/
│ ├── __init__.py
│ └── user_service.py
└── tests/
 ├── conftest.py
 ├── test_user_api.py
 └── test_user_database.py

我们可以将昂贵的数据库连接 Fixture 放在 tests/conftest.py 中。

tests/conftest.py

import pytest

# 一个 session 级别的 fixture,模拟数据库连接
@pytest.fixture(scope="session")
def db_conn():
 print("\n[conftest] Creating DB connection")
 # 模拟连接对象
 conn = {"status": "connected", "data": {}}
 yield conn
 # 清理工作
 print("\n[conftest] Closing DB connection")
 conn["status"] = "closed"

# 使用内置 fixtures 创建共享资源
@pytest.fixture(scope="session")
def shared_tmp_dir(tmp_path_factory):
 """创建会话级别的共享临时目录"""
 return tmp_path_factory.mktemp("shared_data")

@pytest.fixture
def mock_env(monkeypatch):
 """为所有测试提供统一的环境变量配置"""
 monkeypatch.setenv("ENV", "test")
 monkeypatch.setenv("DEBUG", "True")
 return monkeypatch

现在，tests 目录下的所有测试文件都可以直接使用这些 Fixtures。

tests/test_user_api.py

def test_user_creation_api(db_conn):
 # 注意：我们没有从任何地方导入 db_conn
 assert db_conn["status"] == "connected"
 # ... 模拟 API 调用来创建用户

tests/test_user_database.py

def test_user_data_consistency(db_conn, shared_tmp_dir):
 assert db_conn["status"] == "connected"

 # 使用共享临时目录
 data_file = shared_tmp_dir / "test_data.txt"
 data_file.write_text("test")

 # ... 模拟直接检查数据库

当你运行 pytest 时，db_conn Fixture 只会被创建一次，然后被所有需要它的测试函数共享，最后在所有测试结束后被销毁。这就是 conftest.py 和 scope="session" 结合的强大之处。

Markers (标记)：组织和控制测试

Markers 用于给测试函数打上标签，方便你对它们进行分组、跳过或标记为预期失败。

常用内置标记

@pytest.mark.skip: 无条件跳过测试。

@pytest.mark.skip(reason="Function not implemented yet")
def test_new_feature():
 ...

@pytest.mark.skipif: 根据条件跳过测试。

import sys

@pytest.mark.skipif(sys.version_info < (3, 8), reason="requires Python 3.8 or higher")
def test_modern_syntax():
 ...

@pytest.mark.xfail: 标记为预期失败 (XFAIL - Expected Failure)。如果测试失败，结果是 XFAIL；如果意外通过，结果是 XPASS。
```
@pytest.mark.xfail(reason="Bug #123 is not fixed yet")
def test_known_bug():
 assert some_buggy_function() == False
```

自定义标记

你可以创建自己的标记来对测试进行分类，例如 “slow”, “api”, “ui”。为了避免拼写错误和警告，最好在 pytest.ini 中注册它们。

pytest.ini (在项目根目录创建此文件)

[pytest]
markers =
 slow: marks tests as slow to run
 api: marks tests related to API calls

test_file.py

import pytest

@pytest.mark.slow
def test_very_slow_operation():
 ...

@pytest.mark.api
def test_api_endpoint():
 ...

运行带有特定标记的测试 (-m)

# 只运行标记为 "slow" 的测试
pytest -m slow

# 运行所有不是 "slow" 的测试
pytest -m "not slow"

# 运行 "api" 或 "slow" 的测试
pytest -m "api or slow"

参数化 (`parametrize`)：用不同数据多次运行同一测试

当你需要用多组不同的输入和输出来测试同一个函数时，参数化非常有用。

import pytest
from calculator import add

# 使用 @pytest.mark.parametrize 装饰器
@pytest.mark.parametrize("input1, input2, expected", [
 (1, 2, 3), # 测试用例1
 (-1, 1, 0), # 测试用例2
 (10, 0, 10), # 测试用例3
 (99, 1, 100), # 测试用例4
 pytest.param(1, 1, 3, marks=pytest.mark.xfail) # 标记为预期失败的用例
])
def test_add_multiple(input1, input2, expected):
 assert add(input1, input2) == expected

第一个参数是参数名的字符串，用逗号分隔。
第二个参数是一个列表，列表中的每个元素（通常是元组）对应一组测试数据。
Pytest 会为每一组数据生成并运行一个独立的测试。

配置文件 (`pytest.ini`)

pytest.ini 是 Pytest 的主配置文件，通常放在项目的根目录。它可以让你自定义 Pytest 的行为。

一个常见的 pytest.ini 示例：

[pytest]
# 设置默认的命令行参数
addopts = -v --strict-markers -ra

# 指定测试文件所在的目录
testpaths = tests

# 定义自定义标记,避免拼写错误和警告
markers =
 slow: marks tests as slow to run
 smoke: marks tests for smoke testing

# 忽略某些目录或文件
norecursedirs = .git venv *.egg-info

-ra 是一个非常有用的参数，它会在测试结束后，简要报告所有通过（p）、失败（f）、跳过（s）等结果的原因。

常用插件

pytest-cov: 生成测试覆盖率报告。
```
pip install pytest-cov
pytest --cov=my_project --cov-report=html
```
这会生成一个 htmlcov 目录，里面有详细的 HTML 覆盖率报告。

pytest-xdist: 并行运行测试，加快执行速度。

pip install pytest-xdist
pytest -n auto # 'auto' 会根据 CPU 核心数自动决定进程数

实战示例（结合内置 Fixtures 和 conftest.py）

让我们用一个更完整的例子来展示这些概念如何协同工作。

项目结构:

my_project/
├── app/
│ ├── __init__.py
│ ├── math_operations.py
│ └── file_processor.py
├── tests/
│ ├── conftest.py
│ ├── test_math_operations.py
│ └── test_file_processor.py
└── pytest.ini

app/math_operations.py

def add(a, b):
 return a + b

def divide(a, b):
 if b == 0:
 raise ValueError("Cannot divide by zero")
 return a / b

app/file_processor.py

import os

def process_file(file_path):
 """读取文件并返回行数"""
 with open(file_path, 'r') as f:
 lines = f.readlines()
 return len(lines)

def get_config():
 """从环境变量获取配置"""
 return {
 "mode": os.getenv("APP_MODE", "production"),
 "debug": os.getenv("DEBUG", "false").lower() == "true"
 }

tests/conftest.py

import pytest

# 使用 tmp_path_factory 创建共享测试数据
@pytest.fixture(scope="session")
def test_data_dir(tmp_path_factory):
 """创建包含测试数据的共享目录"""
 data_dir = tmp_path_factory.mktemp("test_data")

 # 创建一些测试文件
 (data_dir / "sample.txt").write_text("line1\nline2\nline3")
 (data_dir / "empty.txt").write_text("")

 return data_dir

# 提供统一的环境变量配置
@pytest.fixture
def test_env(monkeypatch):
 """为测试设置环境变量"""
 monkeypatch.setenv("APP_MODE", "test")
 monkeypatch.setenv("DEBUG", "true")

# 定义一个在所有测试函数中都可用的 fixture
@pytest.fixture
def base_data():
 """提供一组基础测试数据"""
 return {"x": 10, "y": 5}

tests/test_math_operations.py

import pytest
from app.math_operations import add, divide

# 测试类,用于组织相关测试
class TestMath:
 # 使用来自 conftest.py 的 fixture
 def test_add(self, base_data):
 result = add(base_data["x"], base_data["y"])
 assert result == 15

 # 参数化测试
 @pytest.mark.parametrize("a, b, expected", [
 (10, 2, 5.0),
 (8, 4, 2.0),
 (-6, 3, -2.0)
 ])
 def test_divide_parametrized(self, a, b, expected):
 assert divide(a, b) == expected

 # 测试异常情况
 def test_divide_by_zero(self):
 with pytest.raises(ValueError, match="Cannot divide by zero"):
 divide(10, 0)

tests/test_file_processor.py

import pytest
from app.file_processor import process_file, get_config

class TestFileProcessor:
 # 使用 tmp_path 创建测试文件
 def test_process_file_with_tmp_path(self, tmp_path):
 """使用 tmp_path 测试文件处理"""
 # 创建临时文件
 test_file = tmp_path / "test.txt"
 test_file.write_text("line1\nline2\nline3\nline4")

 # 测试处理
 result = process_file(test_file)
 assert result == 4

 # 使用共享的测试数据目录
 def test_process_shared_file(self, test_data_dir):
 """使用共享测试数据"""
 sample_file = test_data_dir / "sample.txt"
 result = process_file(sample_file)
 assert result == 3

 def test_process_empty_file(self, test_data_dir):
 """测试空文件"""
 empty_file = test_data_dir / "empty.txt"
 result = process_file(empty_file)
 assert result == 0

class TestConfig:
 # 使用 monkeypatch 测试环境变量
 def test_get_config_with_env(self, test_env):
 """测试从环境变量读取配置"""
 config = get_config()

 assert config["mode"] == "test"
 assert config["debug"] is True

 def test_get_config_default(self, monkeypatch):
 """测试默认配置"""
 # 删除环境变量,使用默认值
 monkeypatch.delenv("APP_MODE", raising=False)
 monkeypatch.delenv("DEBUG", raising=False)

 config = get_config()

 assert config["mode"] == "production"
 assert config["debug"] is False

 # 使用 capsys 测试输出
 def test_print_config(self, capsys, test_env):
 """测试配置输出"""
 config = get_config()
 print(f"Running in {config['mode']} mode")

 captured = capsys.readouterr()
 assert "Running in test mode" in captured.out

pytest.ini

[pytest]
addopts = -v --strict-markers
testpaths = tests
markers =
 slow: marks tests as slow to run
 integration: marks tests as integration tests

如何运行?

在 my_project 根目录下，直接运行 pytest 命令。

pytest

预期输出:

============================= test session starts ==============================
...
collected 8 items

tests/test_file_processor.py::TestFileProcessor::test_process_file_with_tmp_path PASSED [ 12%]
tests/test_file_processor.py::TestFileProcessor::test_process_shared_file PASSED [ 25%]
tests/test_file_processor.py::TestFileProcessor::test_process_empty_file PASSED [ 37%]
tests/test_file_processor.py::TestConfig::test_get_config_with_env PASSED [ 50%]
tests/test_file_processor.py::TestConfig::test_get_config_default PASSED [ 62%]
tests/test_file_processor.py::TestConfig::test_print_config PASSED [ 75%]
tests/test_math_operations.py::TestMath::test_add PASSED [ 87%]
tests/test_math_operations.py::TestMath::test_divide_parametrized[10-2-5.0] PASSED [100%]

============================== 8 passed in ...s ===============================

这个实战示例展示了如何：

结合使用多个内置 fixtures（tmp_path, tmp_path_factory, monkeypatch, capsys）
使用 conftest.py 提供共享 fixtures
在一个测试文件中结合使用测试类、参数化和异常测试
组织项目结构以支持复杂的测试场景

总结

这个教程涵盖了 Pytest 最核心和最常用的功能，特别是强大的内置 fixtures。掌握了这些，你已经可以高效地为你的项目编写健壮的测试了。

学习路径建议

从编写简单的 test_ 函数和使用 assert 开始。
学习使用 Fixture 来管理测试的准备和清理工作。
掌握内置 Fixtures：
- tmp_path 用于文件系统测试
- monkeypatch 用于 Mock 和修改对象
- capsys 用于捕获输出
- request 用于高级 fixture 配置
- tmp_path_factory 用于共享临时资源
使用 conftest.py 来组织和共享你的 Fixtures，使其在整个测试套件中可用。
当你发现测试用例重复时，使用 @pytest.mark.parametrize 进行参数化。
当测试集变大时，使用 Markers (@pytest.mark) 来组织和筛选测试。
通过 pytest.ini 配置文件来固化你的测试习惯。
根据需要，探索并使用插件来扩展 Pytest 的功能。

内置 Fixtures 快速参考

Fixture	作用域	用途	返回类型
`tmp_path`	function	创建临时目录	`pathlib.Path`
`tmp_path_factory`	session	创建共享临时目录	`TempPathFactory`
`capsys`	function	捕获 stdout/stderr	`CaptureFixture`
`capfd`	function	捕获文件描述符输出	`CaptureFixture`
`monkeypatch`	function	Mock 和修改对象	`MonkeyPatch`
`request`	function	访问测试请求信息	`FixtureRequest`

最好的学习方法是实践。尝试为你自己的项目编写测试，或者为一个你喜欢的小型开源项目贡献测试代码。

要了解更多信息，请随时查阅 Pytest 官方文档。

pydantic使用教程

Wed, 11 Jun 2025 10:59:38 +0800


- 环境变量配置的代码

基础使用

Pydantic 是一个基于 Python 类型提示进行数据验证和设置管理的库。它能够解析和验证复杂的数据结构，并将其转换为 Python 对象，同时在数据不符合规范时给出清晰的错误提示。

核心优势

代码更简洁、更健壮: 通过类型提示来定义数据结构，Pydantic 会自动进行验证，减少大量的样板代码。
出色的编辑器支持: 由于完全基于类型提示，IDE（如 VS Code, PyCharm）可以提供精准的代码补全和类型检查。
极佳的性能: Pydantic 的核心验证逻辑由 Rust 实现，速度非常快。
与框架无缝集成: 它被 FastAPI、Django Ninja 等现代 Python Web 框架广泛用作核心组件，用于请求和响应模型的定义。

快速入门：定义你的第一个模型

首先，确保你已经安装了 Pydantic:

pip install pydantic

最基本的使用方式是创建一个继承自 pydantic.BaseModel 的类。

from pydantic import BaseModel

class User(BaseModel):
 id: int
 name: str = 'John Doe' 带有默认值的字段
 signup_ts: datetime | None = None 可以是 datetime 类型或者 None

 创建 User 实例
user_data = {'id': 123, 'name': 'Alice'}
user = User(**user_data)

print(user.id)
 > 123

print(user.name)
 > Alice

print(user.model_dump()) 将模型实例转换为字典
 > {'id': 123, 'name': 'Alice', 'signup_ts': None}

数据验证

如果传入的数据类型不正确，Pydantic 会自动进行转换；如果无法转换，则会抛出一个 ValidationError。

from pydantic import BaseModel, ValidationError

class User(BaseModel):
 id: int
 name: str

 尝试用一个字符串来代替整数 ID
user_data = {'id': '123', 'name': 'Alice'} '123' 会被自动转换为整数 123

try:
 user = User(**user_data)
 print(user)
except ValidationError as e:
 print(e)
 > id=123 name='Alice'

 尝试用一个无法转换的类型
invalid_data = {'id': 'not a number', 'name': 'Bob'}

try:
 User(**invalid_data)
except ValidationError as e:
 print(e.json())

运行后，你会得到一个清晰的 JSON 格式错误报告：

[
 {
 "type": "int_parsing",
 "loc": [
 "id"
 ],
 "msg": "Input should be a valid integer, unable to parse string as an integer",
 "input": "not a number"
 }
]

常用功能与进阶用法

1. 嵌套模型 (Nested Models)

你可以将一个 BaseModel 嵌套在另一个模型中，以构建复杂的数据结构。

from pydantic import BaseModel
from typing import List

class Item(BaseModel):
 name: str
 price: float

class Order(BaseModel):
 order_id: int
 items: List[Item] 一个包含 Item 模型的列表

order_data = {
 'order_id': 9527,
 'items': [
 {'name': 'Apple', 'price': 5.5},
 {'name': 'Banana', 'price': 2.8}
 ]
}

order = Order(**order_data)
print(order.items[0].name)
 > Apple

print(order.model_dump_json(indent=2)) 转换为格式化的 JSON 字符串

输出：

{
 "order_id": 9527,
 "items": [
 {
 "name": "Apple",
 "price": 5.5
 },
 {
 "name": "Banana",
 "price": 2.8
 }
 ]
}

2. 字段验证与约束 (Field Validation)

Pydantic 提供了 Field 函数来为字段添加额外的约束。

from pydantic import BaseModel, Field

class Product(BaseModel):
 product_id: int
 name: str = Field(min_length=3, max_length=50)
 price: float = Field(gt=0, description="The price must be greater than zero") gt = greater than
 tags: list[str] = []

在这个例子中：

name 的长度必须在 3 到 50 个字符之间。
price 的值必须大于 0。

3. 自定义验证器 (Custom Validators)

当内置的验证规则不满足需求时，你可以使用 @validator 装饰器创建自己的验证逻辑。

注意: 在 Pydantic V2 中，更推荐使用带有 @field_validator 的函数。

from pydantic import BaseModel, field_validator

class UserRegistration(BaseModel):
 username: str
 password: str
 password_confirmation: str

 @field_validator('password_confirmation')
 @classmethod
 def passwords_match(cls, v: str, values: 'ValidationInfo') -> str:
 v 是 'password_confirmation' 字段的值
 values.data 包含了模型中所有已解析的字段值
 if 'password' in values.data and v != values.data['password']:
 raise ValueError('Passwords do not match')
 return v

4. 设置管理 (Settings Management)

Pydantic 的 BaseSettings 是管理应用配置的利器。它可以自动从环境变量或 .env 文件中读取配置。

首先，安装 pydantic-settings：

pip install pydantic-settings

创建一个 .env 文件:

 .env
API_KEY="your_secret_api_key"
DATABASE_URL="postgresql://user:password@host:port/db"

然后定义你的设置类：

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
 api_key: str
 database_url: str
 可以在这里为其他配置项提供默认值
 app_name: str = "My Awesome App"

 class Config:
 env_file = ".env" 指定 .env 文件名

 创建 Settings 实例
settings = Settings()

print(settings.api_key)
 > your_secret_api_key

print(settings.app_name)
 > My Awesome App

5. 别名生成器 (Alias Generator)

有时，输入的 JSON/dict 的键名可能不是合法的 Python 标识符 (比如 user-id)，或者你想在内部使用驼峰命名法 userId，而在外部暴露蛇形命名法 user_id。这时 alias 或 alias_generator 就派上用场了。

from pydantic import BaseModel, Field
from pydantic.alias_generators import to_camel

class Person(BaseModel):
 first_name: str
 last_name: str

 class Config:
 alias_generator = to_camel 将蛇形命名转换为驼峰命名
 populate_by_name = True 允许通过字段名和别名两种方式来赋值

 使用别名（驼峰）来创建实例
person_data = {
 'firstName': 'John',
 'lastName': 'Doe'
}
person = Person(**person_data)

print(person.first_name)
 > John

 序列化时也会使用别名
print(person.model_dump(by_alias=True))
 > {'firstName': 'John', 'lastName': 'Doe'}

总结

Pydantic 是一个功能强大且易于使用的库。通过本教程，你应该已经掌握了它的核心用法：

使用 BaseModel 定义数据结构。
利用类型提示进行自动数据验证和转换。
通过嵌套模型构建复杂的数据对象。
使用 Field 和 @field_validator 添加自定义约束和逻辑。
借助 BaseSettings 优雅地管理应用配置。

建议在实际项目中多多使用，并查阅 Pydantic 官方文档以了解更多高级功能。

管理应用的变量配置（环境变量和初始值的加载）

🚀 使用 Pydantic BaseSettings 轻松管理应用配置

在任何应用开发中，管理配置（如数据库连接字符串、API密钥、调试开关等）都是一个关键环节。将配置硬编码在代码中会带来安全风险和维护困难。Pydantic 的 BaseSettings 提供了一个优雅的解决方案，可以自动从环境变量或 .env 文件中读取配置，并提供类型检查和验证。

本教程将通过分析你提供的 DemoSettings 脚本，带你深入了解 BaseSettings 的核心功能和最佳实践。

核心概念：什么是 BaseSettings？

简单来说，BaseSettings 是一个 Pydantic 模型，但它被赋予了“超能力”：

自动读取源：它会按特定顺序自动从环境变量和 .env 文件中查找并加载配置项。
类型转换：它会自动将读取到的字符串（如 “true”, “8000”）转换为正确的 Python 类型（如 bool, int）。
默认值：你可以像在普通类中一样提供默认值。
验证：你可以使用 Pydantic 强大的验证器来确保配置值的格式正确。

定义你的配置模型

我们从代码的核心 DemoSettings 类开始。

class DemoSettings(BaseSettings):
 """演示配置类"""

 基本配置
 app_name: str = "Demo App"
 debug: bool = False
 port: int = 8000

 API Keys (可选)
 dashscope_api_key: Optional[str] = None
 openai_api_key: Optional[str] = None

 ...

关键点说明:

继承 BaseSettings: 这是让 Pydantic 知道这个模型用于管理配置的关键。
定义字段: 像定义普通 Pydantic 模型一样，为每个配置项声明一个带类型注解的类属性。
提供默认值: app_name: str = "Demo App" 这行代码意味着，如果在任何地方都找不到 APP_NAME 这个配置，它的值将默认为 "Demo App"。
可选配置: 使用 Optional[str] (在 Python 3.10+ 中可写为 str | None) 来表示非必需的配置项，如 redis_url 和 API 密钥。

Pydantic 会自动将字段名（如 app_name）转换为大写（APP_NAME）来查找对应的环境变量。

配置 BaseSettings 的行为

你可以在模型内部进行精细的配置，告诉 Pydantic 如何加载和处理设置。代码中优雅地处理了 Pydantic v1 和 v2 的差异。

Pydantic v2 (推荐)

 Pydantic v2 配置
model_config = SettingsConfigDict(
 env_file=".env",
 env_file_encoding="utf-8",
 case_sensitive=False,
)

model_config: 这是 Pydantic v2 中配置模型的标准方式。
env_file=".env": 指示 Pydantic 加载当前目录下的 .env 文件。
env_file_encoding="utf-8": 确保正确读取包含中文字符的 .env 文件。
case_sensitive=False: 设置为 False 意味着环境变量名不区分大小写（例如 DEBUG 和 debug 会被同等对待）。

Pydantic v1 (旧版)

 Pydantic v1 配置
class Config:
 env_file = ".env"
 env_file_encoding = "utf-8"
 case_sensitive = False

如果你还在使用旧版本的 Pydantic，则需要通过一个内嵌的 Config 类来完成相同的配置。

添加自定义验证 ✅

这是 BaseSettings 最强大的功能之一。你可以确保加载的配置值符合预期的格式。

 Pydantic v2
@field_validator("dashscope_api_key")
@classmethod
def validate_dashscope_key(cls, v):
 if v and not v.startswith("sk-"):
 print(f"警告: DASHSCOPE_API_KEY 可能格式不正确: {v[:10]}...")
 return v

这段代码为 dashscope_api_key 字段添加了一个验证器。在 Pydantic 尝试填充这个字段的值后，它会调用这个函数：

检查值 v 是否存在。
如果存在，检查它是否以 "sk-" 开头。
如果格式不符，打印一条警告信息。
必须返回验证后的值 v。

这可以有效防止因配置错误（例如复制粘贴时漏掉了前缀）导致应用在运行时出错。

理解配置加载的优先级

Pydantic BaseSettings 按非常明确的优先级顺序加载配置，这让你能够灵活地在不同环境中覆盖设置。

优先级从高到低：

初始化参数：在创建实例时直接传入的参数。

 port 将会是 9000，忽略所有其他来源
settings = DemoSettings(port=9000)

环境变量：系统级的环境变量。
```
 在终端中设置
export PORT=8080
```
.env 文件中的变量：在项目根目录的 .env 文件中定义的变量。
```
 .env 文件内容
PORT=8888
```
模型中定义的默认值：代码中字段的默认值。
```
 DemoSettings 类中的定义
port: int = 8000
```

💡 这个优先级顺序非常实用：你可以在代码中设置一个安全的默认值，在 .env 文件中为本地开发提供一套配置，而在生产服务器上通过环境变量来覆盖关键配置（如数据库连接信息），而无需修改任何代码。

实战演练：运行演示脚本

现在，让我们按照演示脚本的逻辑来实际操作一下。

步骤 1: 准备文件

将你的代码保存为 config_demo.py。
在与 config_demo.py 相同的目录下，创建一个名为 .env 的文件。

步骤 2: 填充 .env 文件

向 .env 文件中添加一些内容。这会覆盖代码中的默认值。

 .env
 覆盖默认的 debug 模式
DEBUG=true

 提供一个可选的 openai_api_key
OPENAI_API_KEY="sk-abcdef123456"

 为演示优先级，我们在这里也设置 PORT
PORT=8888

步骤 3: 设置环境变量 (可选)

为了演示最高优先级的环境变量，打开你的终端并执行以下命令（Windows 使用 set 而不是 export）：

export DASHSCOPE_API_KEY="sk-this-is-from-env-variable"
export PORT=9999

步骤 4: 运行脚本

现在，在你的终端中运行 Python 脚本：

python config_demo.py

步骤 5: 分析输出

你将看到类似下面的输出，它清晰地展示了配置的来源和优先级：

============================================================
BaseSettings 功能演示
使用 Pydantic v2
============================================================

1. 当前相关环境变量:
 DASHSCOPE_API_KEY = sk-thi...able
 OPENAI_API_KEY = (未设置)
 DEBUG = (未设置)
 PORT = 9999

2. 创建 BaseSettings 实例:
 ✓ 配置实例创建成功

3. 加载的配置值:
 app_name: Demo App
 debug: True
 port: 9999
 database_url: sqlite:///demo.db
 dashscope_api_key: sk-thi...able
 openai_api_key: sk-abc...456
 redis_url: (未设置)

4. .env 文件演示:
 .env 文件存在，内容:
 2: DEBUG=true
 5: OPENAI_API_KEY=sk-abc...456
 8: PORT=8888

5. 配置优先级演示:
 优先级顺序: 初始化参数 > .env 文件 > 环境变量 > 默认值
 使用初始化参数: app_name='Custom App', port=9000

...

输出解读：

debug: True：值来自 .env 文件，覆盖了代码中默认的 False。
port: 9999：值来自环境变量，它的优先级高于 .env 文件中的 8888。
dashscope_api_key: 值来自环境变量。
openai_api_key: 值来自 .env 文件。
app_name: Demo App：由于环境变量和 .env 文件都未设置，所以使用了代码中的默认值。
在优先级演示部分，port 变为 9000，app_name 变为 Custom App，这证明了初始化参数拥有最高优先级。

总结

通过使用 Pydantic 的 BaseSettings，你可以实现一个健壮、可维护且安全的配置系统。

分离配置与代码：让你的代码库更干净，更易于部署到不同环境。
消除魔法字符串：通过强类型字段访问配置（settings.port），而不是字典键（os.getenv("PORT")），减少了拼写错误。
自带验证和类型安全：在应用启动时就捕获配置错误，而不是在运行时。
清晰的优先级：让你能够自信地管理不同环境下的配置。

将 BaseSettings 集成到你的下一个 Python 项目中吧！

好的，这是接续上面教程的完整 Python 演示代码。

附录：完整演示代码

你可以将以下代码保存为 config_demo.py 文件，并按照教程中的步骤进行操作来亲自体验 BaseSettings 的功能。

"""
BaseSettings 功能演示
演示如何使用 Pydantic BaseSettings 从环境变量和 .env 文件加载配置
"""
import os
from typing import Optional
try:
 # Pydantic v2
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from pydantic import field_validator
 PYDANTIC_V2 = True
except ImportError:
 # Pydantic v1
 from pydantic import BaseSettings, validator
 PYDANTIC_V2 = False
from pathlib import Path


class DemoSettings(BaseSettings):
 """演示配置类"""

 # 基本配置
 app_name: str = "Demo App"
 debug: bool = False
 port: int = 8000

 # API Keys
 dashscope_api_key: Optional[str] = None
 openai_api_key: Optional[str] = None

 # 数据库配置
 database_url: str = "sqlite:///demo.db"

 # 可选配置
 redis_url: Optional[str] = None

 if PYDANTIC_V2:
 # Pydantic v2 配置
 model_config = SettingsConfigDict(
 env_file=".env",
 env_file_encoding="utf-8",
 case_sensitive=False,
 )

 @field_validator("dashscope_api_key")
 @classmethod
 def validate_dashscope_key(cls, v):
 if v and not v.startswith("sk-"):
 print(f"警告: DASHSCOPE_API_KEY 可能格式不正确: {v[:10]}...")
 return v
 else:
 # Pydantic v1 配置
 @validator("dashscope_api_key")
 def validate_dashscope_key(cls, v):
 if v and not v.startswith("sk-"):
 print(f"警告: DASHSCOPE_API_KEY 可能格式不正确: {v[:10]}...")
 return v

 class Config:
 env_file = ".env"
 env_file_encoding = "utf-8"
 case_sensitive = False


def demonstrate_basesettings():
 """演示 BaseSettings 的功能"""

 print("=" * 60)
 print("BaseSettings 功能演示")
 print(f"使用 Pydantic {'v2' if PYDANTIC_V2 else 'v1'}")
 print("=" * 60)

 # 1. 显示当前环境变量
 print("\n1. 当前相关环境变量:")
 env_vars = ["DASHSCOPE_API_KEY", "OPENAI_API_KEY", "DEBUG", "PORT"]
 for var in env_vars:
 value = os.getenv(var)
 if value:
 # 对于 API Key，只显示前几位和后几位
 if "API_KEY" in var and len(value) > 10:
 display_value = f"{value[:6]}...{value[-4:]}"
 else:
 display_value = value
 print(f" {var} = {display_value}")
 else:
 print(f" {var} = (未设置)")

 # 2. 创建配置实例
 print("\n2. 创建 BaseSettings 实例:")
 try:
 settings = DemoSettings()
 print(" ✓ 配置实例创建成功")
 except Exception as e:
 print(f" ✗ 配置实例创建失败: {e}")
 return

 # 3. 显示加载的配置
 print("\n3. 加载的配置值:")
 print(f" app_name: {settings.app_name}")
 print(f" debug: {settings.debug}")
 print(f" port: {settings.port}")
 print(f" database_url: {settings.database_url}")

 if settings.dashscope_api_key:
 masked_key = f"{settings.dashscope_api_key[:6]}...{settings.dashscope_api_key[-4:]}"
 print(f" dashscope_api_key: {masked_key}")
 else:
 print(f" dashscope_api_key: (未设置)")

 if settings.openai_api_key:
 masked_key = f"{settings.openai_api_key[:6]}...{settings.openai_api_key[-4:]}"
 print(f" openai_api_key: {masked_key}")
 else:
 print(f" openai_api_key: (未设置)")

 if settings.redis_url:
 print(f" redis_url: {settings.redis_url}")
 else:
 print(f" redis_url: (未设置)")

 # 4. 演示 .env 文件功能
 print("\n4. .env 文件演示:")
 env_file_path = Path(".env")
 if env_file_path.exists():
 print(" .env 文件存在，内容:")
 with open(env_file_path, 'r', encoding='utf-8') as f:
 for line_num, line in enumerate(f, 1):
 line = line.strip()
 if line and not line.startswith('#'):
 # 隐藏敏感信息
 if "API_KEY" in line:
 key, value = line.split('=', 1)
 if len(value) > 10:
 value = f"'{value[:6]}...{value[-4:]}'"
 line = f"{key}={value}"
 print(f" {line_num}: {line}")
 else:
 print(" .env 文件不存在")
 print(" 你可以创建 .env 文件来测试配置优先级:")
 print(" 例如: echo DEBUG=true > .env")

 # 5. 演示配置优先级
 print("\n5. 配置优先级演示:")
 print(" 优先级顺序: 初始化参数 > 环境变量 > .env 文件 > 默认值")

 # 使用初始化参数覆盖
 try:
 custom_settings = DemoSettings(app_name="Custom App", port=9000)
 print(f" 使用初始化参数: app_name='{custom_settings.app_name}', port={custom_settings.port}")
 except Exception as e:
 print(f" 初始化参数演示失败: {e}")

 # 6. 显示所有配置的字典形式
 print("\n6. 所有配置 (字典形式):")
 try:
 if PYDANTIC_V2:
 config_dict = settings.model_dump()
 else:
 config_dict = settings.dict()

 for key, value in config_dict.items():
 if "api_key" in key.lower() and value and len(str(value)) > 10:
 value = f"{str(value)[:6]}...{str(value)[-4:]}"
 print(f" {key}: {value}")
 except Exception as e:
 print(f" 配置字典显示失败: {e}")

 print("\n" + "=" * 60)
 print("演示完成!")
 print("=" * 60)


if __name__ == "__main__":
 demonstrate_basesettings()

教程：使用 Pydantic 的 BaseSettings 精通应用配置管理 – 调整变量优先顺序

管理应用的配置（如 API 密钥、数据库 URL 和调试开关）是一项基础而重要的任务。将这些值硬编码在代码中是一种非常糟糕的做法。Pydantic 的 BaseSettings 提供了一个强大而优雅的解决方案，它能够从环境变量或 .env 文件中加载你的配置，并结合了强大的类型验证功能。

本教程将引导你有效使用 BaseSettings，从基础设置到高级的优先级管理。

什么是 BaseSettings？

BaseSettings 是一个 Pydantic 模型，它可以自动从你的环境中读取配置值。这使你能够将配置与代码分离，极大地提高了安全性和灵活性。

其基本思想非常简单：

定义一个继承自 BaseSettings 的类。
将你的配置变量声明为带有类型提示的类属性。
Pydantic 会处理剩下的事情：读取值、将其转换为正确的类型，并进行验证。

让我们深入代码，看看它是如何工作的。

基础设置：DemoSettings 类

首先，我们定义配置的结构。DemoSettings 类包含了常见的配置项，如应用名称、API 密钥和数据库 URL。它同时演示了如何兼容 Pydantic v1 和 v2。

定义配置类

import os
from typing import Optional
try:
 # Pydantic v2
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from pydantic import field_validator
 PYDANTIC_V2 = True
except ImportError:
 # Pydantic v1
 from pydantic import BaseSettings, validator
 PYDANTIC_V2 = False

class DemoSettings(BaseSettings):
 """演示配置类"""

 # --- 带有默认值的字段 ---
 app_name: str = "Demo App"
 debug: bool = False
 port: int = 8000

 # --- 用于敏感数据的字段 (API Keys) ---
 dashscope_api_key: Optional[str] = None
 openai_api_key: Optional[str] = None

 # --- 带有复杂值的字段 ---
 database_url: str = "sqlite:///demo.db"

 # --- Pydantic 的配置 ---
 if PYDANTIC_V2:
 # Pydantic v2 使用 model_config 字典进行配置
 model_config = SettingsConfigDict(
 env_file=".env", # 要加载的 dotenv 文件名
 env_file_encoding="utf-8", # dotenv 文件的编码
 case_sensitive=False, # 环境变量是否区分大小写
 )
 else:
 # Pydantic v1 使用内部 Config 类进行配置
 class Config:
 env_file = ".env"
 env_file_encoding = "utf-8"
 case_sensitive = False

关键点：

类型提示 (Type Hinting): 每个配置项（app_name, debug 等）都有一个类型提示（str, bool）。Pydantic 会自动将来自环境的字符串值转换为这些类型。例如，环境变量 DEBUG 的值如果是 "true" 或 "1"，会被转换成布尔值 True。
默认值: 字段可以有默认值（例如 app_name: str = "Demo App"）。如果在任何其他地方都找不到值，则会使用这些默认值。
Optional 字段: 使用 Optional[str] 表示该配置项不是必需的。
配置 (model_config / class Config): 这是你告诉 BaseSettings 如何工作的地方。这里最重要的设置是 env_file=".env"，它指示 Pydantic 在当前目录中查找并加载一个名为 .env 的文件。

配置加载的优先级

Pydantic 从多个来源加载配置。理解其优先级顺序至关重要。默认情况下，优先级顺序如下：

环境变量 (Environment Variables): 这是最重要的来源。在你的 shell 中设置的变量（例如 export DEBUG=true）将始终优先于 .env 文件中的同名变量。
.env 文件: 从 env_file 指定的文件中加载的值。
默认值: 在你的 DemoSettings 类中直接定义的默认值。

⚠️ 关于初始化参数的说明： 如果你在创建 Settings 对象时传递了参数，比如 DemoSettings(port=9000)，会发生什么？在标准的 BaseSettings 实现中，环境变量仍然会覆盖这些初始化参数。所提供的代码演示了这一点，并向你展示了在需要时如何更改此行为。

实际演示

假设你有以下 .env 文件：

.env

# 应用的配置
APP_NAME="来自 .env 的超棒应用"
DEBUG=true
DASHSCOPE_API_KEY="sk-envfile-xxxxxxxxxxxx"

并且你在终端中设置了一个环境变量：

export DEBUG=false

当你创建 DemoSettings 的实例时：

settings = DemoSettings()

最终得到的值将是：

settings.app_name: "来自 .env 的超棒应用" (来自 .env 文件)
settings.debug: False (来自环境变量，它覆盖了 .env 文件中的值)
settings.port: 8000 (来自类中的默认值，因为其他地方都未设置)
settings.dashscope_api_key: "sk-envfile-xxxxxxxxxxxx" (来自 .env 文件)

高级主题：覆盖环境变量

有时，你需要以编程方式设置一个配置值，即使它已经被定义为环境变量。正如我们所注意到的，BaseSettings 的默认行为会阻止这种情况。演示代码提供了两种解决方案。

方法一：使用 CustomPrioritySettings 自定义类

这是推荐的方法。你可以创建一个自定义的配置类，修改其初始化逻辑，以确保传递给构造函数 (__init__) 的参数具有最高优先级。

class CustomPrioritySettings(BaseSettings):
 """
 一个自定义配置类，其中初始化参数会覆盖环境变量。
 """

 # ... (与 DemoSettings 完全相同的字段) ...
 app_name: str = "Demo App"
 debug: bool = False
 # ... 等等 ...

 def __init__(self, **kwargs):
 # 首先，调用父类的 __init__ 方法。这将像往常一样
 # 从环境和 .env 文件中加载值。
 super().__init__()

 # 现在，遍历在初始化时提供的关键字参数，
 # 并用它们来覆盖从环境中加载的任何值。
 for key, value in kwargs.items():
 if hasattr(self, key):
 setattr(self, key, value)

工作原理：

super().__init__() 首先运行标准的 BaseSettings 初始化流程，从环境和 .env 文件中加载所有配置。
然后，for 循环使用 kwargs 中的值来手动设置对象的属性。这有效地覆盖了刚刚从环境中加载的任何值。

使用方法：

# 假设 DASHSCOPE_API_KEY 已被设置为环境变量。
# 使用自定义类，下面的初始化将拥有最高优先级。

settings = CustomPrioritySettings(dashscope_api_key="sk-override-from-code")

# settings.dashscope_api_key 现在将是 "sk-override-from-code"
print(f"自定义密钥: {settings.dashscope_api_key}")

方法二：临时修改环境（简单直接）

如果你只需要覆盖一次值，并且不想创建自定义类，可以在创建配置实例之前临时删除环境变量。

# 保存原始的环境变量
original_key = os.environ.get('DASHSCOPE_API_KEY')

# 临时删除它
if original_key:
 del os.environ['DASHSCOPE_API_KEY']

# 初始化配置。现在，初始化参数将被使用。
temp_settings = DemoSettings(dashscope_api_key="sk-init-override-success")

# 恢复环境变量，以免影响应用的其他部分
if original_key:
 os.environ['DASHSCOPE_API_KEY'] = original_key

这种方法可行，但通常不够简洁，不推荐在生产代码中使用。

完整的演示脚本

所提供的脚本通过打印配置在每个步骤中的状态，清晰地演示了所有这些概念。这是观察优先级规则和覆盖技术如何实际运作的绝佳方式。

你可以运行该脚本并通过以下方式进行实验：

创建或修改 .env 文件。
设置和取消设置环境变量（export DEBUG=true 或 unset DEBUG）。
观察最终配置如何变化。

这种动手实践的方法将巩固你对 BaseSettings 如何简化应用配置的理解。编码愉快！✨

tableprint使用教程

Sun, 16 Mar 2025 02:39:12 +0800

Python tableprint 使用教程

1. 什么是 tableprint？

tableprint 是一个 Python 库，用于在终端或控制台中以美观的 ASCII 表格格式打印数据。它特别适合打印数值数据或结构化数据，支持动态添加行或一次性打印整个表格。常见的应用场景包括数据分析、计算结果展示等。

2. 安装 tableprint

要使用 tableprint，首先需要安装它。可以通过 pip 安装：

pip install tableprint

安装完成后，您可以在 Python 脚本中导入它。

3. 基本用法

tableprint 提供了几种主要函数，用于生成和打印表格：

tableprint.table()：一次性打印整个表格。
tableprint.header()、tableprint.row()、tableprint.bottom()：逐步构建表格。
tableprint.banner()：打印装饰性标题。

以下是具体用法和示例：

3.1 使用 `table()` 一次性打印表格

tableprint.table() 接受一个数据矩阵（通常是列表或 NumPy 数组）和标题列表，直接打印整个表格。

import tableprint as tp
import numpy as np

# 准备数据：10行3列的随机数
data = np.random.randn(10, 3)
headers = ['Column A', 'Column B', 'Column C']

# 打印表格
tp.table(data, headers)

输出示例（实际数字会因随机生成而不同）：

╭────────────┬────────────┬────────────╮
│ Column A │ Column B │ Column C │
├────────────┼────────────┼────────────┤
│ 0.123 │ -0.456 │ 1.789 │
│ -0.987 │ 0.654 │ -0.321 │
│ ... │ ... │ ... │
╰────────────┴────────────┴────────────╯

data：二维数据，可以是列表或 NumPy 数组。
headers：列标题列表，长度需与数据列数匹配。
可选参数：
- width：每列宽度（默认 11）。
- style：表格样式（默认 ‘round’，可选 ‘fancy_grid’, ‘grid’, ‘clean’, ‘block’）。

3.2 动态构建表格

如果您需要在循环中逐步打印表格（例如实时计算结果），可以使用 header()、row() 和 bottom()。

import tableprint as tp
import numpy as np

headers = ['A', 'B', 'C']

# 打印表头
print(tp.header(headers))

# 逐行打印数据
for i in range(5):
 data = np.random.randn(3) # 模拟实时生成的数据
 print(tp.row(data), flush=True) # flush=True 确保立即输出

# 打印表格底部
print(tp.bottom(3)) # 参数为列数

输出示例：

╭────────────┬────────────┬────────────╮
│ A │ B │ C │
├────────────┼────────────┼────────────┤
│ 0.234 │ -1.567 │ 0.890 │
│ -0.345 │ 0.123 │ -2.678 │
│ ... │ ... │ ... │
╰────────────┴────────────┴────────────╯

这种方法适合动态数据场景，例如实时监控或逐步计算。

如果只需要打印一个装饰性标题，可以使用 banner()：

import tableprint as tp

tp.banner("Hello, Tableprint!")

输出示例：

******************************
* Hello, Tableprint! *
******************************

width：控制宽度（默认 30）。
style：样式（默认 ‘banner’）。

4. 自定义选项

tableprint 支持一些自定义参数：

width：设置每列宽度。例如：
```
tp.table(data, headers, width=15)
```
style：改变表格外观。支持的样式包括：
- 'round'（默认）：圆角边框。
- 'fancy_grid'：带网格线的复杂样式。
- 'grid'：简单网格。
- 'clean'：无边框。
- 'block'：块状边框。
示例：
```
tp.table(data, headers, style='fancy_grid')
```
format_spec：控制数字格式（默认 ‘5g’，表示 5 位有效数字）。例如：
```
tp.table(data, headers, format_spec='.2f') # 保留两位小数
```

5. 注意事项

数据必须是二维结构，且每行长度需与标题数量一致。
如果使用 NumPy，确保导入 numpy 模块。
输出默认在标准输出（stdout），可以通过 out 参数重定向到文件（高级用法）。

6. 完整示例

以下是一个综合示例，展示多种功能：

import tableprint as tp
import numpy as np

# 数据
data = np.array([[1.2345, 2.3456, 3.4567],
 [4.5678, 5.6789, 6.7890]])
headers = ['X', 'Y', 'Z']

# 打印标题
tp.banner("My Data Table", width=20)

# 打印表格（自定义宽度和样式）
tp.table(data, headers, width=10, style='grid', format_spec='.2f')

输出示例：

********************
* My Data Table *
********************
+----------+----------+----------+
| X | Y | Z |
+----------+----------+----------+
| 1.23 | 2.35 | 3.46 |
+----------+----------+----------+
| 4.57 | 5.68 | 6.79 |
+----------+----------+----------+

总结

tableprint 是一个简单而强大的工具，适合在终端中美观地展示表格数据。通过 table() 可以快速打印完整表格，通过 header()、row()、bottom() 可以动态构建，而 banner() 则提供装饰性标题。

PyYAML

Mon, 24 Feb 2025 00:00:00 +0000

PyYAML 是一个用于处理 YAML 文件的 Python 库。YAML 是一种人类可读的数据序列化格式，常用于配置文件、数据交换等场景。PyYAML 提供了将 YAML 数据与 Python 对象之间进行转换的功能。

以下是 PyYAML 的一些常用代码示例：

1. 安装 PyYAML

首先，你需要安装 PyYAML 库。可以通过以下命令安装：

pip install pyyaml

2. 加载 YAML 文件并解析为 Python 对象

假设你有一个名为 config.yaml 的 YAML 文件，内容如下：

name: John Doe
age: 30
address:
 street: 123 Main St
 city: Anytown
 country: USA
hobbies:
 - Reading
 - Hiking
 - Coding

你可以使用 yaml.load() 或 yaml.safe_load() 来加载这个文件并将其解析为 Python 对象。

import yaml

# 打开并读取 YAML 文件
with open('config.yaml', 'r') as file:
 data = yaml.safe_load(file)

# 访问解析后的 Python 对象
print(data['name']) # 输出: John Doe
print(data['address']['city']) # 输出: Anytown
print(data['hobbies'][0]) # 输出: Reading

3. 将 Python 对象保存为 YAML 文件

你可以使用 yaml.dump() 将 Python 对象保存为 YAML 格式的文件。

import yaml

# Python 对象
data = {
 'name': 'Jane Doe',
 'age': 25,
 'address': {
 'street': '456 Elm St',
 'city': 'Othertown',
 'country': 'Canada'
 },
 'hobbies': ['Swimming', 'Cycling']
}

# 将 Python 对象写入 YAML 文件
with open('output.yaml', 'w') as file:
 yaml.dump(data, file, allow_unicode=True)

生成的 output.yaml 文件内容如下：

address:
 city: Othertown
 country: Canada
 street: 456 Elm St
age: 25
hobbies:
- Swimming
- Cycling
name: Jane Doe

4. 使用 `yaml.load()` 和 `yaml.safe_load()` 的区别

yaml.load()：可以加载任何 YAML 文档，但它可能会执行任意代码（如果 YAML 文件中包含恶意代码），因此不推荐在不信任的输入上使用。
yaml.safe_load()：只加载简单的 YAML 文档，不会执行任意代码，推荐在处理不受信任的输入时使用。

import yaml

# 使用 safe_load 加载 YAML 文件
with open('config.yaml', 'r') as file:
 data = yaml.safe_load(file)

# 使用 load 加载 YAML 文件（不推荐）
with open('config.yaml', 'r') as file:
 data = yaml.load(file, Loader=yaml.FullLoader) # FullLoader 更安全

5. 自定义对象的序列化和反序列化

如果你有自定义的 Python 类，并希望将其序列化为 YAML 或从 YAML 反序列化，你可以通过 yaml.add_representer() 和 yaml.add_constructor() 来实现。

import yaml

class Person:
 def __init__(self, name, age):
 self.name = name
 self.age = age

 def __repr__(self):
 return f"Person(name={self.name}, age={self.age})"

# 定义如何将 Person 对象转换为 YAML
def person_representer(dumper, data):
 return dumper.represent_mapping('!person', {'name': data.name, 'age': data.age})

# 定义如何从 YAML 转换回 Person 对象
def person_constructor(loader, node):
 value = loader.construct_mapping(node)
 return Person(value['name'], value['age'])

# 注册自定义的 representer 和 constructor
yaml.add_representer(Person, person_representer)
yaml.add_constructor('!person', person_constructor)

# 创建一个 Person 对象
person = Person('Alice', 28)

# 将 Person 对象转换为 YAML 字符串
yaml_str = yaml.dump(person)
print(yaml_str)

# 从 YAML 字符串转换回 Person 对象
loaded_person = yaml.load(yaml_str, Loader=yaml.FullLoader)
print(loaded_person)

输出结果：

!person
age: 28
name: Alice

Person(name=Alice, age=28)

6. 处理多文档 YAML 文件

YAML 文件可以包含多个文档，每个文档由 --- 分隔。你可以使用 yaml.load_all() 或 yaml.safe_load_all() 来加载所有文档。

---
name: John Doe
age: 30
---
name: Jane Doe
age: 25

import yaml

# 读取包含多个文档的 YAML 文件
with open('multi_doc.yaml', 'r') as file:
 for data in yaml.safe_load_all(file):
 print(data)

输出结果：

{'name': 'John Doe', 'age': 30}
{'name': 'Jane Doe', 'age': 25}

总结

yaml.safe_load()：用于安全地加载 YAML 文件。
yaml.dump()：用于将 Python 对象保存为 YAML 文件。
yaml.load_all() 和 yaml.safe_load_all()：用于处理包含多个文档的 YAML 文件。
自定义对象的序列化和反序列化可以通过 yaml.add_representer() 和 yaml.add_constructor() 实现。

这些是 PyYAML 的一些常见用法，适合处理配置文件、数据存储等任务。

pickle

Sun, 23 Feb 2025 00:00:00 +0000

pickle

常用操作

pickle.dump 将对象保存到文件（序列化）

# 定义一个Python对象
data = {"name": "Alice", "age": 25, "scores": [90, 85, 88]}

# 以二进制写模式打开文件
with open("data.pkl", "wb") as file:
 pickle.dump(data, file) # 将对象写入文件

dump参数：

obj（必选）：要序列化的Python对象。可以是几乎任何Python对象（如列表、字典、类实例等）。
file（必选）：文件对象，必须是以二进制写模式（wb）打开的文件，用于写入序列化后的字节流。
protocol（可选）：指定使用的序列化协议版本，默认值是 None（使用当前的默认协议，通常是 4 或更高版本，取决于Python版本）。
- 可选值：
  - 0：人类可读的ASCII格式（较老的协议）。
  - 1：二进制格式，兼容旧版本。
  - 2：更高效的二进制格式（Python 2.3+）。
  - 3：支持更多对象类型（Python 3.0+）。
  - 4：支持大对象和更多特性（Python 3.4+）。
  - 5：进一步优化，支持缓冲区（Python 3.8+）。
- 建议：使用默认值或明确指定 4 或 5，因为它们效率高且功能强大。
fix_imports（可选，关键字参数）：布尔值，默认 True。如果为 True，会在协议 0 或 1 下修复导入问题（主要用于跨Python 2/3兼容性）。
buffer_callback（可选，关键字参数）：Python 3.8+ 新增，一个回调函数，用于处理缓冲区数据（高级用法，通常不常用）。

从文件读取对象（反序列化）

# 以二进制读模式打开文件
with open("data.pkl", "rb") as file:
 loaded_data = pickle.load(file) # 从文件加载对象

print(loaded_data) # 输出: {'name': 'Alice', 'age': 25, 'scores': [90, 85, 88]}

load参数：

file（必选）：文件对象，必须是以二进制读模式（rb）打开的文件，包含序列化数据。
fix_imports（可选，关键字参数）：布尔值，默认 True。处理旧协议（0 或 1）中导入问题（跨Python 2/3兼容性）。
encoding（可选，关键字参数）：字符串，默认 'ASCII'。指定如何解码旧协议中的字符串（主要用于从Python 2生成的pickle文件中读取）。
- 常用值：'ASCII'、'latin1'、'utf-8'。
errors（可选，关键字参数）：字符串，默认 'strict'。指定解码时的错误处理方式。
- 常用值：'strict'（抛出异常）、'ignore'（忽略错误）、'replace'（替换无效字符）。
buffers（可选，关键字参数）：Python 3.8+ 新增，一个可迭代对象，提供外部缓冲区数据（高级用法，通常不常用）。

直接序列化为字节（不保存文件）

# 序列化为字节
byte_data = pickle.dumps(data)
print(byte_data) # 输出字节流

# 从字节反序列化
new_data = pickle.loads(byte_data)
print(new_data) # 输出: {'name': 'Alice', 'age': 25, 'scores': [90, 85, 88]}

序列化为字节对象（不写入文件）。

dumps参数：

obj（必选）：要序列化的Python对象。
protocol（可选）：与 dump() 的 protocol 参数相同，默认是 None。
fix_imports（可选，关键字参数）：布尔值，默认 True，功能同上。
buffer_callback（可选，关键字参数）：与 dump() 中的相同，Python 3.8+ 支持。

loads参数：

bytes_object（必选）：要反序列化的字节对象（通常由 dumps() 生成）。
fix_imports（可选，关键字参数）：布尔值，默认 True，功能同上。
encoding（可选，关键字参数）：字符串，默认 'ASCII'，功能同 load()。
errors（可选，关键字参数）：字符串，默认 'strict'，功能同 load()。
buffers（可选，关键字参数）：与 load() 中的相同，Python 3.8+ 支持。

常用库 on 扎塔-Zata

Typer + Rich 入门教程

目录

为什么是 Typer + Rich

五分钟上手

核心概念

Arguments:必填位置参数

Options:可选命名参数

错误处理

子命令:嵌套 Typer 应用

Rich 怎么用

自动部分(零配置)

手动部分:画表格

进度条 / JSON / Markdown

实战里常用的几个模式

eager --version

配置默认值 + flag 覆盖

--dry-run 模式

排错小抄

一页速查代码

练习题

参考资料

python开发环境配置指南

🚀 2026 现代化 Python 开发环境配置指南：拥抱 uv 与 Just

🛠️ 第一步：准备包管理器 (Windows 特别篇)

1. Git：基石配置

安装 Git

基础配置

2. uv：极速的 Python 全能管家

安装 uv

核心工作流

3. Just：比 Make 更现代的任务运行器

安装 Just

配置你的第一个 Justfile

4. 终端美化 (Optional)

总结

toml_usage_tutorial

什么是 TOML？

为什么使用 TOML？

在 Python 中使用 TOML

安装第三方库

1. 读取 TOML 文件

使用 tomllib (Python 3.11+)

使用 toml (所有 Python 版本)

2. 写入 TOML 文件

示例：创建并写入 TOML 文件

综合示例：读取、修改、再写入

高级话题与注意事项

总结

pytest测试用例使用教程

基础概念

什么是 Pytest？

1. 安装

2. 你的第一个测试

3. 运行测试

Fixture (夹具)：管理测试依赖

使用场景

基本用法

Fixture 的作用域 (scope)

Pytest 常用内置 Fixtures

1. tmp_path: 临时目录管理

2. tmp_path_factory: 跨测试会话的临时目录

3. capsys / capfd: 捕获输出

4. monkeypatch: Mock 和修改对象

5. request: 访问测试请求信息

使用 conftest.py 共享 Fixture

Markers (标记)：组织和控制测试

常用内置标记

自定义标记

参数化 (parametrize)：用不同数据多次运行同一测试

配置文件 (pytest.ini)

常用插件

实战示例（结合内置 Fixtures 和 conftest.py）

总结

学习路径建议

内置 Fixtures 快速参考

pydantic使用教程

基础使用

管理应用的变量配置（环境变量和初始值的加载）

教程：使用 Pydantic 的 BaseSettings 精通应用配置管理 – 调整变量优先顺序

eager `--version`

`--dry-run` 模式

使用 `tomllib` (Python 3.11+)

使用 `toml` (所有 Python 版本)

Fixture 的作用域 (`scope`)

1. `tmp_path`: 临时目录管理

2. `tmp_path_factory`: 跨测试会话的临时目录

3. `capsys` / `capfd`: 捕获输出

4. `monkeypatch`: Mock 和修改对象

5. `request`: 访问测试请求信息

使用 `conftest.py` 共享 Fixture

参数化 (`parametrize`)：用不同数据多次运行同一测试

配置文件 (`pytest.ini`)

3.1 使用 `table()` 一次性打印表格

3.3 使用 `banner()` 打印标题

4. 使用 `yaml.load()` 和 `yaml.safe_load()` 的区别