Python on Veno's Blog

1.2 Lab0

Sun, 10 Aug 2025 00:09:19 +0800

:::warning 如果你在本篇遇到任何的网络问题或疑似网络问题，请向学长私聊求助。 :::

工欲利其事，必先利其器。Lab 0 中我们会进行基础的开发环境搭建，并补全一些你可能不知道的 Python 知识。

概念普及

这一小节给大家普及本篇文档可能你会遇到的陌生词语

Linux? 发行版(distro)?

Linux 严格意义上指的是 Linus Torvalds 最初编写的那个系统内核（kernel）。一个“能用的操作系统”= 内核 + 一堆用户态工具(命令行工具、包管理器、桌面环境…) + 配置 + 生态整合。不同的社区或公司，会在同一个 Linux 内核基础上，搭建并打包自己的“发行版”(distribution, 简写 distro)。

常见发行版：Ubuntu、Debian、Fedora、Arch、openSUSE、CentOS / Rocky / Alma、RHEL 等。它们的差异主要体现在：

包管理器不同（Ubuntu 用 APT，Fedora 用 DNF，Arch 用 pacman）
默认预装的软件 & 配置不同
软件版本策略（偏“新”还是偏“稳”）
社区/企业支持方式（社区滚动更新 vs 企业长期维护 LTS）

你现在在 WSL 装的 Ubuntu，就是“Ubuntu 发行版”。说“我用的是 Linux”通常在实际语境里=“我用的是某个 Linux 发行版”。

:::tip 什么时候需要关心“发行版差异”？写/跑代码 -> 几乎不用纠结；部署生产、写系统级脚本、看教程命令对不上时 -> 才需要意识到“也许是发行版不一样”。 :::

:::warning 小坑网上复制的命令如果带 yum / dnf / pacman 而你系统里只有 apt，不要怀疑人生——只是发行版不一样，换成对应包管理器就好。 :::

Shell? 终端(Terminal)?

Terminal（终端）是一个“窗口/程序”，负责把你敲的字符传给后面真正执行命令的“Shell”，再把结果展示出来。Shell 则是“命令解释器”——接收你输入的文本命令，解析、执行，然后输出结果。

类比：

终端 = 聊天窗口
Shell = 正在和你对话、帮你办事的“客服”

常见 Shell：bash、zsh、fish、powershell（不是 Linux 传统 shell 但理念类似）。你在 WSL 里默认启动的一般是 bash；很多开发者会换成更好用（补全更强/主题更丰富）的 zsh + oh-my-zsh。

如何知道自己当前 shell？

1

echo $SHELL

:::tip “我打开 VS Code 内置终端”“我在 Windows Terminal 新建了一个标签页”——这些动作都是在启动一个“终端程序实例”；里面跑的那一行提示符（veno@pc:~$）背后那个解释命令的才是 shell。 :::

:::warning Ctrl+C 在 shell 中 Ctrl + C 不是复制，是“向前台进程发送中断信号”（终止当前正在运行的命令）。复制请用 Ctrl + Shift + C（在大多数终端里）。 :::

包管理器

包管理器（package manager）= “下载/安装/升级/卸载软件/库的自动化工具 + 依赖关系解决器”。

举些例子：

操作系统层面：

Ubuntu: apt (sudo apt install xxx), snap…
Fedora: dnf
Arch: pacman, yay, paru
。。。

编程语言生态层面：

Python: pip / (最推荐的) uv / poetry / pdm
Node.js: npm / pnpm / yarn
Rust: cargo
。。。

为什么需要包管理器？

自动解决依赖：安装 A 顺便装它需要的 B/C
版本管理：指定版本/锁定版本避免“昨天能跑今天炸”
统一卸载：不会在系统角落留下一堆孤儿文件

虚拟机和容器

虚拟机（Virtual Machine, VM）= 在你的物理机器（Host）里，用软件模拟出另一套“硬件”并在其上运行一个“客体操作系统”。常见软件：VMware、VirtualBox、Hyper-V、WSL2（底层也用类似虚拟化能力）。

它解决什么问题？

隔离：不同项目/系统互不影响
一致性：开发、测试、线上使用一致环境
安全：把“可能作死”的尝试关在沙盒里

你可能还见过一个词叫“容器”，简单来说容器就是比虚拟机更轻量更快的系统级隔离工具，同样后端开发中经常用到。

“虚拟机”和“容器” 区别（简化理解）：

虚拟机：Guest OS 完整存在 -> 较重 -> 启动慢
容器：共享宿主机内核，只隔离文件/进程/网络命名空间 -> 轻量 -> 启动快

WSL2 其实就是：微软做的一层“极轻量虚拟机 + 与 Windows 深度整合的文件/网络桥接”。

:::tip “我到底该用 WSL 还是直接装虚拟机？”——写后端/学 Linux → 先用 WSL 足够；需要研究内核、做内核模块、玩系统级实验 → 真 VM, 或者直接装实体机 Linux :::

Python 虚拟环境

Python 虚拟环境 (virtual environment, venv) = 给某个项目准备的一份“隔离的 Python 解释器 + 其 site-packages 目录”。这样不同项目的依赖（版本）互不污染。

为什么必须用？

你 A 项目需要 fastapi==0.115.x，B 项目还停在 0.110.x，全局安装会冲突。
线上部署要复现本地依赖组合，需要可复制、可锁定的环境。

常见方式：

标准库 python -m venv venv + source venv/bin/activate
uv / poetry / pipenv / pdm：在“虚拟环境 + 依赖锁定 + 脚本运行”上提供更高级封装

uv 做了什么？

自动创建/复用隔离环境
解析 pyproject.toml 里声明的依赖
生成/使用锁文件（uv.lock）保证团队一致

:::tip 判断当前是否已激活虚拟环境执行 which python / which pip，如果路径落在项目缓存/虚拟目录里（而不是 /usr/bin/python3），就说明你在“虚拟”里。或者看提示符是否多了形如 (venv) 的前缀（取决于工具）。 :::

:::warning 常见误区

“我已经有 WSL 或虚拟机了，还需要 Python 虚拟环境吗？”——需要。系统级环境隔离 ≠ 语言级依赖隔离。
“直接全局 pip install 不是更简单吗？”——初期简单，后期灾难：版本冲突、无法复现、卸不干净，可能在项目中引入别人没有的依赖也无法发觉。

:::

开发环境配置

Windows 配置流程

安装 WSL2

WSL2 (Windows Subsystem for Linux 2)，本质上其实是一个运行在 Windows 的轻量级 Linux 虚拟机。

大多数后端服务最终会部署在 Linux 服务器中，因此对于后端学习，我们最好尽快熟悉 Linux 的命令行操作。

对于 Windows 10 版本 2004 及更高版本（内部版本 19041 及更高版本）或 Windows 11 ，使用以下教程：

如何使用 WSL 在 Windows 上安装 Linux

对于 Windows 10 老版本（低于上面所说的版本），参考：

旧版 WSL 的手动安装步骤

上面的微软式中文文档经过一些零基础小白的测试，已经确定会给他们造成一些歧义，而英文不会。你可以选择切换到英文阅读上面给出的官方文档，或者跟着本流程走一遍。

下面我们正式开始 WSL2 的安装。

如果你是 Windows 11, 那么打开你的 Windows 开始菜单，搜索“终端”或“Terminal”或“Windows Terminal”，你应该能搜到这个应用，它是默认附加在 Windows 11 上的。通过这个应用你可以更方便地以标签页的方式开启和管理你的 Shell 窗口，就像浏览器的标签页一样。

我们使用它打开一个管理员权限的 Powershell, 在其中输入：

1

wsl --install

如果这里你出现了一些奇怪的报错，比如下图:

403 实际上是 HTTP 状态码 403 Forbidden, 这也是网络报错，请向学长私聊求助。

:::tip

截至编写本教程时，wsl –install 会默认安装 Ubuntu 24.04 LTS 版本。本教程假设你安装的是该版本。

:::

这个指令会自动帮你启用 Windows 的虚拟机平台功能，并安装 Ubuntu 作为 WSL 的默认发行版。安装完成之后，如果可能的话，则会自动启动 Ubuntu, 开始用户名和密码的初始化。

但你大概率之前没有启用过虚拟机平台功能，除非你安装过 VMWare 之类的虚拟机软件。这个时候并不会自动启动 Ubuntu。此时界面应当会类似下图：

此时虚拟机平台功能和 Ubuntu 都已经成功安装，只是因为虚拟机平台功能需要重启电脑才能启用，因此才没有自动启动 Ubuntu 。

我们需要重启电脑，再次打开 Windows Terminal, 在 Powershell 中输入:

1

wsl

如此即可启动 Ubuntu。你也可以在 Windows Terminal 中将 Ubuntu 添加到下拉菜单快捷启动列表里，以后启动会更方便。

系统将要求你为 Linux 发行版创建“用户名”和“密码”。用户名建议使用3-8个英文小写字符。

此用户名和密码特定于安装的每个单独的 Linux 分发版，与 Windows 用户名无关。
注意，输入密码时，屏幕上不会显示任何内容。这称为盲人键入。你不会看到你正在键入的内容，这是完全正常的。
创建用户名和密码后，该帐户将是分发版的默认用户，并将在启动时自动登录。
此帐户将被视为 Linux 管理员，能够运行 sudo (Super User Do) 管理命令。
在 WSL 上运行的每个 Linux 发行版都有其自己的 Linux 用户帐户和密码。每当添加分发版、重新安装或重置时，都必须配置一个 Linux 用户帐户。

设置用户名和密码之后，我们正式完成了 WSL 的安装。

注意区分，本文以后的所有命令行操作如果未说明，则默认是在 Ubuntu 的 Shell 环境中运行，而不是 Powershell。

设置镜像源

由于网络原因，我们需要给 Ubuntu 设置软件仓库的镜像源，才能正常安装软件包。

:::tip 网站镜像（mirror sites, mirrors；镜像站点，镜像网站）是指对网站内容的拷贝，这类网站通常具有与原站不同的URL，但托管了相同或者是几乎相同的内容。镜像原意是光学里指的物体在镜面中所成之像。引申到计算机网络上，镜像通常用于为相同信息内容提供不同的源，特别是在下载量大的时候提供了一种可靠的网络连接。 :::

这里我们使用清华大学镜像站。在搜索引擎搜索ubuntu 清华镜像，你应该可以搜到下面的网站。

ubuntu | 镜像站使用帮助 | 清华大学开源软件镜像站

我们使用的是 24.04 LTS。想确认你的 wsl 安装了什么版本的 ubuntu，你可以运行:

1

lsb_release -a

镜像站使用帮助中有这样的描述：

在 Ubuntu 24.04 之前，Ubuntu 的软件源配置文件使用传统的 One-Line-Style，路径为 /etc/apt/sources.list；从 Ubuntu 24.04 开始，Ubuntu 的软件源配置文件变更为 DEB822 格式，路径为 /etc/apt/sources.list.d/ubuntu.sources。

将系统自带的对应文件做个备份，然后根据格式的选择下面对应的内容替换，即可使用选择的软件源镜像。

要备份，其实就是复制一份原文件出来的意思。Linux 中的复制指令是cp, 即 copy 的缩写。

1
2


sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak
# 这里相当于复制了一份文件到ubuntu.sources.bak, 之后可以放心修改 ubuntu.sources 了。

之后，选择 DEB882 格式的正确 Ubuntu 版本，复制它生成的配置，替换原来的镜像源文件内容。

1

sudo nano /etc/apt/sources.list.d/ubuntu.sources

输入指令，你会看到类似这样的界面(文件名没有 .bak):

:::tip nano 是 Unix 和类 Unix 系统中的一个终端文本编辑器。它通过 Control 键来控制。比如 Ctrl+O 保存当前文件；Ctrl+W 进入搜索菜单。nano 在屏幕底部显示两行快捷键，列出了当前状态下能用的命令。如果要查看完整的列表，可以按 Ctrl+G 进入帮助屏幕。nano同时支持用鼠标点击屏幕下方的快捷键来操作。 :::

下面快捷键提示中的^指的是 Ctrl，M 是“Meta 键”的缩写，在这里实际上是指 Alt 键。

我们需要删除文件原来的内容，把我们刚刚从网站上复制的配置复制进去。按住 Shift + 方向键下, 控制光标选中文件全部内容，之后^K Cut剪切掉。

这里之所以是剪切而不是退格，是因为 nano 中 Backspace 只会删除掉光标之前的一个字符，而不是删除我们选中的内容。删除掉文件原来的内容之后，我们向文件中用Ctrl + Shift + V粘贴我们刚刚从镜像站复制的配置。

:::warning 注意这里 nano 使用的粘贴板是独立的，并不是 Windows 的粘贴板，也就是我们不应该使用^U快捷键粘贴我们复制的配置，我们实际上是通过 Windows Terminal ，将 Windows 的粘贴板内容粘贴到 shell 中。你实际上应该使用的“粘贴”快捷键是 Ctrl + Shift + V。同样，要复制内容我们也是加上 Shift，即 Ctrl + Shift + C。

在 shell 中，Ctrl + C 一般是终止进程的快捷键。 :::

正确粘贴之后，内容应该像这样：

接下来保存文件。^O保存文件，会询问保存的文件名，直接回车保持文件名原样即可。之后^X退出 nano。

修改完镜像源之后，我们更新软件仓库，保证同步:

1

sudo apt update && sudo apt upgrade

:::tip 有没有觉得这些配置编辑操作相当麻烦？你可以尝试学习使用 vim 编辑器，当你熟练使用之后，我们在终端编辑这种配置文件会比 nano 便捷的多。未来的开发中，我们将不可避免地经常在终端中编辑配置文件。 :::

Python 环境配置

本教程基于 Python 3.12 或更高版本。截止教程编写时，wsl 默认安装 Ubuntu 24.04 LTS ，该版本已经默认安装了 Python 3.12.3。

在 ubuntu 中查看当前的 Python 版本:

1

python3 --version

你可能听说过 pip, 它是 Python 基础的包管理器。但现代 Python 开发中我们一般使用更为便捷的包和项目管理器，例如 uv, poetry, pdm 等。本教程使用 uv。

uv 是一个比较新的工具，Ubuntu 软件源不一定包含。我们使用官方的安装脚本:

1

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

如果安装正确，输出应类似下图:

这个输出告诉我们，要使用 uv, 我们需要重启一个 Shell。我们新开一个 Ubuntu 窗口即可。

uv 是一个很强大的工具，建议阅读它的文档，学习使用。

VS Code 配置

本教程使用 VS Code 作为我们的 IDE。

省流：VS Code + WSL 插件 + Python 相关插件

安装 VS Code。下载链接

安装并打开之后，在左侧的插件栏搜索简体中文插件以及 WSL 插件，安装。之后我们就可以在 ubuntu 中使用code指令打开 Windows 中的 VS Code 了。

我们首先使用 uv 创建我们的第一个 Python 项目:

1
2
3
4
5
6
7


$ cd ~ # 移动到家目录(/home/veno)。家目录通常被 "~" 指代
$ pwd # 显示当前工作目录 (present working diretory)
/home/veno/
$ mkdir -p Projects/ && cd Projects/ # 创建 Projects/ 文件夹并进入
$ uv init backend_tutorial # 初始化我们的第一个 Python 项目
Initialized project `backend-tutorial` at `/home/veno/Projects/backend_tutorial`
$ code backend_tutorial # 在 backend_tutorial 文件夹打开 VSCode

:::tip

在文档中，对于多条指令，$字符一般是为了标识一条指令的开头。偷懒复制粘贴的时候可别把$也一起复制进去了。

:::

此时 Ubuntu WSL 应该会自动开始安装 VSCode 服务器，并打开一个 VS Code 窗口:

uv 很方便吧？一下就帮我们把项目初始化好了。

之后，我们在 Ubuntu 的 VS Code 中安装我们所需的所有插件。注意你需要把插件安装到 “WSL:UBUNTU”，而不是“本地”。

你至少需要安装：Python, Pylance, Git Graph。你可以自己探索其他好用的插件。

本 wiki 的 C-Start 课程提供的 VS Code 的配置文件中有一套开箱即用的 C/C++ 配置。你可以参考这个配置文件中好用的插件。大多数时候，等到需要写什么格式的文件再装什么插件就行。

Git 配置

Git 用于我们项目的版本控制。现在不熟悉没关系，你暂时只需要记住一些基础操作就行。

首先我们在 Ubuntu 安装 git:

1

sudo apt install git

安装之后，需要先进行一些配置工作。输入以下指令:

1
2


git config --global user.name "Zhang San" # your name
git config --global user.email "zhangsan@foo.com" # your email

放心，这里的 name 和 email 只是一个标识符，不会真有人给你发验证邮件什么的，填的邮箱不存在也无所谓。在你每次提交代码的时候你都得靠这个标签来说明这个版本是谁提交的。要不然 git 会不让你提交代码。

想学习 Git 的基本操作，你可以看看Learn Git Branching, 闯关式，交互式的 git 教程，很有意思。

关于 Git 和 Github 的更多内容你可以参考旧版 Wiki。

Linux 配置流程

你都装上 Linux 了，该自己动手丰衣足食了(

MacOS 配置流程

我没有 Macbook，等一个有 Macbook 的好心人提一个 PR。

Python 开发知识普及

根据本教程的前置知识要求，你至少已经学会了一门编程语言的基本语法了，或许学的就是 Python。为了以后少走一点弯路，我们在 Lab 0 补齐一些现代 Python 开发的知识。

Type Hint(类型提示)

Python 是一门强类型，动态类型的语言！ 虽然 Python 作为解释型语言看起来语法很随意，类型很随意，但它实际上是有严格的类型验证的，只不过和编译语言不同，Python 作为解释型动态类型语言，对类型的检查被放在了运行时。关于这一点。你可以阅读 Stack Overflow - Is Python Strongly Typed?

在后端世界，代码不再是几十行的小脚本了，而是成百上千行，多人协作，需要长期维护的复杂系统。类型注解是一个必须项。

确保你阅读FastAPI 文档 - Python 类型提示简介

通过写类型注解，你可以明确声明各种变量的类型，并让你的 IDE 在编写代码时就帮你检查类型。写代码时候的这点多敲的字永远好过代码上线之后，周末凌晨被叫起来修 bug 的痛苦。并且有类型注解之后，才能利用好 IDE 的自动补全功能，这会极大提高你的开发效率。

基本上除了 Python, 大多数语言都需要你写出明确的类型声明。趁早适应这一点，别被 Python 惯坏了。

现代类型标注写法

教程使用 Python 3.12。我们不是开发一个开源库，也不是维护什么企业历史遗留项目，不需要考虑兼容问题。因此本教程将全面使用现代类型标注写法。

现代写法更加简洁易读，性能更优，并且与现代 Python 后端框架的集成度更好。

上面的 FastAPI 文档中的大多数写法都是兼容到 Python 3.8+。这里我大概列举一下现代写法和旧写法的参照，建议遵循现代写法来写 Python 代码。

联合类型(Union Types)

现代(3.10+): 使用|操作符

1
2
3
4
5
6


def get_by_id(uid: int | str) -> dict | None:
 ...

# Optional[str] 的现代写法是 str | None
def get_name() -> str | None:
 ...

旧写法:

1
2
3
4
5
6
7


from typing import Union, Optional

def get_by_id_old(uid: Union[int, str]) -> Union[dict, None]:
 ...

def get_name_old() -> Optional[str]:
 ...

标准集合类型

现代(3.9+): 直接使用内置集合类型, 如list, dict, tuple, set。

1
2
3
4
5
6
7
8
9


def process_data(items: list[str], mapping: dict[str, int]) -> set[str]:
 ...

def get_coordinates() -> tuple[float, float]:
 ...

# 嵌套集合类型
def get_user_groups() -> dict[str, list[dict[str, str]]]:
 ...

旧写法:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


from typing import List, Dict, Set, Tuple

def process_data_old(items: List[str], mapping: Dict[str, int]) -> Set[str]:
 ...

def get_coordinates_old() -> Tuple[float, float]:
 ...

def get_user_groups_old() -> Dict[str, List[Dict[str, str]]]:
 ...

类型别名

现代(3.12+): 使用type语句定义类型别名

1
2
3
4
5
6
7
8
9


type UserId = int
type UserData = dict[str, str | int]
type UserList = list[UserData]

def get_user(uid: UserId) -> UserData | None:
 ...

def get_all_users() -> UserList:
 ...

旧写法:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


from typing import TypeAlias

UserId: TypeAlias = int
UserData: TypeAlias = dict[str, str | int]
UserList: TypeAlias = list[UserData]

# 或者更老的写法
UserId = int
UserData = dict[str, str | int]
UserList = list[UserData]

泛型

现代(3.12+): 使用类型参数语法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# 泛型函数
# 直接在函数名后用方括号定义类型变量
def get_first[T](elements: list[T]) -> T | None:
 return elements[0] if elements else None

# 可以对类型变量进行约束
type Number = int | float
def add[N: Number](a: N, b: N) -> N: # 约束 N 必须是 Number 的子类型
 return a + b

# 泛型类
# 新写法：直接在类名后用方括号定义类型变量
class Box[T]:
 def __init__(self, content: T):
 self.content = content

 def get_content(self) -> T:
 return self.content

# 使用泛型类
int_box: Box[int] = Box(123)
str_box: Box[str] = Box("hello")


# 泛型类型别名
# 新写法：在别名定义中使用方括号
type ListOrNone[T] = list[T] | None

def process_data(data: ListOrNone[str]) -> None:
 ...

旧写法:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from typing import TypeVar, Generic, Union

# 1. 必须先定义 TypeVar
T = TypeVar('T')
Number = TypeVar('Number', bound=Union[int, float]) # 约束的旧写法

# 2. 泛型函数
def get_first_old(elements: list[T]) -> T | None:
 ...

# 3. 泛型类，需要继承 Generic[T]
class BoxOld(Generic[T]):
 def __init__(self, content: T):
 self.content = content
 ...

返回自身实例

现代(3.11+): 使用Self类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


from typing import Self

class User:
 def __init__(self, name: str) -> None:
 self.name = name

 def set_name(self, name: str) -> Self:
 self.name = name
 return self

 def copy(self) -> Self:
 return User(self.name)

 @classmethod
 def create_admin(cls) -> Self:
 return cls("admin")

旧写法处理实例创建的时候会有问题:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


from __future__ import annotations
from typing import TypeVar

S = TypeVar('S', bound='ShapeOld')

class ShapeOld:
 def __init__(self, scale: float = 1.0):
 self.scale = scale

 def set_scale(self: S, scale: float) -> S:
 """这个方法签名看起来没问题，可以正确地在子类中返回子类类型。"""
 self.scale = scale
 return self

 def clone(self: S) -> S:
 """
 我们希望克隆一个与 self 类型完全相同的对象 (T)。
 但是，我们只能调用已知的基类构造器 `ShapeOld()`。
 如果 self 是一个 CircleOld 实例，调用 ShapeOld() 返回的却是一个 ShapeOld 实例。
 这与签名的 -> S 承诺相违背，所以静态类型检查器会报错，我们被迫要type: ignore。
 因此 子类必须重写 clone 方法来返回正确的类型，会导致不可避免的代码重复。
 """
 return ShapeOld(self.scale) # Type "ShapeOld" is not assignable to return type "S@clone"

class CircleOld(ShapeOld):
 def __init__(self, scale: float = 1.0, radius: float = 5.0):
 super().__init__(scale)
 self.radius = radius

 def set_radius(self: S, radius: float) -> S:
 """这是一个子类特有的方法。"""
 self.radius = radius # Cannot assign to attribute "radius" for class "ShapeOld*"
 return self

 # def clone(self: S) -> S:
 # """
 # 重写 clone 方法以返回正确的 CircleOld 类型。
 # 这会导致代码重复，因为我们需要手动调用基类构造器。
 # """
 # return CircleOld(self.scale, self.radius)

c_old = CircleOld(scale=1.0, radius=5.0)

c_old.set_scale(1.5).set_radius(10)
print(f"c_old 修改后半径: {c_old.radius}") # 输出: 10

cloned_old = c_old.clone()

print(f"克隆出的对象类型: {type(cloned_old)}") # 输出: <class '__main__.ShapeOld'>


cloned_old.set_radius(20) # AttributeError: 'ShapeOld' object has no attribute 'set_radius

类型注解(Annotated Pattern)

现代(3.9+): 用于给类型附加额外的元数据，主要被 FastAPI、Pydantic、Typer 等现代框架使用，用于实现依赖注入、数据校验等功能。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


from typing import Annotated
from pydantic import Field, StringConstraints

# Pydantic 数据校验
class User:
 name: Annotated[str, StringConstraints(min_length=1, max_length=50)]
 age: Annotated[int, Field(ge=0, le=150)]
 email: Annotated[str, Field(pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')]

# FastAPI 依赖注入
from fastapi import Depends, FastAPI

def get_db():
 # 数据库连接逻辑
 pass

def get_user(user_id: int, db: Annotated[Database, Depends(get_db)]):
 return db.get_user(user_id)

旧写法:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 没有 Annotated 时，只能在函数体或类定义中通过其他方式实现校验和依赖注入
from pydantic import BaseModel, Field

class User(BaseModel):
 name: str = Field(..., min_length=1, max_length=50)
 age: int = Field(..., ge=0, le=150)
 email: str = Field(..., regex=r'^[\w\.-]+@[\w\.-]+\.\w+$')

# FastAPI 早期写法
def get_user(user_id: int, db=Depends(get_db)):
 return db.get_user(user_id)

Type Checking

在 VS Code 中 Ctrl + , 快捷键打开设置，或是从左下角打开设置，搜索 Pylance type checking mode, 有这样的设置：

开启之后，Pylance 插件会自动检查你的类型问题，在你运行代码前就帮你指出。

随便写点小脚本的时候至少开 standard 或者 basic, 但任何严肃项目都肯定是要开 strict 的。

我的个人习惯是，不管什么时候都开着 strict, 养成良好的代码习惯。

使用 Pydantic Settings 优雅地管理多来源的应用配置

Sat, 02 Aug 2025 16:46:15 +0800

场景：我们希望从多种来源，从配置文件导入我们的配置，并且经过 Pydantic 校验。pydantic-settings库提供了方便的API供我们实现这一需求。

Pydantic - Settings Management

下面直接给出代码示例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158


# config.py

import os
from pathlib import Path
from typing import Any, Self
from pydantic import BaseModel
from pydantic_settings import (
 BaseSettings,
 InitSettingsSource,
 PydanticBaseSettingsSource,
 SettingsConfigDict,
 TomlConfigSettingsSource,
 YamlConfigSettingsSource,
)


class EnvVarFileConfigSettingsSource(InitSettingsSource):
 """
 A source that loads configuration from a file specified in an environment variable.
 It automatically selects the TOML or YAML parser based on the file extension.
 """

 def __init__(
 self,
 settings_cls: type[BaseSettings],
 env_var: str = "MYAPP_CONFIG_FILE",
 env_file_encoding: str | None = None,
 ):
 """
 Args:
 settings_cls: The settings class.
 env_var: The name of the environment variable to read the file path from.
 env_file_encoding: The encoding to use for YAML files.
 """
 self.env_var = env_var
 self.file_path_str = os.getenv(env_var)
 self.encoding = env_file_encoding

 file_data: dict[str, Any] = {}

 if not self.file_path_str:
 super().__init__(settings_cls, file_data)
 return

 file_path = Path(self.file_path_str)
 if not file_path.exists():
 print(
 f"Warning: The file '{file_path}' pointed to by the environment variable '{self.env_var}' does not exist."
 )

 # Reuse existing source logic based on file extension
 suffix = file_path.suffix.lower()
 if suffix == ".toml":
 # Internally create a TomlConfigSettingsSource instance to load the file
 file_data = TomlConfigSettingsSource(
 settings_cls, toml_file=file_path
 ).toml_data
 elif suffix in (".yaml", ".yml"):
 # Internally create a YamlConfigSettingsSource instance to load the file
 file_data = YamlConfigSettingsSource(
 settings_cls, yaml_file=file_path, yaml_file_encoding=self.encoding
 ).yaml_data
 else:
 print(f"Warning: Unsupported file type '{suffix}'. Ignored.")

 # Call InitSettingsSource's __init__, passing the data loaded from the file
 super().__init__(settings_cls, file_data)

 def __repr__(self) -> str:
 return f"{self.__class__.__name__}(env_var={self.env_var}, file_path={self.file_path_str!r})"


class DatabaseConfig(BaseModel):
 postgres_user: str = "veno"
 postgres_password: str = "12345678"
 postgres_host: str = "localhost"
 postgres_port: int = 5432
 postgres_db: str = "veno_db"


class Settings(BaseSettings):
 model_config = SettingsConfigDict(
 toml_file=Path("myapp.toml"),
 yaml_file=Path("myapp.yaml") or Path("myapp.yml"),
 yaml_file_encoding="utf-8",
 env_prefix="MYAPP_",
 env_nested_delimiter="__",
 )

 debug: bool = False
 formal: bool = True
 database: DatabaseConfig = DatabaseConfig()

 @classmethod
 def settings_customise_sources(
 cls: type[Self],
 settings_cls: type[BaseSettings],
 init_settings: PydanticBaseSettingsSource,
 env_settings: PydanticBaseSettingsSource,
 dotenv_settings: PydanticBaseSettingsSource,
 file_secret_settings: PydanticBaseSettingsSource,
 ) -> tuple[PydanticBaseSettingsSource, ...]:
 """
 Define the priority of different configuration sources.
 See: https://docs.pydantic.dev/latest/concepts/pydantic_settings/#customise-settings-sources
 """
 return (
 init_settings,
 # Custom Source
 EnvVarFileConfigSettingsSource(settings_cls),
 # env_settings,
 dotenv_settings,
 # See: https://docs.pydantic.dev/latest/concepts/pydantic_settings/#other-settings-source
 TomlConfigSettingsSource(settings_cls),
 YamlConfigSettingsSource(settings_cls),
 file_secret_settings,
 )


settings = Settings()


# main.py

import os
from typing import Annotated
import typer

import playground.config as config_module

cli_app = typer.Typer()
env_config_file = "MYAPP_CONFIG_FILE"


@cli_app.command()
def hello(name: Annotated[str, typer.Option()] = "Veno"):
 print(f"Hello, {name}")
 if config_module.settings.debug:
 print(f"cli_app: {cli_app}")


@cli_app.command()
def bye():
 if config_module.settings.formal:
 print("Goodbye!")
 else:
 print("See ya!")


@cli_app.callback()
def main(config: Annotated[str | None, typer.Option()] = None):
 if config:
 os.environ[env_config_file] = str(config)
 config_module.settings.__init__()


if __name__ == "__main__":
 cli_app()

我们定义了一个Settings(BaseSettings)类，这是我们的应用配置类。我们可以在其中定义应用配置项，或是嵌套其他的子配置类。子配置类不需要再继承BaseSettings, 而是继承BaseModel。

Settings类中，我们可以通过自定义settings_customise_sources方法中返回的元组内元素的顺序，调整 Pydantic 导入配置源的优先级。靠前的配置源中配置项的值将不会被靠后的配置源的配置项值所覆盖。靠前的配置源成功读取之后并不会略过之后的配置源。也就是说，如果某一项配置值在靠前的配置源未出现，但在靠后的配置源出现，则会使用该出现的值。

如果我们希望删除某个配置源，那么我们可以从返回的元组中剔除它（如本例的env_settings）。

要导入新的配置源，同样也可以在返回的元组中添加它们。本例添加了 TomlConfigFileSettingsSource，YamlConfigFileSettingsSource。它们会从Settings类的model_config中的toml_file等变量获取配置文件位置。例如这里会获取运行根目录下的myapp.toml。此处可以参考 Pydantic Settings 的源码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# pydantic_settings/sources/providers/toml.py
class TomlConfigSettingsSource(InitSettingsSource, ConfigFileSourceMixin):
 """
 A source class that loads variables from a TOML file
 """

 def __init__(
 self,
 settings_cls: type[BaseSettings],
 toml_file: PathType | None = DEFAULT_PATH,
 ):
 self.toml_file_path = toml_file if toml_file != DEFAULT_PATH else settings_cls.model_config.get('toml_file')
 self.toml_data = self._read_files(self.toml_file_path)
 super().__init__(settings_cls, self.toml_data)

 def _read_file(self, file_path: Path) -> dict[str, Any]:
 import_toml()
 with open(file_path, mode='rb') as toml_file:
 if sys.version_info < (3, 11):
 return tomli.load(toml_file)
 return tomllib.load(toml_file)

 def __repr__(self) -> str:
 return f'{self.__class__.__name__}(toml_file={self.toml_file_path})'

这里我们自定义了一个从env_var读取配置文件位置的EnvVarFileConfigSettingsSource类，并希望它被优先使用。当MYAPP_CONFIG_FILE环境变量被设置时，它会试图读取 TOML 或 YAML 配置文件。

在main.py中，我们设置了一个 typer 的回调函数，为主 CLI 应用本身添加了--config参数用于指定配置文件位置。用户如果指定了该参数，则会设置MYAPP_CONFIG_FILE环境变量，并重载settings实例。参见: Pydantic - Settings Management - In-place reloading

使用 uv workspace 搭建 Python Monorepo

Thu, 31 Jul 2025 23:29:54 +0800

~~紫外线用 uv 很合理吧(x~~

有时候我们想在同一个仓库中维护多个Python项目，并且保证他们的依赖关系。这种代码组织策略叫 Monorepo, 这样更方便代码的重复利用，并且可以实现多个项目需要同时进行更改时的原子化提交，更便于团队协作 (~~尤其是当团队只有你一个人的时候~~)。

pip + pyproject.toml 不可能实现声明式的 Monorepo 搭建。不过2025年了，大多数人都更喜欢用 uv, poetry, pdm 之类的现代Python包和项目管理器。我倾向于使用uv。

uv 提供了 workspace 功能，和 Rust 的 Cargo 十分相似，因为 uv 本身就很受 Cargo 启发。通过这个功能，我们可以声明式地在 Pyproject.toml 中定义上面所说的 Monorepo ，我认为大多数时候已经足够好用。

uv 关于 workspace 的文档中有一个例子，但只给出了 pyproject.toml 的内容。其实大多数时候我们是不用手动编辑 pyproject.toml 中关于 [tool.uv] 的内容的，因为默认情况下，在现有包内运行 uv init 将将新创建的成员添加到工作区，如果工作区根目录中不存在 [tool.uv.workspace] 表格，则会创建一个。下面展示仅使用 uv 指令实现官方文档示例的仓库框架的搭建。

信天翁和喂鸟器都需要 seeds，信天翁需要喂鸟器。我这里做个小修改，seeds 仍是工作区成员，seeds 同时还需要支持在泥土中执行发芽操作，因此它依赖 dirt 库。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89


❯ pwd
/home/veno/Projects/uv_playground

❯ uv init --package albatross
Initialized project `albatross` at `/home/veno/Projects/uv_playground/albatross`

❯ cd albatross

❯ uv venv
Using CPython 3.13.5 interpreter at: /usr/bin/python3.13
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

❯ uv init --package bird-feeder
Adding `bird-feeder` as member of workspace `/home/veno/Projects/uv_playground/albatross`
Initialized project `bird-feeder` at `/home/veno/Projects/uv_playground/albatross/bird-feeder`

❯ rm bird-feeder -rf

❯ uv init --package packages/bird-feeder
Adding `bird-feeder` as member of workspace `/home/veno/Projects/uv_playground/albatross`
Initialized project `bird-feeder` at `/home/veno/Projects/uv_playground/albatross/packages/bird-feeder`

❯ uv init --package packages/seeds
Adding `seeds` as member of workspace `/home/veno/Projects/uv_playground/albatross`
Initialized project `seeds` at `/home/veno/Projects/uv_playground/albatross/packages/seeds`

❯ uv add tqdm
Resolved 5 packages in 308ms
 Built albatross @ file:///home/veno/Projects/uv_playground/albatross
Prepared 2 packages in 167ms
Installed 2 packages in 2ms
 + albatross==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross)
 + tqdm==4.67.1

❯ uv add bird-feeder
Resolved 5 packages in 5ms
 Built albatross @ file:///home/veno/Projects/uv_playground/albatross
 Built bird-feeder @ file:///home/veno/Projects/uv_playground/albatross/packages/bird-feeder
Prepared 2 packages in 5ms
Uninstalled 1 package in 0.60ms
Installed 2 packages in 3ms
 ~ albatross==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross)
 + bird-feeder==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross/packages/bird-feeder)

❯ uv init --lib libs/dirt
Adding `dirt` as member of workspace `/home/veno/Projects/uv_playground/albatross`
Initialized project `dirt` at `/home/veno/Projects/uv_playground/albatross/libs/dirt`

❯ uv add dirt --package seeds
Resolved 6 packages in 194ms
 Built seeds @ file:///home/veno/Projects/uv_playground/albatross/packages/seeds
 Built dirt @ file:///home/veno/Projects/uv_playground/albatross/libs/dirt
Prepared 2 packages in 8ms
Installed 2 packages in 2ms
 + dirt==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross/libs/dirt)
 + seeds==0.1.0 (from file:///home/veno/Projects/uv_playground/albatross/packages/seeds)

❯ tree .
.
├── libs
│ └── dirt
│ ├── pyproject.toml
│ ├── README.md
│ └── src
│ └── dirt
│ ├── __init__.py
│ └── py.typed
├── packages
│ ├── bird-feeder
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src
│ │ └── bird_feeder
│ │ └── __init__.py
│ └── seeds
│ ├── pyproject.toml
│ ├── README.md
│ └── src
│ └── seeds
│ └── __init__.py
├── pyproject.toml
├── README.md
├── src
│ └── albatross
│ └── __init__.py
└── uv.lock

14 directories, 14 files

pyproject.toml 中的内容较多，这里就不贴了，读者可以自己在电脑上试一下便知。

如果希望工作区不包含 seeds , 则需要在根项目，也就是albatross包的pyproject.toml中编辑 [tool.uv.workspace], 添加exclude = ["packages/seeds"]。

Every workspace needs a root, which is also a workspace member. In the above example, albatross is the workspace root, and the workspace members include all projects under the packages directory, except seeds.

这里 uv 的官方文档给出的例子是 Monorepo 中有一个根项目和几个辅助库。由于每一个工作区都需要一个根，如果我们想创建的 Monorepo 中，各个项目之间的地位是等价的，那么我们需要注意的是我们仍然需要先初始化整个 Monorepo 的根。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


# 首先初始化根项目
❯ uv init --bare # 使用--bare参数，仅生成一个pyproject.toml文件
Initialized project `monorepo`

❯ uv init --package packages/pkg_a
Adding `pkg-a` as member of workspace `/home/veno/Projects/uv_playground/monorepo`
Initialized project `pkg-a` at `/home/veno/Projects/uv_playground/monorepo/packages/pkg_a`

❯ uv init --package packages/pkg_b
Adding `pkg-b` as member of workspace `/home/veno/Projects/uv_playground/monorepo`
Initialized project `pkg-b` at `/home/veno/Projects/uv_playground/monorepo/packages/pkg_b`

❯ cat ./pyproject.toml
[project]
name = "monorepo"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = []

[tool.uv.workspace]
members = [
 "packages/pkg_a",
 "packages/pkg_b",
]

❯ tree .
.
├── packages
│ ├── pkg_a
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src
│ │ └── pkg_a
│ │ └── __init__.py
│ └── pkg_b
│ ├── pyproject.toml
│ ├── README.md
│ └── src
│ └── pkg_b
│ └── __init__.py
└── pyproject.toml

8 directories, 7 files

附：

UV Documentation - Using workspaces