建立实验项目与版本坐标

目标：能够创建一个固定使用 Python 3.12 的 uv 项目，并解释课程基线、当前 Python 版本与实验目录之间的关系。

你不是从零学习编程，而是在重新校准 Python 心智模型。最容易出错的第一步，是把“系统里有某个 Python”“项目声明兼容某个 Python”和“本次命令实际由某个解释器执行”混成一件事。

把它们分成三层：

语言版本决定语法和标准库能力，例如 match 需要 3.10+，TaskGroup 需要 3.11+，新的类型参数语法需要 3.12+。
项目约束写在 pyproject.toml 的 requires-python 中，表示这个项目承诺支持的范围。
实际解释器由本次环境选择；应通过 sys.version_info 或 python -VV 观察，而不是凭提示符猜。

原始项目固定 Python 3.12，因此本课程也用 3.12 作为所有实验的共同基线。Python 3.14 是当前稳定版本，并带来延迟求值标注、t-string、改进的 free-threaded 模式和新的解释器并发能力；这些是升级视野，不是本课程前半段的先决条件。

第一个可运行实验

新建一个终端目录，不要复制原项目中的 .venv：

uv init textlab --package --python 3.12
cd textlab
uv run python -VV

--package 会建立 src/textlab/ 和构建配置。另在项目根目录新建 main.py：

from __future__ import annotations

import platform
import sys


def runtime_summary() -> str:
    version = f"{sys.version_info.major}.{sys.version_info.minor}"
    implementation = platform.python_implementation()
    return f"{implementation} {version}: TextLab ready"


if __name__ == "__main__":
    message = runtime_summary()
    assert message.endswith("TextLab ready")
    print(message)

运行：

uv run python main.py

预期输出形如：

CPython 3.12: TextLab ready

CPython 和小版本应与你的环境一致。if __name__ == "__main__" 让文件既能作为脚本运行，又能在以后被测试导入时不自动执行打印。

按执行顺序理解

from __future__ import annotations 在 3.12 中让标注延迟以字符串形式保存，减少一部分前向引用问题；后面会专门讨论类型标注。
runtime_summary() 只计算并返回字符串，因此容易测试。
脚本入口负责副作用——打印；核心函数本身不打印。
assert 是这里的实验自检，不是用户输入校验。它证明输出满足我们预期的稳定部分。

引导实验：区分声明与现实

打开 pyproject.toml，找到 requires-python。
运行 uv run python -c 'import sys; print(sys.executable)'。
运行系统的 python3 -c 'import sys; print(sys.executable)'。
比较两个路径。即使版本相同，它们也可能来自不同环境。

如果 uv 没有找到 3.12，先运行 uv python install 3.12，再执行 uv sync。不要通过删除 requires-python 来绕过约束。

独立练习

给 runtime_summary() 增加一个参数 project: str，使输出变成 CPython 3.12: textlab ready，并保持导入文件时不打印。

参考实现

from __future__ import annotations

import platform
import sys


def runtime_summary(project: str) -> str:
    version = f"{sys.version_info.major}.{sys.version_info.minor}"
    return f"{platform.python_implementation()} {version}: {project} ready"


if __name__ == "__main__":
    print(runtime_summary("textlab"))

验收命令：

uv run python main.py
uv run python -c 'import main; assert "textlab" in main.runtime_summary("textlab")'

出现问题时