miku@cachyos:~/Code/python-learning$ omp teach week01-python-environment-basics --fish-first --step-by-step

source780 行教学文档

weekWeek 01

shellfish-first 命令版

backlink20 周计划

Week 01：CachyOS Python 环境与基础语法

适用对象：已经安装 VS Code，正在用 CachyOS / Arch 系 Linux，准备按 20 周 AI / 量化成长计划开始 Week 01：环境与 Python 基础。

核心结论
不需要把所有事情都放在命令行里做。你可以主要在 VS Code 里写代码、看文件、运行 notebook；但必须掌握少量命令行，因为 Python 环境、包管理、脚本运行、Git、项目复现都依赖这些基础命令。

本教程采用：

ompprompt

VS Code 负责：写代码、看文件、运行脚本、调试、使用 notebook
uv 负责：创建虚拟环境、安装依赖、记录项目配置
终端负责：创建目录、激活环境、运行命令、检查结果

本文命令行默认按 fish shell 写；如果某一步需要 Bash / Zsh，会单独标注。

当前机器已经具备：

ompprompt

Python 3.14.6
uv 0.11.31
VS Code 1.130.0

因此不需要从零安装 Python，直接建立学习环境即可。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	变量、字符串、列表、函数、文件读写
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`src/week01_basic.py`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

def mean(xs):
    if not xs:
        raise ValueError("xs must not be empty")
    return sum(xs) / len(xs)
with open(“data/numbers.txt”, “w”, encoding=“utf-8”) as f:
f.write(“1\n2\n3\n”)
with open(“data/numbers.txt”, encoding=“utf-8”) as f:
nums = [float(line.strip()) for line in f if line.strip()]
print(mean(nums))

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `src/week01_basic.py`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 为什么不能完全不用命令行

你不需要成为 Linux 高手，但不能完全绕开命令行。

原因有四个：

环境隔离需要命令：每个项目应有自己的 .venv，避免不同项目的包互相污染。
安装包需要命令：例如 numpy、pandas、matplotlib、scikit-learn。
复现实验需要命令：以后别人看你的项目，需要知道如何一键安装依赖并运行。
Git 和部署需要命令：提交代码、查看状态、解决冲突，迟早会用到。

最低限度只需要会这些：

ompfish

pwd        # 看当前在哪个目录
ls         # 看当前目录有什么文件
cd         # 进入目录
mkdir      # 创建文件夹
code .     # 用 VS Code 打开当前目录
uv init    # 初始化 Python 项目
uv venv    # 创建虚拟环境
uv add     # 安装依赖
python     # 运行 Python

2. 建立统一学习目录

先给未来 20 周的学习项目留一个统一位置。

打开终端，执行：

ompfish

mkdir -p ~/Code/python-learning
cd ~/Code/python-learning
pwd

逐句解释：

命令	含义
`mkdir`	创建文件夹
`-p`	如果上级目录不存在，就一起创建；如果目录已存在，也不要报错
`~/Code/python-learning`	你的 Python 学习总目录，`~` 表示当前用户主目录
`cd`	进入这个目录
`pwd`	打印当前所在路径，用来确认你没有走错目录

如果输出类似：

ompprompt

/home/miku/Code/python-learning

说明位置正确。

3. 创建第一个 Week 01 项目

每周一个小项目，不要把所有练习都堆在一个文件夹里。

ompfish

mkdir week01-basics
cd week01-basics

建议结构：

ompprompt

week01-basics/
├── notes/       # 学习笔记
├── src/         # Python 源代码
├── data/        # 小数据文件
├── notebooks/   # Jupyter notebook
└── reports/     # 报告或总结

创建这些目录：

ompfish

mkdir -p notes src data notebooks reports

检查：

ompfish

ls

应该看到：

ompprompt

data  notebooks  notes  reports  src

4. 初始化 Python 项目

在 week01-basics 目录里执行：

ompfish

uv init

这一步会生成项目配置文件，通常包括：

ompprompt

pyproject.toml
README.md
main.py

解释：

文件	作用
`pyproject.toml`	记录项目名称、Python 版本、依赖包
`README.md`	项目说明，未来给老师、面试官或自己回看
`main.py`	默认入口脚本，可以改也可以删除

如果 uv init 提示文件已存在，不用慌，说明当前目录里已经有项目文件。

5. 创建虚拟环境 `.venv`

执行：

ompfish

uv venv

它会创建：

ompprompt

.venv/

.venv 是这个项目自己的 Python 环境。以后这个项目安装的包都放在里面，不污染系统 Python。

为什么重要：

ompprompt

系统 Python：给操作系统和系统工具用
项目 .venv：给当前学习项目用

不要把所有包直接装进系统 Python。CachyOS / Arch 是滚动发行版，系统 Python 更应该保持干净。

6. 激活虚拟环境

先确认你在真正的项目目录里，而不是只在总目录 ~/Code/python-learning 里：

ompfish

pwd
ls

如果你按本文创建的是 week01-basics 项目，那么应先进入：

ompfish

cd ~/Code/python-learning/week01-basics

判断标准：当前目录里应该能看到 pyproject.toml 和 .venv/。如果你在 ~/Code/python-learning 总目录下执行激活命令，而虚拟环境其实建在 week01-basics/.venv/，就会找错位置。

6.1 如果你使用 fish shell

你现在遇到的报错就是 fish shell 把 Bash 版激活脚本当成 fish 脚本执行了。

fish 里应执行：

ompfish

source .venv/bin/activate.fish

不要在 fish 里执行：

ompprompt

Bash/Zsh activate 脚本

.venv/bin/activate 是给 Bash / Zsh 用的，里面有 变量=值 这种语法；fish 不支持这种写法，所以会报：

ompprompt

不支持使用 '='

6.2 如果你使用 bash 或 zsh

Bash / Zsh 才使用：

ompprompt

Bash/Zsh activate 脚本

6.3 激活成功后的检查

成功后，终端提示符前面通常会出现：

ompprompt

(.venv)

这表示当前终端已经进入项目环境。

验证 Python 路径：

ompfish

command -v python
python --version

你希望看到的 command -v python 应该类似：

ompprompt

/home/miku/Code/python-learning/week01-basics/.venv/bin/python

如果看到的是 /usr/bin/python，说明虚拟环境没有激活成功，或者你不在创建 .venv 的项目目录里。

7. 安装第一批学习包

Week 01 到 Week 04 建议安装：

ompfish

uv add numpy pandas matplotlib jupyter ipykernel

逐个解释：

包	用途
`numpy`	数值计算，数组、矩阵、随机数
`pandas`	表格数据处理，CSV、DataFrame
`matplotlib`	基础画图
`jupyter`	notebook 环境
`ipykernel`	让 VS Code / Jupyter 使用当前虚拟环境

安装完成后，pyproject.toml 会记录这些依赖。以后别人拿到你的项目，可以根据配置恢复环境。

8. 用 VS Code 打开项目

确认你还在项目目录：

ompfish

pwd

然后执行：

ompfish

code .

含义：用 VS Code 打开当前目录。

不要只打开单个 .py 文件，应该打开整个项目文件夹。这样 VS Code 才能识别 .venv、pyproject.toml、目录结构和相对路径。

9. 在 VS Code 里选择 Python 解释器

打开 VS Code 后：

按 Ctrl + Shift + P。
输入 Python: Select Interpreter。
选择当前项目的解释器：

ompprompt

.venv/bin/python

如果列表里没看到，可以手动选择：

ompprompt

/home/miku/Code/python-learning/week01-basics/.venv/bin/python

这一步的意义：告诉 VS Code 使用当前项目环境，而不是系统 Python。

10. 写第一个脚本

在 src/ 下新建文件：

ompprompt

src/hello.py

内容：

omppython

print("Hello, Python")
scores = [85, 92, 78]
mean_score = sum(scores) / len(scores)
print(mean_score)

用终端运行：

ompfish

python src/hello.py

应该输出：

ompprompt

Hello, Python
85.0

如果 VS Code 右上角运行按钮也能跑出同样结果，说明解释器配置正确。

11. 写第一个 pandas 练习

新建：

ompprompt

src/pandas_demo.py

内容：

omppython

import pandas as pd
data = {
“name”: [“Alice”, “Bob”, “Cindy”],
“score”: [85, 92, 78],
}
df = pd.DataFrame(data)
print(df)
print(“mean score:”, df[“score”].mean())

运行：

ompfish

python src/pandas_demo.py

如果能看到表格和平均分，说明：

ompprompt

Python 能运行
pandas 已安装
VS Code 项目路径正确
虚拟环境可用

12. 建立 notebook

在 VS Code 里新建：

ompprompt

notebooks/week01.ipynb

第一次打开 notebook 时，右上角选择 Kernel：

ompprompt

.venv/bin/python

新建一个 cell：

omppython

import pandas as pd
pd.DataFrame({“x”: [1, 2, 3], “y”: [2, 4, 6]})

如果表格正常显示，notebook 环境配置成功。

13. 推荐项目结构

Week 01 最终建议变成：

ompprompt

week01-basics/
├── .venv/
├── data/
│   └── scores.csv
├── notebooks/
│   └── week01.ipynb
├── notes/
│   └── week01-python.md
├── reports/
│   └── week01-summary.md
├── src/
│   ├── hello.py
│   └── pandas_demo.py
├── pyproject.toml
├── README.md
└── uv.lock

其中：

路径	说明
`.venv/`	虚拟环境，不手动编辑，不提交到 Git
`data/`	小数据文件
`notebooks/`	交互式分析
`notes/`	学习笔记
`reports/`	阶段总结
`src/`	正式 Python 脚本
`pyproject.toml`	项目依赖配置
`uv.lock`	锁定依赖版本，保证复现

14. Git 初始化

如果你要把练习当成项目积累，建议从 Week 01 就用 Git。

ompfish

git init

创建 .gitignore：

ompfish

printf "%s\n" ".venv/" "__pycache__/" ".ipynb_checkpoints/" "*.pyc" ".env" > .gitignore

解释：

条目	为什么忽略
`.venv/`	虚拟环境很大，可以重建，不应提交
`__pycache__/`	Python 自动缓存
`.ipynb_checkpoints/`	Jupyter 自动生成
`*.pyc`	编译缓存
`.env`	可能包含 API key

查看状态：

ompfish

git status

提交：

ompfish

git add README.md pyproject.toml uv.lock src notes notebooks reports data .gitignore
git commit -m "init python learning environment"

如果你暂时还不熟 Git，可以先不提交，但至少要理解 .venv/ 不该放进仓库。

15. 以后每天怎么用

每次重新打开项目，如果你使用 fish：

ompfish

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate.fish
code .

如果教程不是 fish 版本，可能会写：

ompprompt

cd ~/Code/python-learning/week01-basics
Bash/Zsh activate 脚本
code .

如果只在 VS Code 里运行，解释器选好后不一定每次都要手动激活；但只要你在终端里运行 python，建议先激活。

16. 常见错误排查

16.1 VS Code 找不到 pandas

现象：

ompprompt

ModuleNotFoundError: No module named 'pandas'

检查：

ompfish

command -v python
python -c "import pandas as pd; print(pd.__version__)"

如果终端能导入，但 VS Code 不能，说明 VS Code 解释器没选 .venv/bin/python。

16.2 终端前面没有 `(.venv)`

先确认当前目录：

ompfish

pwd
ls

如果你在 ~/Code/python-learning 总目录，先进入具体项目：

ompfish

cd ~/Code/python-learning/week01-basics

fish 用户重新激活：

ompfish

source .venv/bin/activate.fish

如果你看到别人使用 Bash / Zsh：

ompprompt

Bash/Zsh activate 脚本

16.3 不知道当前在哪个目录

执行：

ompfish

pwd
ls

如果看不到 pyproject.toml，说明你不在项目根目录。

16.4 uv add 失败

先检查网络和当前目录：

ompfish

pwd
uv --version

确认在项目目录后再执行：

ompfish

uv add pandas

17. Week 01 验收清单

完成后你应该能做到：

能解释 .venv 是什么。
能用 uv add 安装包。
能在 VS Code 里选择 .venv/bin/python。
能运行 python src/hello.py。
能运行 pandas 示例。
能创建 notebook 并选择当前 kernel。
知道 .venv/ 不应该提交到 Git。
知道如何从终端进入项目目录。

18. 最小命令速查

18.1 创建项目

ompfish

mkdir -p ~/Code/python-learning/week01-basics
cd ~/Code/python-learning/week01-basics

18.2 初始化环境

ompfish

uv init
uv venv

18.3 激活环境

fish 用户执行：

ompfish

source .venv/bin/activate.fish

如果教程不是 fish 版本，可能会提到：

ompprompt

Bash/Zsh activate 脚本

18.4 安装包

ompfish

uv add numpy pandas matplotlib jupyter ipykernel

18.5 打开 VS Code

ompfish

code .

18.6 运行脚本

ompfish

python src/hello.py

19. 和 20 周计划的关系

这篇文档对应 20 周 AI / 量化成长计划的：

ompprompt

Phase 1 / Week 01：环境与 Python 基础

完成本文后，你就可以进入下一步：

ompprompt

Week 01：Python 基础语法、函数、列表、字典、字符串、文件读写
Week 02：Python 进阶 + Linux 工作流
Week 03：NumPy / Pandas
Week 04：可视化 + EDA 报告

最终目标不是“装好了环境”，而是能持续产出可运行、可复现、可解释的小项目。

20. Week 01 Python 基础语法练习

前面的步骤解决“环境能不能跑”。Week 01 还要完成一个最小 Python 脚本，证明你能写函数、处理列表、读写文件，并从终端运行。

20.1 新建练习脚本

确认你在项目目录：

ompfish

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate.fish
pwd

新建脚本：

ompfish

mkdir -p src data notes
printf "%s\n" "name,score" "Alice,85" "Bob,92" "Cindy,78" > data/scores.csv
code src/week01_basic.py

逐句解释：

命令	含义
`mkdir -p src data notes`	确保代码、数据、笔记目录存在
`printf ... > data/scores.csv`	用 fish 兼容方式生成一个小 CSV 文件
`code src/week01_basic.py`	用 VS Code 打开脚本文件

20.2 写入 Python 代码

在 src/week01_basic.py 里写：

omppython

from pathlib import Path
def mean(xs: list[float]) -> float:
if not xs:
raise ValueError(“xs must not be empty”)
return sum(xs) / len(xs)
def read_scores(path: str) -> list[float]:
lines = Path(path).read_text(encoding=“utf-8”).strip().splitlines()
scores: list[float] = []
for line in lines[1:]:
name, score_text = line.split(”,”)
scores.append(float(score_text))
return scores
scores = read_scores(“data/scores.csv”)
print(“scores:”, scores)
print(“mean:”, mean(scores))

这段代码练到的能力：

代码	训练点
`def mean(...)`	函数定义
`list[float]`	类型提示
`if not xs`	基础条件判断
`Path(...).read_text(...)`	文件读取
`splitlines()`	字符串处理
`for line in lines[1:]`	列表切片和循环
`float(score_text)`	类型转换
`print(...)`	终端输出

20.3 从 fish 终端运行

ompfish

python src/week01_basic.py

期望输出类似：

ompprompt

scores: [85.0, 92.0, 78.0]
mean: 85.0

如果能跑通，说明你已经完成 Week 01 最小代码闭环：

ompprompt

创建数据 -> 写 Python 函数 -> 读取文件 -> 终端运行 -> 得到结果

20.4 写学习笔记

ompfish

code notes/week01-python.md

建议写下：

ompmarkdown

# Week 01 Python 笔记
我今天学会了

如何用 fish 激活 .venv
如何用 python 运行脚本
如何定义函数
如何读取 CSV 文本

我还不熟的地方

路径和当前目录
list / dict / for loop
报错信息怎么读

下次要做

把 read_scores 改得更健壮
学 pandas 读取 CSV

20.5 Week 01 最终验收

ompfish

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate.fish
python src/week01_basic.py
test -f notes/week01-python.md; and echo "notes exists"
test -f data/scores.csv; and echo "data exists"

你应该能确认：

source .venv/bin/activate.fish 不报错。
command -v python 指向 .venv/bin/python。
python src/week01_basic.py 能输出平均分。
notes/week01-python.md 存在。
你能解释 mean(xs) 为什么要处理空列表。

完成这些后，再进入 Week 02：Python 进阶 + Linux 工作流。

plain

Week 01：CachyOS Python 环境与基础语法

Week 01：CachyOS Python 环境与基础语法

0. 本周详细教学：语法、规范、验收

0.1 本周真正要学会什么

0.2 代码语法精讲

0.3 本周程序规范

0.4 本周练习分层

0.5 本周和主线的连接

1. 为什么不能完全不用命令行

2. 建立统一学习目录

3. 创建第一个 Week 01 项目

4. 初始化 Python 项目

5. 创建虚拟环境 .venv

6. 激活虚拟环境

6.1 如果你使用 fish shell

6.2 如果你使用 bash 或 zsh

6.3 激活成功后的检查

7. 安装第一批学习包

8. 用 VS Code 打开项目

9. 在 VS Code 里选择 Python 解释器

10. 写第一个脚本

11. 写第一个 pandas 练习

12. 建立 notebook

13. 推荐项目结构

14. Git 初始化

15. 以后每天怎么用

16. 常见错误排查

16.1 VS Code 找不到 pandas

16.2 终端前面没有 (.venv)

16.3 不知道当前在哪个目录

16.4 uv add 失败

17. Week 01 验收清单

18. 最小命令速查

18.1 创建项目

18.2 初始化环境

18.3 激活环境

18.4 安装包

18.5 打开 VS Code

18.6 运行脚本

19. 和 20 周计划的关系

20. Week 01 Python 基础语法练习

20.1 新建练习脚本

20.2 写入 Python 代码

20.3 从 fish 终端运行

20.4 写学习笔记

我今天学会了

我还不熟的地方

下次要做

20.5 Week 01 最终验收

5. 创建虚拟环境 `.venv`

16.2 终端前面没有 `(.venv)`