跳转到主要内容

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 KeyAuthenticationError: 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 greetgreet.hello("小明")默认首选,名字来源一目了然
from greet import hellohello("小明")常用函数少打前缀;但名字可能撞车
from greet import hello as hihi("小明")撞车时改名,或遵循惯例缩写
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 .venvuv venv
装包pip install requestsuv pip install requests
按清单装pip install -r requirements.txtuv pip install -r requirements.txt
导出清单pip freeze > requirements.txtuv pip freeze > requirements.txt
跑脚本python3 main.pyuv run main.py(环境不全自动补)
加依赖并记档手动编辑 pyproject.tomluv 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'

按顺序过这张清单,基本能命中:

  1. 真没装:pip show xxx 看装没装,没装就装。
  2. 装错环境:包装进全局,程序跑在 .venv(或反过来)。pip -V 显示的安装路径和 which python3 显示的解释器路径,必须同在(或同不在)一个 .venv 里。
  3. 装错解释器:电脑里有多个 Python(3.12、3.13 各一套)时,pip 和 python3 可能不是一对。用 python3 -m pip install xxx 强制”给当前解释器装”,一劳永逸。
  4. 包名 ≠ 导入名:pip 装 langchain-openai(横线),import 写 langchain_openai(下划线)——装包名和导入名是两套命名,别只盯着报错里的导入名去 pip install langchain_openai(装不上)。
  5. 文件名拼错 / 运行方式不对: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 的变体,就近遮蔽)。