Python
17 模块、包与项目工程化
import 体系、venv/pip/uv、.env 与 API Key 管理
- Python
- 进阶
目标:搞懂
from langchain_openai import ChatOpenAI背后的安装、导入、配置三件事;学会把程序拆成多个文件和包、用虚拟环境管依赖、用 .env 藏密钥。LangChain 书里每个示例开头那几行”固定仪式”,读完本章全部透明。
1. 为什么需要:一行代码背后的三件事
LangChain 书的第一个示例开头是这样的:
from langchain_openai import ChatOpenAI
入门课(01-准备工作)教过你怎么敲这行字,但从没展开。这短短一行背后是三件独立的事,任何一件没做对,程序都跑不起来:
| 没做哪件事 | 你会看到什么 |
|---|---|
| 没安装包 | ModuleNotFoundError: No module named 'langchain_openai' |
| 没配置 API Key | AuthenticationError: Error code: 401 |
| Key 直接写在代码里 | 当时能跑;一旦传上 GitHub,几分钟内被爬虫盗刷 |
本章按这三件事展开:第 2~4 节讲导入(模块与包的机制),第 5 节讲安装(环境与依赖),第 6 节讲配置(环境变量与 .env),第 7 节用多文件小项目串起来,第 9 节回到 LangChain 对号入座。
2. 模块与 import:Python 到底在干什么
2.1 模块就是一个 .py 文件
任何 .py 文件都是一个模块(module),文件名去掉后缀就是模块名。先造一个会被反复导入的例子:
# greet.py
GREETING = "你好"
def hello(name):
return f"{GREETING},{name}!"
def _internal():
return "下划线开头:内部实现,不希望外人用"
在同目录另一个文件里,四种导入写法:
import greet # 写法 1:整体导入,用前缀访问
from greet import hello # 写法 2:只拿一个名字进来
from greet import hello as hi # 写法 3:拿进来并改名
from greet import * # 写法 4:公开名字全部倒进来(不推荐)
| 写法 | 调用方式 | 适用场景 |
|---|---|---|
import greet | greet.hello("小明") | 默认首选,名字来源一目了然 |
from greet import hello | hello("小明") | 常用函数少打前缀;但名字可能撞车 |
from greet import hello as hi | hi("小明") | 撞车时改名,或遵循惯例缩写 |
from greet import * | hello("小明") | 基本不用,原因见下 |
import * 为什么不推荐:一,读代码的人不知道 hello 从哪来;二,它会悄悄覆盖当前文件里的同名变量——你定义的 GREETING 会莫名变成模块里的值;三,哪些名字能进来不受你控制——默认跳过 _ 开头的名字(_internal 进不来),模块作者也可以用 __all__ 列表指定导出哪些。真实项目几乎都禁用它。
2.2 import 的执行模型:把那个文件从头到尾跑一遍
import greet 不是一句”声明”,而是执行:Python 找到 greet.py,把它从头到尾运行一次(所以模块顶层可以写任何语句),运行中诞生的变量、函数、类都挂到一个”模块对象”上,greet.hello 就是从这个对象上取属性。
一个能”看见”这次执行的实验:
# counter.py
print("== counter.py 被执行了一次 ==")
value = 0
def add():
global value # 声明 value 指模块顶层的那个变量(第 8 章 4.2)
value += 1
return value
>>> import counter
== counter.py 被执行了一次 ==
>>> counter.add()
1
>>> import counter # 第二次 import:没有任何打印
>>> counter.add()
2
第二次 import 安静的原因:Python 用一个字典 sys.modules 缓存已加载的模块,同一个模块在一个进程里只执行一次,之后再 import 直接取缓存。这就是”模块是单例”——模块顶层变量因此被全程序共享(能这么用,但全局状态多了难排查,别滥用)。
2.3 标准库、第三方库、自己写的文件
| 类别 | 哪来的 | 例子 | 要安装吗 |
|---|---|---|---|
| 标准库 | 装 Python 自带 | os、json、random、pathlib | 不用 |
| 第三方库 | 用 pip 从 PyPI(全球包仓库)安装 | langchain_openai、dotenv | 要 |
| 自己写的 | 同目录(或包里)的 .py 文件 | greet、storage | 不用 |
import 找模块的顺序由 sys.path 列表决定,第一项是脚本所在目录(交互模式下是当前目录 '')——这个”就近优先”会制造第 8 节的大坑(比如自己写了个 json.py)。
另外一条真实项目的惯例:import 写在文件顶部,分三组——标准库 / 第三方 / 自己的模块——组间空行。LangChain 书里所有代码都长这样,第 9 节逐行拆给你看。
3. if __name__ == "__main__": 一个文件的两种身份
先看没有它会怎样。你想写个工具脚本,既有函数又有演示代码:
# ❌ tool.py:演示代码裸奔在顶层
def run():
print("工具正在运行")
run() # 为了"直接跑能看到效果",把它放在顶层
问题:另一个文件 import tool 只想借 run() 函数,可 import 会执行整个文件(2.2 节),run() 被莫名调用,凭空打印”工具正在运行”。
机制:Python 给每个模块一个内置变量 __name__,它的值取决于文件以什么身份进入程序:
- 直接运行(
python3 tool.py):__name__等于字符串"__main__" - 被导入(
import tool):__name__等于模块名"tool"
验证:
# who.py
print(f"我的 __name__ 是 {__name__}")
$ python3 who.py
我的 __name__ 是 __main__
$ python3 -c "import who" # -c:把后面的字符串当代码执行
我的 __name__ 是 who
于是标准写法是把”直接运行才做的事”包进判断里,俗称 main 守卫:
# ✅ tool.py
def run():
print("工具正在运行")
if __name__ == "__main__":
run()
直接跑:条件成立,执行入口逻辑;被导入:条件不成立,外界只拿到干净的函数定义。一个文件由此获得两种身份——既是库(别人 import 它的能力),又是脚本(自己能跑)。开源项目的源码入口几乎都有这行;你自己的多文件项目里,通常只有入口文件需要它(第 7 节的 main.py)。
4. 包:用目录组织模块
文件多了,一个目录下几十个 .py 会乱。**包(package)**就是把模块按目录归类:一个带 __init__.py 的目录就是一个包,__init__.py 可以是空文件,作用是向 Python 声明”这个目录是包,不是普通文件夹”。
bookstore/
├── main.py # 入口脚本,在包外
└── bookstore/ # 包
├── __init__.py
├── models.py
└── api/
├── __init__.py # 子目录也要有,才算子包
├── helpers.py
└── client.py
导入时用点号路径,点号就是目录层级:
from bookstore.models import Book # 包.模块 import 名字
from bookstore.api.client import fetch # 跨两层同理
__init__.py 还有个惯用法:在里面写导入,把常用名字”汇聚”到包顶层——
# bookstore/__init__.py
from bookstore.models import Book
>>> from bookstore import Book # 使用者不用记 Book 藏在哪个子模块
包内部的模块互相引用可以用相对导入:一个点 = 当前包,两个点 = 上一级包:
# bookstore/api/client.py
from ..models import Book # .. :上一级包 bookstore 里的 models
from . import helpers # . :当前包 bookstore.api 里的 helpers
相对导入只能在包内部使用——直接运行的脚本(__name__ 为 "__main__" 的文件)里写 from . import x 会报 ImportError: attempted relative import with no known parent package。现在记住概念即可:包内互相引用用相对或绝对路径都行,入口脚本待在包外、用绝对路径导入。以后在别的库源码里看到 from ..utils import ...,就是它。
5. 环境与依赖:venv、pip 与 uv
5.1 为什么需要虚拟环境
pip 装的包默认进”全局环境”——一套 Python 一份,所有项目共用。这像合租房的公共冰箱:A 项目要 langchain 1.x,B 项目还停在旧版 0.1,冰箱却只能放一版,卸了装、装了卸,最后谁也跑不起来。
**虚拟环境(venv)**就是给每个项目一间独立厨房:一个普通文件夹(惯例叫 .venv),里面装着一套独立的 Python 和包。项目用哪套,取决于终端里”激活”了哪个。
5.2 创建与激活(Mac / Windows)
# —— Mac ——
cd 你的项目目录
python3 -m venv .venv # 创建:.venv/ 里放一套独立环境
source .venv/bin/activate # 激活
# —— Windows(命令提示符)——
python -m venv .venv
.venv\Scripts\activate # PowerShell 用 .venv\Scripts\Activate.ps1
激活成功的标志:提示符前多出 (.venv)。此后 pip install 装进这间厨房,python3 也指向这套环境(which python3 / Windows where python 可验证路径已在 .venv 里)。退出用 deactivate。.venv 不进 git、随手可删重建,也不要手改里面的东西。
安装与换源(下载慢时切国内镜像,一句带过):
pip install requests
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
5.3 uv:更快的现代替代品
uv 是近两年流行的 Python 包管理器(Rust 编写),装包比 pip 快一个数量级,还能顺带管理 Python 版本和项目。命令和 pip 几乎一一对应,会 pip 就会 uv:
| 做什么 | pip 系 | uv 系 |
|---|---|---|
| 建虚拟环境 | python3 -m venv .venv | uv venv |
| 装包 | pip install requests | uv pip install requests |
| 按清单装 | pip install -r requirements.txt | uv pip install -r requirements.txt |
| 导出清单 | pip freeze > requirements.txt | uv pip freeze > requirements.txt |
| 跑脚本 | python3 main.py | uv run main.py(环境不全自动补) |
| 加依赖并记档 | 手动编辑 pyproject.toml | uv add requests(自动写进 pyproject.toml) |
本仓库 LangChain 书用 pip,也注明可用 uv 替代;两者产物(.venv、requirements.txt)互通。
5.4 requirements.txt 与 pyproject.toml
换电脑复原环境靠”依赖清单”。最传统的是 requirements.txt——每行一个包和精确版本,用 pip freeze > requirements.txt 从当前环境生成:
langchain==1.1.0
langchain-openai==1.0.3
python-dotenv==1.0.1
pip install -r requirements.txt # 新机器一条命令复原
现代项目更多用 pyproject.toml,它不止是依赖清单,而是项目档案——项目名、版本、要求的 Python 版本、依赖全写在一处:
[project]
name = "my-ledger"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
"python-dotenv",
]
一句话区别:requirements.txt 只回答”装什么”,pyproject.toml 回答”这个项目是什么 + 装什么”,是 uv / poetry 等现代工具链的标准格式。
6. 环境变量与 .env:密钥的正确姿势
环境变量是操作系统层面的键值表(终端 env 命令可看全量),程序里用 os 模块读:
>>> import os
>>> os.environ["OPENAI_API_KEY"] # 字典式取法:没有这个键 → 当场 KeyError
Traceback (most recent call last):
...
KeyError: 'OPENAI_API_KEY'
>>> os.getenv("OPENAI_API_KEY") # 函数式取法:没有 → 安静返回 None
>>> os.getenv("OPENAI_API_KEY", "未配置") # 第二参数是默认值
'未配置'
怎么选:确定必须有、缺了就该崩(快速失败,错误越早暴露越好排查)用 os.environ["X"];可有可无用 os.getenv("X", 默认值)。
API Key 为什么放环境变量而不写进代码?其一,代码会跟着 git 走:就算事后删掉那行,历史提交里永远留着,而 GitHub 上有爬虫在分钟级扫描 sk- 开头的字符串盗刷。其二,配置与代码分离:本机用测试 Key、服务器用生产 Key,代码一行不改,换环境就是换变量。
但环境变量手动设太麻烦(重开终端就没了),惯例是放一个 .env 文件在项目根目录,用第三方库 python-dotenv 加载:
# .env —— 永远不进 git 的文件
OPENAI_API_KEY=sk-xxx
pip install python-dotenv
import os
from dotenv import load_dotenv
load_dotenv() # 把 .env 的键值读进 os.environ
print(os.getenv("OPENAI_API_KEY")) # sk-xxx
load_dotenv() 的机制一句话:打开项目根目录的 .env,逐行解析 KEY=VALUE,塞进 os.environ——等于替你批量设置环境变量。惯例:只在程序入口调用一次;团队协作时提交一个 .env.example(只有键名、值留空),真 .env 各自填。
最后一步保险:.gitignore(git 的忽略清单,列进去的文件不上传)里加上这几行:
# .gitignore
.env
.venv/
__pycache__/
顺带认识 __pycache__:运行后目录里多出的这个文件夹是 Python 的字节码缓存(编译结果),删了会自动重建,不用管、不进 git。
7. 实战:把记账本拆成三个文件
11-实战小项目 的记账本是单文件。现在用本章知识把它工程化——按职责拆成三个模块:
ledger/
├── main.py # 入口:读命令、调度(唯一有 main 守卫的文件)
├── words.py # 文本层:解析一行输入、格式化一条记录
└── storage.py # 数据层:增、查、落盘
# words.py —— 只管"文本进、结构出",不碰文件、不碰 input/print
def parse(line):
"""把 'add 20 午饭' 解析成 (金额, 备注);解析不了返回 None"""
parts = line.split()
if len(parts) == 3 and parts[0] == "add" and parts[1].isdigit():
return int(parts[1]), parts[2]
return None
def render(no, amount, note):
"""把一条记录格式化成给人看的文本"""
return f"{no}. {amount} 元 - {note}"
# storage.py —— 只管数据:ledger.json 的读写
import json
from pathlib import Path
FILE = Path("ledger.json")
def load():
if not FILE.exists():
return []
return json.loads(FILE.read_text(encoding="utf-8"))
def add(amount, note):
records = load()
records.append({"amount": amount, "note": note})
FILE.write_text(json.dumps(records, ensure_ascii=False), encoding="utf-8")
return len(records)
# main.py —— 入口:循环读命令,把活派给两个模块
import storage
import words
def main():
print("命令:add 金额 备注(如 add 20 午饭)| list 看全部 | q 退出")
while True:
line = input("> ").strip()
if line == "q":
break
if line == "list":
for no, r in enumerate(storage.load(), 1):
print(words.render(no, r["amount"], r["note"]))
continue
parsed = words.parse(line)
if parsed is None:
print("看不懂这条命令")
else:
amount, note = parsed
print(f"已记第 {storage.add(amount, note)} 笔")
if __name__ == "__main__":
main()
$ python3 main.py
命令:add 金额 备注(如 add 20 午饭)| list 看全部 | q 退出
> add 20 午饭
已记第 1 笔
> add 35 打车
已记第 2 笔
> list
1. 20 元 - 午饭
2. 35 元 - 打车
> q
拆分的核心不是”文件变多”,而是依赖方向:main 导入 words 和 storage;words 和 storage 互相不认识,更不知道 main 的存在。箭头永远从入口指向底层:
main.py ──▶ words.py (纯函数,最底层)
──▶ storage.py (只依赖标准库)
单向依赖的三个好处:每个文件单独打开就能读懂(单一职责);words 这种纯函数模块好写测试(18-异常处理、调试与测试);想换存法(比如 SQLite)只改 storage.py,main 和 words 一行不动。想单独试 storage,也可以在它末尾加一个 main 守卫的自测块——正是第 3 节”两种身份”的用武之地。
8. 常见坑
坑 1:ModuleNotFoundError: No module named 'xxx'
按顺序过这张清单,基本能命中:
- 真没装:
pip show xxx看装没装,没装就装。 - 装错环境:包装进全局,程序跑在 .venv(或反过来)。
pip -V显示的安装路径和which python3显示的解释器路径,必须同在(或同不在)一个.venv里。 - 装错解释器:电脑里有多个 Python(3.12、3.13 各一套)时,
pip和python3可能不是一对。用python3 -m pip install xxx强制”给当前解释器装”,一劳永逸。 - 包名 ≠ 导入名:pip 装
langchain-openai(横线),import 写langchain_openai(下划线)——装包名和导入名是两套命名,别只盯着报错里的导入名去pip install langchain_openai(装不上)。 - 文件名拼错 / 运行方式不对:import 对大小写敏感(
Storage≠storage);python3 -m 包.模块这种启动方式要求当前站在项目根目录,站错位置同样报这个错。
坑 2:循环导入
# ❌ a.py
import b # ① 执行 a 的第 1 行:转去执行 b.py
def greet():
return "hi"
# ❌ b.py
from a import greet # ② a 才执行到第 1 行,greet 还没定义!
print("b 加载完成")
$ python3 a.py
ImportError: cannot import name 'greet' from partially initialized module 'a'
(most likely due to a circular import)
原因回到 2.2 节的执行模型:import 就是执行文件。a 执行到一半去执行 b,b 又回头要 a 里还没轮到定义的名字——此刻 a 只是个”半成品模块”(报错原文 partially initialized)。修法三选一:
# ✅ b.py 修法其一:延迟导入——函数被调用时 a 早就加载完了
def banner():
from a import greet
return greet() + "!"
另外两招:把 import 从文件顶部挪到函数体内(即上面的延迟导入);更根本的是用第 7 节的单向依赖原则——把 a、b 都要用的东西抽到第三个模块 c,让 a→c、b→c,环就断了。
坑 3:把自己的文件命名为 json.py
你练习 json 模块时顺手建了个 json.py,灾难开始:同目录任何文件 import json,拿到的是你写的那个(2.3 节:sys.path 第一项是脚本目录,就近优先)。自己的代码报 AttributeError: module 'json' has no attribute 'dumps' 还算好的;更隐蔽的是第三方库内部也 import json,于是 langchain 在你面前莫名其妙地崩。高危名单:json.py、random.py、email.py、test.py、typing.py——练习文件永远别用标准库的名字。中招后:改名,顺手删掉 __pycache__ 清缓存,再跑。
9. 在 LangChain 里的样子
回到开头的三件事,用 LangChain 书(第 1 章)的真实代码对号入座。
第一件事:装了什么。 书的 README 给的安装命令:
pip install "langchain>=1.0" "langchain-openai>=1.0" python-dotenv pydantic
# RAG 章节额外:pip install langchain-classic langchain-text-splitters
# Agent/记忆章节额外:pip install langgraph langgraph-checkpoint-postgres
用本章的眼光读:langchain-openai 提供 ChatOpenAI(注意 pip 名横线、import 名下划线,坑 1 第 4 条);langchain 是上层封装,pip 会沿依赖树自动带上公共底层 langchain-core;python-dotenv 供下一件事的 load_dotenv;pydantic 做数据建模(21-pydantic数据建模)。引号里的 >=1.0 是版本约束——锁住 1.x 系列,防止将来 2.0 的破坏性更新直接弄坏书里的代码。
第二件事:导入了什么。 书里几乎每个示例的开头都长这样:
import os # ① 标准库组
from dotenv import load_dotenv # ② 第三方组
from langchain_core.messages import HumanMessage # ② 包.模块 import 名字
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI
load_dotenv() # ③ 进口仪式:加载 .env
chat_model = ChatOpenAI(api_key=os.environ["OPENAI_API_KEY"])
simple_chain = chat_model.pipe(StrOutputParser()) # ④ 组链(第 22 章展开)
逐行对照本章:两组 import 之间的空行就是 2.3 节的分组惯例;from langchain_core.messages import HumanMessage 是”包.模块”的点号路径;load_dotenv() 在入口处只调用一次,把 .env 灌进 os.environ;os.environ["OPENAI_API_KEY"] 用字典式取法——Key 没配好就当场崩,快速失败比把空值传进 API 深处再报错好排查得多。
第三件事:.env 里放了什么。 就一行:
OPENAI_API_KEY=sk-xxx
书的 README 还提醒:任选一种模型服务、不混配变量;.env 不提交 git,可选做法是在 .gitignore 中加入 .env。再讲一个本章能解释的细节:构造 ChatOpenAI 时不传 api_key 也行,它会自动去环境变量 OPENAI_API_KEY 里找——环境变量是框架约定的标准交接点:你把钥匙放进环境,谁来取、怎么取,框架管。
至此三件事闭环:pip install 解决”包从哪来”,import 解决”名字怎么拿”,.env + load_dotenv() 解决”钥匙放哪、怎么进程序”。
小练习
练习 1:同目录有个 tools.py,里面有函数 now()。写一行 import 语句,把它以别名 n 引入当前文件。
练习答案
from tools import now as n
练习 2:运行 python3 a.py,屏幕打印几行、什么顺序?若把 a.py 改成只有一行 import b,输出变吗?
# a.py
import b
import b
print("A 结束")
# b.py
print("B 加载")
练习答案
两行:先 B 加载,后 A 结束。import 是”执行文件”:第一行立刻执行 b.py 全文;第二行命中 sys.modules 缓存,什么都不做。改成一行 import b 输出不变——模块一个进程只执行一次,写几次 import 都一样。
练习 3:改造下面的脚本,使它直接 python3 ask.py 运行时才提问,被其他文件导入时保持安静。
def ask(prompt):
return input(prompt)
print(ask("你叫什么?"))
练习答案
def ask(prompt):
return input(prompt)
if __name__ == "__main__":
print(ask("你叫什么?"))
直接运行时 __name__ 是 "__main__",条件成立;被导入时它是 "ask",条件不成立,外界只拿到 ask 函数。
练习 4:pip install requests 显示安装成功,但 python3 main.py(main.py 第一行 import requests)仍报 ModuleNotFoundError: No module named 'requests'。给出两个最可能的原因和验证方法。
练习答案
① 装错环境:requests 装进了全局(或另一个 venv),当前激活的是别的环境。验证:pip -V 看安装路径、which python3 看解释器路径,两者不在同一个 .venv 里就是它。② 装错解释器:机器上多个 Python 版本,pip 与 python3 不是一对。验证:改用 python3 -m pip install requests(强制装给当前解释器)后再跑。顺手确认没有把自己的文件命名为 requests.py(坑 3 的变体,就近遮蔽)。