编程语言 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-lru_cache 缓存装饰器

Fri, 29 May 2026 11:09:25 +0800

Python `lru_cache` 缓存装饰器详解

lru_cache 是 Python 标准库 functools 里的一个装饰器，作用很纯粹：

记住函数的入参 → 返回值，下次同样入参直接返回缓存结果，不再执行函数体。

LRU = Least Recently Used（最近最少使用），是它在缓存满时的淘汰策略。

1. 它解决了什么问题

一个常见的痛点：某个函数纯计算，但比较慢（读盘、解析、网络、递归、DP 子问题等等）。同样入参被反复调用时，每一次都重算一遍，是纯浪费。

import time

def slow_square(x: int) -> int:
 time.sleep(1)
 return x * x

slow_square(3) # 1 秒
slow_square(3) # 又 1 秒
slow_square(3) # 再 1 秒……

加上 lru_cache：

from functools import lru_cache

@lru_cache(maxsize=128)
def slow_square(x: int) -> int:
 time.sleep(1)
 return x * x

slow_square(3) # 1 秒（miss，真的算）
slow_square(3) # 0 秒（hit，从缓存取）
slow_square(3) # 0 秒（hit）

2. 基本用法

from functools import lru_cache

@lru_cache(maxsize=128)
def fib(n: int) -> int:
 if n < 2:
 return n
 return fib(n - 1) + fib(n - 2)

fib(50) # 一瞬间出结果；没有 cache 时这是经典指数爆炸

maxsize=128：最多记住 128 组不同的 (入参 → 结果) 映射。
超出后最久没被命中的那个条目会被踢掉（这就是 LRU 的"L"和"R"）。
缓存挂在函数对象上，进程生命周期内一直存在；不同进程之间不共享。

3. 入参必须是可哈希的

lru_cache 内部把入参组成 tuple 当作 dict 的 key，所以入参必须是 hashable：

可以做 key	不能做 key
`int` / `float` / `str` / `bool`	`list`
`tuple`（且其中元素也都可哈希）	`dict`
`frozenset`	`set`
`bytes` / `None`	普通可变对象
`pathlib.Path`	`numpy.ndarray`

传入不可哈希参数时会抛 TypeError: unhashable type。

@lru_cache
def bad(x):
 return sum(x)

bad([1, 2, 3]) # TypeError: unhashable type: 'list'
bad((1, 2, 3)) # OK

关键字参数也会参与 key 计算，并且 f(1, 2) 和 f(1, b=2) 被当作不同的缓存条目——尽量统一调用风格。

4. 自带的辅助能力

被装饰的函数会多出三个方法：

fib.cache_info()
# CacheInfo(hits=48, misses=51, maxsize=128, currsize=51)

fib.cache_clear() # 清空整张缓存表
fib.cache_parameters() # {'maxsize': 128, 'typed': False}（3.9+）

cache_info() 调优时很有用：hits 远大于 misses 才说明缓存值钱。
cache_clear() 是测试或长跑服务里热更新配置时必备——下一节会展开。

5. `maxsize` 和 `typed` 怎么选

@lru_cache(maxsize=None, typed=False)
def f(...): ...

maxsize=None 或直接 @functools.cache（3.9+）：无大小上限、无淘汰。适合"键空间天然有限"的场景，比如解析一份固定文件、有限枚举类型。
maxsize=数字：留个上限防内存爆炸；常用 128、256、1024，按调用模式估。
typed=True：把 f(1) 和 f(1.0) 当成两个不同 key。默认 False，多数情况下不用动。

6. 实战例子：缓存配置文件解析

我在自己的项目里用 lru_cache 包装一个读取 TOML 配置的函数：

import tomllib
from functools import lru_cache
from pathlib import Path
from typing import Any


@lru_cache(maxsize=4)
def load_models_config(config_path: str | Path | None = None) -> dict[str, Any]:
 """加载 config.toml 中的 [models] section，并缓存解析结果。"""
 resolved_path = Path(config_path) if config_path else DEFAULT_TOML
 with open(resolved_path, "rb") as toml_file_handle:
 raw_toml_data = tomllib.load(toml_file_handle)
 return raw_toml_data.get("models", {})

收益：

长跑进程（API server、Agent runtime）里同样的配置可能被读上百次，加 cache 后只读盘一次。
maxsize=4 是保守值——默认 key 只有 None（默认路径），留三个余量给测试或自定义路径。

7. 三个常见陷阱

7.1 返回的是同一个对象，不是拷贝

@lru_cache
def get_settings() -> dict[str, Any]:
 return {"db_url": "postgres://..."}

cfg = get_settings()
cfg["db_url"] = "evil" # ⚠️ 改的是缓存里的那个 dict

get_settings()["db_url"] # 'evil'，已经被污染

对策：要么让函数返回不可变结构（frozendict、tuple、@dataclass(frozen=True)），要么在调用方拿到后立刻 copy.deepcopy，要么明确约定"只读"。

7.2 外部状态变了，缓存不会感知

@lru_cache
def read_file(path: str) -> str:
 return Path(path).read_text(encoding="utf-8")

read_file("config.toml") # 读到 v1
# ... 文件被改了 ...
read_file("config.toml") # 还是 v1！

lru_cache 只看入参，不看文件 mtime、不看时间戳。热重载场景不能用 lru_cache；要么换成手动管理的缓存层 + watchdog，要么手动 cache_clear()。

7.3 测试之间缓存会泄漏

pytest 跑在同一个 Python 进程里，模块级别的 @lru_cache 函数缓存会跨测试残留。前一个测试用 tmp_path 写入的配置，可能被后一个测试当作"默认配置"读到。

对策：写一个 autouse fixture 在每个测试前清缓存。

@pytest.fixture(autouse=True)
def _clear_models_config_cache() -> None:
 load_models_config.cache_clear()

8. `lru_cache` vs `functools.cache`（3.9+）

from functools import cache, lru_cache

@cache # 等价于 lru_cache(maxsize=None)
def f(x): ...

@lru_cache(maxsize=128) # 有上限，会淘汰
def g(x): ...

@cache：写法最简洁；无上限、无 LRU 淘汰、有内存风险。键空间小、可控时用它。
@lru_cache(maxsize=...)：键空间不确定、可能膨胀时用它，留一道保险。

9. 在类的方法上慎用

class Service:
 @lru_cache(maxsize=128)
 def expensive(self, x: int) -> int:
 ...

这种写法会把 self 也作为 cache key 的一部分，看上去能跑，但有两个副作用：

每个 Service 实例都有自己一份缓存（其实是 method 共享一张表、按 self 隔离）。
缓存会持有 self 的强引用，让本来该被回收的实例无法被 GC——是个隐蔽的内存泄漏。

更稳妥的做法：把要缓存的部分抽成模块级函数（不依赖 self），或者用第三方库 cachetools 的 @cachedmethod。

10. 一图小结

场景	推荐做法
纯计算函数、入参 hashable	`@lru_cache(maxsize=128)`
入参取值空间小、不会膨胀	`@functools.cache`
入参里有 `list` / `dict`	先把它转 `tuple` / `frozenset` 再缓存，或不用 cache
文件 / 配置可能被外部改	不要用 `lru_cache`，自己管理失效
测试之间不能共享缓存	autouse fixture 调 `.cache_clear()`
实例方法	抽成模块级函数，或换 `cachetools.cachedmethod`

lru_cache 是 Python 里"用最少的代码换到最多的性能"的几个工具之一，但用之前最好先想清楚两件事：

同样入参真的会被反复调用吗？ 如果不会，加 cache 只是徒增复杂度。
被缓存的返回值是否安全共享？ 是否需要担心调用方误改、外部状态过期、self 泄漏？

想清楚这两点，再决定要不要加 @lru_cache。

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 来安装上述工具。

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

Alembic

Fri, 12 Sep 2025 17:43:01 +0800

常用命令

# === Alembic 核心命令速查 ===

# 1. 初始化
# 作用：在项目中创建 Alembic 环境 (alembic.ini, env.py 等)
alembic init <alembic目录名>

# 2. 生成迁移脚本
# 作用：对比模型与数据库差异，自动生成迁移文件
alembic revision -m "简短的描述" --autogenerate

# 3. 执行升级 (应用迁移)
# 作用：将数据库更新到最新版本
alembic upgrade head
# 作用：升级到指定版本
alembic upgrade <版本号>
# 作用：向前升级 1 个版本
alembic upgrade +1

# 4. 执行降级 (回滚迁移)
# 作用：将数据库回滚 1 个版本
alembic downgrade -1
# 作用：回滚到指定版本
alembic downgrade <版本号>
# 作用：回滚到最初始 (空) 状态
alembic downgrade base

# 5. 查看状态
# 作用：查看当前数据库所在的版本
alembic current
# 作用：查看所有迁移历史
alembic history

# 6. 标记版本 (不执行SQL)
# 作用：将数据库“欺骗”为已处于某个版本 (常用于修复错误状态)
alembic stamp head
alembic stamp <版本号>

# 7. 查看迁移内容
# 作用：显示某个迁移版本将执行的 SQL (预览)
alembic show <版本号或head>

什么是 Alembic？

Alembic 是一个为 SQLAlchemy 设计的轻量级数据库迁移工具。在软件开发中，特别是项目迭代过程中，数据库的结构（Schema）几乎不可避免地会发生变化，例如添加新表、增加字段、修改数据类型等。直接在生产数据库上手动修改 SQL 是一件风险很高且难以追踪和协作的事情。

Alembic 的出现就是为了解决这个问题。它允许你：

版本化管理数据库结构：就像使用 Git 管理代码一样，Alembic 可以为你的数据库结构的每一次变更创建一个版本。
生成迁移脚本：它可以自动或半自动地检测你的 SQLAlchemy 模型（Models）与当前数据库结构之间的差异，并生成相应的 Python 迁移脚本。
轻松升级和降级：你可以通过简单的命令，将数据库结构“升级”到最新版本，或者“降级”到任意一个旧版本。
团队协作：团队成员可以共享迁移脚本，确保每个人的开发环境和最终的生产环境数据库结构保持一致。
保证数据安全：它提供了在迁移过程中处理现有数据的能力。

简单来说，Alembic 就是连接你的应用程序代码（通过 SQLAlchemy 模型定义）和数据库实际状态之间的桥梁，并用版本化的脚本来管理这种变化。

Alembic 核心概念

在开始使用之前，理解几个核心概念至关重要：

Migration (迁移)：指从一个数据库结构版本变为另一个版本的操作。
Revision (版本号)：Alembic 会为每一次迁移生成一个唯一的、有序的版本号（一个哈希字符串），用于标识数据库的特定状态。
Migration Script (迁移脚本)：一个包含 upgrade() 和 downgrade() 两个函数的 Python 文件。upgrade() 函数定义了如何将数据库“升级”到这个版本，而 downgrade() 则定义了如何“降级”回上一个版本。
Environment (环境)：Alembic 的运行环境。它由 alembic.ini 配置文件和 env.py 脚本文件定义，用于配置数据库连接、SQLAlchemy 模型的元数据等。

Alembic 使用教程

下面我们将通过一个实际的例子，一步步带你入门 Alembic。

第一步：安装

首先，确保你已经安装了 SQLAlchemy 和 Alembic。如果还没有，可以通过 uv或者 pip 安装：

uv add sqlalchemy almbic
---
pip install sqlalchemy alembic

同时，你需要为你想要连接的数据库安装相应的驱动。例如，对于 PostgreSQL，你可能需要安装 psycopg2-binary：

pip install psycopg2-binary

如果是Sqlite的话，就不需要安装驱动

第二步：初始化 Alembic 环境

在一个新的项目目录中，运行以下命令来创建一个 Alembic “迁移仓库”：

alembic init alembic

这个命令会创建一个名为 alembic 的文件夹和一个 alembic.ini 配置文件。目录结构如下：

your_project/
├── alembic/
│ ├── versions/ # 存放所有迁移脚本的地方
│ ├── script.py.mako # 生成迁移脚本的模板
│ └── env.py # 配置和运行Alembic环境的脚本
└── alembic.ini # Alembic 的主配置文件

第三步：配置数据库连接

打开 alembic.ini 文件，找到 sqlalchemy.url 这一行，并修改它以指向你的数据库。例如，使用 Sqlite：

# atexample.ini
...
sqlalchemy.url = sqlite:///./resources/app.db
...

页可以在env.py文件中进行配置’config.set_main_option(“sqlalchemy.url”, settings.database_url) '

from alembic import context

# Add the project root to the path to import our app modules
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))

# Import our database configuration and models
from app.core.database import Base
from app.core.config import settings
from app.models import User # Import models for autogenerate

# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config

# Set the database URL from our configuration
config.set_main_option("sqlalchemy.url", settings.database_url)

第四步：关联 SQLAlchemy 模型

现在，需要让 Alembic知道你的 SQLAlchemy 模型定义在哪里，以便进行比较。

创建你的模型：假设你在项目根目录下有一个 models.py 文件，内容如下：

# models.py
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base):
 __tablename__ = 'users'
 id = Column(Integer, primary_key=True)
 name = Column(String(50), nullable=False)
 email = Column(String(100)) # 假设我们稍后会把这个字段设为非空

配置 env.py：打开 alembic/env.py 文件，进行以下修改：
- 导入你的模型 Base：
```
# 在文件顶部
from my_project.models import Base # 假设你的项目名叫 my_project
```
- 找到 target_metadata = None 这一行，并将其修改为：
```
# 指向你的模型的 Base.metadata
target_metadata = Base.metadata
```
这步操作告诉 Alembic：“请以 Base.metadata 中定义的模型作为最终的数据库结构标准。”

第五步：创建第一个迁移脚本

现在，你的数据库还是空的，而你的代码中已经定义了一个 User 模型。让我们来生成第一个迁移脚本，以在数据库中创建 users 表。

运行以下命令：

alembic revision --autogenerate -m "Create users table"

revision: 创建一个新的版本脚本。
--autogenerate: 这个是 Alembic 的核心功能之一。它会自动检测 target_metadata (你的模型) 和当前数据库之间的差异，并自动生成迁移代码。
-m "...": 为这次迁移添加一段简短的描述信息。

执行成功后，你会在 alembic/versions/ 目录下看到一个新的 Python 文件，文件名类似 xxxxxxxxxxxx_create_users_table.py。打开它，内容大致如下：

需要非常注意的一点是，upgrade和downgrade函数需要再次检查一下，因为会生成错误，例如，想要设置默认的数值，需要在生成之后添加server_default=‘0’参数

"""Create users table

Revision ID: xxxxxxxxxxxx
Revises:
Create Date: 2023-10-27 10:00:00.000000

"""
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision: str = 'xxxxxxxxxxxx'
down_revision: Union[str, None] = None
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
 # ### commands auto generated by Alembic - please adjust! ###
 op.create_table('users',
 sa.Column('id', sa.Integer(), nullable=False),
 sa.Column('name', sa.String(length=50), nullable=False),
 sa.Column('email', sa.String(length=100), nullable=True),
 sa.PrimaryKeyConstraint('id')
 )
 # ### end Alembic commands ###


def downgrade() -> None:
 # ### commands auto generated by Alembic - please adjust! ###
 op.drop_table('users')
 # ### end Alembic commands ###

upgrade() 函数包含了创建 users 表的代码，而 downgrade() 则包含了删除该表的代码。

第六步：应用迁移 (升级数据库)

现在，我们来执行这个迁移脚本，真正地在数据库中创建这张表。

运行以下命令：

alembic upgrade head

upgrade: 执行升级操作。
head: head 是一个特殊的标识符，代表最新的版本。这条命令的意思是“将数据库升级到最新版本”。

执行后，连接到你的数据库，你会发现 users 表已经被成功创建了。同时，数据库中还会多出一张名为 alembic_version 的表，它用来记录当前数据库的版本号。

第七步：进行模型变更并再次迁移

项目继续开发，需求变更，我们需要给 User 模型增加一个 fullname 字段，并且把 email 字段设置为非空。

修改模型：

# models.py
class User(Base):
 __tablename__ = 'users'
 id = Column(Integer, primary_key=True)
 name = Column(String(50), nullable=False)
 fullname = Column(String(100)) # 新增字段
 email = Column(String(100), nullable=False) # 修改为非空

生成新的迁移脚本：再次运行 autogenerate 命令：

alembic revision --autogenerate -m "Add fullname column and set email to non-nullable"

Alembic 会检测到模型的变动，并生成一个新的迁移脚本。内容可能如下：

"""Add fullname column and set email to non-nullable

Revision ID: yyyyyyyyyyyy
Revises: xxxxxxxxxxxx
Create Date: 2023-10-27 10:10:00.000000

"""
...
def upgrade() -> None:
 # ### commands auto generated by Alembic - please adjust! ###
 op.add_column('users', sa.Column('fullname', sa.String(length=100), nullable=True))
 op.alter_column('users', 'email',
 existing_type=sa.VARCHAR(length=100),
 nullable=False)
 # ### end Alembic commands ###

def downgrade() -> None:
 # ### commands auto generated by Alembic - please adjust! ###
 op.alter_column('users', 'email',
 existing_type=sa.VARCHAR(length=100),
 nullable=True)
 op.drop_column('users', 'fullname')
 # ### end Alembic commands ###

注意：将一个可空列改为不可空列时，如果表中已有数据且该列为 NULL，直接升级会失败。autogenerate 无法解决所有逻辑问题，有时需要你手动编辑迁移脚本，例如为已有行的 email 列提供一个默认值。

应用新的迁移：
```
alembic upgrade head
```
执行后，users 表的结构就会被更新。

第八步：降级数据库

如果你想撤销最近的一次迁移，可以执行降级操作。

# 降级一个版本
alembic downgrade -1

# 降级到指定的版本号
alembic downgrade yyyyyyyyyyyy

# 降级到最初始的状态（空数据库）
alembic downgrade base

常用 Alembic 命令总结

alembic init <directory>: 初始化 Alembic 仓库。
alembic revision --autogenerate -m "message": 自动生成新的迁移脚本。
alembic upgrade head: 升级到最新版本。
alembic upgrade +1: 升级一个版本。
alembic upgrade <revision>: 升级到指定版本。
alembic downgrade base: 降级到最初始状态。
alembic downgrade -1: 降级一个版本。
alembic downgrade <revision>: 降级到指定版本之前。
alembic history: 显示迁移历史记录。
alembic current: 显示当前数据库的版本号。
alembic stamp head: 不执行迁移脚本，但将数据库的版本号标记为最新。这在手动修改数据库后，想让 Alembic 状态与数据库同步时很有用。

希望这份详细的介绍和教程能帮助你快速上手 Alembic！它是一个非常强大且实用的工具，在任何使用 SQLAlchemy 的项目中都值得引入。

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 如何简化应用配置的理解。编码愉快！✨

python-将py文件编译为pyc文件并运行

Mon, 28 Apr 2025 17:24:39 +0800

py编译为pyc(为了代码加密)

问题提醒

1. 版本号问题：编译版本和runtime版本不一致会导致报错

打包过程

我在2025年5月左右开发了一个软件项目，想要将其发布，代码中有我的api-key，因此我需要将代码进行加密。

（打包我使用的是PyStand项目，他最简单的方式当然是直接粘贴源码了。）

项目结构如下：

实际上必要的程序是我用红框圈起来的，src是放了我的核心代码，run.py是入口程序，然后config.yaml是配置文件

1. 新建compile_py.py文件并填入代码

其中script文件夹就是源码，out_文件夹用来防止编译后的文件，可以手动创建一下

需要注意的是，运行这边编译代码的py版本和runtime的嵌入版本要一致，大版本一致就行了，比如编译是3.11.16和runtime3.11.15好像没什么影响


import py_compile
import os
import hashlib

# 配置
script_dir = 'script' # 输入文件夹
output_dir = 'out_' # 输出根目录
preserve_structure = True # 是否保留文件夹结构（True/False）

# 确保 script 文件夹存在
if not os.path.exists(script_dir):
 print(f"Error: Directory '{script_dir}' does not exist.")
 exit(1)

# 遍历 script 文件夹及其子文件夹
for root, _, files in os.walk(script_dir):
 for filename in files:
 if filename.endswith('.py'):
 # 构造完整的 .py 文件路径
 py_file = os.path.join(root, filename)

 # 计算相对路径
 relative_path = os.path.relpath(py_file, script_dir)
 base_name = os.path.splitext(filename)[0]

 if preserve_structure:
 # 保留文件夹结构：输出到 output_dir 下的相对路径
 pyc_relative_dir = os.path.dirname(relative_path)
 pyc_dir = os.path.join(output_dir, pyc_relative_dir)
 os.makedirs(pyc_dir, exist_ok=True)
 pyc_filename = f"{base_name}.pyc"
 pyc_file = os.path.join(pyc_dir, pyc_filename)
 else:
 # 不保留结构：平铺到 output_dir，使用哈希前缀避免冲突
 hash_prefix = hashlib.md5(relative_path.encode()).hexdigest()[:8]
 pyc_filename = f"{hash_prefix}_{base_name}.pyc"
 pyc_file = os.path.join(output_dir, pyc_filename)

 try:
 # 编译 .py 文件为 .pyc 文件
 py_compile.compile(py_file, cfile=pyc_file)
 print(f"Compiled {py_file} to {pyc_file}")
 except Exception as e:
 print(f"Failed to compile {py_file}: {e}")

2. 不编译py外文件，手动修改

因为不编译py文件以外的，但是需要用到配置文件，就手动移动一下，然后把整个文件夹移动到PyStand的分发包里面

（其中我把两个test文件删除了）

PyQt-设备像素设置

Thu, 24 Apr 2025 11:06:37 +0800

让Qt应用在高DOI或者高分辨率显示器上看起来更加清晰（最新pyqt6已经不需要设置）

QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True) QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True)

目的

这两行代码的目的是让你的 Qt 应用程序在高 DPI（Dots Per Inch，每英寸点数）或高分辨率显示器（例如 Retina 屏、4K 显示器）上看起来更清晰、大小更合适。

代码解释

QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True)
- QApplication: 这是你的 Qt 应用程序的核心类。
- setAttribute: 这是设置应用程序级别属性的方法。
- Qt.AA_EnableHighDpiScaling: 这是一个枚举值（属性标志）。当它被设置为 True 时，它告诉 Qt 启用基于显示器 DPI 的自动缩放。这意味着 Qt 会尝试自动调整窗口、控件（按钮、文本框等）的大小以及字体大小，使它们在不同 DPI 的屏幕上看起来比例一致。
- True: 启用这个属性。
QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True)
- Qt.AA_UseHighDpiPixmaps: 这是另一个属性标志。当它被设置为 True 时，它告诉 Qt 在高 DPI 显示器上使用高分辨率版本的像素图（pixmaps），也就是图标和图片。如果你为图标提供了 @2x 或类似的高分辨率版本（例如 icon.png 和 icon@2x.png），设置此项能让 Qt 自动选择合适的版本，从而在高 DPI 屏幕上显示清晰的图标，而不是模糊的低分辨率版本。
- True: 启用这个属性。

何时以及如何使用

这两行代码非常重要的一点是：它们必须在创建 QApplication 实例之前被调用。因为它们影响应用程序如何初始化以及如何与操作系统的显示设置交互。

简单示例 (以 PyQt5 为例)

import sys

# 导入你需要的 PyQt 或 PySide 模块
# 可能是 PyQt5, PyQt6, PySide2, PySide6
# 这里以 PyQt6 为例
# from PyQt6.QtWidgets import QApplication, QWidget, QLabel, QVBoxLayout
# from PyQt6.QtCore import Qt # Qt 模块包含枚举值


from PyQt5.QtWidgets import (
 QMainWindow, QWidget, QVBoxLayout, QHBoxLayout,
 QTabWidget, QAction, QFileDialog, QMessageBox,
 QSplitter, QToolBar, QStatusBar, QLabel, QComboBox,QApplication
)
from PyQt5.QtCore import Qt


# --- 关键步骤 ---
# 在创建 QApplication 实例之前设置高 DPI 属性
# 注意: 在 Qt 6 已经自动支持了， 所以不需要单独写代码



# 在 Qt 5 中，通常直接是 Qt.AA_...
# 设置高 DPI 支持
# PyQt5 需要显式启用高 DPI 缩放
QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True)
QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True)
# --- 关键步骤结束 ---

# 创建 QApplication 实例
# sys.argv 允许你传递命令行参数给应用程序
app = QApplication(sys.argv)

# 创建一个简单的窗口
window = QWidget()
window.setWindowTitle('高 DPI 示例')

# 添加一些控件
layout = QVBoxLayout()
label = QLabel('这个标签在高 DPI 屏幕上应该看起来很清晰。')
layout.addWidget(label)
window.setLayout(layout)

# 设置窗口大小并显示
window.resize(300, 150)
window.show()

# 启动应用程序的事件循环
# 程序会在这里等待用户交互，直到窗口关闭
sys.exit(app.exec())

总结

为了让你的 PyQt/PySide 应用在现代高分辨率屏幕上获得良好的视觉效果（避免元素过小或图像模糊），请在创建 QApplication 对象之前添加这两行代码（pyqt5）。
AA_EnableHighDpiScaling 主要负责 UI 元素（控件、字体、布局）的缩放。
AA_UseHighDpiPixmaps 主要负责图像和图标的清晰度。

在较新的 Qt 版本（尤其是 Qt 6）中，AA_EnableHighDpiScaling 可能已经是默认启用的，但显式设置它是一个好的实践，可以确保跨版本和平台的兼容性。而 AA_UseHighDpiPixmaps 通常仍然需要显式设置以加载高分辨率图像资源。

设备像素比

除了之前提到的 AA_EnableHighDpiScaling 和 AA_UseHighDpiPixmaps 这两个用于自动处理高 DPI 的应用程序属性之外，还有一些相关的函数和概念，它们允许你查询 DPI 信息或进行更手动的控制。

最接近且常用的相关功能是查询设备像素比 (Device Pixel Ratio)。

核心概念：设备像素比 (Device Pixel Ratio)

定义：设备像素比是指物理像素（屏幕上实际的光点）与设备无关像素（也称为逻辑像素，是应用程序绘制时使用的标准坐标单位，通常基于 96 DPI）之间的比例。
意义：
- 在标准 DPI 显示器上，这个比例通常是 1.0。
- 在高 DPI 显示器（如 Retina 或 4K 屏）上，这个比例会大于 1.0（例如 1.5, 2.0, 2.5 等），表示一个逻辑像素对应了多个物理像素。
用途：你可以使用这个比率来：
1. 手动缩放：在需要精确控制像素的情况下（例如自定义绘图 paintEvent），将逻辑坐标或尺寸乘以这个比率来得到物理像素尺寸。
2. 加载资源：根据比率选择不同分辨率的图像资源（虽然 AA_UseHighDpiPixmaps 通常会自动处理）。
3. 调试：检查应用程序当前的缩放状态。

相关函数和类

QWidget.devicePixelRatio() -> int / QWidget.devicePixelRatioF() -> float
- 获取控件（Widget）当前所在屏幕的设备像素比。
- 返回整数版本 (devicePixelRatio) 或更精确的浮点数版本 (devicePixelRatioF)。
- 这是最常用的，因为它直接关联到你正在操作的那个窗口或控件。
QScreen 类
- 代表一个物理显示屏幕。
- QGuiApplication.primaryScreen(): 获取系统的主屏幕对象。
- QWidget.screen(): 获取控件当前所在的 QScreen 对象。
- QScreen.devicePixelRatio() -> float: 获取这个特定屏幕的设备像素比。
- QScreen.logicalDotsPerInch() -> float: 获取屏幕的逻辑 DPI (通常是 96 DPI，但也可能被系统设置为其他值)。
- QScreen.physicalDotsPerInch() -> float: 获取屏幕的物理 DPI (实际硬件的像素密度)。
- QScreen.geometry() -> QRect: 获取屏幕的几何尺寸（使用逻辑像素）。
- QScreen.availableGeometry() -> QRect: 获取屏幕的可用几何尺寸（排除任务栏等，使用逻辑像素）。

教程和示例

下面的示例展示了如何获取窗口和屏幕的设备像素比以及其他相关信息，并包含了一个简单的自定义绘图控件，演示如何在 paintEvent 中考虑像素比。

import sys
from PyQt6.QtWidgets import (QApplication, QMainWindow, QWidget, QLabel,
 QVBoxLayout, QTextEdit)
# QGuiApplication 用于获取屏幕信息
from PyQt6.QtGui import QGuiApplication, QPainter, QColor, QFont, QPaintEvent
from PyQt6.QtCore import Qt, QRectF, QSize

# --- 依然建议先设置自动缩放属性 ---
# 这让 Qt 框架自动处理大部分 UI 元素的缩放
try:
 # Qt 6 风格
 QApplication.setAttribute(Qt.ApplicationAttribute.AA_EnableHighDpiScaling, True)
 QApplication.setAttribute(Qt.ApplicationAttribute.AA_UseHighDpiPixmaps, True)
except AttributeError:
 # Qt 5 风格
 QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True)
 QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True)
# ---

# 自定义绘图控件，演示如何在 paintEvent 中使用 devicePixelRatio
class DrawingWidget(QWidget):
 def minimumSizeHint(self) -> QSize:
 # 提供一个基于逻辑像素的最小尺寸提示
 return QSize(200, 100)

 # 重写 paintEvent 进行自定义绘图
 def paintEvent(self, event: QPaintEvent):
 painter = QPainter(self)
 painter.setRenderHint(QPainter.RenderHint.Antialiasing) # 让绘制更平滑

 # 获取当前控件的设备像素比 (浮点数版本更精确)
 ratio = self.devicePixelRatioF()

 # 准备绘制信息
 text = f"Device Pixel Ratio: {ratio:.2f}"
 logical_rect = QRectF(10.0, 10.0, 180.0, 50.0) # 使用逻辑像素定义矩形

 # 绘制背景矩形 (QPainter 默认使用逻辑坐标)
 painter.setBrush(QColor(230, 240, 255)) # 淡蓝色背景
 painter.setPen(Qt.PenStyle.NoPen) # 无边框
 painter.drawRoundedRect(logical_rect, 5.0, 5.0) # 圆角矩形

 # 绘制文字 (QPainter 会根据 Qt 的缩放设置自动处理字体大小)
 # 但如果你需要基于物理像素精确控制，可能需要手动计算
 painter.setPen(QColor("black"))
 font = QFont()
 # 你可以尝试设置逻辑点大小，Qt 会处理缩放
 font.setPointSizeF(10)
 painter.setFont(font)

 # 在矩形内绘制文本 (文本位置也是逻辑坐标)
 painter.drawText(logical_rect.adjusted(5, 5, -5, -5), Qt.AlignmentFlag.AlignCenter, text)

 # 示例：如果需要绘制一个固定物理像素大小的线条 (需要手动计算)
 # 假设需要绘制一条 2 个物理像素宽的线
 physical_line_width = 2
 logical_line_width = physical_line_width / ratio # 计算对应的逻辑宽度

 pen = painter.pen() # 获取当前画笔
 pen.setColor(QColor("red"))
 pen.setWidthF(logical_line_width) # 设置逻辑宽度
 painter.setPen(pen)

 # 绘制线条 (坐标仍是逻辑像素)
 painter.drawLine(int(logical_rect.left()), int(logical_rect.bottom()) + 10,
 int(logical_rect.right()), int(logical_rect.bottom()) + 10)

 painter.end() # 结束绘制

# 主窗口类
class MainWindow(QMainWindow):
 def __init__(self):
 super().__init__()
 self.setWindowTitle("查询 DPI 和设备像素比")
 self.setGeometry(100, 100, 500, 450) # 初始位置和大小 (逻辑像素)

 # 用于显示信息的文本框
 self.info_display = QTextEdit()
 self.info_display.setReadOnly(True)
 self.info_display.setLineWrapMode(QTextEdit.LineWrapMode.NoWrap) # 不自动换行

 # 自定义绘图控件实例
 self.drawing_widget = DrawingWidget()

 # 布局
 central_widget = QWidget()
 layout = QVBoxLayout(central_widget)
 layout.addWidget(QLabel("信息查询结果:"))
 layout.addWidget(self.info_display)
 layout.addWidget(QLabel("自定义绘图区域:"))
 layout.addWidget(self.drawing_widget)

 self.setCentralWidget(central_widget)

 # 在窗口显示后查询信息会更可靠
 self.initial_query_done = False

 # 查询并显示 DPI 和屏幕信息
 def query_and_display_info(self):
 info = []

 # 1. 获取窗口自身的设备像素比
 # 注意: 最好在窗口实际显示到屏幕上之后获取 (例如在 showEvent 或 moveEvent 中)
 window_dpr = self.devicePixelRatio()
 window_dpr_f = self.devicePixelRatioF()
 info.append(f"--- 窗口 (Window) ---")
 info.append(f"devicePixelRatio(): {window_dpr} (int)")
 info.append(f"devicePixelRatioF(): {window_dpr_f:.2f} (float)")

 # 2. 获取窗口所在的屏幕信息
 current_screen = self.screen() # QWidget.screen() 获取当前屏幕
 if not current_screen:
 # 如果窗口还没显示或找不到屏幕，尝试获取主屏幕
 current_screen = QGuiApplication.primaryScreen()

 if current_screen:
 screen_name = current_screen.name()
 screen_dpr = current_screen.devicePixelRatio()
 logical_dpi_x = current_screen.logicalDotsPerInchX()
 logical_dpi_y = current_screen.logicalDotsPerInchY()
 physical_dpi_x = current_screen.physicalDotsPerInchX()
 physical_dpi_y = current_screen.physicalDotsPerInchY()
 geometry = current_screen.geometry() # 逻辑像素矩形
 available_geometry = current_screen.availableGeometry() # 可用逻辑像素矩形

 info.append(f"\n--- 当前屏幕 (Screen: {screen_name}) ---")
 info.append(f"devicePixelRatio(): {screen_dpr:.2f}")
 info.append(f"logicalDotsPerInch (X, Y): {logical_dpi_x:.1f}, {logical_dpi_y:.1f}")
 info.append(f"physicalDotsPerInch (X, Y): {physical_dpi_x:.1f}, {physical_dpi_y:.1f}")
 info.append(f"geometry (逻辑像素): {geometry.width()}x{geometry.height()} @ ({geometry.x()},{geometry.y()})")
 info.append(f"availableGeometry (逻辑像素): {available_geometry.width()}x{available_geometry.height()}")

 # 计算物理像素尺寸
 physical_width = geometry.width() * screen_dpr
 physical_height = geometry.height() * screen_dpr
 info.append(f"物理像素 (计算): {int(physical_width)}x{int(physical_height)}")
 else:
 info.append("\n无法获取屏幕信息。")

 self.info_display.setText("\n".join(info))
 # 更新自定义绘图区域，因为它依赖于 devicePixelRatio
 self.drawing_widget.update()

 # 重写 showEvent，在窗口首次显示时查询信息
 def showEvent(self, event):
 super().showEvent(event)
 if not self.initial_query_done:
 self.query_and_display_info()
 self.initial_query_done = True

 # 重写 moveEvent，当窗口移动（可能移动到不同 DPI 的屏幕）时更新信息
 def moveEvent(self, event):
 super().moveEvent(event)
 # 只有在窗口可见时移动才更新，避免初始化时多次调用
 if self.isVisible():
 self.query_and_display_info()

# --- 主程序入口 ---
app = QApplication(sys.argv)
main_window = MainWindow()
main_window.show()
sys.exit(app.exec())

代码解释

AA_ 属性设置：我们仍然保留了开头的 AA_EnableHighDpiScaling 和 AA_UseHighDpiPixmaps 设置，因为它们是让 Qt 框架自动处理大部分 UI 缩放的基础，推荐使用。
DrawingWidget：这是一个自定义控件，重写了 paintEvent。
- 在 paintEvent 内部，我们首先通过 self.devicePixelRatioF() 获取当前控件的设备像素比 ratio。
- 我们使用 QPainter 进行绘图。QPainter 的坐标系统默认是基于逻辑像素的。当你调用 drawRect, drawText 等函数时，你提供的坐标和尺寸是逻辑单位。
- Qt 的渲染引擎在启用了高 DPI 缩放后，会自动将这些逻辑坐标映射到物理像素上进行绘制。因此，对于标准的控件和文本绘制，你通常不需要手动乘以 ratio。
- 手动缩放场景：示例中演示了如果你需要绘制一个具有固定物理像素宽度的线条（例如 2 像素），你需要用物理宽度除以 ratio 得到对应的逻辑宽度，然后设置给 QPen。这是手动控制像素级细节的一个例子。
MainWindow：
- query_and_display_info 方法：
  - 获取窗口自身的 devicePixelRatio() 和 devicePixelRatioF()。
  - 通过 self.screen() 或 QGuiApplication.primaryScreen() 获取当前的 QScreen 对象。
  - 从 QScreen 对象获取更详细的信息，如屏幕的 devicePixelRatio, 逻辑 DPI, 物理 DPI, 几何尺寸（逻辑像素）等。
  - 计算并显示屏幕的物理像素尺寸。
- showEvent 和 moveEvent：重写这两个事件处理函数，确保在窗口首次显示或移动到新屏幕时，调用 query_and_display_info 来更新显示的信息，并触发 DrawingWidget 的重绘 (update())。

总结

AA_EnableHighDpiScaling 和 AA_UseHighDpiPixmaps 是实现自动高 DPI 适应性的关键属性，适用于大多数标准 UI 元素。
QWidget.devicePixelRatio(), QWidget.devicePixelRatioF() 和 QScreen 类及其方法允许你查询当前的缩放比例和屏幕信息。
查询到的 devicePixelRatio 对于需要手动控制像素级细节的场景（如自定义绘图、与需要物理像素坐标的库交互）非常有用。
对于标准的 QPainter 绘图操作，通常使用逻辑坐标即可，Qt 的自动缩放机制会处理好物理像素的映射。只有在需要精确控制物理尺寸或绘制像素对齐的图形时，才需要手动介入计算。

PyQt-入门教程（AI生成）

Thu, 24 Apr 2025 10:39:35 +0800

PyQt6 入门教程（详细版本）

PyQt6 是一个用于创建桌面应用程序的 Python 库，它是 Qt 框架的 Python 绑定。Qt 是一个功能强大的跨平台框架，支持 GUI 开发、网络编程、数据库操作等。通过 PyQt6，你可以轻松地开发跨平台的桌面应用程序。

本教程将从零开始，逐步引导你学习 PyQt6 的基本概念和使用方法。

一、环境准备

在开始之前，你需要确保你的开发环境已经安装了以下内容：

Python
确保你已经安装了 Python 3.6 或更高版本。可以通过以下命令检查：
```
python --version
```
安装 PyQt6
使用 pip 安装 PyQt6：
```
pip install PyQt6
```
安装 PyQt6 工具（可选）
如果你想使用 Qt Designer（一个可视化设计工具），可以安装 pyqt6-tools：
```
pip install pyqt6-tools
```
安装完成后，可以在 Scripts 目录下找到 designer.exe 文件，启动它即可使用 Qt Designer。

二、第一个 PyQt6 程序

让我们从一个简单的例子开始，创建一个窗口并显示它。

示例代码：Hello World

import sys
from PyQt6.QtWidgets import QApplication, QWidget

# 创建主程序类
class MyApp(QWidget):
 def __init__(self):
 super().__init__()
 self.initUI()

 def initUI(self):
 # 设置窗口标题
 self.setWindowTitle("Hello PyQt6")
 # 设置窗口大小
 self.setGeometry(100, 100, 400, 300)
 # 显示窗口
 self.show()

if __name__ == "__main__":
 # 创建应用实例
 app = QApplication(sys.argv)
 # 创建窗口实例
 window = MyApp()
 # 进入主循环
 sys.exit(app.exec())

代码解析

导入模块
- QApplication: 管理应用程序的控制流和主要设置。
- QWidget: 所有用户界面对象的基类。
创建自定义类
- MyApp 继承自 QWidget，我们在这里定义窗口的行为。
- __init__ 方法初始化窗口，并调用 initUI 方法设置界面。
设置窗口属性
- setWindowTitle: 设置窗口标题。
- setGeometry: 设置窗口的位置和大小（x, y, width, height）。
显示窗口
- 调用 show() 方法让窗口可见。
主程序入口
- 创建 QApplication 实例。
- 创建窗口实例并进入主事件循环。

运行上述代码后，你会看到一个标题为 “Hello PyQt6” 的窗口。

三、添加控件

在 PyQt6 中，你可以通过添加控件（如按钮、标签、文本框等）来丰富界面。

示例代码：带按钮的窗口

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QVBoxLayout, QLabel

class MyApp(QWidget):
 def __init__(self):
 super().__init__()
 self.initUI()

 def initUI(self):
 # 设置窗口标题和大小
 self.setWindowTitle("Button Example")
 self.setGeometry(100, 100, 300, 200)

 # 创建垂直布局
 layout = QVBoxLayout()

 # 创建标签
 self.label = QLabel("Hello, PyQt6!", self)
 layout.addWidget(self.label)

 # 创建按钮
 button = QPushButton("Click Me", self)
 button.clicked.connect(self.on_button_click) # 绑定点击事件
 layout.addWidget(button)

 # 设置布局
 self.setLayout(layout)

 def on_button_click(self):
 # 修改标签文本
 self.label.setText("Button Clicked!")

if __name__ == "__main__":
 app = QApplication(sys.argv)
 window = MyApp()
 window.show()
 sys.exit(app.exec())

代码解析

控件介绍
- QLabel: 用于显示文本或图片。
- QPushButton: 按钮控件。
- QVBoxLayout: 垂直布局管理器，用于排列控件。
事件绑定
- button.clicked.connect(self.on_button_click) 将按钮的点击事件与自定义方法 on_button_click 绑定。
动态更新界面
- 在 on_button_click 方法中修改标签的文本内容。

运行代码后，点击按钮会触发事件，标签的内容会变为 “Button Clicked!"。

四、信号与槽机制

PyQt6 的核心之一是信号与槽机制（Signals and Slots）。信号是由控件发出的事件，槽是响应这些事件的函数。

示例代码：信号与槽

import sys
from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QLineEdit, QVBoxLayout

class MyApp(QWidget):
 def __init__(self):
 super().__init__()
 self.initUI()

 def initUI(self):
 self.setWindowTitle("Signal and Slot Example")
 self.setGeometry(100, 100, 300, 200)

 # 创建垂直布局
 layout = QVBoxLayout()

 # 创建输入框
 self.input_box = QLineEdit(self)
 layout.addWidget(self.input_box)

 # 创建按钮
 button = QPushButton("Show Text", self)
 button.clicked.connect(self.show_text) # 绑定点击事件
 layout.addWidget(button)

 # 设置布局
 self.setLayout(layout)

 def show_text(self):
 # 获取输入框内容并显示
 text = self.input_box.text()
 print(f"Input Text: {text}")

if __name__ == "__main__":
 app = QApplication(sys.argv)
 window = MyApp()
 window.show()
 sys.exit(app.exec())

代码解析

QLineEdit
- 用于接收用户输入的单行文本框。
信号与槽
- button.clicked.connect(self.show_text) 将按钮的点击信号连接到 show_text 方法。
- 在 show_text 方法中，通过 self.input_box.text() 获取输入框的内容。

运行代码后，在输入框中输入内容并点击按钮，控制台会打印出输入的文本。

五、使用 Qt Designer 设计界面

对于复杂的界面，手动编写代码可能效率较低。这时可以使用 Qt Designer 来设计界面，然后将其转换为 Python 代码。

步骤

打开 Qt Designer
启动 designer.exe，创建一个新的窗口或对话框。
设计界面
拖拽控件到窗口中，设置控件属性。
保存 .ui 文件
将设计好的界面保存为 .ui 文件。
使用 pyuic6 转换为 Python 代码
在终端中运行以下命令：
```
pyuic6 your_file.ui -o your_file.py
```

加载 .ui 文件
也可以直接在代码中加载 .ui 文件：

from PyQt6.uic import loadUi
from PyQt6.QtWidgets import QMainWindow, QApplication
import sys

class MainWindow(QMainWindow):
 def __init__(self):
 super().__init__()
 loadUi("your_file.ui", self)

if __name__ == "__main__":
 app = QApplication(sys.argv)
 window = MainWindow()
 window.show()
 sys.exit(app.exec())

六、总结

通过本教程，你应该已经掌握了以下内容：

如何安装 PyQt6 和相关工具。
创建一个简单的窗口并添加控件。
使用信号与槽机制处理用户交互。
使用 Qt Designer 快速设计界面。

接下来，你可以尝试更复杂的项目，例如多窗口应用、数据绑定、文件操作等。PyQt6 提供了丰富的功能，适合开发各种类型的桌面应用程序。祝你学习愉快！

python-staticmethod 修饰符

Mon, 07 Apr 2025 14:15:40 +0800

Python `staticmethod` 修饰符详解教程

什么是 `staticmethod`？

在 Python 中，staticmethod 是一个内置装饰器，用于将类中的方法定义为静态方法。静态方法是一种特殊的方法，它属于类，但不依赖于类或其实例的状态。换句话说，它不需要访问实例属性（通过 self）或类属性（通过 cls），行为更像是一个普通的函数，只是被组织在类的命名空间中。

核心特点

不需要传递 self 或 cls 参数。
可以通过类名直接调用，也可以通过实例调用。
不与类的状态绑定，独立性强。

为什么需要 `staticmethod`？

在面向对象编程中，方法通常与对象（实例）或类本身相关联。但有时候，我们需要定义一些与类逻辑相关但又不需要访问类或实例数据的函数。这时，staticmethod 就派上用场了。它能：

提高代码组织性：将相关功能封装到类中，避免散落在全局命名空间。
增强可读性：让代码的意图更清晰，表示这个方法与类有逻辑关联。
方便调用：无需实例化即可使用。

如何使用 `staticmethod`

使用 @staticmethod 装饰器来定义静态方法。以下是基本语法：

class ClassName:
 @staticmethod
 def method_name(arg1, arg2, ...):
 # 方法逻辑
 return result

示例 1：简单的静态方法

class MathUtils:
 @staticmethod
 def add(a, b):
 return a + b

# 通过类名调用
print(MathUtils.add(3, 5)) # 输出 8

# 创建实例后调用（也可以但不常见）
math = MathUtils()
print(math.add(3, 5)) # 输出 8

在这个例子中，add 是一个静态方法，它只负责计算两个数的和，不需要知道类的任何信息。

与普通方法和类方法的对比

为了更好地理解 staticmethod，我们将其与普通方法和类方法对比：

1. 普通方法

需要 self 参数，绑定到实例。
用于操作实例的数据。

class Dog:
 def bark(self):
 return "Woof!"

dog = Dog()
print(dog.bark()) # 输出 Woof!
# print(Dog.bark()) # 错误！需要实例

2. 类方法（`@classmethod`）

需要 cls 参数，绑定到类。
可以访问或修改类状态。

class Dog:
 species = "Canine"

 @classmethod
 def get_species(cls):
 return cls.species

print(Dog.get_species()) # 输出 Canine
dog = Dog()
print(dog.get_species()) # 输出 Canine

3. 静态方法（`@staticmethod`）

不需要 self 或 cls。
独立于类和实例。

class Dog:
 @staticmethod
 def make_sound():
 return "Some generic sound"

print(Dog.make_sound()) # 输出 Some generic sound
dog = Dog()
print(dog.make_sound()) # 输出 Some generic sound

对比总结

类型	绑定对象	参数	典型用途
普通方法	实例	`self`	操作实例数据
类方法	类	`cls`	操作类数据或工厂方法
静态方法	无	无特殊参数	独立功能，逻辑上归属类

使用场景

staticmethod 的典型应用场景包括：

1. 工具函数

当某个功能与类相关但不需要访问类或实例状态时，可以使用静态方法。例如，一个数学工具类：

class MathTools:
 @staticmethod
 def is_even(number):
 return number % 2 == 0

 @staticmethod
 def factorial(n):
 if n == 0:
 return 1
 return n * MathTools.factorial(n - 1)

print(MathTools.is_even(4)) # 输出 True
print(MathTools.factorial(5)) # 输出 120

2. 数据格式化或转换

在需要对数据进行独立处理时，静态方法很实用。例如：

class Formatter:
 @staticmethod
 def capitalize_text(text):
 return text.capitalize()

 @staticmethod
 def reverse_text(text):
 return text[::-1]

print(Formatter.capitalize_text("hello")) # 输出 Hello
print(Formatter.reverse_text("world")) # 输出 dlrow

3. 辅助功能

在复杂的类中，静态方法可以作为辅助工具。例如：

class Student:
 def __init__(self, name, score):
 self.name = name
 self.score = score

 @staticmethod
 def grade_from_score(score):
 if score >= 90:
 return "A"
 elif score >= 80:
 return "B"
 else:
 return "C"

student = Student("Alice", 85)
grade = Student.grade_from_score(student.score)
print(f"{student.name}'s grade: {grade}") # 输出 Alice's grade: B

注意事项

不要滥用：
- 如果一个方法需要访问实例或类的数据，就不应该使用 staticmethod，而应选择普通方法或类方法。
与模块级函数的区别：
- 如果方法与类完全无关，可以直接定义为模块级函数，而不是静态方法。静态方法适合逻辑上属于类的场景。
可读性优先：
- 使用静态方法时，确保它的命名和功能清楚地表明它与类的关系。

练习题

以下是一些练习，帮助你巩固对 staticmethod 的理解：

练习 1：温度转换

编写一个 Temperature 类，包含两个静态方法：

celsius_to_fahrenheit(celsius)：将摄氏度转换为华氏度（公式：F = C * 9/5 + 32）。
fahrenheit_to_celsius(fahrenheit)：将华氏度转换为摄氏度（公式：C = (F - 32) * 5/9）。

参考答案：

class Temperature:
 @staticmethod
 def celsius_to_fahrenheit(celsius):
 return celsius * 9/5 + 32

 @staticmethod
 def fahrenheit_to_celsius(fahrenheit):
 return (fahrenheit - 32) * 5/9

print(Temperature.celsius_to_fahrenheit(0)) # 输出 32.0
print(Temperature.fahrenheit_to_celsius(32)) # 输出 0.0

练习 2：字符串工具

创建一个 StringUtils 类，包含以下静态方法：

is_palindrome(text)：判断字符串是否为回文。
count_vowels(text)：统计字符串中的元音字母（a, e, i, o, u）数量。

参考答案：

class StringUtils:
 @staticmethod
 def is_palindrome(text):
 return text.lower() == text.lower()[::-1]

 @staticmethod
 def count_vowels(text):
 vowels = "aeiou"
 return sum(1 for char in text.lower() if char in vowels)

print(StringUtils.is_palindrome("racecar")) # 输出 True
print(StringUtils.count_vowels("hello")) # 输出 2

总结

staticmethod 的作用：定义与类相关的独立方法，不依赖实例或类状态。
使用方法：通过 @staticmethod 装饰器声明，无需 self 或 cls。
适用场景：工具函数、数据处理、辅助功能等。
与其他方法的区别：普通方法操作实例，类方法操作类，静态方法独立运行。

pyserial-使用教程

Thu, 03 Apr 2025 10:15:25 +0800

基础教程

1. 安装 pyserial

首先，你需要安装 pyserial 库。可以通过 pip 安装：

pip install pyserial

2. 基本概念

串口通信（Serial Communication）是通过串行端口（如 USB 转串口设备、COM 端口等）进行数据传输的一种方式。常见用途包括与微控制器（如 Arduino）、传感器或其他硬件设备通信。

在 Python 中，pyserial 提供了一个简单的接口来操作串口。

3. 基础代码示例

以下是一个简单的示例，展示如何打开串口、发送数据和接收数据：

import serial
import time

# 配置串口参数
port = 'COM3' # Windows 示例，Linux/Mac 可能是 '/dev/ttyUSB0'
baudrate = 9600 # 波特率，根据设备设置
timeout = 1 # 读取超时时间（秒）

# 初始化串口
try:
 ser = serial.Serial(
 port=port,
 baudrate=baudrate,
 timeout=timeout
 )
 print(f"已连接到 {port}")
except serial.SerialException as e:
 print(f"连接失败: {e}")
 exit()

# 发送数据
message = "Hello, Serial!\n"
ser.write(message.encode('utf-8')) # 将字符串编码为字节并发送
print(f"已发送: {message.strip()}")

# 接收数据
time.sleep(1) # 等待一秒，确保有数据返回
if ser.in_waiting > 0: # 检查是否有数据在缓冲区
 data = ser.readline().decode('utf-8').strip() # 读取一行并解码
 print(f"收到: {data}")

# 关闭串口
ser.close()
print("串口已关闭")

4. 代码解释

serial.Serial(): 创建一个串口对象，参数包括端口号、波特率和超时时间。
port: 串口名称。Windows 上是 COMx（如 COM3），Linux/Mac 上是 /dev/ttyUSBx 或 /dev/ttySx。
baudrate: 数据传输速率，常见值有 9600、115200 等，需与设备一致。
timeout: 读取超时，避免程序无限等待。
write(): 发送数据，需将字符串编码为字节（如 encode('utf-8')）。
readline(): 读取一行数据（以换行符 \n 结束）。
in_waiting: 检查缓冲区是否有数据。

5. 如何找到串口号

在连接设备后，你需要知道设备的串口号。可以用以下代码列出所有可用串口：

import serial.tools.list_ports

ports = serial.tools.list_ports.comports()
for port in ports:
 print(f"端口: {port.device}, 描述: {port.description}")

运行后会显示类似：

端口: COM3, 描述: USB Serial Port (COM3)
端口: COM1, 描述: Communications Port (COM1)

根据描述选择正确的端口。

6. 常见问题与解决

端口被占用: 确保没有其他程序（如 Arduino IDE 的串口监视器）占用端口。
波特率不匹配: 确认波特率与设备一致。
无数据返回: 检查设备是否正确连接并发送数据。

7. 高级示例：持续读取数据

以下是一个循环读取串口数据的示例：

import serial
import time

ser = serial.Serial('COM3', 9600, timeout=1)

try:
 while True:
 if ser.in_waiting > 0:
 data = ser.readline().decode('utf-8').strip()
 print(f"收到: {data}")
 time.sleep(0.1) # 短暂休眠，避免占用过多 CPU
except KeyboardInterrupt:
 print("程序终止")
finally:
 ser.close()
 print("串口已关闭")

8. 与硬件交互示例（如 Arduino）

假设 Arduino 运行以下代码：

void setup() {
 Serial.begin(9600);
}

void loop() {
 if (Serial.available() > 0) {
 String msg = Serial.readString();
 Serial.println("收到: " + msg);
 }
}

Python 端可以这样与之交互：

import serial
import time

ser = serial.Serial('COM3', 9600, timeout=1)
time.sleep(2) # 等待 Arduino 重启

ser.write("Test\n".encode('utf-8'))
time.sleep(1)

if ser.in_waiting > 0:
 response = ser.readline().decode('utf-8').strip()
 print(response) # 输出: 收到: Test

ser.close()

9. 更多资源

官方文档: pyserial 文档
示例项目: 搜索 “Python serial Arduino” 可找到更多与硬件交互的案例。

代码实战

发送命令，随后接收数据，校验，重发

def set_current(port, current):
 """设置镀膜电流"""
 global_logger.info(f"开始设置镀膜电流 - 端口: {port}, 电流值: {current}")
 ready = SerialReader(port=port, baudrate=baudrate_global)
 command = f"CMD05,{current}\n"
 global_logger.info(f"发送设置电流命令: {command.strip()}")

 retry_count = 0
 max_retries = 2
 while retry_count <= max_retries:
 response = ready.send_command(command)
 start_time = time.time()
 while time.time() - start_time < 3:
 if response and response.strip() == "CMD05":
 global_logger.info(f"设置镀膜电流成功 - 响应: {response.strip()}")
 expected_response = f"CMD05,{current}"
 if expected_response.strip() in response.strip():
 global_logger.info("命令响应一致，设置成功")
 return True
 else:
 global_logger.warning(f"命令响应不一致 - 期望: {expected_response}, 实际: {response.strip()}")
 # 显示成功消息框
 messagebox.showinfo("命令响应不一致", f" 期望: {expected_response}, 实际: {response.strip()}")
 return False
 time.sleep(0.1)
 response = ready.read_data()
 retry_count += 1

 if retry_count > max_retries:
 global_logger.warning("设置镀膜电流失败 - 无响应")
 return False

Matlab-基本语法

Fri, 21 Mar 2025 14:37:58 +0800

MATLAB 基础语法教程

1. MATLAB 简介

MATLAB 是一种用于数值计算、可视化和编程的高级语言。它广泛应用于工程、科学和数学领域。MATLAB 的语法简单直观，适合初学者。

2. 基本操作

启动 MATLAB: 打开 MATLAB 软件后，你会看到命令窗口（Command Window），可以直接输入命令。

简单计算: MATLAB 可以像计算器一样使用。例如：

5 + 3 % 输出 8
10 * 2 % 输出 20
6 / 2 % 输出 3
2 ^ 3 % 输出 8（2的3次方）

分号（;）: 在命令末尾加分号可以抑制输出。例如：
```
a = 5; % 不会显示结果
b = 10 % 显示 b = 10
```

3. 变量

赋值: 使用 = 定义变量，无需声明类型。

x = 10; % 数字
name = '张三'; % 字符串（用单引号）

查看变量: 直接输入变量名即可显示其值。
```
x % 输出 10
```

清除变量:

clear x % 删除变量 x
clear all % 删除所有变量

4. 矩阵与数组

MATLAB 的核心是矩阵（Matrix Laboratory）。数组是 MATLAB 的基本数据结构。

向量:

row = [1 2 3]; % 行向量，用空格或逗号分隔
column = [1; 2; 3]; % 列向量，用分号分隔

矩阵:

A = [1 2 3; 4 5 6; 7 8 9]; % 3x3 矩阵

索引: 从 1 开始计数。

A(1, 2) % 输出第1行第2列的值，即 2
A(:, 2) % 输出第2列，即 [2; 5; 8]

5. 基本运算

元素级运算: 在运算符前加点号 . 表示逐元素操作。

a = [1 2 3];
b = [4 5 6];
a + b % 输出 [5 7 9]
a .* b % 逐元素相乘，输出 [4 10 18]
a .^ 2 % 逐元素平方，输出 [1 4 9]

矩阵运算:

A * B % 矩阵乘法（需维度匹配）
A' % 矩阵转置
inv(A) % 矩阵求逆

6. 控制流

if 语句:

x = 10;
if x > 0
 disp('x 是正数');
elseif x == 0
 disp('x 是零');
else
 disp('x 是负数');
end

for 循环:

for i = 1:5
 disp(i);
end
% 输出 1 2 3 4 5

while 循环:

x = 0;
while x < 5
 disp(x);
 x = x + 1;
end

7. 函数

内置函数: MATLAB 有许多内置函数。

sin(pi/2) % 输出 1
sqrt(16) % 输出 4
sum([1 2 3]) % 输出 6

自定义函数: 在新文件（如 myFunc.m）中定义。
```
function y = myFunc(x)
 y = x^2 + 3;
end
```
调用：myFunc(5) 输出 28。

8. 数据可视化

绘制简单图形:

x = 0:0.1:10; % 从 0 到 10，步长 0.1
y = sin(x);
plot(x, y); % 绘制正弦曲线
title('正弦函数');
xlabel('x');
ylabel('sin(x)');

多条曲线:

y2 = cos(x);
plot(x, y, 'b-', x, y2, 'r--'); % 蓝色实线和红色虚线
legend('sin(x)', 'cos(x)');

9. 常用命令

clc: 清除命令窗口。
clear: 清除变量。
who: 显示当前变量。
help 命令名: 查看命令帮助，例如 help plot。

小练习

创建一个 2x3 矩阵，并计算它的转置。
编写一个 for 循环，打印 1 到 10 的平方。
绘制一个简单的二次函数 y = x^2 的图形。

python-相对导入错误attempted relative import with no known parent package

Thu, 20 Mar 2025 11:46:30 +0800

下面是一个简洁的教程，旨在帮助读者理解并解决你在运行 arxiv.py 时遇到的 ImportError: attempted relative import with no known parent package 错误。这个教程将从问题背景开始，逐步分析原因，并提供多种解决方案。

教程：解决 Python 相对导入错误 - “attempted relative import with no known parent package”

背景

假设你有一个 Python 项目，目录结构如下：

Upick/
├── src/
│ ├── crawler/
│ │ ├── arxiv.py
│ │ └── base.py

在 arxiv.py 中，你尝试使用相对导入：

from .base import BaseCrawler

然后在命令行中运行：

python -u "c:\Users\zata\Desktop\UPick\src\crawler\arxiv.py"

结果却报错：

Traceback (most recent call last):
 File "c:\Users\zata\Desktop\UPick\src\crawler\arxiv.py", line 7, in <module>
 from .base import BaseCrawler
ImportError: attempted relative import with no known parent package

这个错误困扰了许多 Python 开发者。本教程将解释其原因并提供解决方案。

问题原因

在 Python 中，相对导入（例如 from .base import BaseCrawler）依赖于包结构。当你直接运行一个 .py 文件（例如 python arxiv.py），Python 会将其视为独立脚本，而不是包的一部分。这时，相对导入无法解析，因为 Python 不知道当前文件所属的包。

在这个例子中：

arxiv.py 使用 .base 表示从同一目录（crawler）导入 base.py。
但直接运行 arxiv.py 时，Python 不认为 crawler 是一个包，因此无法找到 .base。

前置条件

要解决这个问题，确保你的项目满足以下条件：

base.py 存在于 crawler 目录下，并且定义了 BaseCrawler 类。
你希望保持模块化的代码结构，而不是硬编码绝对路径。

解决方案

方法 1：以模块方式运行 (推荐)

Python 提供了 -m 参数，允许你以模块方式运行脚本，这样可以正确解析包结构。

步骤：

添加包标志文件
确保 crawler 目录下有一个空的 __init__.py 文件。这是 Python 识别包的标志。更新后的结构：

Upick/
├── src/
│ ├── crawler/
│ │ ├── __init__.py
│ │ ├── arxiv.py
│ │ └── base.py

切换到项目根目录
在命令行中进入 Upick 目录：
```
cd C:\Users\zata\Desktop\Upick
```
运行模块
使用以下命令运行：
```
python -m src.crawler.arxiv
```
-m 表示将 src.crawler.arxiv 作为模块运行，而不是直接运行文件。

为什么有效？

以模块方式运行时，Python 会从 Upick 开始解析包结构，识别 src 和 crawler 作为包，因此相对导入 from .base import BaseCrawler 可以正常工作。

方法 2：调整 PYTHONPATH

如果你希望直接运行文件，可以通过设置 PYTHONPATH 来告诉 Python 包的根目录。

步骤：

设置 PYTHONPATH
将 PYTHONPATH 设置为包含 src 的父目录：
```
set PYTHONPATH=C:\Users\zata\Desktop\Upick\src
```

运行文件
在命令行中运行：

python -u "c:\Users\zata\Desktop\UPick\src\crawler\arxiv.py"

注意：

仍然需要在 crawler 目录下有 __init__.py 文件。
这种方法不如方法 1 优雅，因为它依赖于环境变量。

方法 3：改为绝对导入

如果你不想依赖包结构，可以将相对导入改为绝对导入。

步骤：

修改导入语句
编辑 arxiv.py，将：

from .base import BaseCrawler

改为：

from src.crawler.base import BaseCrawler

设置 PYTHONPATH
在命令行中运行：

set PYTHONPATH=C:\Users\zata\Desktop\Upick
python -u "c:\Users\zata\Desktop\UPick\src\crawler\arxiv.py"

优点与缺点：

优点：无需依赖包结构和 __init__.py。
缺点：代码中硬编码了路径，移植性较差。

方法 4：检查文件和结构

有时问题出在文件本身。确保以下几点：

base.py 存在于 crawler 目录下。

base.py 中正确定义了 BaseCrawler 类，例如：

# base.py
class BaseCrawler:
 def __init__(self):
 print("BaseCrawler initialized")

crawler 目录下有 __init__.py。

测试与验证

运行后，如果没有错误，arxiv.py 将成功导入 BaseCrawler 并执行后续逻辑。如果仍有问题，可以检查：

是否遗漏了 __init__.py。
base.py 中的类名是否拼写正确。

总结

Python 的相对导入依赖于包结构，直接运行脚本会导致 ImportError。通过以模块方式运行（python -m）、调整 PYTHONPATH 或改为绝对导入，你可以轻松解决问题。根据项目需求选择适合的方法，但通常以模块方式运行是最优解。

python-应如何定义包通用的变量-推荐config.py

Wed, 19 Mar 2025 11:27:34 +0800

可以解决循环调用error的问题

在一个项目中定义包通用的变量（即在整个包或模块间共享的全局变量），需要考虑代码的组织结构、可维护性和避免命名冲突。以下是几种常见的方法，适用于 Python（假设你用的是 Python）

方法 1：使用配置文件模块

这是最推荐的方式，适合定义包通用的变量。将所有全局变量集中在一个独立的模块中，然后在需要的地方导入使用。

示例

项目结构：

project/
├── src/
│ ├── __init__.py
│ ├── config.py
│ ├── main.py
│ └── utils.py
├── db/
│ └── mydatabase.db

定义 config.py：

# src/config.py
from pathlib import Path

# 项目根目录
BASE_DIR = Path(__file__).resolve().parent.parent

# 通用变量
DB_PATH = BASE_DIR / "db" / "mydatabase.db"
API_KEY = "your-api-key"
DEBUG_MODE = True
MAX_RETRIES = 5

在其他模块中使用：

# src/main.py
from config import DB_PATH, DEBUG_MODE

import sqlite3

def main():
 conn = sqlite3.connect(DB_PATH)
 if DEBUG_MODE:
 print(f"连接到数据库: {DB_PATH}")
 # 其他逻辑

if __name__ == "__main__":
 main()

在包的其他文件使用：

# src/utils.py
from config import MAX_RETRIES

def retry_operation():
 for _ in range(MAX_RETRIES):
 print("尝试操作...")

优点：

变量集中管理，易于修改。
导入明确，避免命名冲突。
适合大型项目。

方法 2：定义在包的 `init.py` 中

如果你想让变量直接绑定到包的命名空间，可以在包的 __init__.py 中定义。

示例

项目结构：

project/
├── src/
│ ├── __init__.py
│ ├── main.py
│ └── utils.py

编辑 src/__init__.py：

# src/__init__.py
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent
DB_PATH = BASE_DIR / "db" / "mydatabase.db"
API_KEY = "your-api-key"

使用时直接从包导入：

# src/main.py
from src import DB_PATH

import sqlite3

conn = sqlite3.connect(DB_PATH)
print(f"数据库路径: {DB_PATH}")

优点：

变量直接绑定到包，访问方便。
适合小型包。

缺点：

__init__.py 可能会变得臃肿，不适合定义大量变量或复杂逻辑。

方法 3：使用类封装全局变量

如果你希望变量有更好的封装性，可以用一个类来管理全局变量。

示例

# src/config.py
from pathlib import Path

class Config:
 BASE_DIR = Path(__file__).resolve().parent.parent
 DB_PATH = BASE_DIR / "db" / "mydatabase.db"
 API_KEY = "your-api-key"
 DEBUG_MODE = True

# src/main.py
from config import Config
import sqlite3

conn = sqlite3.connect(Config.DB_PATH)
if Config.DEBUG_MODE:
 print(f"连接到: {Config.DB_PATH}")

优点：

变量有命名空间（Config.），避免冲突。
可以添加方法动态修改变量（如果需要）。
适合需要组织性和扩展性的项目。

方法 4：使用环境变量（适用于敏感信息）

对于一些敏感或需要动态配置的变量（如数据库路径、API 密钥），可以结合环境变量管理。

示例

使用 python-dotenv 加载 .env 文件：

project/
├── .env
├── src/
│ ├── __init__.py
│ ├── config.py
│ └── main.py

创建 .env 文件：

DB_NAME=mydatabase.db
API_KEY=your-api-key
DEBUG_MODE=true

定义 config.py：

# src/config.py
from pathlib import Path
import os
from dotenv import load_dotenv

load_dotenv() # 加载 .env 文件

BASE_DIR = Path(__file__).resolve().parent.parent
DB_PATH = BASE_DIR / "db" / os.getenv("DB_NAME")
API_KEY = os.getenv("API_KEY")
DEBUG_MODE = os.getenv("DEBUG_MODE", "false").lower() == "true"

使用：

# src/main.py
from config import DB_PATH, API_KEY
import sqlite3

conn = sqlite3.connect(DB_PATH)
print(f"使用 API Key: {API_KEY}")

优点：

敏感信息不硬编码，安全性更高。
便于在不同环境（开发、生产）中切换配置。

注意：

需要安装 python-dotenv：pip install python-dotenv。
.env 文件不要提交到版本控制（如 Git），可以用 .gitignore 忽略。

选择建议

小型项目：用方法 1（独立 config.py）或方法 2（__init__.py）。
中大型项目：用方法 1 或方法 3（类封装），结构更清晰。
涉及敏感信息或部署：用方法 4（环境变量），结合方法 1。

额外注意

避免真正的全局变量：不要在模块顶层直接修改变量（如 global 关键字），容易导致意外副作用。
常量命名：通用变量通常用大写字母（如 DB_PATH），表示它们是常量。
文档化：在定义变量时加注释，说明用途。

如果你有具体的项目结构或语言要求（比如不是 Python），告诉我，我可以进一步优化方案！

python-在项目中应该如何定义文件路径

Wed, 19 Mar 2025 10:57:57 +0800

虽然也是老生常态的事情了，无论是把代码打包成exe还是在多平台的迁移上，经常会涉及到这个问题，原本我以为我已经不会再犯错了，没想到今天还是又犯错了，算是给自己提一个醒吧。

具体描述一下遇到了什么问题：

我写了一个项目，在项目中，我使用了绝对路径定义了一个sqlite数据库，如下：

在windows平台上运行没有问题，然后放到Linux上，重要的是！！！它也不报错，然后我部署好之后我也没有看文件路径，心想没有报错能有什么事情，然后第二天发现没有按照原本方式执行，这时候就感觉有问题了，然后进入docker一看，生成了这么一个文件：

笑死了….

如何在python中定义文件路径

在项目中定义文件路径时，尤其是涉及到像 SQLite 数据库这样的资源，关键是要确保路径的可移植性和可靠性。以下是一些建议和操作步骤，帮助你在项目中合理定义和管理文件路径：

1. 理解相对路径和绝对路径

绝对路径：从文件系统的根目录开始，例如 /home/user/project/db/mydatabase.db（Linux/Mac）或 C:\Users\user\project\db\mydatabase.db（Windows）。这种方式依赖具体的文件系统结构，不利于跨平台或项目迁移。
相对路径：相对于当前工作目录或项目根目录，例如 ./db/mydatabase.db。这种方式更灵活，推荐在项目中使用。

为了让项目更健壮，建议使用相对路径，并结合编程语言提供的工具动态生成路径。

2. SQLite 数据库路径的定义方法

假设你的项目结构如下：

project/
├── src/
│ └── main.py
├── db/
│ └── mydatabase.db
└── README.md

Python 示例

在 Python 中，可以使用 os 或 pathlib 模块来动态构建路径，确保跨平台兼容：

import os
from pathlib import Path

# 方法 1：使用 os 模块
BASE_DIR = os.path.dirname(os.path.abspath(__file__)) # 获取当前脚本所在目录
DB_PATH = os.path.join(BASE_DIR, "..", "db", "mydatabase.db") # 构建数据库路径
DB_PATH = os.path.normpath(DB_PATH) # 规范化路径，处理斜杠差异

# 方法 2：使用 pathlib（更现代的方式）
BASE_DIR = Path(__file__).resolve().parent # 当前脚本目录
DB_PATH = BASE_DIR / ".." / "db" / "mydatabase.db" # 使用 / 拼接路径

# 连接 SQLite 数据库
import sqlite3
conn = sqlite3.connect(DB_PATH)
print(f"数据库路径: {DB_PATH}")

__file__：表示当前脚本的文件路径。
os.path.abspath 或 Path.resolve()：将路径转换为绝对路径，避免相对路径的歧义。
os.path.join 或 Path 的 / 操作符：跨平台拼接路径，自动处理 Windows 和 Unix 的斜杠差异。

3. 最佳实践

a. 将路径定义为配置

将文件路径集中管理，避免硬编码。例如：

# config.py
from pathlib import Path
BASE_DIR = Path(__file__).resolve().parent.parent # 项目根目录
DB_PATH = BASE_DIR / "db" / "mydatabase.db"

# main.py
from config import DB_PATH
import sqlite3
conn = sqlite3.connect(DB_PATH)

b. 检查文件是否存在

在连接数据库前，确保文件存在：

if not DB_PATH.exists():
 raise FileNotFoundError(f"数据库文件不存在: {DB_PATH}")
conn = sqlite3.connect(DB_PATH)

c. 考虑打包或部署

如果项目会被打包（如用 PyInstaller），相对路径可能失效。可以用以下方式动态检测：

import sys
if getattr(sys, 'frozen', False): # 如果是打包后的可执行文件
 BASE_DIR = Path(sys.executable).parent
else:
 BASE_DIR = Path(__file__).resolve().parent.parent
DB_PATH = BASE_DIR / "db" / "mydatabase.db"

d. 数据库初始化

如果数据库文件不存在，可以在代码中创建：

if not DB_PATH.exists():
 conn = sqlite3.connect(DB_PATH) # 创建空数据库
 # 这里可以添加表结构初始化代码
else:
 conn = sqlite3.connect(DB_PATH)

4. 注意事项

权限问题：确保程序对目标路径有读写权限，尤其是部署到服务器时。
跨平台兼容：始终使用 os.path.join 或 pathlib 处理路径，避免手动写斜杠。
安全性：不要将数据库放在公开访问的目录（如 web 服务器的根目录），建议放在项目专用目录中。

5. 总结

对于你的 SQLite 数据库，推荐的做法是：

将数据库放在项目目录的子文件夹中（如 db/mydatabase.db）。
使用 pathlib 或 os 动态构建路径，基于项目根目录。
将路径定义在配置文件中，方便维护。
在代码中检查文件是否存在并处理异常。

python中将函数设置为定时任务

Tue, 18 Mar 2025 15:59:11 +0800

将函数设置为定时任务有几种方法。以下是几种常用的实现方案：

方案1：使用Python的schedule库

这是一个在Python应用程序内部实现的轻量级定时任务方案：

import schedule
import time
import threading
from src.db import refresh_content

def run_scheduler():
 """启动定时任务调度器"""
 # 每小时执行一次刷新
 schedule.every(1).hour.do(refresh_content)

 # 也可以设置特定时间执行，例如每天凌晨2点
 # schedule.every().day.at("02:00").do(refresh_content)

 while True:
 schedule.run_pending()
 time.sleep(60) # 每分钟检查一次是否有待执行的任务

# 在单独的线程中运行调度器，这样不会阻塞主应用
def start_scheduler_thread():
 scheduler_thread = threading.Thread(target=run_scheduler)
 scheduler_thread.daemon = True # 设置为守护线程，这样主程序退出时线程也会退出
 scheduler_thread.start()

将此代码添加到应用程序启动过程中：

if __name__ == "__main__":
 # 启动定时任务
 start_scheduler_thread()

 # 启动主应用（例如Gradio界面）
 app.launch()

方案2：使用APScheduler库

APScheduler是一个更强大的Python调度库，支持持久化任务和多种调度器后端：

from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.triggers.interval import IntervalTrigger
from src.db import refresh_content

def setup_scheduler():
 """设置并启动APScheduler调度器"""
 scheduler = BackgroundScheduler()

 # 添加刷新任务，每小时执行一次
 scheduler.add_job(
 func=refresh_content,
 trigger=IntervalTrigger(hours=1),
 id='refresh_content_job',
 name='刷新订阅内容',
 replace_existing=True
 )

 # 启动调度器
 scheduler.start()
 return scheduler

在主应用中集成：

if __name__ == "__main__":
 # 启动定时任务调度器
 scheduler = setup_scheduler()

 # 启动主应用
 try:
 app.launch()
 finally:
 # 在应用关闭时优雅地关闭调度器
 scheduler.shutdown()

方案3：使用系统级定时任务

Linux/Mac上使用cron

创建一个独立的Python脚本，例如refresh_subscriptions.py：

#!/usr/bin/env python3
# refresh_subscriptions.py
from src.db import refresh_content

if __name__ == "__main__":
 result = refresh_content()
 print(result)

使用crontab设置定时任务：

# 编辑crontab
crontab -e

# 添加以下行，每小时执行一次
0 * * * * /path/to/python /path/to/refresh_subscriptions.py >> /path/to/logs/refresh.log 2>&1

Windows上使用任务计划程序

创建类似的Python脚本
打开任务计划程序，创建基本任务
设置触发器为每小时执行一次
操作设置为运行Python解释器，参数为脚本路径

方案4：使用Celery（对于大型应用）

如果你的应用较大，可以考虑使用Celery：

# 设置Celery
from celery import Celery
from celery.schedules import crontab

app = Celery('subscription_manager', broker='redis://localhost:6379/0')

# 配置定时任务
app.conf.beat_schedule = {
 'refresh-content-hourly': {
 'task': 'tasks.refresh_content_task',
 'schedule': crontab(minute=0, hour='*'), # 每小时整点执行
 },
}

# 定义任务
@app.task
def refresh_content_task():
 from src.db import refresh_content
 return refresh_content()

实现建议

对于简单部署：使用方案1或方案2，将定时任务集成到主应用中
对于生产环境：使用方案3，将刷新任务与Web应用分离，降低相互影响
对于高负载场景：使用方案4，实现任务队列和分布式处理

python-logging模块添加日志

Tue, 18 Mar 2025 14:30:39 +0800

在 Python 项目中添加日志功能是一个很好的实践，可以帮助你跟踪程序运行状态、调试问题以及记录重要事件。对于一个包含多个文件且存在调用关系的项目，可以通过以下步骤实现日志功能：

基本概念

1. 使用 Python 的 `logging` 模块

Python 内置的 logging 模块非常强大且灵活，适合在多文件项目中使用。相比 print，它提供了日志级别（如 DEBUG、INFO、ERROR 等）、格式化输出、文件记录等功能。

2. 基本实现步骤

以下是一个在多文件项目中添加日志的通用方法：

(1) 创建一个日志配置模块

在一个单独的文件（例如 logger.py）中配置日志，这样可以全局复用。

# logger.py
import logging
import os

# 创建日志器
logger = logging.getLogger('MyProject')
logger.setLevel(logging.DEBUG) # 设置全局日志级别

# 创建日志处理器（输出到控制台）
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO) # 控制台显示 INFO 及以上级别

# 创建日志处理器（输出到文件）
log_dir = "logs"
if not os.path.exists(log_dir):
 os.makedirs(log_dir)
file_handler = logging.FileHandler(os.path.join(log_dir, "app.log"), encoding="utf-8")
file_handler.setLevel(logging.DEBUG) # 文件记录 DEBUG 及以上级别

# 设置日志格式
formatter = logging.Formatter(
 "%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s"
)
console_handler.setFormatter(formatter)
file_handler.setFormatter(formatter)

# 将处理器添加到日志器
logger.addHandler(console_handler)
logger.addHandler(file_handler)

# 提供获取日志器的方法
def get_logger(name):
 return logging.getLogger(f"MyProject.{name}")

这个配置：

将日志同时输出到控制台和文件。
文件日志记录所有级别（DEBUG 及以上），控制台只显示 INFO 及以上。
日志格式包括时间、模块名、级别、文件名、行号和消息。

(2) 在其他文件中使用日志

在项目中的各个文件里，通过 logger.py 获取日志器并使用。

例如，假设你有两个文件 module1.py 和 module2.py，它们之间有调用关系：

# module1.py
from logger import get_logger

logger = get_logger("module1")

def func1():
 logger.debug("正在执行 func1")
 logger.info("func1 开始调用 func2")
 from module2 import func2
 func2()
 logger.info("func1 执行完成")

# module2.py
from logger import get_logger

logger = get_logger("module2")

def func2():
 logger.debug("正在执行 func2")
 logger.warning("func2 中可能有潜在问题")
 logger.info("func2 执行完成")

(3) 主程序入口

在主程序中调用这些模块：

# main.py
from logger import get_logger
from module1 import func1

logger = get_logger("main")

if __name__ == "__main__":
 logger.info("程序启动")
 func1()
 logger.info("程序结束")

运行后，日志会同时输出到控制台和 logs/app.log 文件中。文件中的日志可能如下：

2025-03-17 10:00:00,123 - MyProject.main - INFO - main.py:7 - 程序启动
2025-03-17 10:00:00,125 - MyProject.module1 - DEBUG - module1.py:5 - 正在执行 func1
2025-03-17 10:00:00,126 - MyProject.module1 - INFO - module1.py:6 - func1 开始调用 func2
2025-03-17 10:00:00,127 - MyProject.module2 - DEBUG - module2.py:5 - 正在执行 func2
2025-03-17 10:00:00,128 - MyProject.module2 - WARNING - module2.py:6 - func2 中可能有潜在问题
2025-03-17 10:00:00,129 - MyProject.module2 - INFO - module2.py:7 - func2 执行完成
2025-03-17 10:00:00,130 - MyProject.module1 - INFO - module1.py:8 - func1 执行完成
2025-03-17 10:00:00,131 - MyProject.main - INFO - main.py:9 - 程序结束

控制台只会显示 INFO 及以上级别的日志。

3. 高级配置（可选）

如果项目较大或需求更复杂，可以考虑以下优化：

(1) 使用配置文件

将日志配置写入一个配置文件（例如 logging_config.ini），然后通过 logging.config 加载：

# logging_config.ini
[loggers]
keys=root

[handlers]
keys=consoleHandler,fileHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler,fileHandler

[handler_consoleHandler]
class=StreamHandler
level=INFO
formatter=simpleFormatter
args=(sys.stdout,)

[handler_fileHandler]
class=FileHandler
level=DEBUG
formatter=simpleFormatter
args=('logs/app.log', 'a', 'utf-8')

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s

在 logger.py 中加载：

# logger.py
import logging.config

logging.config.fileConfig("logging_config.ini")
logger = logging.getLogger("MyProject")

def get_logger(name):
 return logging.getLogger(f"MyProject.{name}")

(2) 日志按时间分割

使用 logging.handlers.TimedRotatingFileHandler 实现日志按时间（例如每天）分割：

# logger.py
from logging.handlers import TimedRotatingFileHandler

file_handler = TimedRotatingFileHandler(
 "logs/app.log", when="midnight", interval=1, backupCount=7, encoding="utf-8"
)
file_handler.setLevel(logging.DEBUG)

这会每天生成一个新日志文件，并保留最近 7 天的日志。

(3) 避免重复日志

如果模块被多次导入，确保日志处理器不会重复添加。可以在 logger.py 中添加检查：

if not logger.handlers:
 logger.addHandler(console_handler)
 logger.addHandler(file_handler)

4. 注意事项

日志级别：合理选择日志级别（DEBUG 用于调试，INFO 用于常规信息，WARNING 用于警告，ERROR 用于错误）。
性能：日志过多可能影响性能，建议在生产环境中调整日志级别（例如只记录 INFO 以上）。
模块化：通过 get_logger("模块名") 为每个模块创建独立的日志器，便于追踪调用关系。

5. 总结

通过以上方法，你可以在多文件 Python 项目中实现统一的日志管理。推荐从简单的 logger.py 开始，随着项目需求增加再逐步优化配置。

在 Python 的 logging 模块中，日志级别是用来区分日志消息重要性的一种机制。不同的级别对应不同的使用场景，帮助开发者或运维人员快速筛选和定位信息。logging 模块内置了以下几种标准日志级别，从低到高排列：

日志级别划分

以下是 Python logging 模块的标准日志级别及其数值（数值越大，级别越高）：

级别	数值	描述
`NOTSET`	0	未设置，默认级别，通常不直接使用。
`DEBUG`	10	调试信息，通常用于开发和调试阶段，记录详细的程序运行细节。
`INFO`	20	常规信息，用于确认程序按预期运行，记录关键步骤或状态。
`WARNING`	30	警告信息，表示可能存在问题，但程序仍能继续运行（默认级别）。
`ERROR`	40	错误信息，表示发生了较严重的问题，某些功能可能无法正常执行。
`CRITICAL`	50	严重错误信息，表示程序遇到致命问题，可能无法继续运行。

各日志级别的使用场景

DEBUG（调试）
- 用途：记录详细的调试信息，例如变量值、函数调用栈、循环迭代等。
- 场景：开发和测试阶段，用于排查问题。
- 示例：
```
logger.debug("变量 x 的值: %s", x)
```
INFO（信息）
- 用途：记录程序正常运行时的关键信息，例如启动、结束、重要步骤完成。
- 场景：生产环境中确认程序正常运行。
- 示例：
```
logger.info("服务器启动成功，监听端口: 8080")
```
WARNING（警告）
- 用途：记录潜在问题或非预期情况，但不影响程序继续运行。
- 场景：提醒开发者或用户注意某些异常情况。
- 示例：
```
logger.warning("配置文件未找到，使用默认设置")
```
ERROR（错误）
- 用途：记录发生的错误，通常会导致某些功能失效。
- 场景：生产环境中记录需要修复的问题。
- 示例：
```
logger.error("数据库连接失败: %s", exception_message)
```
CRITICAL（严重）
- 用途：记录致命错误，通常会导致程序崩溃或无法继续运行。
- 场景：需要立即关注和处理的问题。
- 示例：
```
logger.critical("系统内存不足，程序即将退出")
```

日志级别的工作机制

日志器的级别：通过 logger.setLevel() 设置，只有大于等于该级别的日志才会记录。
- 例如，如果设置为 INFO，则 DEBUG 日志不会输出，但 INFO、WARNING、ERROR 和 CRITICAL 会输出。
处理器的级别：每个处理器（如 StreamHandler、FileHandler）也可以单独设置级别，决定输出哪些日志。
- 例如，控制台只显示 INFO 及以上，文件记录 DEBUG 及以上。

示例代码

import logging

# 创建日志器
logger = logging.getLogger("example")
logger.setLevel(logging.DEBUG) # 日志器记录所有级别

# 创建控制台处理器，只显示 INFO 及以上
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)
console_handler.setFormatter(logging.Formatter("%(levelname)s - %(message)s"))
logger.addHandler(console_handler)

# 创建文件处理器，记录 DEBUG 及以上
file_handler = logging.FileHandler("example.log", encoding="utf-8")
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(logging.Formatter("%(asctime)s - %(levelname)s - %(message)s"))
logger.addHandler(file_handler)

# 测试不同级别日志
logger.debug("这是一个调试信息")
logger.info("这是一个常规信息")
logger.warning("这是一个警告信息")
logger.error("这是一个错误信息")
logger.critical("这是一个严重错误信息")

输出结果：

控制台（只显示 INFO 及以上）：

INFO - 这是一个常规信息
WARNING - 这是一个警告信息
ERROR - 这是一个错误信息
CRITICAL - 这是一个严重错误信息

文件 example.log（记录 DEBUG 及以上）：

2025-03-17 10:00:00,123 - DEBUG - 这是一个调试信息
2025-03-17 10:00:00,124 - INFO - 这是一个常规信息
2025-03-17 10:00:00,125 - WARNING - 这是一个警告信息
2025-03-17 10:00:00,126 - ERROR - 这是一个错误信息
2025-03-17 10:00:00,127 - CRITICAL - 这是一个严重错误信息

如何选择日志级别

开发阶段：多用 DEBUG 和 INFO，方便调试。
生产环境：通常设置为 INFO 或 WARNING，避免过多调试信息影响性能。
异常处理：用 ERROR 或 CRITICAL 记录错误，并结合异常堆栈（如 logger.exception()）。

自定义日志级别（可选）

如果内置级别不够用，可以通过 logging.addLevelName() 定义新级别：

logging.addLevelName(15, "VERBOSE")
logger.setLevel(15)
logger.log(15, "这是一个自定义VERBOSE信息")

Python-Docstring 的详细教程

Tue, 18 Mar 2025 11:52:29 +0800

下面是一个关于 Python 中 Docstring 的详细教程，涵盖其定义、作用、格式、常见风格、最佳实践以及如何与工具（如 Sphinx）结合生成文档。我会尽量全面且清晰地讲解。

什么是 Docstring？

Docstring 是 Python 中的文档字符串（Documentation String），用于为模块、类、函数或方法提供说明。它是一个特殊的字符串，通常写在定义的开头，用三引号 (""" 或 ''') 包裹。Docstring 的主要作用是：

文档化代码：为开发者提供函数或类的使用说明。
自动化工具支持：如 Sphinx、pydoc 等工具可以提取 Docstring 生成 API 文档。
运行时访问：通过 __doc__ 属性访问，例如 print(function.__doc__)。

示例：

def add(a, b):
 """Add two numbers together."""
 return a + b

print(add.__doc__) # 输出: Add two numbers together.

Docstring 的基本规则

根据 Python 的官方规范 PEP 257，Docstring 有以下基本要求：

位置：必须是模块、类、函数定义的第一行语句。
格式：使用三引号（"""），支持多行。
内容：
- 单行 Docstring：简短描述，直接写在一行。
- 多行 Docstring：第一行是摘要，空一行，后续行是详细说明。
缩进：与代码块对齐。

单行示例：

def square(n):
 """Return the square of a number."""
 return n * n

多行示例：

def divide(a, b):
 """Divide two numbers and return the result.

 This function performs division and handles division by zero.
 """
 return a / b

Docstring 的常见风格

不同的项目可能采用不同的 Docstring 风格，以下是三种主流风格的详细说明：

1. reStructuredText (reST) 风格

特点：Sphinx 默认支持，常用于生成专业文档。
字段：使用 :param、:return: 等标记。
语法：基于 reST 标记语言，支持复杂格式。

示例：

def multiply(a, b):
 """Multiply two numbers.

 :param float a: The first number to multiply.
 :param float b: The second number to multiply.
 :return: The product of a and b.
 :rtype: float
 :raises TypeError: If inputs are not numbers.
 """
 return a * b

字段说明：

:param <type> <name>:：描述参数类型和作用。
:return:：描述返回值。
:rtype:：返回值类型。
:raises <exception>:：可能抛出的异常。

2. Google 风格（推荐）

特点：简洁直观，易读，需 Sphinx 的 napoleon 插件支持。
字段：使用 Args:、Returns: 等标题。

示例：

def subtract(a, b):
 """Subtract b from a.

 Args:
 a (float): The number to subtract from.
 b (float): The number to subtract.

 Returns:
 float: The difference between a and b.

 Raises:
 TypeError: If inputs are not numbers.
 """
 return a - b

字段说明：

Args:：列出参数，格式为 name (type): description。
Returns:：返回值描述，可附带类型。
Raises:：异常描述。

3. Numpy 风格

特点：结构化强，字段用横线分隔，适合科学计算项目。
字段：使用 Parameters、Returns 等。

示例：

def power(base, exponent):
 """Raise base to the power of exponent.

 Parameters
 ----------
 base : float
 The base number.
 exponent : int
 The exponent to raise the base to.

 Returns
 -------
 float
 The result of base raised to exponent.

 Raises
 ------
 ValueError
 If exponent is negative.
 """
 return base ** exponent

字段说明：

Parameters：参数列表，每个参数占一行，类型和描述分行。
Returns：返回值描述。
Raises：异常描述。

Docstring 的最佳实践

简洁但完整：
- 第一行是简短的摘要（通常不超过一句话）。
- 详细说明放在后续段落，避免冗长。
描述所有公共接口：
- 为所有对外暴露的模块、类、函数写 Docstring。
- 私有函数（以 _ 开头）可选择性添加。
参数和返回值：
- 列出所有参数的类型、作用，默认值（如有）。
- 说明返回值的类型和含义。
异常处理：
- 如果函数可能抛出异常，必须在 Docstring 中说明。
一致性：
- 项目中统一使用一种风格（如 Google 风格），避免混用。
与类型提示结合：
- Python 3.5+ 支持类型提示（Type Hints），可以减少 Docstring 中类型描述的重复。

类型提示示例：

def greet(name: str) -> str:
 """Greet a person.

 Args:
 name: The name of the person.

 Returns:
 A greeting message.
 """
 return f"Hello, {name}!"

如何使用 Docstring 生成文档？

1. 使用内置工具 pydoc

Python 自带的 pydoc 可以直接生成简单的文档：

python -m pydoc your_module

或生成 HTML：

python -m pydoc -w your_module

2. 使用 Sphinx（推荐）

链接
sphinx使用

Sphinx 是生成专业文档的首选工具，尤其是结合 autodoc 扩展。

步骤：

安装 Sphinx：
```
pip install sphinx
```
初始化文档：
```
mkdir docs
cd docs
sphinx-quickstart
```
按提示配置，生成 conf.py 和 index.rst。

启用扩展：在 conf.py 中添加：

extensions = ['sphinx.ext.autodoc']
sys.path.insert(0, os.path.abspath('../src')) # 代码路径

如果使用 Google/Numpy 风格，添加：

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

编写 .rst 文件：在 index.rst 中添加：

.. automodule:: your_module
 :members:
 :undoc-members:

生成文档：
```
make html # 或 make.bat html（Windows）
```
打开 docs/_build/html/index.html 查看结果。

常见问题与解答

Q1：Docstring 和注释有什么区别？

Docstring：用于文档化，写在定义开头，可被工具提取。
注释：用 # 写在代码中，仅供开发者阅读，不生成文档。

Q2：没有 Docstring 会怎样？

工具（如 Sphinx）只会提取函数签名，文档内容为空，影响可读性。

Q3：如何选择风格？

小型项目：Google 风格（简单易读）。
大型项目或开源：reST（Sphinx 默认）或 Numpy（科学项目）。
团队协作：与团队约定一致。

完整示例

以下是一个综合示例，展示不同风格的 Docstring：

# 文件: math_utils.py
def calculate(a: float, b: float, operation: str = "add") -> float:
 """Perform a mathematical operation on two numbers.

 Google Style:
 Args:
 a (float): The first number.
 b (float): The second number.
 operation (str, optional): The operation to perform. Defaults to "add".

 Returns:
 float: The result of the operation.

 Raises:
 ValueError: If operation is not supported.

 Numpy Style:
 Parameters
 ----------
 a : float
 The first number.
 b : float
 The second number.
 operation : str, optional
 The operation to perform. Defaults to "add".

 Returns
 -------
 float
 The result of the operation.

 Raises
 ------
 ValueError
 If operation is not supported.
 """
 if operation == "add":
 return a + b
 elif operation == "multiply":
 return a * b
 else:
 raise ValueError("Unsupported operation")

运行 Sphinx 后，生成的文档会根据配置解析 Google 或 Numpy 风格。

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() 则提供装饰性标题。

python-数据类

Sat, 15 Mar 2025 20:43:43 +0800

在 Python 中，数据类（Data Classes）是通过 dataclasses 模块实现的，它在 Python 3.7+ 中引入。数据类是一种简洁的方式，用于创建主要用于存储数据的类，自动生成诸如 __init__、__repr__、__eq__ 等特殊方法。结合 typing 模块，数据类可以更优雅地定义类型安全的结构体。

以下是关于数据类的使用教程：

1. 基本概念

数据类通过装饰器 @dataclass 定义，减少样板代码。你只需要声明字段和类型，Python 会自动为你生成构造器和其他方法。

from dataclasses import dataclass

@dataclass
class Person:
 name: str
 age: int
 height: float

# 创建实例
p = Person("Alice", 25, 1.75)
print(p) # 输出: Person(name='Alice', age=25, height=1.75)

name: str 表示字段 name 是字符串类型。
@dataclass 自动生成 __init__，所以你可以直接传入参数创建对象。

2. 导入和基本用法

需要从 dataclasses 模块导入 dataclass：

from dataclasses import dataclass

@dataclass
class Point:
 x: int
 y: int

p1 = Point(1, 2)
p2 = Point(1, 2)
print(p1) # 输出: Point(x=1, y=2)
print(p1 == p2) # 输出: True（自动生成 __eq__）

3. 默认值

你可以为字段指定默认值：

@dataclass
class Student:
 name: str
 id: int = 0 # 默认值
 grade: str = "A"

s = Student("Bob")
print(s) # 输出: Student(name='Bob', id=0, grade='A')

注意：带默认值的字段必须放在没有默认值的字段后面（与普通函数参数规则一致）。

4. 与 `typing` 结合

数据类可以与 typing 模块结合，支持复杂类型。

(1) 使用容器类型

from dataclasses import dataclass
from typing import List, Dict, Optional

@dataclass
class Team:
 name: str
 members: List[str]
 scores: Dict[str, int]
 leader: Optional[str] = None

t = Team("Alpha", ["Alice", "Bob"], {"Alice": 90, "Bob": 85})
print(t) # 输出: Team(name='Alpha', members=['Alice', 'Bob'], scores={'Alice': 90, 'Bob': 85}, leader=None)

(2) 使用 Union 或其他类型

from typing import Union

@dataclass
class Product:
 id: Union[int, str]
 price: float

p = Product("ABC123", 19.99)
print(p) # 输出: Product(id='ABC123', price=19.99)

5. 不可变数据类

通过设置 frozen=True，可以创建不可变（immutable）的数据类，防止字段被修改。

@dataclass(frozen=True)
class ImmutablePoint:
 x: int
 y: int

p = ImmutablePoint(1, 2)
# p.x = 3 # 会抛出 FrozenInstanceError

6. 自定义行为

(1) 添加方法

数据类仍然是普通的类，你可以添加自定义方法：

@dataclass
class Rectangle:
 width: float
 height: float

 def area(self) -> float:
 return self.width * self.height

r = Rectangle(3.0, 4.0)
print(r.area()) # 输出: 12.0

(2) 自定义 `__post_init__`

如果需要在初始化后执行额外逻辑，可以定义 __post_init__：

@dataclass
class Employee:
 name: str
 salary: float
 bonus: float = 0.0

 def __post_init__(self):
 self.total_salary = self.salary + self.bonus

e = Employee("Alice", 50000, 5000)
print(e.total_salary) # 输出: 55000.0

7. 高级选项

@dataclass 接受一些参数来控制行为：

order=True：生成比较方法（如 __lt__, __gt__），支持排序。
frozen=True：使对象不可变。
init=False：禁用自动生成 __init__。
repr=False：禁用自动生成 __repr__。

示例：

@dataclass(order=True)
class Student:
 name: str
 score: int

s1 = Student("Alice", 90)
s2 = Student("Bob", 85)
print(s1 > s2) # 输出: True（基于字段顺序比较）

8. 与类型检查工具结合

数据类与 mypy 配合使用时，可以检测类型错误：

@dataclass
class Book:
 title: str
 pages: int

b = Book("Python Guide", "300") # 类型错误：pages 应为 int

运行 mypy script.py 会报错。

9. 与普通类的对比

普通类：

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

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

 def __eq__(self, other):
 if isinstance(other, Person):
 return self.name == other.name and self.age == other.age
 return False

数据类：

@dataclass
class Person:
 name: str
 age: int

数据类自动生成上述方法，代码更简洁。

10. 完整示例

from dataclasses import dataclass
from typing import List, Optional

@dataclass
class Course:
 title: str
 students: List[str]
 credits: int = 3
 instructor: Optional[str] = None

 def add_student(self, student: str) -> None:
 self.students.append(student)

c = Course("Python 101", ["Alice", "Bob"])
c.add_student("Charlie")
print(c) # 输出: Course(title='Python 101', students=['Alice', 'Bob', 'Charlie'], credits=3, instructor=None)

11. 注意事项

数据类适用于简单的、主要用于存储数据的类。如果逻辑复杂，建议使用普通类。
类型注解是可选的，但推荐使用以提高可读性和工具支持。
默认值必须是不可变对象（如 int, str），避免使用 list 或 dict 作为默认值（可以用 field 解决，见下文）。

使用 `field` 指定默认工厂

from dataclasses import dataclass, field

@dataclass
class Inventory:
 items: List[str] = field(default_factory=list) # 使用工厂函数创建默认值

i = Inventory()
i.items.append("apple")
print(i) # 输出: Inventory(items=['apple'])

希望这个教程能帮你掌握数据类的用法！如果有更多问题或需要具体示例，请随时告诉我。

python-typing提高代码可读性

Sat, 15 Mar 2025 20:34:43 +0800


-

首先掌握

typedDict

from typing import TypedDict

# 定义一个 TypedDict
class Person(TypedDict):
 name: str
 age: int
 email: NotRequired[str] # 可选字段

# 使用这个类型
person: Person = {"name": "Alice", "age": 25} # 合法
# person = {"name": "Alice"} # 非法：缺少 'age' 键
# person = {"name": "Alice", "age": "25"} # 非法：'age' 应该是 int 类型

特点

固定键：TypedDict 定义的键是固定的，不能随意添加或删除未定义的键。
类型检查：类型检查工具（如 mypy）会验证字典是否符合定义的结构。
继承性：可以通过继承扩展 TypedDict。

基本类型注解

from typing import List, Dict, Tuple, Set, Optional, Union

# 基本类型
name: str = "Alice"
age: int = 25
height: float = 1.75
is_student: bool = True

# 容器类型
numbers: List[int] = [1, 2, 3]
scores: Dict[str, int] = {"Alice": 90, "Bob": 85}
point: Tuple[int, int, str] = (10, 20, "origin")
unique_numbers: Set[int] = {1, 2, 3}

# 可选类型和联合类型
middle_name: Optional[str] = None # 可以是字符串或 None
id: Union[int, str] = 123 # 可以是整数或字符串


# 函数注解
def greet(name: str) -> str:
 return f"Hello, {name}!"

# 类注解
class Point:
 x: int
 y: int
 def __init__(self, x: int, y: int):
 self.x = x
 self.y = y

# 泛型
from typing import TypeVar
T = TypeVar('T') # 表示任何类型
def identity(item: T) -> T:
 return item
T = TypeVar('T', int, float)
def add(a: T, b: T) -> T:
 return a + b

# 嵌套类型
from typing import List, Dict
def process_data(data: List[Dict[str, int]]) -> List[int]:
 return [item["value"] for item in data]

# callable类型
from typing import Callable
def apply(func: Callable[[int], int], value: int) -> int:
 return func(value)

# Any类型
from typing import Any
def print_anything(value: Any) -> None:
 print(value)

# 类型别名
Vector = List[float]
def normalize(vector: Vector) -> Vector:
 return [v / sum(vector) for v in vector]

# 自定义类型
from typing import NewType
UserId = NewType('UserId', int)

typing

typing 模块在 Python 3.5+ 中引入，用于支持类型注解（Type Hints），帮助开发者在代码中声明变量、函数参数和返回值的类型。它主要用于静态类型检查工具（如 mypy）和提高代码可读性，而不是运行时强制类型检查。

以下是逐步讲解：

1. 基础概念

类型注解是 Python 中一种可选的语法，用于标注变量或函数的预期类型。它不会影响代码的运行，但可以被工具（如 IDE 或 mypy）用来检测类型错误。

# 没有类型注解
x = 42

# 有类型注解
x: int = 42

2. 导入 `typing` 模块

typing 模块提供了许多工具，用于处理复杂类型（如列表、字典、函数等）。

from typing import List, Dict, Optional, Union

3. 基本类型注解

Python 的内置类型（如 int, str, float, bool）可以直接使用。

name: str = "Alice"
age: int = 25
height: float = 1.75
is_student: bool = True

4. 容器类型

typing 提供了支持泛型（Generic Types）的工具，用于指定容器内的元素类型。

(1) `List`

表示列表及其元素类型：

from typing import List

numbers: List[int] = [1, 2, 3] # 列表中的元素是整数
names: List[str] = ["Alice", "Bob"]

(2) `Dict`

表示字典及其键值类型：

from typing import Dict

scores: Dict[str, int] = {"Alice": 90, "Bob": 85} # 键是字符串，值是整数

(3) `Tuple`

表示元组及其元素类型：

from typing import Tuple

point: Tuple[int, int, str] = (10, 20, "origin") # 元组有 3 个元素，类型分别是 int, int, str

(4) `Set`

表示集合及其元素类型：

from typing import Set

unique_numbers: Set[int] = {1, 2, 3}

5. 可选类型和联合类型

(1) `Optional`

表示一个值可以是某种类型或 None：

from typing import Optional

middle_name: Optional[str] = None # 可以是字符串或 None
middle_name = "Marie" # 合法

(2) `Union`

表示一个值可以是多种类型之一：

from typing import Union

id: Union[int, str] = 123 # 可以是整数或字符串
id = "ABC123" # 也合法

注意：从 Python 3.10 开始，可以直接使用 | 运算符替代 Union，例如 int | str。

id: int | str = 123 # Python 3.10+

6. 函数类型注解

函数的参数和返回值也可以添加类型注解。

def add(a: int, b: int) -> int:
 return a + b

def greet(name: str) -> str:
 return f"Hello, {name}"

a: int 表示参数 a 应为整数。
-> int 表示函数返回值的类型是整数。

可选参数

from typing import Optional

def get_full_name(first: str, last: str, middle: Optional[str] = None) -> str:
 if middle:
 return f"{first} {middle} {last}"
 return f"{first} {last}"

7. 复杂类型

(1) 嵌套类型

from typing import List, Dict

# 列表中的元素是字典
students: List[Dict[str, int]] = [
 {"Alice": 90},
 {"Bob": 85}
]

(2) `Callable`

表示可调用对象（如函数）的类型：

from typing import Callable

def apply(func: Callable[[int, int], int], a: int, b: int) -> int:
 return func(a, b)

# 示例用法
def multiply(x: int, y: int) -> int:
 return x * y

result = apply(multiply, 3, 4) # 返回 12

Callable[[int, int], int] 表示一个函数，接受两个 int 参数，返回 int。

8. 自定义类型

可以使用 TypeAlias 定义类型别名（Python 3.6+）：

from typing import TypeAlias

Vector: TypeAlias = List[float]

def magnitude(v: Vector) -> float:
 return sum(x * x for x in v) ** 0.5

在 Python 3.12+ 中，可以直接用 type 关键字：

type Vector = List[float] # Python 3.12+

9. Any 类型

Any 表示任意类型，相当于禁用类型检查：

from typing import Any

data: Any = 42 # 可以是任何类型
data = "hello" # 合法

10. 使用类型检查工具

类型注解不会在运行时强制执行。要检查类型错误，可以使用 mypy：

安装 mypy：
```
pip install mypy
```
运行检查：
```
mypy your_script.py
```

示例：

# test.py
def add(a: int, b: int) -> int:
 return a + b

print(add("1", "2")) # 类型错误

运行 mypy test.py 会提示参数类型不匹配。

11. 常见问题

类型注解会影响性能吗？ 不会，类型注解仅用于静态检查，运行时会被忽略。
Python 版本差异？
- Python 3.9+ 支持内置类型（如 list[int]）代替 List[int]。
- Python 3.10+ 支持 | 替代 Union。
- Python 3.12+ 支持 type 关键字定义类型别名。

12. 完整示例

from typing import List, Dict, Optional, Union

def process_data(
 numbers: List[int],
 info: Dict[str, str],
 flag: Optional[bool] = None
) -> Union[str, int]:
 if flag:
 return sum(numbers)
 return info.get("name", "Unknown")

result = process_data([1, 2, 3], {"name": "Alice"}, True)
print(result) # 输出 6

Annotated

Annotated 是 typing 模块中的一种高级类型注解工具，引入于 Python 3.9（typing_extensions 模块在早期版本支持）。它允许为类型注解附加元数据（metadata），这些元数据可以被工具、库或运行时处理。

基本语法

from typing import Annotated

 语法：Annotated[类型, 元数据]
x: Annotated[int, "some metadata"] = 42

Annotated[Type, metadata]：Type 是变量的实际类型，metadata 是附加的任意信息（如字符串、对象等）。
元数据不会影响运行时行为，仅供静态分析工具或自定义逻辑使用。

常见用途

提供额外上下文： Annotated 可以为类型添加描述信息，供工具解析。例如，指定变量的约束或用途。

from typing import Annotated

 表示年龄必须是正整数
Age = Annotated[int, "Must be positive"]
def set_age(age: Age) -> None:
 assert age > 0, "Age must be positive"
 print(f"Age set to {age}")

set_age(25) 正常
set_age(-5) 抛出 AssertionError

与静态类型检查工具结合：工具如 mypy 或 pyright 可以解析 Annotated 的元数据，执行特定检查。例如，某些库（如 pydantic）利用 Annotated 定义字段约束。

from typing import Annotated
from pydantic import BaseModel, PositiveInt

class Person(BaseModel):
 age: Annotated[int, PositiveInt]

person = Person(age=30) 正常
 person = Person(age=-1) 抛出 ValidationError

运行时元数据处理：开发者可以编写代码解析 Annotated 的元数据。例如，检查字段的约束或生成文档。

from typing import Annotated, get_type_hints, get_args, get_origin

def process_metadata(cls):
 for name, hint in get_type_hints(cls, include_extras=True).items():
 if get_origin(hint) is Annotated:
 type_, *metadata = get_args(hint)
 print(f"Field {name}: Type={type_}, Metadata={metadata}")

class User:
 name: Annotated[str, "User's full name"]
 id: Annotated[int, "Unique identifier"]

process_metadata(User)
 输出：
 Field name: Type=<class 'str'>, Metadata=['User's full name']
 Field id: Type=<class 'int'>, Metadata=['Unique identifier']

与第三方库集成：许多库（如 pydantic, typer, fastapi）使用 Annotated 定义额外约束或行为。例如，FastAPI 用它来指定 API 参数的元数据。

from fastapi import FastAPI
from typing import Annotated
from pydantic import StringConstraints

app = FastAPI()

@app.get("/user/{name}")
async def get_user(name: Annotated[str, StringConstraints(min_length=3)]):
 return {"name": name}

注意事项

运行时行为：Annotated 本身不影响运行时逻辑，元数据的处理依赖工具或自定义代码。
兼容性：Python 3.9+ 内置 Annotated，早期版本需使用 typing_extensions。
元数据任意性：元数据可以是任何对象（字符串、类、函数等），但需要工具或代码明确如何解析。
与普通类型注解的区别：普通类型注解只描述类型，Annotated 允许附加额外信息。

示例：综合使用

from typing import Annotated, get_type_hints, get_args, get_origin

 定义带有元数据的类型
PositiveInt = Annotated[int, "Must be positive"]

def validate_positive(value: PositiveInt) -> None:
 for annotation in get_args(get_type_hints(validate_positive)['value']):
 if annotation == "Must be positive":
 assert value > 0, "Value must be positive"
 print(f"Valid value: {value}")

validate_positive(10) 输出: Valid value: 10
 validate_positive(-1) 抛出 AssertionError

总结

typing 库为 Python 提供类型注解支持，增强代码健壮性和可读性。
Annotated 是 typing 的高级工具，用于为类型附加元数据，广泛用于静态检查、运行时验证和第三方库集成。
使用 Annotated 时，需结合工具（如 mypy、pydantic）或自定义逻辑解析元数据。

TypedDict

TypedDict 简介

TypedDict 是用于定义具有固定键和特定类型值的字典的类型注解工具。它最初在 typing 模块中引入（Python 3.8+），但 typing_extensions.TypedDict 提供了向后兼容支持，适用于 Python 3.7 及更早版本。TypedDict 允许开发者为字典的键值对指定明确的类型，增强静态类型检查和代码清晰度。

如果你是3.8+的版本，建议直接从typing中导入

与普通 dict 类型注解（如 dict[str, Any]）不同，TypedDict 确保字典有特定键，且每个键对应特定类型的值，适合描述结构化的字典数据（如 JSON 对象）。

TypedDict 的基本用法

TypedDict 定义一个类，继承自 dict，用于指定字典的结构。以下是基本语法和用法：

基本定义

from typing import TypedDict

 定义一个 TypedDict
class Person(TypedDict):
 name: str
 age: int

 使用
person: Person = {"name": "Alice", "age": 30} 正确
 person = {"name": "Bob", "age": "25"} mypy 报错：age 类型应为 int
 person = {"name": "Charlie"} mypy 报错：缺少 age 键

键名和类型在类定义中指定。
静态类型检查工具（如 mypy）会验证字典是否符合 TypedDict 定义的结构。

可选键使用 NotRequired（Python 3.11+ 或 typing_extensions）可以标记某些键为可选：

from typing_extensions import TypedDict, NotRequired

class Person(TypedDict):
 name: str
 age: NotRequired[int] age 是可选的

person: Person = {"name": "Alice"} 正确
person2: Person = {"name": "Bob", "age": 25} 也正确

必需键默认情况下，所有键都是必需的。可以用 Required（Python 3.11+ 或 typing_extensions）显式声明：

from typing_extensions import TypedDict, Required

class Person(TypedDict):
 name: Required[str]
 age: NotRequired[int]

与 Annotated 结合

TypedDict 可以与 Annotated 结合，为键值对附加元数据，进一步描述约束或用途。例如：

from typing import Annotated
from typing_extensions import TypedDict

class Person(TypedDict):
 name: Annotated[str, "Full name of the person"]
 age: Annotated[int, "Must be positive"]

 运行时验证元数据
def validate_person(person: Person):
 from typing import get_type_hints, get_args, get_origin
 hints = get_type_hints(Person, include_extras=True)
 for key, hint in hints.items():
 if get_origin(hint) is Annotated:
 _, *metadata = get_args(hint)
 if key == "age" and "Must be positive" in metadata:
 assert person[key] > 0, "Age must be positive"

person: Person = {"name": "Alice", "age": 30}
validate_person(person) 正确
 validate_person({"name": "Bob", "age": -1}) 抛出 AssertionError

高级用法

继承 TypedDict 支持继承，允许扩展或重用现有定义：

from typing_extensions import TypedDict

class Person(TypedDict):
 name: str
 age: int

class Employee(Person):
 employee_id: str

employee: Employee = {"name": "Alice", "age": 30, "employee_id": "E123"} 正确

总数控制（Total） TypedDict 支持 total 参数（默认为 True），控制是否所有键都必须存在：

from typing_extensions import TypedDict

class Person(TypedDict, total=False):
 name: str
 age: int

person: Person = {"name": "Alice"} 正确，age 可选

与第三方库 TypedDict 常用于与 pydantic 或 FastAPI 配合，定义结构化的输入/输出数据：

from typing_extensions import TypedDict
from pydantic import BaseModel

class Person(TypedDict):
 name: str
 age: int

class PersonModel(BaseModel):
 data: Person

person = PersonModel(data={"name": "Alice", "age": 30}) 验证通过

注意事项

静态检查：TypedDict 主要用于静态类型检查，运行时行为仍为普通字典。
兼容性：Python 3.7 及以下需使用 typing_extensions.TypedDict；3.8+ 可用 typing.TypedDict。
限制：TypedDict 不支持动态键（如任意字符串键），仅限固定键。
与 Annotated 协同：Annotated 可为 TypedDict 的字段添加元数据，增强描述能力。
运行时验证：需手动或借助库（如 pydantic）实现元数据或类型的运行时检查。

总结

typing_extensions.TypedDict 提供了一种类型安全的方式来定义结构化的字典，适合描述固定键值对的数据结构。
结合 Annotated，可以为字段添加元数据，增强类型注解的表达力。
主要用于静态类型检查（如 mypy），也可与运行时验证工具或框架（如 pydantic, FastAPI）集成。

python使用教程-难点和遇到的问题

Thu, 13 Mar 2025 10:17:58 +0800

功能实现和知识点

python程序后台运行

python后台运行

linux

# 1. 使用nohup
nohup python3 script.py > output.log 2>&1 &

# 你也可以把上面这个代码放入.sh文件中
echo 'nohup python3 script.py > output.log 2>&1 &' >> run_script.sh

chmod +x script.py

./script.py


# 2. 使用tmux

sudo apt install tmux # Ubuntu/Debian
# 或
sudo yum install tmux # CentOS/RHEL

tmux new -s my_session # 创建会话

python3 your_script.py # 在会话中运行 Python 脚本

# 按 Ctrl+B，然后按 D # 断开会话（脚本继续运行）

---

tmux attach -t my_session # 恢复会话
tmux kill-session -t my_session # 终止会话

nohup详细解释

nohup python3 script.py > output.log 2>&1 &
作用：使 Python 脚本在终端关闭后继续运行。
解释：
nohup：忽略挂起信号（HUP），防止终端关闭导致进程终止。
python3 script.py：运行你的 Python 脚本。
> output.log：将标准输出重定向到 output.log。
2>&1：将标准错误输出也重定向到 output.log。
&：将进程放入后台运行。

Python 函数定义教程

什么是函数？函数是一段可重用的代码块，用于执行特定任务。它可以接受输入（参数），处理逻辑，并返回输出（返回值）。函数使代码更模块化、可读和可维护。

函数的基本定义在 Python 中，函数使用 def 关键字定义，基本语法如下：

def function_name(parameters):
 """Docstring: 函数的说明文档"""
 # 函数体
 # 执行具体逻辑
 return result # 可选的返回值

def: 定义函数的关键字。
function_name: 函数的名称，遵循变量命名规则（小写字母、单词用下划线分隔）。
parameters: 函数的输入参数（可选）。
:: 表示函数体开始。
函数体: 缩进的代码块，包含函数的逻辑。
return: 返回结果（可选），如果没有 return，函数默认返回 None。
文档字符串（Docstring）: 用三引号 """ 包裹，描述函数的作用、参数和返回值（推荐使用）。

示例：

def greet(name):
 """返回对指定用户的问候语。

 参数:
 name (str): 用户的姓名。

 返回:
 str: 格式化的问候语。
 """
 message = f"你好，{name}！"
 return message

# 调用函数
print(greet("Alice")) # 输出: 你好，Alice！

参数的类型 Python 函数支持多种参数类型，帮助灵活处理输入：

位置参数按顺序传递参数，调用时必须按照定义的顺序提供。

示例：

def add(a, b):
 """返回两个数的和。"""
 return a + b

print(add(3, 5)) # 输出: 8

关键字参数调用时指定参数名，顺序不重要，增强代码可读性。

示例：

def introduce(name, age):
 """介绍一个人。"""
 return f"{name} 是 {age} 岁。"

print(introduce(age=25, name="Bob")) # 输出: Bob 是 25 岁。

默认参数为参数设置默认值，如果调用时不提供该参数，则使用默认值。

示例：

def greet(name, greeting="你好"):
 """返回问候语，带有默认问候词。"""
 return f"{greeting}，{name}！"

print(greet("Alice")) # 输出: 你好，Alice！
print(greet("Bob", "Hi")) # 输出: Hi，Bob！

可变参数：*args *args 允许函数接受任意数量的位置参数，参数被收集为一个元组。

示例：

def sum_numbers(*args):
 """返回所有输入数字的和。"""
 return sum(args)

print(sum_numbers(1, 2, 3)) # 输出: 6
print(sum_numbers(1, 2, 3, 4, 5)) # 输出: 15

关键字可变参数：**kwargs **kwargs 允许函数接受任意数量的关键字参数，参数被收集为一个字典。

示例：

def print_info(**kwargs):
 """打印所有关键字参数。"""
 for key, value in kwargs.items():
 print(f"{key}: {value}")

print_info(name="Alice", age=25, city="Shanghai")
# 输出:
# name: Alice
# age: 25
# city: Shanghai

编写出色的函数：最佳实践要编写高质量的函数，遵循以下原则：

单一职责原则一个函数只做一件事，保持逻辑简单。例如，计算面积的函数不应同时打印结果。

示例：

def calculate_circle_area(radius):
 """计算圆的面积。"""
 return 3.14159 * radius ** 2

def print_area(area):
 """打印面积。"""
 print(f"面积是: {area}")

# 使用
area = calculate_circle_area(5)
print_area(area) # 输出: 面积是: 78.53975

使用有意义的函数和参数名函数名应清晰描述其功能，参数名应直观。例如，calculate_circle_area(radius) 比 calc(x) 更清晰。

始终添加文档字符串文档字符串（Docstring）描述函数的作用、参数和返回值，方便他人理解和使用。

示例：

def divide(a, b):
 """将两个数相除并返回结果。

 参数:
 a (float): 被除数。
 b (float): 除数，不能为 0。

 返回:
 float: 除法结果。

 抛出:
 ZeroDivisionError: 当 b 为 0 时抛出。
 """
 return a / b

处理异常在函数中处理可能的错误，增强健壮性。

示例：

def divide_safe(a, b):
 """安全地执行除法操作。

 参数:
 a (float): 被除数。
 b (float): 除数。

 返回:
 float 或 None: 除法结果，如果除数为 0 则返回 None。
 """
 try:
 return a / b
 except ZeroDivisionError:
 print("错误：除数不能为 0！")
 return None

print(divide_safe(10, 0)) # 输出: 错误：除数不能为 0！ None
print(divide_safe(10, 2)) # 输出: 5.0

限制函数长度函数体应尽量简短（建议不超过 20-30 行）。如果逻辑复杂，拆分为多个小函数。

使用类型提示（Type Hints） Python 3.5+ 支持类型提示，增强代码可读性和 IDE 支持。

示例：

def add_numbers(a: float, b: float) -> float:
 """返回两个数的和。"""
 return a + b

高级函数技巧使用 lambda 函数 lambda 用于定义简短的匿名函数，常用于一次性或简单逻辑。

示例：

# 定义一个 lambda 函数
square = lambda x: x ** 2
print(square(5)) # 输出: 25

# 在 sorted 中使用 lambda
names = ["Alice", "Bob", "Charlie"]
sorted_names = sorted(names, key=lambda x: len(x))
print(sorted_names) # 输出: ['Bob', 'Alice', 'Charlie']

函数作为参数函数可以作为参数传递给其他函数，常见于回调函数。

示例：

def apply_operation(numbers, operation):
 """对数字列表应用指定操作。"""
 return [operation(x) for x in numbers]

def double(x):
 return x * 2

numbers = [1, 2, 3]
result = apply_operation(numbers, double)
print(result) # 输出: [2, 4, 6]

装饰器装饰器是函数的高级用法，用于在不修改函数代码的情况下添加功能。

示例：

def log_function(func):
 """记录函数调用信息。"""
 def wrapper(*args, **kwargs):
 print(f"调用函数: {func.__name__}，参数: {args}, {kwargs}")
 return func(*args, **kwargs)
 return wrapper

@log_function
def add(a, b):
 """返回两个数的和。"""
 return a + b

print(add(3, 5))
# 输出:
# 调用函数: add，参数: (3, 5), {}
# 8

实践：编写一个出色的函数任务：编写一个函数，计算一个数的阶乘，支持输入验证和异常处理。

示例：

def factorial(n: int) -> int:
 """计算 n 的阶乘。

 参数:
 n (int): 非负整数。

 返回:
 int: n 的阶乘。

 抛出:
 ValueError: 如果 n 不是非负整数。
 """
 if not isinstance(n, int):
 raise ValueError("输入必须是整数")
 if n < 0:
 raise ValueError("输入必须是非负整数")
 if n == 0 or n == 1:
 return 1
 result = 1
 for i in range(2, n + 1):
 result *= i
 return result

# 测试
try:
 print(factorial(5)) # 输出: 120
 print(factorial(-1)) # 抛出 ValueError
except ValueError as e:
 print(f"错误: {e}")

总结

函数使用 def 定义，包含函数名、参数、函数体和返回值。
使用 *args 和 **kwargs 处理可变参数。
编写出色的函数需要：单一职责、有意义的命名、文档字符串、异常处理、类型提示等。
高级技巧如 lambda 函数、函数作为参数和装饰器可以进一步提升代码灵活性。

从.py文件中获取函数对象和参数的字典

在给定的Python脚本中，通过模块导入和反射机制，如何动态获取包含模型函数的模块中的函数及其默认参数，并构建一个字典以便后续使用？

解决方案

test.py

# test.py
import numpy as np
def return_inputs(*args):
 return args
# 前处理 要求输入为 X, y, **params 输出为 X_new, y_new
def mahalanobis(X, y,threshold=95):
 mahal_X = np.asarray(X)
 x_mu = mahal_X - np.mean(mahal_X, axis=0)
 cov = np.cov(mahal_X.T)
 inv_covmat = np.linalg.inv(cov)
 left_term = np.dot(x_mu, inv_covmat)
 mahal = np.dot(left_term, x_mu.T)
 d = mahal.diagonal()
 threshold = np.percentile(d, threshold)
 mahal_x = mahal_X[d < threshold]
 return mahal_x, y[d < threshold]

main.py


import test as AF # 导入包含模型函数的模块
import inspect
def getModelParamsFromAF():

 # 获取模块中的所有成员
 module_members = AF.__dict__.items()

 # 构建models字典
 models = {}
 for name, member in module_members:
 if callable(member): # 检查成员是否为函数
 # 使用inspect模块获取函数的参数信息
 params = inspect.signature(member).parameters
 default_params = {param: params[param].default for param in params if params[param].default != inspect.Parameter.empty}

 models[name] = (member, default_params)
 return models

print(getModelParamsFromAF())

总结 本问题涉及在Python脚本中通过模块导入和反射机制，动态获取包含模型函数的模块中的函数及其默认参数，并将其构建成一个字典。通过利用inspect模块获取函数参数信息，作者实现了一个函数getModelParamsFromAF()，该函数返回一个包含模型函数及其默认参数的字典。这种动态获取参数的方法可以方便后续使用，提高代码的灵活性和可维护性。最后，通过print语句输出获取到的模型函数及其默认参数，以便进行进一步的分析和使用。

Python 多进程

相关问题	地址
python使用进程池多进程时，如何打印错误信息	博客园

在python机器学习中，我想要进行自动调参，这需要比较大的运算能力，但是我发现cpu的性能总是不能跑满，原来是我用了多线程，python对于多线程的支持并不是很好可以看廖雪峰

python多线程为什么不能把多核CPU的性能吃满？ 因为Python的线程虽然是真正的线程，但解释器执行代码时，有一个GIL锁：Global Interpreter Lock，任何Python线程执行前，必须先获得GIL锁，然后，每执行100条字节码，解释器就自动释放GIL锁，让别的线程有机会执行。这个GIL全局锁实际上把所有线程的执行代码都给上了锁，所以，多线程在Python中只能交替执行，即使100个线程跑在100核CPU上，也只能用到1个核。

GIL是Python解释器设计的历史遗留问题，通常我们用的解释器是官方实现的CPython，要真正利用多核，除非重写一个不带GIL的解释器。

所以，在Python中，可以使用多线程，但不要指望能有效利用多核。如果一定要通过多线程利用多核，那只能通过C扩展来实现，不过这样就失去了Python简单易用的特点。

不过，也不用过于担心，Python虽然不能利用多线程实现多核任务，但可以通过多进程实现多核任务。多个Python进程有各自独立的GIL锁，互不影响。

目前python团队已经计划在3.13版本以后删除GIL锁CSDN链接

把多线程改成多线程 一个例子，根据自己核心数创建进程，然后把数据写入json文件中最后合并

from multiprocessing import Pool
import multiprocessing
import os, time, random
import json

def long_time_task(name):
 print('Run task %s (%s)...' % (name, os.getpid()))
 start = time.time()
 # 需要保存的数据
 data = {
 "name": str(name)
 }

 # 将数据写入JSON文件
 with open('data'+str(name)+'.json', 'w') as f:
 json.dump(data, f, indent=4)
 end = time.time()
 print('Task %s runs %0.2f seconds.' % (name, (end - start)))

if __name__=='__main__':
 print('Parent process %s.' % os.getpid())
 p = Pool()
 # 获取CPU的核心数
 cpu_cores = multiprocessing.cpu_count()
 print(cpu_cores)
 for i in range(cpu_cores):
 p.apply_async(long_time_task, args=(i,))
 print('Waiting for all subprocesses done...')
 p.close()
 p.join()


 files = []
 file_path = os.path.dirname(__file__)
 for file in os.listdir(file_path):
 if file.find('data') != -1:
 files.append(file)
 merged_data = []

 # 遍历每个文件，读取并解析 JSON 数据，然后添加到合并后的数据列表中
 for file_name in files:
 with open(file_name, 'r') as file:
 print(file_name)
 data = json.load(file)
 merged_data.append(data)

 # 将合并后的数据写入新的 JSON 文件
 with open('merged.json', 'w') as merged_file:
 json.dump(merged_data, merged_file, indent=4)

 print('JSON 文件已合并完成。')

 print('All subprocesses done.')

加进程锁

from multiprocessing import Process, Queue, Pool
import multiprocessing
import os, time, random

def write1(q, lock):
 lock.acquire() # 加上锁
 for value in ['A', 'B', 'C']:
 print('Put %s to queue...' % value)
 q.put(value)
 time.sleep(random.random())
 lock.release()

def write2(q, lock):
 lock.acquire() # 加上锁
 for value in ['D', 'E', 'F']:
 print('Put %s to queue...' % value)
 q.put(value)
 time.sleep(random.random())
 lock.release()

if __name__ == '__main__':
 q = Queue()
 manager = multiprocessing.Manager()
 lock = manager.Lock()
 pw1 = Process(target=write1, args=(q, lock))
 pw2 = Process(target=write2, args=(q, lock))
 # 启动子进程pw，写入:
 pw1.start()
 pw2.start()
 # pr.start()
 pw1.join()
 pw2.join()
 # pr.join()
 print('所有数据都写入并且读完')

总结

写过另外一个程序

collection_lock = Lock()
def collect_with_retry():
 if collection_lock.acquire(blocking=False):
 try:
 main()
 # break
 except Exception as e:
 self.logger.error(f"Collection failed: {str(e)}")
 finally:
 collection_lock.release()
 else:
 self.logger.warning("Failed to acquire lock for collection after multiple attempts")
if not hasattr(self, 'collection_thread') or not self.collection_thread.is_alive():
 self.collection_thread = Thread(target=collect_with_retry)
 self.collection_thread.daemon = True
 self.collection_thread.start()
else:
 self.logger.warning("Collection is already in progress")

文件所在文件夹外的另一文件导入函数或类

要在一个Python文件中从位于该文件所在文件夹外的另一个文件导入函数或类，你需要确保两个文件都在Python的搜索路径中。假设你有如下的目录结构：

project/
│
├── utils.py
│
└── subfolder/
 └── myfile.py

在这种情况下，utils.py 文件位于 subfolder 文件夹的外面。要从 myfile.py 中导入 utils.py 中的内容，你可以使用几种方法：

方法1: 修改系统路径在 myfile.py 中，你可以添加代码来修改系统路径，这样 Python 就可以找到 utils.py 文件。示例如下：

import sys
sys.path.insert(0, '../')

from utils import *

这里 sys.path.insert(0, '../') 将 utils.py 文件所在的上级目录添加到 Python 搜索路径的开始处，确保 Python 可以找到并导入 utils.py。

方法2: 使用相对导入如果你的项目结构适合使用包的结构（即目录中有 __init__.py 文件），你可以使用相对导入。首先，确保每个需要作为包处理的目录中都有一个空的 __init__.py 文件：

project/
│
├── utils.py
│
└── subfolder/
 ├── __init__.py
 └── myfile.py

然后，在 myfile.py 中使用相对导入：

from ..utils import *

注意，使用相对导入时，你的脚本必须作为包的一部分运行，不能直接作为主脚本运行，否则会出错。即，你需要这样的方式执行代码：

python -m myproject.submodule1.myscript

方法3:使用环境变量你可以设置 PYTHONPATH 环境变量，使其包括 utils.py 所在的目录。这样，当你运行 Python 时，它会自动将该目录添加到搜索路径中。

在 Unix-like 系统中，你可以在终端中这样设置：

export PYTHONPATH="/path/to/project:$PYTHONPATH"

在 Windows 系统中，你可以在命令提示符中这样设置：

set PYTHONPATH=C:\path\to\project;%PYTHONPATH%

这样设置之后，你可以在 myfile.py 中正常导入：

from utils import *

选择最适合你项目结构和需求的方法来导入模块。如果你正在开发一个较大的项目，考虑使用环境变量或确保你的项目可以作为包运行，这通常更为稳定和灵活。

OS库常用函数

获取当前工作目录：

import os
current_directory = os.getcwd()
print(current_directory)

改变工作目录：
```
os.chdir('/path/to/directory')
```

列出目录中的文件：

files = os.listdir('/path/to/directory')
print(files)

创建新目录：
```
os.mkdir('new_directory')
```
删除目录：
```
os.rmdir('new_directory')
```

检查文件或目录是否存在：

exists = os.path.exists('/path/to/file_or_directory')
print(exists)

获取文件大小：

file_size = os.path.getsize('/path/to/file')
print(file_size)

如何避免类重复创建实例

在 Python 中，为了避免一个类重复创建实例（例如，确保某个类在程序运行中只存在一个实例），可以使用 单例模式（Singleton Pattern）。单例模式是一种设计模式，保证一个类只有一个实例，并提供一个全局访问点。以下是实现单例模式的几种方法，以及如何避免类重复创建的说明：

方法 1：使用类方法和类属性通过在类中维护一个静态变量（类属性）来保存唯一实例，并在实例化时检查是否已存在实例。

class Singleton:
 _instance = None # 类属性，用于存储唯一实例

 def __new__(cls):
 if cls._instance is None:
 cls._instance = super().__new__(cls) # 创建新实例
 return cls._instance

# 测试
s1 = Singleton()
s2 = Singleton()
print(s1 is s2) # 输出: True，说明是同一个实例

说明：

__new__ 方法在对象创建时被调用，用于控制实例的创建。
_instance 保存类的唯一实例，如果已存在则直接返回，不重复创建。
is 运算符验证 s1 和 s2 是同一个对象。

方法 2：使用装饰器通过装饰器实现单例模式，适用于多个类需要单例逻辑的情况。

def singleton(cls):
 instances = {} # 存储类与实例的映射

 def get_instance(*args, **kwargs):
 if cls not in instances:
 instances[cls] = cls(*args, **kwargs)
 return instances[cls]

 return get_instance

@singleton
class Singleton:
 def __init__(self):
 print("实例化 Singleton")

# 测试
s1 = Singleton()
s2 = Singleton()
print(s1 is s2) # 输出: True

说明：

装饰器 singleton 维护一个字典 instances，存储类的唯一实例。
每次调用类时，检查是否已有实例，若无则创建，若有则返回现有实例。
@singleton 装饰器使类自动具备单例行为。

方法 3：使用元类（Metaclass）通过自定义元类来控制类的实例化过程，实现单例模式。

class SingletonMeta(type):
 _instances = {}

 def __call__(cls, *args, **kwargs):
 if cls not in cls._instances:
 cls._instances[cls] = super().__call__(*args, **kwargs)
 return cls._instances[cls]

class Singleton(metaclass=SingletonMeta):
 def __init__(self):
 print("实例化 Singleton")

# 测试
s1 = Singleton()
s2 = Singleton()
print(s1 is s2) # 输出: True

说明：

SingletonMeta 是一个元类，控制类的创建过程。
__call__ 方法在类被调用（实例化）时触发，检查是否已有实例。
通过 metaclass=SingletonMeta，类自动实现单例模式。

方法 4：模块级单例 Python 的模块本身就是单例的（模块只导入一次），因此可以在模块级别定义一个全局对象来模拟单例。

# singleton.py
class Singleton:
 def __init__(self):
 print("实例化 Singleton")

singleton_instance = Singleton()

# 使用时
from singleton import singleton_instance

说明：

Python 模块在程序运行期间只加载一次，因此 singleton_instance 是唯一的。
这种方式简单，但不够灵活，适合简单的全局对象需求。

注意事项

线程安全：上述方法在多线程环境中可能不安全，可能导致多个实例被创建。如果需要线程安全，可以使用锁机制。例如：

import threading

class Singleton:
 _instance = None
 _lock = threading.Lock()

 def __new__(cls):
 with cls._lock:
 if cls._instance is None:
 cls._instance = super().__new__(cls)
 return cls._instance

单例的适用场景：
- 需要全局唯一实例的场景，如配置管理器、日志记录器、数据库连接池等。
- 不适合所有类，滥用单例可能导致代码难以测试和维护。
替代方案：
- 如果不需要严格的单例，可以使用全局变量或工厂模式。
- 在某些情况下，依赖注入（Dependency Injection）可能比单例更适合。
测试单例：
- 使用 is 运算符检查两个实例是否相同。
- 确保单例的属性在所有实例中共享。

总结

推荐方法：方法 1（__new__）最简单直接，适合大多数场景。
灵活性：方法 2（装饰器）适合多个类复用单例逻辑。
高级需求：方法 3（元类）适合需要深度控制类行为的场景。
模块级单例：方法 4 适合简单的全局对象需求。
线程安全：在多线程环境中，添加锁机制以避免竞争条件。

装饰器函数 @….

在sklearn中看到红框中的函数，于是好奇是什么东西，查到python-函数前一行加@xxxx的含义

于是找到函数定义：def validate_params(parameter_constraints, *, prefer_skip_nested_validation):

但是，里面没有定义func参数 于是再看到下面，原来这个函数下面又定义了一个def decorator(func): 这样是可以的嘛？于是去尝试

def test_func():
 print(1111)
 def inner_func(func):
 func()
 return

@test_func()
def some_func():
 print("pp")
 return
some_func()

这也不行啊

进一步了解到，原来：它是通过 functools 重写了装饰器函数，你要这样写才行

import functools
def test_func():
 print(1111)
 ### 装饰器函数
 def decorator(func):
 @functools.wraps(func)
 def wrapper(*args, **kwargs):
 return func(*args, **kwargs)
 return wrapper
 return decorator

@test_func()
def some_func():
 print("pp")
 return

some_func()

下面是具体介绍

@validate_params 装饰器的运作原理

装饰器定义：

validate_params 是一个装饰器函数。它的作用是用于验证被装饰函数的参数类型是否符合预设的约束条件。

参数约束：

parameter_constraints 是一个字典，用于定义每个参数的允许类型。例如，可以指定某个参数可以是列表或 NumPy 数组。

内部装饰器：

decorator 是 validate_params 内部定义的装饰器函数。它接受被装饰的函数 func 作为参数。

参数绑定：

在 wrapper 函数中，使用 signature(func).bind(*args, **kwargs).arguments 将传入的参数与函数的签名进行绑定，生成一个包含所有参数及其值的字典 params。

参数验证：

对字典中的每个参数进行检查。使用 any() 函数来判断该参数的值是否符合定义的约束条件。如果不符合，则抛出一个自定义的异常 InvalidParameterError，并提供错误信息。

调用原函数：

如果所有参数都通过了验证，wrapper 函数就会调用原始的被装饰函数 func，并返回其结果。

@validate_params 装饰器的核心功能是自动检查函数参数的类型。这可以帮助开发者在调用函数之前发现潜在的错误，增强代码的健壮性和可维护性。通过这种方式，确保了函数在执行时获得正确类型的输入，从而减少了运行时错误的风险。我写了一个示例代码：

import functools
import numpy as np
from inspect import signature

class InvalidParameterError(ValueError):
 pass

def validate_params(parameter_constraints, *, prefer_skip_nested_validation):
 """装饰器用于验证函数和方法的参数类型和值。"""

 def decorator(func):
 setattr(func, "_parameter_constraints", parameter_constraints)

 @functools.wraps(func)
 def wrapper(*args, **kwargs):
 params = signature(func).bind(*args, **kwargs).arguments
 to_ignore = ["self", "cls"]
 params = {k: v for k, v in params.items() if k not in to_ignore}

 validate_parameter_constraints(parameter_constraints, params, caller_name=func.__qualname__)

 return func(*args, **kwargs)

 return wrapper

 return decorator

def validate_parameter_constraints(parameter_constraints, params, caller_name):
 for param, constraints in parameter_constraints.items():
 if param not in params:
 continue
 value = params[param]
 valid = False
 for constraint in constraints:
 # 检查是否为类型
 if isinstance(constraint, type):
 if isinstance(value, constraint):
 valid = True
 break
 # 检查是否为 None
 elif constraint is None and value is None:
 valid = True
 break

 if not valid:
 expected_types = ', '.join(c.__name__ if isinstance(c, type) else str(c) for c in constraints)
 raise InvalidParameterError(f"{caller_name}: '{param}' must be one of types: {expected_types}.")

@validate_params(
 {
 "y_true": [list, np.ndarray],
 "y_pred": [list, np.ndarray],
 "sample_weight": [list, np.ndarray, None],
 },
 prefer_skip_nested_validation=True,
)
def mean_squared_error(y_true, y_pred, *, sample_weight=None):
 """计算均方误差 (MSE)。"""

 if sample_weight is not None:
 sample_weight = np.array(sample_weight)

 y_true = np.array(y_true)
 y_pred = np.array(y_pred)

 if sample_weight is not None:
 return np.average((y_pred - y_true) ** 2, weights=sample_weight)
 else:
 return np.mean((y_pred - y_true) ** 2)

# 示例用法
y_true = [3, -0.5, 2, 7] # 真实值
y_pred = [2.5, 0.0, 2, 8] # 预测值
print(mean_squared_error(y_true, y_pred)) # 输出均方误差

结果

sklearn中源码


def validate_params(parameter_constraints, *, prefer_skip_nested_validation):
 """Decorator to validate types and values of functions and methods.

 Parameters
 ----------
 parameter_constraints : dict
 A dictionary `param_name: list of constraints`. See the docstring of
 `validate_parameter_constraints` for a description of the accepted constraints.

 Note that the *args and **kwargs parameters are not validated and must not be
 present in the parameter_constraints dictionary.

 prefer_skip_nested_validation : bool
 If True, the validation of parameters of inner estimators or functions
 called by the decorated function will be skipped.

 This is useful to avoid validating many times the parameters passed by the
 user from the public facing API. It's also useful to avoid validating
 parameters that we pass internally to inner functions that are guaranteed to
 be valid by the test suite.

 It should be set to True for most functions, except for those that receive
 non-validated objects as parameters or that are just wrappers around classes
 because they only perform a partial validation.

 Returns
 -------
 decorated_function : function or method
 The decorated function.
 """

 def decorator(func):
 # The dict of parameter constraints is set as an attribute of the function
 # to make it possible to dynamically introspect the constraints for
 # automatic testing.
 setattr(func, "_skl_parameter_constraints", parameter_constraints)

 @functools.wraps(func)
 def wrapper(*args, **kwargs):
 global_skip_validation = get_config()["skip_parameter_validation"]
 if global_skip_validation:
 return func(*args, **kwargs)

 func_sig = signature(func)

 # Map *args/**kwargs to the function signature
 params = func_sig.bind(*args, **kwargs)
 params.apply_defaults()

 # ignore self/cls and positional/keyword markers
 to_ignore = [
 p.name
 for p in func_sig.parameters.values()
 if p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD)
 ]
 to_ignore += ["self", "cls"]
 params = {k: v for k, v in params.arguments.items() if k not in to_ignore}

 validate_parameter_constraints(
 parameter_constraints, params, caller_name=func.__qualname__
 )

 try:
 with config_context(
 skip_parameter_validation=(
 prefer_skip_nested_validation or global_skip_validation
 )
 ):
 return func(*args, **kwargs)
 except InvalidParameterError as e:
 # When the function is just a wrapper around an estimator, we allow
 # the function to delegate validation to the estimator, but we replace
 # the name of the estimator by the name of the function in the error
 # message to avoid confusion.
 msg = re.sub(
 r"parameter of \w+ must be",
 f"parameter of {func.__qualname__} must be",
 str(e),
 )
 raise InvalidParameterError(msg) from e

 return wrapper

 return decorator




@validate_params(
 {
 "y_true": ["array-like"],
 "y_pred": ["array-like"],
 "sample_weight": ["array-like", None],
 "multioutput": [StrOptions({"raw_values", "uniform_average"}), "array-like"],
 },
 prefer_skip_nested_validation=True,
)
def mean_absolute_error(
 y_true, y_pred, *, sample_weight=None, multioutput="uniform_average"
):
 """Mean absolute error regression loss.

 Read more in the :ref:`User Guide <mean_absolute_error>`.

 Parameters
 ----------
 y_true : array-like of shape (n_samples,) or (n_samples, n_outputs)
 Ground truth (correct) target values.

 y_pred : array-like of shape (n_samples,) or (n_samples, n_outputs)
 Estimated target values.

 sample_weight : array-like of shape (n_samples,), default=None
 Sample weights.

 multioutput : {'raw_values', 'uniform_average'} or array-like of shape \
 (n_outputs,), default='uniform_average'
 Defines aggregating of multiple output values.
 Array-like value defines weights used to average errors.

 'raw_values' :
 Returns a full set of errors in case of multioutput input.

 'uniform_average' :
 Errors of all outputs are averaged with uniform weight.

 Returns
 -------
 loss : float or ndarray of floats
 If multioutput is 'raw_values', then mean absolute error is returned
 for each output separately.
 If multioutput is 'uniform_average' or an ndarray of weights, then the
 weighted average of all output errors is returned.

 MAE output is non-negative floating point. The best value is 0.0.

 Examples
 --------
 >>> from sklearn.metrics import mean_absolute_error
 >>> y_true = [3, -0.5, 2, 7]
 >>> y_pred = [2.5, 0.0, 2, 8]
 >>> mean_absolute_error(y_true, y_pred)
 0.5
 >>> y_true = [[0.5, 1], [-1, 1], [7, -6]]
 >>> y_pred = [[0, 2], [-1, 2], [8, -5]]
 >>> mean_absolute_error(y_true, y_pred)
 0.75
 >>> mean_absolute_error(y_true, y_pred, multioutput='raw_values')
 array([0.5, 1. ])
 >>> mean_absolute_error(y_true, y_pred, multioutput=[0.3, 0.7])
 0.85...
 """
 y_type, y_true, y_pred, multioutput = _check_reg_targets(
 y_true, y_pred, multioutput
 )
 check_consistent_length(y_true, y_pred, sample_weight)
 output_errors = np.average(np.abs(y_pred - y_true), weights=sample_weight, axis=0)
 if isinstance(multioutput, str):
 if multioutput == "raw_values":
 return output_errors
 elif multioutput == "uniform_average":
 # pass None as weights to np.average: uniform mean
 multioutput = None

 return np.average(output_errors, weights=multioutput)

from abc import ABC, abstractmethod 关于抽象基类

在 Python 中，from abc import ABC, abstractmethod 是用于实现抽象基类（Abstract Base Class, ABC）的导入语句。让我们逐步解析它的含义和作用：

模块 abc abc 是 Python 的标准库模块，全称是 Abstract Base Classes，用于定义抽象基类。抽象基类是一种不能直接实例化的类，通常用于定义一组子类必须实现的接口或方法。
ABC ABC 是 abc 模块中的一个类，任何继承自 ABC 的类都会被标记为抽象基类。抽象基类不能被直接实例化，必须通过子类继承并实现其抽象方法后才能使用。
abstractmethod abstractmethod 是 abc 模块中的一个装饰器，用于将方法标记为抽象方法。抽象方法是子类必须实现的方法，否则子类也会被视为抽象类，无法实例化。
代码示例 以下是一个使用 ABC 和 abstractmethod 的简单例子：

from abc import ABC, abstractmethod

# 定义一个抽象基类
class Animal(ABC):
 @abstractmethod
 def make_sound(self):
 """子类必须实现这个方法"""
 pass

# 定义一个具体子类
class Dog(Animal):
 def make_sound(self):
 return "Woof!"

# 定义另一个具体子类
class Cat(Animal):
 def make_sound(self):
 return "Meow!"

# 测试代码
dog = Dog()
print(dog.make_sound()) # 输出: Woof!

cat = Cat()
print(cat.make_sound()) # 输出: Meow!

# 试图实例化抽象基类会报错
# animal = Animal() # TypeError: Can't instantiate abstract class Animal with abstract methods make_sound

代码解析

Animal 类：通过继承 ABC，它成为一个抽象基类。
make_sound 方法：被 @abstractmethod 装饰，表示子类必须实现这个方法。
子类 Dog 和 Cat：它们继承了 Animal，并实现了 make_sound 方法，因此可以被实例化。
不能实例化 Animal：如果尝试直接创建 Animal 的实例，会抛出错误，因为它是一个抽象类，且包含未实现的抽象方法。

用途

接口定义：确保子类实现特定的方法，强制执行某种契约。
代码规范：提高代码的可维护性和可读性，明确子类的行为要求。
多态性：支持多态设计，允许不同的子类以自己的方式实现抽象方法。

注意事项

如果子类没有实现抽象基类中的所有抽象方法，实例化该子类会抛出 TypeError。
抽象基类可以包含普通方法（非抽象方法），这些方法可以有默认实现。
@abstractmethod 必须与 ABC 一起使用，否则不会强制要求子类实现。

总结 from abc import ABC, abstractmethod 是 Python 中用于定义抽象基类的工具。ABC 是一个基类，用于创建抽象类；abstractmethod 是一个装饰器，用于标记必须由子类实现的方法。这种机制在面向对象编程中非常有用，尤其是在需要定义统一接口或强制子类实现特定方法时。

函数名前不同下划线’_‘数量所代表的含义

在 Python 中，函数名前加下划线（_）通常是为了表示特定的命名约定或用途，主要与代码的可读性、访问控制和命名空间管理有关。以下是函数名前加单下划线（_）和双下划线（__）以及不加下划线的区别和含义：

不加下划线的函数（普通函数）

含义：这是最常见的函数命名方式，表示函数是公开的（public），可以被模块内外任意访问和调用。
用途：用于定义模块或类的公共接口，任何代码都可以直接调用这些函数。
示例：
```
def public_function():
 print("这是一个公开函数")
```
- 任何地方都可以调用 public_function()，没有任何访问限制。

单下划线开头的函数（_function）

含义：以单下划线 _ 开头的函数表示它是受保护的（protected）或内部使用的。这是 Python 的命名约定，提示开发者这个函数主要用于模块或类内部，不建议外部直接调用。
实际效果：并没有真正的访问限制，外部代码仍然可以访问和调用，只是约定上表示“这个函数是内部实现细节，最好不要直接使用”。
用途：
- 用于模块内部的辅助函数，提示用户不要直接调用。
- 在类中表示受保护的方法，建议子类或内部逻辑使用。

示例：

class MyClass:
 def _protected_method(self):
 print("这是一个受保护的方法")

obj = MyClass()
obj._protected_method() 可以调用，但不推荐

虽然可以调用 _protected_method，但开发者看到单下划线会知道这是内部方法，不建议直接使用。

双下划线开头的函数（__function）

含义：以双下划线 __ 开头的函数表示私有（private），用于实现 Python 的**名称改写（name mangling）**机制。这是 Python 中一种更强的封装方式，旨在防止外部代码直接访问这些方法。
实际效果：Python 会将 __function 的名称改写为 _ClassName__function，以避免子类或外部代码意外覆盖或调用。这种机制并不是完全禁止访问，而是增加了访问难度。
用途：
- 用于类的私有方法，确保方法不会被子类意外重写或被外部直接调用。
- 强调方法是类的内部实现细节。

示例：

class MyClass:
 def __private_method(self):
 print("这是一个私有方法")

obj = MyClass()
 obj.__private_method() 会报错：AttributeError
obj._MyClass__private_method() 可以这样访问，但不推荐

直接调用 __private_method 会失败，因为名称被改写为 _MyClass__private_method。
仍然可以通过改写后的名称访问，但这违背了封装的意图。

双下划线开头和结尾的函数（__function__）

含义：以双下划线开头和结尾的函数是 Python 的特殊方法（magic methods 或 dunder methods），用于定义类的特殊行为或内置功能。这些方法由 Python 解释器在特定场景下自动调用。
用途：
- 实现类的内置行为，例如 __init__（构造函数）、__str__（字符串表示）、__len__（长度）等。
- 这些方法是公开的，但通常由 Python 内部调用，而不是开发者直接调用。

示例：

class MyClass:
 def __init__(self, name):
 self.name = name

 def __str__(self):
 return f"MyClass with name: {self.name}"

obj = MyClass("Test")
print(obj) 自动调用 __str__，输出: MyClass with name: Test

单下划线作为函数名（_）

含义：单独使用 _ 作为函数名或变量名，通常用于表示临时或占位符，在代码中不打算实际使用。
用途：
- 在循环或解包中忽略不需要的值。
- 有时在模块中定义 _ 作为临时函数名（不常见）。

示例：

for _ in range(5): 忽略循环变量
 print("Hello")

总结对比

前缀	含义	访问限制	典型用途
`function`	公开函数	无限制	模块或类的公共接口
`_function`	受保护函数	约定限制（可访问）	模块或类内部的辅助方法
`__function`	私有函数	名称改写（难以直接访问）	类内部的私有实现
`__function__`	特殊方法	无限制（由 Python 自动调用）	定义类的内置行为
`_`	占位符	无限制	忽略变量或临时函数

注意事项

约定 vs. 强制：Python 的下划线命名是约定而非强制。单下划线是提示，开发者应尊重但可以绕过；双下划线通过名称改写提供更强的封装，但仍可通过改写后的名称访问。
代码风格：遵循 Python 的 PEP 8 命名规范，使用下划线来提高代码可读性和维护性。
文化习惯：在 Python 社区中，尊重下划线约定是良好编程习惯的体现，避免直接访问 _ 或 __ 开头的方法。

示例综合对比

class Example:
 def public_method(self):
 print("公开方法")

 def _protected_method(self):
 print("受保护方法")

 def __private_method(self):
 print("私有方法")

 def __init__(self):
 print("特殊方法：初始化")

obj = Example() 调用 __init__
obj.public_method() 正常调用
obj._protected_method() 可以调用，但不推荐
 obj.__private_method() 报错
obj._Example__private_method() 可以访问，但不推荐

通过这些命名约定，Python 提供了灵活的封装机制，同时保持了语言的简洁性和开放性。

函数中的*号和**号

在 Python 中，* 和 ** 是用于处理函数参数的特殊符号。它们分别表示不同的含义，主要用于处理可变数量的参数和解包操作。以下是详细的介绍：

1. **单星号* 的作用** * 主要用在以下两种场景：

(1) *定义可变位置参数（args） 在函数定义中，*args 用于接收任意数量的位置参数。这些参数会被打包成一个元组（tuple），供函数内部使用。

def my_function(*args):
 print(args) # args 是一个元组

my_function(1, 2, 3)
# 输出: (1, 2, 3)

*args 中的 args 只是一个约定俗成的名字，你可以使用其他名字，比如 *values。
这些参数是按位置传递的，调用时不需要指定参数名。

(2) 解包可迭代对象 在函数调用时，* 可以用来解包一个可迭代对象（如列表、元组等），将其元素作为独立的位置参数传递给函数。

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

numbers = [1, 2, 3]
result = add(*numbers) # 等价于 add(1, 2, 3)
print(result)
# 输出: 6

2. **双星号** 的作用** ** 主要用在以下两种场景：

(1) **定义可变关键字参数（kwargs） 在函数定义中，**kwargs 用于接收任意数量的关键字参数。这些参数会被打包成一个字典（dictionary），供函数内部使用。

def my_function(**kwargs):
 print(kwargs) # kwargs 是一个字典

my_function(a=1, b=2, c=3)
# 输出: {'a': 1, 'b': 2, 'c': 3}

**kwargs 中的 kwargs 同样只是一个约定俗成的名字，你可以使用其他名字，比如 **options。
这些参数是通过键值对传递的，调用时需要指定参数名。

(2) 解包字典 在函数调用时，** 可以用来解包一个字典，将其键值对作为独立的关键字参数传递给函数。

def greet(name, age):
 print(f"Hello {name}, you are {age} years old.")

info = {"name": "Alice", "age": 25}
greet(**info) # 等价于 greet(name="Alice", age=25)
# 输出: Hello Alice, you are 25 years old.

3. ***和** 的结合使用** 在一个函数定义中，可以同时使用 *args 和 **kwargs，分别处理位置参数和关键字参数。

def my_function(*args, **kwargs):
 print("Positional arguments:", args)
 print("Keyword arguments:", kwargs)

my_function(1, 2, 3, a=4, b=5)
# 输出:
# Positional arguments: (1, 2, 3)
# Keyword arguments: {'a': 4, 'b': 5}

4. **注意事项**

顺序规则：在函数定义中，参数的顺序必须是：
1. 普通参数
2. *args
3. 带默认值的参数
4. **kwargs
示例：
```
def example(a, b, *args, c=10, **kwargs):
 pass
```
强制关键字参数：从 Python 3 开始，可以通过在 * 后面添加参数来强制要求某些参数必须通过关键字传递。例如：
```
def example(a, *, b):
 print(a, b)

example(1, b=2) # 正确
example(1, 2) # 错误，TypeError
```

总结

* 用于处理可变数量的位置参数或解包可迭代对象。
** 用于处理可变数量的关键字参数或解包字典。
它们可以单独使用，也可以结合使用，提供了灵活的函数参数处理方式。

如果你有更多具体问题，欢迎继续提问！

Pydantic 的Filed函数

Pydantic 的Filed函数，用于在数据模型中定义字段的额外信息、验证和约束。它可以用于设置字段的默认值、限制字段的取值范围、添加字段描述等。以下是一些常用的 Field 用法：

设置默认值

from pydantic import BaseModel, Field

class MyClass(BaseModel):
 my_field: str = Field(default="Hello, World!")

添加描述：

from pydantic import BaseModel, Field

class MyClass(BaseModel):
 my_field: str = Field(..., description="This is a sample field.")

在这个例子中，为 my_field 添加了描述 “This is a sample field.”。

添加验证约束：

from pydantic import BaseModel, Field

class MyClass(BaseModel):
 my_field: int = Field(..., gt=0, lt=10)

在这个例子中，my_field 的值必须大于 0 且小于 10，否则会引发验证错误。

使用自定义验证器：

from pydantic import BaseModel, Field, validator

class MyClass(BaseModel):
 my_field: str = Field(...)

 @validator("my_field")
 def check_length(cls, value):
 if len(value) < 5:
 raise ValueError("The length of my_field must be at least 5 characters.")
 return value

在这个例子中，添加了一个自定义验证器 check_length，用于检查 my_field 的长度。如果长度小于 5 个字符，将引发一个值错误。

这些只是 Field 的一些基本用法。使用 Pydantic，您可以根据需要添加更多自定义验证和约束，以确保数据模型中的字段符合预期。

python 中的`async` 和 `await` （异步编程）

异步操作（Asynchronous Operation）是指一种非阻塞的操作方式，允许程序在等待某些耗时任务（如 I/O 操作、网络请求等）完成的同时，继续执行其他任务。

在 Python 中，async 和 await 是用于处理异步编程的关键字。它们允许你编写非阻塞的代码，特别适用于 I/O 密集型任务（如网络请求、文件读写等），以提高程序的并发性能。

1. async的作用 async 关键字用于定义一个异步函数（也称为协程）。异步函数与普通函数不同，它不会立即执行，而是返回一个协程对象，该对象可以在事件循环中被调度执行。示例：

import asyncio

async def my_coroutine():
 print("Hello")
 await asyncio.sleep(1) # 模拟异步操作
 print("World")

# 调用异步函数并不会直接执行它，而是返回一个协程对象
coro = my_coroutine()

# 需要通过事件循环来运行协程
asyncio.run(coro)

在这个例子中，my_coroutine 是一个异步函数，使用 async 定义。调用 my_coroutine() 并不会立即执行函数体中的代码，而是返回一个协程对象。要真正执行这个协程，你需要使用 asyncio.run() 或者将其放入事件循环中。

2. await 的作用 await 关键字用于等待一个异步操作完成。它只能在 async 函数内部使用，并且后面必须跟一个可等待对象（如协程、任务、Future 等）。当遇到 await 时，当前协程会暂停执行，直到等待的操作完成。

示例：

import asyncio

async def fetch_data():
 print("开始获取数据...")
 await asyncio.sleep(2) # 模拟耗时的 I/O 操作
 print("数据获取完成")
 return {"data": "some data"}

async def main():
 result = await fetch_data() # 等待 fetch_data 协程完成
 print(f"结果: {result}")

asyncio.run(main())

在这个例子中，await fetch_data() 会让 main 协程暂停，直到 fetch_data 协程完成并返回结果。

3. 其他类似的参数或概念 除了 async 和 await，Python 的异步编程还涉及以下几个重要概念和工具：

asyncio 模块 asyncio 是 Python 标准库中的一个模块，提供了实现异步编程所需的基础设施，包括事件循环、任务调度等。常见的功能包括：

asyncio.run()：运行顶层的协程。
asyncio.create_task()：创建一个任务，用于并发执行多个协程。
asyncio.gather()：并发运行多个协程并收集结果。
asyncio.sleep()：模拟异步延迟。

示例：

import asyncio

async def task1():
 print("Task 1 开始")
 await asyncio.sleep(1)
 print("Task 1 完成")

async def task2():
 print("Task 2 开始")
 await asyncio.sleep(2)
 print("Task 2 完成")

async def main():
 # 并发执行两个任务
 await asyncio.gather(task1(), task2())

asyncio.run(main())

async for 和 async with

async for：用于异步迭代器，适用于需要异步生成数据的场景。
async with：用于异步上下文管理器，适用于需要异步资源管理的场景。

示例：async for

import asyncio

class AsyncIterable:
 def __aiter__(self):
 self.data = [1, 2, 3]
 return self

 async def __anext__(self):
 if not self.data:
 raise StopAsyncIteration
 await asyncio.sleep(1) # 模拟异步操作
 return self.data.pop(0)

async def main():
 async for item in AsyncIterable():
 print(item)

asyncio.run(main())

示例：async with

import asyncio

class AsyncContextManager:
 async def __aenter__(self):
 print("进入上下文")
 await asyncio.sleep(1)
 return self

 async def __aexit__(self, exc_type, exc_val, exc_tb):
 print("退出上下文")
 await asyncio.sleep(1)

async def main():
 async with AsyncContextManager() as manager:
 print("在上下文中执行")

asyncio.run(main())

concurrent.futures 模块 虽然不属于 async/await 的范畴，但 concurrent.futures 提供了另一种实现并发的方式，特别是通过线程池或进程池执行任务。

示例：

from concurrent.futures import ThreadPoolExecutor
import time

def blocking_task(seconds):
 print(f"开始阻塞任务 {seconds} 秒")
 time.sleep(seconds)
 print(f"阻塞任务完成")
 return seconds

def main():
 with ThreadPoolExecutor() as executor:
 future = executor.submit(blocking_task, 2)
 print("主线程继续执行其他任务")
 result = future.result() # 阻塞等待结果
 print(f"结果: {result}")

main()

总结

async 用于定义异步函数，返回协程对象。
await 用于等待异步操作完成，只能在 async 函数中使用。
其他相关概念包括 asyncio 模块、async for、async with 等，它们共同构成了 Python 异步编程的核心工具。

Python项目生成requirements.txt文件

1.使用pipreqs生成requirement.txt

```python
pip install pipreqs
pipreqs . # .表示当前路径
```
遇到问题
**1. 遇到编码错误问题**
> ![在这里插入图片描述](https://i-blog.csdnimg.cn/blog_migrate/9b7c8a250113823a277df162dc9e1b20.png)
> 解决方法
> ```python pipreqs --encoding=iso-8859-1 ```
**2. 遇到'pipreqs' is not recognized as an internal or external command,operable program or batch file.**
> 使用以下命令：
> `python -m pipreqs.pipreqs . --encoding=utf8 --force`

pipreqs –help

pipreqs - Generate pip requirements.txt file based on imports

Usage:
 pipreqs [options] [<path>]

Arguments:
 <path> The path to the directory containing the application
 files for which a requirements file should be
 generated (defaults to the current working
 directory).

Options:
 --use-local Use ONLY local package info instead of querying PyPI.
 --pypi-server <url> Use custom PyPi server.
 --proxy <url> Use Proxy, parameter will be passed to requests
 library. You can also just set the environments
 parameter in your terminal:
 $ export HTTP_PROXY="http://10.10.1.10:3128"
 $ export HTTPS_PROXY="https://10.10.1.10:1080"
 --debug Print debug information
 --ignore <dirs>... Ignore extra directories, each separated by a comma
 --no-follow-links Do not follow symbolic links in the project
 --encoding <charset> Use encoding parameter for file open
 --savepath <file> Save the list of requirements in the given file
 --print Output the list of requirements in the standard
 output
 --force Overwrite existing requirements.txt
 --diff <file> Compare modules in requirements.txt to project
 imports
 --clean <file> Clean up requirements.txt by removing modules
 that are not imported in project
 --mode <scheme> Enables dynamic versioning with <compat>,
 <gt> or <non-pin> schemes.
 <compat> | e.g. Flask~=1.1.2
 <gt> | e.g. Flask>=1.1.2
 <no-pin> | e.g. Flask
 --scan-notebooks Look for imports in jupyter notebook files.

遇到的问题

导入路径问题（原本main函数调用它，现在直接运行该文件，导包路径变化）

问题描述 在运行 Python 文件时，可能会遇到以下错误：

ModuleNotFoundError: No module named 'utils'

原因：

Python 的模块导入机制依赖于当前工作目录和 sys.path 中的路径。
当直接运行某个文件时，Python 会将该文件所在目录添加到 sys.path，而不是项目的根目录，导致无法正确导入其他模块。

解决方法 (一般再临时调试时候会出现，我推荐使用方法三）

方法 1：修改 sys.path 在代码中手动将项目的根目录添加到 sys.path：

import sys
import os

current_dir = os.path.dirname(os.path.abspath(__file__))
project_root = os.path.abspath(os.path.join(current_dir, '..'))

if project_root not in sys.path:
 sys.path.append(project_root)

from utils.subgraph_extraction import *

优点：简单直接，适合快速调试。
缺点：不够优雅，可能不适合复杂项目。

方法 2：使用相对导入如果项目是一个包（包含 __init__.py），可以使用相对导入：

from ..utils.subgraph_extraction import *

然后从项目的根目录运行脚本：

python -m utils.Core_functions

优点：符合 Python 包管理规范，适合大型项目。
缺点：不能直接运行单个文件，需要调整运行方式。

方法 3：设置环境变量 PYTHONPATH 在运行脚本前，设置环境变量 PYTHONPATH 指向项目的根目录。比如这样，我原本再根目录调用这个文件，没有问题，但是现在我想要进入这个文件里面运行它就会报错：这样再运行就没问题了

Linux/MacOS：

export PYTHONPATH=/path/to/your/project
python utils/Core_functions.py

Windows（命令提示符）：

set PYTHONPATH=C:\path\to\your\project
python utils\Core_functions.py

Windows（PowerShell）：

$env:PYTHONPATH = "C:\path\to\your\project"
python utils\Core_functions.py

优点：无需修改代码，适合团队协作。
缺点：需要每次运行前设置环境变量。

方法 4：使用 IDE 配置工作目录通过 IDE 配置运行时的工作目录为项目的根目录。

PyCharm：
1. 打开运行配置（Run/Debug Configurations）。
2. 设置 Working Directory 为项目的根目录。

VSCode：在 .vscode/launch.json 中添加以下配置：

{
 "version": "0.2.0",
 "configurations": [
 {
 "name": "Run Core_functions",
 "type": "python",
 "request": "launch",
 "program": "utils/Core_functions.py",
 "cwd": "${workspaceFolder}"
 }
 ]
}

优点：适合开发环境，无需修改代码。
缺点：仅适用于特定 IDE。

方法 5：重构项目结构将所有模块组织为一个包，并通过入口脚本（如 main.py）统一调用。例如：

project/
├── main.py
├── utils/
│ ├── __init__.py
│ ├── Core_functions.py
│ └── subgraph_extraction.py

在 main.py 中：

from utils.Core_functions import some_function

if __name__ == "__main__":
 some_function()

然后始终通过 main.py 运行项目：

python main.py

优点：规范项目结构，避免路径问题。
缺点：需要对项目进行一定的重构。

总结

临时调试：推荐 方法 1 或 方法 3。
长期维护：推荐 方法 2 或 方法 5。
IDE 开发：推荐 方法 4。

根据具体需求选择合适的方法即可！

SQLAlchemy简单入门

Tue, 11 Mar 2025 09:43:28 +0800

基础使用

SQLAlchemy 是 Python 中最流行的 ORM（对象关系映射）工具，用于操作数据库。它分为两部分：SQLAlchemy Core（底层 SQL 操作）和 SQLAlchemy ORM（对象映射）。本教程将涵盖两者的基础知识和示例。

1. 安装 SQLAlchemy

首先，您需要安装 SQLAlchemy 和数据库驱动（例如 SQLite、MySQL 或 PostgreSQL）。这里以 SQLite 为例，因为它无需额外安装数据库服务器。

pip install sqlalchemy

如果使用 MySQL 或 PostgreSQL，需要安装对应的驱动：

MySQL: pip install pymysql
PostgreSQL: pip install psycopg2

2. SQLAlchemy Core 基础

SQLAlchemy Core 提供了一种接近原生 SQL 的方式来操作数据库。

2.1 连接数据库

首先，我们需要创建一个引擎（Engine）来连接数据库。

from sqlalchemy import create_engine

# SQLite 数据库（文件存储在本地）
engine = create_engine('sqlite:///example.db', echo=True) # echo=True 打印 SQL 日志

2.2 定义表结构

使用 Table 对象定义数据库表。

from sqlalchemy import Table, Column, Integer, String, MetaData

# 创建元数据对象
metadata = MetaData()

# 定义 users 表
users = Table(
 'users',
 metadata,
 Column('id', Integer, primary_key=True),
 Column('name', String),
 Column('age', Integer)
)

2.3 创建表

将定义的表结构应用到数据库中。

# 创建所有表
metadata.create_all(engine)

2.4 插入数据

使用 insert() 方法插入数据。

from sqlalchemy import insert

# 插入单条数据
with engine.connect() as connection:
 stmt = insert(users).values(name='Alice', age=25)
 connection.execute(stmt)
 connection.commit()

# 插入多条数据
with engine.connect() as connection:
 stmt = insert(users).values([
 {'name': 'Bob', 'age': 30},
 {'name': 'Charlie', 'age': 35}
 ])
 connection.execute(stmt)
 connection.commit()

2.5 查询数据

使用 select() 方法查询数据。

from sqlalchemy import select

with engine.connect() as connection:
 stmt = select(users).where(users.c.age > 25) # 查询年龄大于 25 的用户
 result = connection.execute(stmt)
 for row in result:
 print(row) # 输出：(id, name, age)

2.6 更新和删除

更新和删除数据分别使用 update() 和 delete()。

from sqlalchemy import update, delete

with engine.connect() as connection:
 # 更新
 stmt = update(users).where(users.c.name == 'Alice').values(age=26)
 connection.execute(stmt)
 connection.commit()

 # 删除
 stmt = delete(users).where(users.c.name == 'Charlie')
 connection.execute(stmt)
 connection.commit()

3. SQLAlchemy ORM 基础

SQLAlchemy ORM 将数据库表映射为 Python 类，提供更面向对象的方式。

3.1 定义模型

使用声明式基类（Declarative Base）定义表结构。

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import declarative_base, Session

# 创建基类
Base = declarative_base()

# 定义 User 类
class User(Base):
 __tablename__ = 'users'
 id = Column(Integer, primary_key=True)
 name = Column(String)
 age = Column(Integer)

 def __repr__(self):
 return f"<User(name='{self.name}', age={self.age})>"

# 创建引擎和表
engine = create_engine('sqlite:///example_orm.db', echo=True)
Base.metadata.create_all(engine)

3.2 添加数据

使用会话（Session）操作数据。

# 创建会话
with Session(engine) as session:
 # 添加单个用户
 alice = User(name='Alice', age=25)
 session.add(alice)

 # 添加多个用户
 session.add_all([
 User(name='Bob', age=30),
 User(name='Charlie', age=35)
 ])

 # 提交事务
 session.commit()

3.3 查询数据

使用 query 或 select 进行查询。

with Session(engine) as session:
 # 查询所有用户
 users = session.query(User).all()
 for user in users:
 print(user)

 # 过滤查询
 older_users = session.query(User).filter(User.age > 25).all()
 for user in older_users:
 print(user)

3.4 更新和删除

直接修改对象或使用 delete()。

with Session(engine) as session:
 # 更新
 alice = session.query(User).filter_by(name='Alice').first()
 alice.age = 26
 session.commit()

 # 删除
 charlie = session.query(User).filter_by(name='Charlie').first()
 session.delete(charlie)
 session.commit()

4. 关系（Relationships）

SQLAlchemy ORM 支持表之间的关系，例如一对多。

4.1 定义关系模型

以下是一个用户（User）和地址（Address）的一对多关系示例。

from sqlalchemy import ForeignKey
from sqlalchemy.orm import relationship

class User(Base):
 __tablename__ = 'users'
 id = Column(Integer, primary_key=True)
 name = Column(String)
 addresses = relationship('Address', back_populates='user') # 一对多关系

class Address(Base):
 __tablename__ = 'addresses'
 id = Column(Integer, primary_key=True)
 email = Column(String)
 user_id = Column(Integer, ForeignKey('users.id'))
 user = relationship('User', back_populates='addresses') # 多对一关系

# 创建表
Base.metadata.create_all(engine)

4.2 操作关系数据

添加用户及其地址。

with Session(engine) as session:
 user = User(name='Alice')
 user.addresses = [Address(email='alice@example.com'), Address(email='alice2@example.com')]
 session.add(user)
 session.commit()

 # 查询
 alice = session.query(User).filter_by(name='Alice').first()
 print(alice.addresses) # 输出 Alice 的所有地址

5. 高级功能

5.1 事务管理

SQLAlchemy 会话默认支持事务。如果需要手动控制：

with Session(engine) as session:
 try:
 session.add(User(name='Test'))
 session.commit()
 except Exception as e:
 session.rollback()
 print(f"Error: {e}")

5.2 原生 SQL

如果需要执行原生 SQL：

with engine.connect() as connection:
 result = connection.execute("SELECT * FROM users WHERE age > 25")
 for row in result:
 print(row)

5.3 连接池

SQLAlchemy 默认使用连接池管理数据库连接，可以通过 pool_size 和 max_overflow 配置：

engine = create_engine('sqlite:///example.db', pool_size=5, max_overflow=10)

6. 总结

Core 适合需要灵活 SQL 的场景。
ORM 适合面向对象编程，简化数据库操作。
通过 engine、metadata 和 session，SQLAlchemy 提供了强大的数据库操作能力。

Model类的使用


class Subscription(db.Model):
 id = db.Column(db.Integer, primary_key=True)
 name = db.Column(db.String(100), nullable=False)
 url = db.Column(db.String(500), nullable=False)
 category = db.Column(db.String(50), nullable=False)
 check_frequency = db.Column(db.String(50), nullable=False)
 last_checked = db.Column(db.DateTime, nullable=True)
 last_updated = db.Column(db.DateTime, nullable=True)
 status = db.Column(db.String(20), default='active')
 created_at = db.Column(db.DateTime, default=datetime.utcnow)

 # Foreign keys
 user_id = db.Column(db.Integer, db.ForeignKey('user.id'), nullable=False)

 # Relationships
 selectors = db.relationship('Selector', backref='subscription', lazy='dynamic', cascade='all, delete-orphan')
 changes = db.relationship('Change', backref='subscription', lazy='dynamic', cascade='all, delete-orphan')

 def __repr__(self):
 return f'<Subscription {self.name}>'

您提供的代码片段展示了一个使用 Flask-SQLAlchemy（基于 SQLAlchemy 的扩展）定义的 Subscription 模型类。这个类定义了一个数据库表结构，并包含了字段、外键和关系。以下是对这个类的详细解析：

前置条件

db = SQLAlchemy()：这是一个 Flask-SQLAlchemy 的实例，通常在 Flask 应用中初始化。它封装了 SQLAlchemy 的功能，并与 Flask 应用上下文绑定。

需要导入必要的模块，例如：

from flask_sqlalchemy import SQLAlchemy
from datetime import datetime

类定义

class Subscription(db.Model):

Subscription 是一个继承自 db.Model 的类，db.Model 是 Flask-SQLAlchemy 提供的基类，用于声明数据库模型。
这个类会映射到数据库中的一个表，默认表名为类名的小写形式（subscription）。如果想自定义表名，可以添加 __tablename__ = 'custom_name'。

字段（Columns）

每个字段使用 db.Column 定义，指定数据类型和约束条件。以下是逐一解析：

id = db.Column(db.Integer, primary_key=True)
- 类型：Integer（整数）。
- 约束：primary_key=True 表示这是主键，唯一标识每一行。通常会自动递增（SQLite 和 PostgreSQL 默认支持）。
- 作用：作为表的主键，用于唯一标识每个订阅记录。
name = db.Column(db.String(100), nullable=False)
- 类型：String(100)（长度最多 100 个字符的字符串）。
- 约束：nullable=False 表示该字段不能为空，必须提供值。
- 作用：存储订阅的名称，例如“新闻订阅”。
url = db.Column(db.String(500), nullable=False)
- 类型：String(500)（长度最多 500 个字符的字符串）。
- 约束：nullable=False 表示不能为空。
- 作用：存储订阅的 URL，例如某个网站的地址。
category = db.Column(db.String(50), nullable=False)
- 类型：String(50)（长度最多 50 个字符的字符串）。
- 约束：nullable=False 表示不能为空。
- 作用：存储订阅的类别，例如“科技”或“娱乐”。
check_frequency = db.Column(db.String(50), nullable=False)
- 类型：String(50)。
- 约束：nullable=False 表示不能为空。
- 作用：存储检查频率，例如“daily”或“weekly”。（注：如果频率是固定的选项，可以考虑使用 db.Enum 类型。）
last_checked = db.Column(db.DateTime, nullable=True)
- 类型：DateTime（日期时间类型）。
- 约束：nullable=True 表示可以为空。
- 作用：记录上一次检查订阅的时间，可能为空（例如新创建时尚未检查）。
last_updated = db.Column(db.DateTime, nullable=True)
- 类型：DateTime。
- 约束：nullable=True 表示可以为空。
- 作用：记录订阅内容最后更新的时间，可能为空（例如未发生变化）。
status = db.Column(db.String(20), default='active')
- 类型：String(20)。
- 约束：default='active' 表示默认值为“active”。
- 作用：存储订阅的状态，例如“active”或“inactive”。
created_at = db.Column(db.DateTime, default=datetime.utcnow)
- 类型：DateTime。
- 约束：default=datetime.utcnow 表示默认值为当前 UTC 时间（注意：这里使用的是函数 datetime.utcnow 而不是 datetime.utcnow()，因为 SQLAlchemy 需要一个可调用的对象）。
- 作用：记录订阅创建的时间。

外键（Foreign Key）

user_id = db.Column(db.Integer, db.ForeignKey('user.id'), nullable=False)

类型：Integer。
外键：db.ForeignKey('user.id') 表示这是一个外键，引用 user 表的 id 列。
约束：nullable=False 表示不能为空，必须关联一个用户。
作用：将 Subscription 与 User 表关联，表示每个订阅属于某个用户。

注意：这里假设存在一个 User 模型类，定义了 id 字段，例如：

class User(db.Model):
 id = db.Column(db.Integer, primary_key=True)
 # 其他字段...

关系（Relationships）

SQLAlchemy ORM 支持表之间的关系，这里定义了两个一对多关系：

selectors = db.relationship('Selector', backref='subscription', lazy='dynamic', cascade='all, delete-orphan')
- 目标：Selector 是一个关联的模型类，表示“选择器”（可能用于指定订阅内容的提取规则）。
- backref：'subscription' 表示在 Selector 类中可以通过 subscription 属性反向访问对应的 Subscription 对象。
- lazy：'dynamic' 表示返回一个动态查询对象（而不是直接加载所有数据），可以用 .all() 或 .filter() 等方法进一步操作。
- cascade：'all, delete-orphan' 表示所有操作（包括删除）都会级联到相关记录，且如果 Subscription 被删除，所有关联的 Selector 也会被删除（孤儿删除）。
- 作用：一个订阅可以有多个选择器（一对多关系）。
假设的 Selector 类：
```
class Selector(db.Model):
 id = db.Column(db.Integer, primary_key=True)
 subscription_id = db.Column(db.Integer, db.ForeignKey('subscription.id'))
 # 其他字段...
```
changes = db.relationship('Change', backref='subscription', lazy='dynamic', cascade='all, delete-orphan')
- 目标：Change 表示“变更”记录（可能用于跟踪订阅内容的更改）。
- backref：'subscription' 允许从 Change 反向访问 Subscription。
- lazy：'dynamic' 同上。
- cascade：'all, delete-orphan' 同上。
- 作用：一个订阅可以有多个变更记录（一对多关系）。
假设的 Change 类：
```
class Change(db.Model):
 id = db.Column(db.Integer, primary_key=True)
 subscription_id = db.Column(db.Integer, db.ForeignKey('subscription.id'))
 # 其他字段...
```

字符串表示方法

def __repr__(self):
 return f'<Subscription {self.name}>'

定义了对象的字符串表示形式。
调用 print(subscription) 时会显示类似 <Subscription News> 的输出，便于调试。

整体功能解析

Subscription 类描述了一个订阅系统中的核心实体，可能用于一个订阅管理或内容监控应用：

字段：记录订阅的基本信息（名称、URL、类别等）、状态和时间戳。
外键：通过 user_id 与用户关联，确保每个订阅属于某个用户。
关系：
- selectors：允许为订阅定义多个选择器（例如 CSS 选择器或 XPath，用于提取网页内容）。
- changes：记录订阅内容的变更历史。
级联删除：当订阅被删除时，关联的 selectors 和 changes 也会自动删除。

示例用法

假设在 Flask 应用中初始化并使用这个模型：

from flask import Flask
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'
db = SQLAlchemy(app)

# 定义模型（如上所述）

# 创建表
with app.app_context():
 db.create_all()

# 添加数据
with app.app_context():
 new_subscription = Subscription(
 name='Tech News',
 url='https://example.com',
 category='Tech',
 check_frequency='daily',
 user_id=1
 )
 db.session.add(new_subscription)
 db.session.commit()

# 查询
with app.app_context():
 subscription = Subscription.query.filter_by(name='Tech News').first()
 print(subscription) # 输出: <Subscription Tech News>
 print(subscription.selectors.all()) # 查询关联的 selectors

注意事项

Flask 上下文：Flask-SQLAlchemy 需要在应用上下文中操作（如 with app.app_context():）。
外键完整性：确保 user_id 引用的 User 记录存在，否则会抛出异常。
动态加载：lazy='dynamic' 适合大数据量场景，但需要显式调用 .all() 或其他方法来获取数据。

SQLAlchemy Relationships 教程：理解数据库表之间的关系

在这篇教程中，我们将探讨如何使用 SQLAlchemy（一个流行的 Python ORM 工具）中的 db.relationship 来定义和操作数据库表之间的关系。我们将以一个简单的订阅监控系统为例，逐步讲解代码，并展示如何通过关系字段简化数据库操作。

当前日期是 2025年3月10日，我们将使用最新版本的 SQLAlchemy 语法。

示例背景：订阅监控系统

假设我们正在构建一个系统，用于监控网页的变化。系统中包含以下三个表：

Subscription（订阅）：表示用户订阅的网页监控任务。
Selector（选择器）：定义订阅中要监控的网页元素（如某个 <div> 或 <p>）。
Change（变化）：记录选择器检测到的变化（如内容更新或元素出现/消失）。

这些表之间存在关联：

一个 Subscription 可以有多个 Selector 和多个 Change（一对多）。
一个 Selector 可以有多个 Change（一对多）。
Change 属于某个 Subscription 和某个 Selector。

我们将使用 SQLAlchemy 的 db.relationship 来定义这些关系。

模型代码

以下是完整的模型定义，我们将在后面逐一讲解其中的 Relationships。

from app import db
from datetime import datetime

# 订阅表
class Subscription(db.Model):
 id = db.Column(db.Integer, primary_key=True)
 name = db.Column(db.String(100), nullable=False)
 url = db.Column(db.String(500), nullable=False)
 category = db.Column(db.String(50), nullable=False)
 check_frequency = db.Column(db.String(50), nullable=False)
 last_checked = db.Column(db.DateTime, nullable=True)
 last_updated = db.Column(db.DateTime, nullable=True)
 status = db.Column(db.String(20), default='active')
 created_at = db.Column(db.DateTime, default=datetime.utcnow)

 # 外键
 user_id = db.Column(db.Integer, db.ForeignKey('user.id'), nullable=False)

 # 关系字段
 selectors = db.relationship('Selector', backref='subscription', lazy='dynamic', cascade='all, delete-orphan')
 changes = db.relationship('Change', backref='subscription', lazy='dynamic', cascade='all, delete-orphan')

 def __repr__(self):
 return f'<Subscription {self.name}>'

# 选择器表
class Selector(db.Model):
 id = db.Column(db.Integer, primary_key=True)
 name = db.Column(db.String(100), nullable=False)
 selector_path = db.Column(db.String(500), nullable=False)
 monitor_type = db.Column(db.String(50), nullable=False) # content_change, element_presence, attribute_change
 keywords = db.Column(db.String(500), nullable=True)
 last_content = db.Column(db.Text, nullable=True)
 created_at = db.Column(db.DateTime, default=datetime.utcnow)

 # 外键
 subscription_id = db.Column(db.Integer, db.ForeignKey('subscription.id'), nullable=False)

 def __repr__(self):
 return f'<Selector {self.name} for {self.subscription_id}>'

# 变化表
class Change(db.Model):
 id = db.Column(db.Integer, primary_key=True)
 selector_id = db.Column(db.Integer, db.ForeignKey('selector.id'), nullable=False)
 old_content = db.Column(db.Text, nullable=True)
 new_content = db.Column(db.Text, nullable=True)
 change_type = db.Column(db.String(50), nullable=False) # content_change, element_appeared, element_disappeared, attribute_change
 created_at = db.Column(db.DateTime, default=datetime.utcnow)

 # 外键
 subscription_id = db.Column(db.Integer, db.ForeignKey('subscription.id'), nullable=False)

 # 关系字段
 selector = db.relationship('Selector')

 def __repr__(self):
 return f'<Change {self.id} for {self.subscription_id}>'

什么是 `db.relationship`？

db.relationship 是 SQLAlchemy 提供的一种工具，用于定义数据库表之间的关系。它允许你：

通过对象属性访问关联的数据，而无需手动编写 SQL 查询。
支持一对多、多对一等关系。
通过 backref 参数实现双向访问。

在我们的代码中，db.relationship 连接了 Subscription、Selector 和 Change 三个表。

逐步解析代码中的 `Relationships`

`Subscription` 中的关系

在 Subscription 类中定义了两个关系字段：

`selectors = db.relationship('Selector', backref='subscription', lazy='dynamic', cascade='all, delete-orphan')`

含义：
- Subscription 和 Selector 是一对多关系。一个订阅可以有多个选择器。
- Selector 表中的 subscription_id 是外键，指向 Subscription 的 id。
参数解析：
- 'Selector'：关联的目标模型类。
- backref='subscription'：在 Selector 中生成一个反向引用属性 subscription，允许从 Selector 访问其所属的 Subscription。
- lazy='dynamic'：延迟加载，返回一个动态查询对象，需要手动调用 .all() 或其他方法获取数据。
- cascade='all, delete-orphan'：当 Subscription 被删除时，其所有 Selector 也会被删除；如果某个 Selector 失去了与 Subscription 的关联，也会被删除。

用法示例：

sub = Subscription.query.get(1) # 获取 ID 为 1 的订阅
all_selectors = sub.selectors.all() # 获取所有相关选择器
for selector in all_selectors:
 print(selector.name)

`changes = db.relationship('Change', backref='subscription', lazy='dynamic', cascade='all, delete-orphan')`

含义：
- Subscription 和 Change 是一对多关系。一个订阅可以有多个变化记录。
参数解析：
- 同上，backref 和 cascade 的作用类似。

用法示例：

sub = Subscription.query.get(1)
all_changes = sub.changes.all() # 获取所有变化记录
for change in all_changes:
 print(f"Change: {change.old_content} -> {change.new_content}")

`Change` 中的关系

`selector = db.relationship('Selector')`

含义：
- Change 和 Selector 是一对多关系。一个选择器可以有多个变化记录。
- Change 表中的 selector_id 是外键，指向 Selector 的 id。
参数解析：
- 'Selector'：关联的目标模型类。
- 默认 lazy='select'：在访问时自动加载关联的 Selector 对象。
- 没有 backref，因此无法从 Selector 直接访问其所有 Change（需要手动查询）。

用法示例：

change = Change.query.get(1) # 获取 ID 为 1 的变化记录
related_selector = change.selector # 获取对应的选择器
print(related_selector.name)

`Relationships` 的核心作用

通过 db.relationship，我们可以：

简化数据访问：
- 无需编写复杂的 SQL JOIN 查询，直接通过对象属性访问关联数据。
支持双向导航：
- 例如，从 Subscription 到 Selector（sub.selectors），或从 Selector 到 Subscription（selector.subscription）。
自动管理外键：
- 创建对象时，SQLAlchemy 会自动处理外键赋值。
级联操作：
- 删除 Subscription 时，其所有 Selector 和 Change 也会被删除。

实战示例

让我们通过一个完整示例展示 Relationships 的用法。

创建数据

# 创建一个订阅
sub = Subscription(
 name="Tech News",
 url="https://example.com/news",
 category="News",
 check_frequency="daily",
 user_id=1
)

# 创建两个选择器
selector1 = Selector(
 name="Headline",
 selector_path="div.headline",
 monitor_type="content_change",
 subscription=sub # 自动关联
)
selector2 = Selector(
 name="Summary",
 selector_path="p.summary",
 monitor_type="content_change",
 subscription=sub
)

# 创建一个变化记录
change = Change(
 selector_id=selector1.id,
 old_content="Old Headline",
 new_content="New Headline",
 change_type="content_change",
 subscription=sub
)

# 保存到数据库
db.session.add(sub)
db.session.commit()

查询数据

# 获取订阅
sub = Subscription.query.filter_by(name="Tech News").first()

# 查看所有选择器
print("Selectors:")
for selector in sub.selectors:
 print(f"- {selector.name}: {selector.selector_path}")

# 查看所有变化
print("Changes:")
for change in sub.changes:
 print(f"- {change.old_content} -> {change.new_content}")

# 从变化反向访问选择器
first_change = sub.changes.first()
print(f"Change belongs to selector: {first_change.selector.name}")

输出示例：

Selectors:
- Headline: div.headline
- Summary: p.summary
Changes:
- Old Headline -> New Headline
Change belongs to selector: Headline

总结

db.relationship 是 SQLAlchemy 中定义表关系的核心工具。
它通过外键建立联系，支持对象化导航和级联操作。
参数如 backref、lazy 和 cascade 提供了灵活的控制方式。
在实际开发中，合理使用 Relationships 可以大大简化代码，提高开发效率。

【python】init.py为什么要写

Thu, 06 Mar 2025 21:15:32 +0800

参考：

https://www.bilibili.com/video/BV1QA94YPEMK

特性

如果两个文件在同一个路径下，这里是一个main，一个moduleA，当main中import moduleA，那么moduleA中的代码就会执行。

但是如果ModelA在一个package里面，然后main中import packageA，那么modelA中的代码不会执行。

如果package中有一个__init__.py，那么import package，init.py中的代码就会执行。

说明

在 Python 中，__init__.py 文件的主要作用是标记一个目录为 Python 的包（package）。它的存在告诉 Python 解释器，这个目录不仅仅是一个普通的文件夹，而是包含模块（modules）或子包的集合，可以被导入使用。以下是一些具体原因和用途：

包的标识 （只在py3.3之前）如果一个目录里没有 __init__.py，Python 不会把它当作包，你就无法通过 import 语句导入里面的模块。比如说，有个目录结构：
```
my_package/
 __init__.py
 module1.py
 module2.py
```
因为有 __init__.py，你可以用 import my_package.module1 来导入 module1.py。
初始化代码
__init__.py 可以包含代码，在包被导入时自动执行。比如，你可以在里面定义一些变量、函数，或者导入子模块，方便用户使用。例如：
```
# my_package/__init__.py
from .module1 import some_function
version = "1.0"
```
这样，导入包时就能直接用 my_package.some_function() 或 my_package.version。
控制导入行为
你可以通过 __init__.py 指定当用户用 from my_package import * 时暴露哪些内容，用 __all__ 变量来定义：
```
# my_package/__init__.py
__all__ = ['module1', 'module2']
from . import module1, module2
```
历史背景
在 Python 3.3 之前，__init__.py 是必须的，不然目录不会被识别为包。从 Python 3.3 开始引入了“命名空间包”（namespace packages），允许没有 __init__.py 的目录也能作为包的一部分，但 __init__.py 仍然是组织代码的常用方式。

为什么需要写它？
简单来说，写 __init__.py 是为了让你的代码更有结构化、可重用性更强，尤其是在开发大型项目或库时。它就像一个“门面”，帮你管理模块的组织和初始化。

如果你只是随便写点小脚本，可能用不到它。但要是想把代码打包分享给别人，或者维护一个复杂的项目，__init__.py 就很有必要了。

有啥具体场景困扰你吗？可以告诉我，我帮你细化一下！

python的命名规范

Thu, 06 Mar 2025 11:26:47 +0800

Python 的命名规范主要遵循 PEP 8（Python Enhancement Proposal 8），这是 Python 官方推荐的风格指南。以下是 PEP 8 中关于命名规范的主要内容，结合实际开发中的常见实践，我为你整理了一个清晰的说明：

1. 基本原则

可读性优先：命名应该清晰、直观，能够反映变量、函数或类的用途。
一致性：在项目中保持命名风格一致。

2. 命名风格

根据不同的对象类型，Python 使用不同的命名约定：

(1) 变量 (Variables)

规则：使用小写字母，多个单词用下划线 _ 分隔（蛇形命名法，snake_case）。
示例：
```
user_name = "Alice"
total_count = 42
```
注意：避免使用单个字符（如 x、i），除非是在循环或数学公式中。

(2) 常量 (Constants)

规则：使用全大写字母，多个单词用下划线 _ 分隔。
示例：
```
MAX_SIZE = 100
PI = 3.14159
```
注意：通常用于模块级别的全局常量。

(3) 函数 (Functions) 和方法 (Methods)

规则：与变量相同，使用小写字母，多个单词用下划线 _ 分隔（snake_case）。

示例：

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

def get_user_info(user_id):
 pass

(4) 类 (Classes)

规则：使用驼峰命名法（CapWords 或 PascalCase），即每个单词首字母大写，不用下划线。

示例：

class MyClass:
 pass

class UserProfile:
 pass

(5) 模块 (Modules) 和包 (Packages)

规则：使用小写字母，尽量短且有意义，多个单词可以用下划线 _ 分隔（但更推荐单个单词）。

示例：

# 模块文件
mymodule.py
data_processing.py

# 包目录
mypackage/

(6) 私有标识符

规则：
- 单下划线 _ 开头：表示“弱私有”，仅作为约定，提示开发者这是一个内部实现细节。
- 双下划线 __ 开头：表示“强私有”，会触发 Python 的名称改编（name mangling），用于类中避免子类覆盖。

示例：

_internal_variable = 10 # 弱私有
class MyClass:
 __private_field = 20 # 强私有

(7) 特殊情况

单下划线 _：用作临时变量或占位符，通常在不需要具体变量名时使用。
```
for _ in range(5):
 print("Hello")
```

3. 命名建议

有意义的名字：避免无意义的缩写或模糊命名。
- 不好：a, tmp, data1
- 好：age, temp_file, user_data
避免与内置名称冲突：不要用 Python 关键字或内置函数名（如 list, str, print）作为变量名。
动词开头用于函数：函数名通常以动词开头，描述其行为。
- 示例：get_data(), process_input()
名词用于类和变量：类名和变量名通常是名词或名词短语。
- 示例：class Car, speed_limit

4. 其他注意事项

长度：名字不宜过长，但也不要为了短而牺牲可读性。
编码：避免使用非 ASCII 字符（如中文），除非有特殊需求且团队一致同意。
大小写敏感：Python 是大小写敏感的，myVar 和 myvar 是不同的标识符。

5. 示例代码

以下是一个综合示例，展示不同命名规范的应用：

# 模块名: data_processor.py

# 常量
MAX_RETRIES = 5

# 类
class DataProcessor:
 def __init__(self):
 self._buffer = [] # 弱私有
 self.__max_size = 100 # 强私有

 # 方法
 def process_data(self, input_data):
 result = self._calculate_sum(input_data)
 return result

 def _calculate_sum(self, numbers): # 弱私有方法
 return sum(numbers)

# 函数
def fetch_user_data(user_id):
 return {"id": user_id, "name": "Alice"}

# 变量
user_info = fetch_user_data(123)

6. 工具支持

你可以用工具（如 pylint 或 flake8）检查代码是否符合 PEP 8 规范。这些工具会提示命名问题。

总结来说，Python 的命名规范旨在提高代码的可读性和一致性。遵循 PEP 8，尤其是蛇形命名法（snake_case）和驼峰命名法（CapWords），是 Python 开发者的普遍共识。如果有具体代码场景需要进一步讨论，可以告诉我，我帮你分析！

python-类-类变量和实例变量

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

在 Python 中，类的变量可以分为类变量和实例变量。它们的定义方式和使用场景有所不同。以下是详细的说明：

1. 类变量

类变量是属于类本身的变量，所有该类的实例共享同一个类变量。它通常直接定义在类的内部，但在 __init__ 方法之外。

定义方式：

class MyClass:
 class_variable = "I am a class variable"

 def __init__(self, instance_variable):
 self.instance_variable = instance_variable

特点：

类变量可以通过类名直接访问，也可以通过实例访问。
如果通过实例修改类变量，实际上是为该实例创建了一个同名的实例变量，而不会影响类变量本身。

示例：

# 访问类变量
print(MyClass.class_variable) # 输出: I am a class variable

# 实例化对象
obj1 = MyClass("Instance 1")
obj2 = MyClass("Instance 2")

# 通过实例访问类变量
print(obj1.class_variable) # 输出: I am a class variable
print(obj2.class_variable) # 输出: I am a class variable

# 修改类变量
MyClass.class_variable = "Modified class variable"
print(obj1.class_variable) # 输出: Modified class variable
print(obj2.class_variable) # 输出: Modified class variable

# 注意：通过实例修改类变量
obj1.class_variable = "Modified by obj1"
print(obj1.class_variable) # 输出: Modified by obj1（这是实例变量）
print(obj2.class_variable) # 输出: Modified class variable（类变量未变）

2. 实例变量

实例变量是属于每个实例的变量，不同实例之间的实例变量互不影响。它们通常通过 __init__ 方法定义，并在实例化时初始化。

定义方式：

class MyClass:
 def __init__(self, instance_variable):
 self.instance_variable = instance_variable

特点：

实例变量只能通过实例访问，不能通过类名直接访问。
每个实例都有自己独立的实例变量。

示例：

# 实例化对象
obj1 = MyClass("Instance 1")
obj2 = MyClass("Instance 2")

# 访问实例变量
print(obj1.instance_variable) # 输出: Instance 1
print(obj2.instance_variable) # 输出: Instance 2

# 修改实例变量
obj1.instance_variable = "Modified Instance 1"
print(obj1.instance_variable) # 输出: Modified Instance 1
print(obj2.instance_variable) # 输出: Instance 2（不受影响）

3. 总结与建议

类变量：如果某个变量是所有实例共享的，或者需要在类级别上进行管理（如计数器、配置信息等），可以直接定义在类中。
实例变量：如果某个变量是每个实例独有的，应该通过 __init__ 方法定义。

示例结合类变量和实例变量：

class Car:
 # 类变量
 total_cars = 0

 def __init__(self, brand, model):
 # 实例变量
 self.brand = brand
 self.model = model
 # 更新类变量
 Car.total_cars += 1

 @classmethod
 def get_total_cars(cls):
 return cls.total_cars

# 创建实例
car1 = Car("Toyota", "Corolla")
car2 = Car("Honda", "Civic")

# 访问实例变量
print(car1.brand, car1.model) # 输出: Toyota Corolla
print(car2.brand, car2.model) # 输出: Honda Civic

# 访问类变量
print(Car.get_total_cars()) # 输出: 2

4. 注意事项

不要在 __init__ 方法中定义类变量，因为这样会导致逻辑混乱，容易误以为它是实例变量。
如果需要动态地为类添加变量，可以使用 setattr 或直接操作类的 __dict__ 属性，但这通常不推荐，除非有特殊需求。

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-lru_cache 缓存装饰器

Python lru_cache 缓存装饰器详解

1. 它解决了什么问题

2. 基本用法

3. 入参必须是可哈希的

4. 自带的辅助能力

5. maxsize 和 typed 怎么选

6. 实战例子：缓存配置文件解析

7. 三个常见陷阱

7.1 返回的是同一个对象，不是拷贝

7.2 外部状态变了，缓存不会感知

7.3 测试之间缓存会泄漏

8. lru_cache vs functools.cache（3.9+）

9. 在类的方法上慎用

10. 一图小结

python开发环境配置指南

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

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

1. Git：基石配置

安装 Git

基础配置

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

安装 uv

核心工作流

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

安装 Just

配置你的第一个 Justfile

4. 终端美化 (Optional)

总结

Alembic

什么是 Alembic？

Alembic 核心概念

Alembic 使用教程

第一步：安装

第二步：初始化 Alembic 环境

第三步：配置数据库连接

第四步：关联 SQLAlchemy 模型

第五步：创建第一个迁移脚本

第六步：应用迁移 (升级数据库)

第七步：进行模型变更并再次迁移

第八步：降级数据库

常用 Alembic 命令总结

toml_usage_tutorial

什么是 TOML？

为什么使用 TOML？

在 Python 中使用 TOML

安装第三方库

1. 读取 TOML 文件

使用 tomllib (Python 3.11+)

使用 toml (所有 Python 版本)

2. 写入 TOML 文件

示例：创建并写入 TOML 文件

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

高级话题与注意事项

总结

pytest测试用例使用教程

基础概念

什么是 Pytest？

eager `--version`

`--dry-run` 模式

Python `lru_cache` 缓存装饰器详解

5. `maxsize` 和 `typed` 怎么选

8. `lru_cache` vs `functools.cache`（3.9+）

使用 `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`)

让Qt应用在高DOI或者高分辨率显示器上看起来更加清晰（最新pyqt6已经不需要设置）

Python `staticmethod` 修饰符详解教程

什么是 `staticmethod`？

为什么需要 `staticmethod`？

如何使用 `staticmethod`

2. 类方法（`@classmethod`）

3. 静态方法（`@staticmethod`）