Python
19 文件与上下文管理器进阶
with 的原理、pathlib、csv/json 实战
- Python
- 进阶
目标:把入门课那句”固定咒语”
with open(...)拆开看清内部机制——上下文管理器协议__enter__/__exit__,并能亲手写出自己的上下文管理器;同时补齐 pathlib、csv、jsonl、encoding 这套文件工具箱。LangChain 书第 9 章的会话持久化file_history.py,用的正是本章的全部内容。
1. 为什么需要:with 管的不是文件,是”上下文”
10-文件和异常 教过一个固定句式:with open(...) as f:,块结束自动关文件,“永远这样写”。但为什么这样写、内部发生了什么,当时没讲。于是你在真实项目里看到这些 with 时会愣住:
import sqlite3, threading, tempfile
counter = 0
with sqlite3.connect("app.db") as conn: # 数据库连接:出错自动回滚,成功自动提交
conn.execute("INSERT INTO users VALUES (1)")
with threading.Lock(): # 锁:块内独占,出来自动释放
counter += 1
with tempfile.TemporaryDirectory() as tmp: # 临时目录:出了块,整个目录自动删除
print(tmp) # (示意:感受 with 的管辖范围,不必运行)
文件、数据库、锁、临时目录——看似不相干,凭什么共用一个 with 语法?因为 with 管理的根本不是”文件”,而是一个通用概念:上下文管理器——任何”进门要登记、出门要销毁”的资源都可以实现它。数据库的”登记”是开始事务、“销毁”是提交或回滚;锁的”登记”是拿锁、“销毁”是放锁;文件的”登记”是打开、“销毁”是关闭。
看懂这套协议,你就能读懂框架里所有 with,还能给自己的代码写 with。
2. with 的真面目:enter 与 exit
2.1 翻译成白话
with X as f: 是个语法糖,Python 在背后做三件事:
# 你写的:
# with open("note.txt", encoding="utf-8") as f:
# content = f.read()
# Python 实际执行的(大致等价):
mgr = open("note.txt", encoding="utf-8") # X:一个"上下文管理器"对象
f = mgr.__enter__() # 进门:登记,返回值交给 as 后的变量
try:
content = f.read() # with 块内的代码
finally:
mgr.__exit__(None, None, None) # 出门:销毁,无论如何都执行
规则只有一条:任何对象只要带一对 __enter__ 和 __exit__ 方法,就能放在 with 后面——这叫上下文管理器协议。open() 返回的文件对象恰好实现了这对方法:__enter__ 返回自己,__exit__ 里调用 self.close()。所以”with 自动关文件”不是魔法,只是有人在 __exit__ 里替你调了 close()。
2.2 关键机制:异常也会触发 exit
不用 with、手动 close 有个致命漏洞:块中间出异常,close 那行执行不到。
f = open("note.txt", encoding="utf-8")
content = f.read()
best = max(content.split()) # 万一这行炸了……
f.close() # ← 永远执行不到,文件一直挂着(Windows 上还会锁住文件)
传统解法是 try/finally(18-异常处理、调试与测试):
f = open("note.txt", encoding="utf-8")
try:
content = f.read()
best = max(content.split()) # 就算炸了……
finally: # finally 无条件执行
f.close() # ……关文件这步也跑不掉
6 行办一件事;with 版只要 2 行,因为它把 try/finally 藏进了 __exit__ 的调用时机里——块无论是正常结束、return、还是抛异常,__exit__ 都保证被调用。眼见为实,写一个把”登记/销毁”打印出来的类:
class Door:
"""把 __enter__/__exit__ 的调用时机打印出来"""
def __init__(self, name):
self.name = name
def __enter__(self):
print(f"[{self.name}] 进门登记")
return self # 这个值交给 as 后面的变量
def __exit__(self, exc_type, exc_val, exc_tb):
print(f"[{self.name}] 出门销毁")
return False # 先记住:False = 不吞异常
with Door("仓库A"):
print("干活")
1 / 0 # 块里炸了
print("这行执行不到") # 异常继续往上抛,程序到此终止
[仓库A] 进门登记
干活
[仓库A] 出门销毁
Traceback (most recent call last):
...
ZeroDivisionError: division by zero
注意顺序:先出门销毁,再看到报错——异常离开 with 块时先路过 __exit__,清理完了才继续往上抛。这就是 with 的核心承诺:清理代码永远执行。
__exit__ 的三个参数,正常结束时是三个 None;出异常时分别是异常类型、异常对象、调用栈信息(可据此做条件清理,比如只在特定异常时回滚事务)。
2.3 exit 的返回值:要不要吞下异常
return False(或不写 return,None 同义)= 异常继续抛;return True = 异常到此为止,当作没发生:
class QuietDoor(Door):
def __exit__(self, exc_type, exc_val, exc_tb):
print("出门销毁,出了事我也不吭声")
return True # 吞掉异常
with QuietDoor("静音仓"):
1 / 0
print("程序还活着") # 能打印出来
标准库的 contextlib.suppress 就是官方的”只吞点名异常”工具,语义即 return True,比光杆 except 安全、比 try/except 短:
import contextlib, json
from pathlib import Path
with contextlib.suppress(FileNotFoundError):
config = json.loads(Path("config.json").read_text(encoding="utf-8"))
# 文件不存在就安静跳过,存在就正常读——第 10 章的 try/except FileNotFoundError 套路的替代品
自己写业务类时 __exit__ 几乎永远 return False:清理归清理,bug 该暴露还得暴露。吞异常是 suppress 这类专职工具的事。
2.4 多目标 with:一句开多个文件
# 把两个文件合并写进第三个
with open("part1.txt", encoding="utf-8") as fa, \
open("part2.txt", encoding="utf-8") as fb, \
open("all.txt", "w", encoding="utf-8") as fw:
fw.write(fa.read() + fb.read())
Python 3.10 起支持括号换行(更整齐,新代码优先用):
with (
open("part1.txt", encoding="utf-8") as fa,
open("part2.txt", encoding="utf-8") as fb,
open("all.txt", "w", encoding="utf-8") as fw,
):
fw.write(fa.read() + fb.read())
退出时按打开的反序依次调用各自的 __exit__(后开的先关),依赖关系不会乱。
3. 手写上下文管理器:两种姿势
3.1 类版:老实实现协议
计时器是实战里最常用的小工具,先用类写:
import time
class Timer:
def __init__(self, label="耗时"):
self.label = label
def __enter__(self):
self.start = time.perf_counter() # 进门:记下开始时刻
return self # as t 拿到的就是 self
def __exit__(self, exc_type, exc_val, exc_tb):
self.elapsed = time.perf_counter() - self.start # 出门:算耗时
print(f"{self.label}: {self.elapsed:.4f} 秒")
return False
with Timer("小睡") as t:
time.sleep(0.3)
print(t.elapsed) # 块外还能取到结果——类版的优势
小睡: 0.3003 秒
0.3003442080011997
类版的本事:self 上可以存状态(start、elapsed),with 块结束后对象还在,结果随取随用。
3.2 @contextmanager:yield 前后 = 进入/退出
16-迭代器与生成器 讲过生成器的执行模型:执行到 yield 暂停、交出值、等被唤醒。@contextmanager 就是拿这个特性拼出来的协议适配器:
- with 进入时,把生成器
next()一下 → yield 之前的代码执行(相当于__enter__),yield 出去的值交给 as; - with 退出时,再唤醒一次 → yield 之后的代码执行(相当于
__exit__); - 块里抛了异常,异常会被”扔进”生成器的 yield 处——所以清理代码要放进 try/finally,否则它可能跟着异常一起飞掉。
from contextlib import contextmanager
@contextmanager
def tag(name):
print(f"<{name}>") # 进入时执行
yield # with 块的代码在这里"嵌入"
print(f"</{name}>") # 退出时执行
with tag("h1"):
print("标题")
<h1>
标题
</h1>
同一个计时器,生成器版:
import time
from contextlib import contextmanager
@contextmanager
def timer(label="耗时"):
start = time.perf_counter()
try:
yield # ← with 块的代码在这里执行
finally: # 块里炸了也要计时收尾
print(f"{label}: {time.perf_counter() - start:.4f} 秒")
with timer("小睡"):
time.sleep(0.3)
小睡: 0.3002 秒
两种写法怎么选:
| 类版 | @contextmanager 版 | |
|---|---|---|
| 代码量 | 多(一个类 + 三个方法) | 少(一个函数) |
| 携带状态 | 强:self 存 start/elapsed,块外可取 | 弱:yield 前的局部变量块外拿不到 |
| 适用场景 | 正式的、多处复用的资源类 | 一次性的小工具、快速包一层 |
经验法则:临时用一下就生成器版;要进项目长期维护、要暴露属性给外部,就类版。
4. pathlib:把路径变成对象
11-实战小项目 的记账本用过 Path,这里补全。核心思想:路径不是普通字符串,而是对象——操作挂在方法上,/ 运算符被重载成”拼路径”。
from pathlib import Path
p = Path("chat_data") / "demo.json" # / 拼路径(两边至少一边是 Path)
print(p) # chat_data/demo.json
print(Path("data") / "sub" / "a.json") # 可以连拼
q = Path("data/report-2026.csv")
print(q.name, q.stem, q.suffix) # 文件名 / 去掉后缀 / 后缀
chat_data/demo.json
data/sub/a.json
report-2026.csv report-2026 .csv
一行读写、建目录、判断存在——持久化的全套动作:
file = Path("chat_data") / "demo.json"
file.parent.mkdir(parents=True, exist_ok=True) # 父目录不存在就建;已存在不报错
file.write_text('{"ok": true}', encoding="utf-8") # 写:一行 = 打开+写入+关闭
print(file.exists()) # True
print(file.read_text(encoding="utf-8")) # 读:一行 = 打开+读取+关闭
read_text/write_text 内部就是 with open(...) as f: return f.read()——第 2 节机制的官方封装,天然关文件、天然扛异常。配置、json 这类小文件永远优先用它们。
glob 通配遍历:
from pathlib import Path
for p in sorted(Path(".").glob("*.json")): # 当前目录所有 json
print(p.name, p.stat().st_size, "字节")
for p in Path(".").glob("**/*.py"): # ** = 递归所有子目录
print(p)
注意 glob 返回的是生成器,只能遍历一次(第 8 节的坑 4)。和老写法的对照:
| 任务 | os.path(老写法) | pathlib(新写法) |
|---|---|---|
| 拼路径 | os.path.join("data", "a.json") | Path("data") / "a.json" |
| 存在吗 | os.path.exists(s) | p.exists() |
| 建目录 | os.makedirs(d, exist_ok=True) | p.mkdir(parents=True, exist_ok=True) |
| 取后缀 | os.path.splitext(s)[1] | p.suffix |
| 列匹配文件 | os.listdir + 手写过滤 | p.glob("*.csv") |
| 读全文 | open/read/close 三行 | p.read_text(encoding="utf-8") |
为什么比字符串拼接好:"a" + "/" + "b" 要自己操心分隔符(Windows 是 \)、容易手滑出现 // 或漏 /,而且拼完还是字符串,什么方法都没有;Path 的 / 自动处理系统差异,拼出来的还是 Path,能继续 .read_text()、.stat() 一路点下去。新代码一律 pathlib,见到 os.path 能读懂即可。
5. csv:用字典的思路处理表格
json 存”列表套字典”最舒服,但表格世界的主流格式是 csv(Excel 双击就能开)。csv 模块的 DictReader/DictWriter 让你把每一行当字典处理,数据还是记账本那套:
import csv
from pathlib import Path
records = [
{"date": "2026-09-28", "item": "咖啡", "type": "支出", "amount": 18},
{"date": "2026-09-29", "item": "工资", "type": "收入", "amount": 8000},
{"date": "2026-09-30", "item": "地铁", "type": "支出", "amount": 4},
]
path = Path("ledger.csv")
with path.open("w", newline="", encoding="utf-8") as f: # csv 要求 newline=""
writer = csv.DictWriter(f, fieldnames=["date", "item", "type", "amount"])
writer.writeheader() # 表头:字典的键
writer.writerows(records) # 一次写多行
读回来并统计:
income = expense = 0
with path.open("r", newline="", encoding="utf-8") as f:
for row in csv.DictReader(f): # 每行自动变成 {'date': ..., 'item': ...}
print(row["date"], row["item"], row["amount"])
if row["type"] == "收入":
income += int(row["amount"]) # 注意:读回来的 amount 是字符串!
else:
expense += int(row["amount"])
print(f"结余:{income - expense}")
2026-09-28 咖啡 18
2026-09-29 工资 8000
2026-09-30 地铁 4
结余:7978
三个要点:
newline="":换行由 csv 模块自己管,Windows 下不加会每行多出一个空行;- csv 没有类型信息:写进去的
18读回来是"18",参与计算要自己int(); - Excel 双击打开中文 csv 乱码的话,写入改用
encoding="utf-8-sig"(见第 7 节)。
6. json 进阶:dump 家族与 jsonl
6.1 dump vs dumps:带 s 的管字符串
| 函数 | 方向 | 记忆点 |
|---|---|---|
json.dumps(obj) | 对象 → 字符串 | string:返回 str,自己决定往哪放 |
json.dump(obj, f) | 对象 → 文件 | 写进已打开的文件对象 f |
json.loads(s) | 字符串 → 对象 | 从 str 解析 |
json.load(f) | 文件 → 对象 | 从已打开的文件对象读 |
选法:配合 pathlib 一行读写(write_text/read_text)用 dumps/loads;配合 with open 直接拿文件对象就用 dump/load。按”手里有没有文件对象”判断,不要混着背。
import json
from pathlib import Path
config = {
"model": "gpt-4o-mini",
"temperature": 0.7,
"tools": [{"name": "search"}, {"name": "calculator"}], # 嵌套结构
}
Path("config.json").write_text(
json.dumps(config, ensure_ascii=False, indent=2), encoding="utf-8"
)
back = json.loads(Path("config.json").read_text(encoding="utf-8"))
print(back == config) # True:嵌套结构完整往返
print(back["tools"][1]["name"]) # calculator
两个参数的意义(第 10 章用过,现在知道为什么):
>>> import json
>>> print(json.dumps({"city": "北京"}))
{"city": "\u5317\u4eac"}
>>> print(json.dumps({"city": "北京"}, ensure_ascii=False))
{"city": "北京"}
ensure_ascii=False:不带它,中文全被转义成\u5317\u4eac——文件合法,但人没法看;indent=2:按 2 空格缩进排版。程序读不在乎,人读差很多——配置、对话历史这类要打开看的文件永远带上。
6.2 jsonl:每行一个 json
存很多条记录有两种做法:整文件一个大 json 数组,或 jsonl(JSON Lines)——每行一个独立的小 json。后者是大模型领域的标配:训练数据每行一条问答对、对话日志每行一条消息、embedding 批处理每行一段文本。
整文件 json 的弱点是追加——第 9 章说过这种存法是”读全量、改、写全量”;jsonl 直接在文件尾续一行。代价是不能整体 json.loads,要逐行处理:
import json
from pathlib import Path
messages = [
{"role": "human", "content": "你好"},
{"role": "ai", "content": "你好!有什么可以帮你?"},
]
path = Path("chat.jsonl")
# 写:一条消息占一行
with path.open("w", encoding="utf-8") as f:
for m in messages:
f.write(json.dumps(m, ensure_ascii=False) + "\n")
# 追加(jsonl 的看家本领:不碰旧数据,直接续写)
with path.open("a", encoding="utf-8") as f:
f.write(json.dumps({"role": "human", "content": "今天天气如何"},
ensure_ascii=False) + "\n")
# 读:逐行 loads,天然流式,大文件也不爆内存(呼应 16 章)
with path.open("r", encoding="utf-8") as f:
for line in f:
if line.strip(): # 防御空行
msg = json.loads(line)
print(f"{msg['role']:>6} | {msg['content']}")
human | 你好
ai | 你好!有什么可以帮你?
human | 今天天气如何
7. encoding 深入:乱码到底怎么来的
第 10 章叮嘱过”每次都带 encoding='utf-8'”,现在讲透为什么。
字符串和字节是两种东西。 内存里的 "你好" 是字符;落盘必须变成字节,转换规则就是编码(encoding)。utf-8 是当今事实标准:给全世界每个字符一个统一编号(Unicode),英文 1 字节、中文通常 3 字节——同一份文件在任何国家的电脑上解释出来都一样。
那不带 encoding 会怎样?Python 会用操作系统当下的默认编码:macOS/Linux 是 utf-8,中文 Windows 是 gbk。于是:同一份代码在 mac 上正常、在同事的 Windows 上乱码;或者 Windows 上用 gbk 去读一个 utf-8 文件,直接报错:
UnicodeDecodeError: 'gbk' codec can't decode byte 0x80 in position 0: illegal multibyte sequence
乱码的本质:字节没变,解释方式变了。用 utf-8 写、用 gbk 读:
>>> "你好".encode("utf-8") # 落盘的 6 个字节
b'\xe4\xbd\xa0\xe5\xa5\xbd'
>>> "你好".encode("utf-8").decode("gbk") # 6 字节被 gbk 按 3 个汉字重新解释
'浣犲ソ'
修复原则:
- 读写两端都显式
encoding="utf-8",新文件一律 utf-8; - 给 Excel 看的 csv 用
utf-8-sig(开头多 3 个字节的标记,Excel 靠它认出 utf-8); - 已经乱掉的数据无法”自动复原”——必须查清它当初用什么编码写的,按那个编码重读。
8. 常见坑
坑 1:with 块外再用文件对象
with open("note.txt", encoding="utf-8") as f:
lines = f.readlines()
print(f.read()) # ❌ with 结束时 __exit__ 已把文件关掉
ValueError: I/O operation on closed file
修法:要内容就在块内取出来存变量(lines 可以块外用);想要”还开着的文件对象”不可能,也不该要。
坑 2:"w" 一打开就清空
with open("log.txt", "w", encoding="utf-8") as f: # ❌ 打开瞬间旧内容已清空
f.write("新的一行") # 哪怕这行没执行,旧内容也没了
追加用 "a";要”先读后改再写”就分两次打开。
坑 3:Windows 默认编码(第 7 节)——跨机器共享的文件,读写两端都显式 utf-8,不要依赖默认值。
坑 4:glob 结果只能遍历一次
from pathlib import Path
py_files = Path(".").glob("*.py") # 返回生成器:吐完就枯竭(16 章)
print([p.name for p in py_files]) # ['a.py', 'b.py']
print([p.name for p in py_files]) # [] —— 第二次为空,而且不报错!
需要多次使用就先固化成列表:files = sorted(Path(".").glob("*.py")),顺带解决 glob 顺序不确定的问题。
9. 在 LangChain 里的样子:持久化三件套
LangChain 书 09-Memory记忆系统.md 的”自管理消息历史”,完整展示了持久化 = 上下文管理器 + pathlib + json 三件套怎么落地。摘编核心的两个函数(to_records/from_records 负责消息对象与字典互转,此处略):
# 摘编自 langchain-book-python/09-Memory记忆系统.md 的 file_history.py
import json
from pathlib import Path
def load_history(session_id):
file = Path("chat_data") / f"{session_id}.json" # ① pathlib 拼路径
if file.exists(): # ② 首次对话:文件还不存在
return json.loads(file.read_text(encoding="utf-8")) # ③ 一行读 + 显式编码
return []
def save_history(session_id, messages):
file = Path("chat_data") / f"{session_id}.json"
file.parent.mkdir(parents=True, exist_ok=True) # ④ 目录不存在就建
file.write_text(
json.dumps(to_records(messages), ensure_ascii=False, indent=2), # ⑤ 中文可读
encoding="utf-8",
)
逐行解读,全是本章内容:
- ① 每个会话一个文件,
/拼路径(第 4 节); - ②
file.exists()判断首次对话、返回空列表——替代了入门课的 try/except FileNotFoundError(也等价于 suppress 版); - ③
read_text(encoding="utf-8")一行读全量,with 打开/关闭藏在它内部(第 2、4 节);json.loads把文本还原成列表(第 6 节); - ④
mkdir(parents=True, exist_ok=True)第一次保存时连chat_data目录一起建好,已存在也不报错; - ⑤
ensure_ascii=False+indent=2:磁盘上的历史文件人能直接打开看。
这份代码没有一个显式的 with,但每一行都站在 with 机制之上——read_text/write_text 就是官方替你写好的上下文管理器封装。这就是”会抄工具”和”懂工具”的区别。
反方向是”读文件进框架”:05-文档加载器.md 的 TextLoader:
from langchain_classic.document_loaders import TextLoader
loader = TextLoader("data/qiu.txt")
docs = loader.load()
# [Document(metadata={'source': 'data/qiu.txt'}, page_content='《秋园小记》\n\n秋天的后园里,墙角有一棵老槐树。风一起……')]
load() 内部干的就是本章第 1 节那套事:打开文件、读全文、关文件、把文本包成 Document 对象,路径自动记进 metadata['source']。两个与本章直接相关的细节:
- TextLoader 默认按 utf-8 读,遇到 gbk 老文件会抛第 7 节那个 UnicodeDecodeError,解法是
TextLoader(path, autodetect_encoding=True)让它自动探测编码; - 批量加载用
DirectoryLoader("./data", glob="**/*.txt")——glob参数就是第 4 节 Path.glob 的通配语法,**递归子目录。
本章的 pathlib、with 协议、持久化习惯,最终都汇进 22-读懂LangChain:语法桥 的总装与自测清单。
小练习
- 用
@contextmanager写一个section(name):进入时打印--- name 开始 ---,退出时打印--- name 结束 ---。要求:块内抛异常时,“结束”那行也必须打印。 - 写类版计时器
Timer:with Timer("任务名") as t:块内time.sleep(0.2),块外打印t.elapsed(秒,保留 4 位小数)。 - 把三笔账(含中文备注)写成
ledger.csv再读回来打印总支出,要求 Excel 打开不乱码。 - 用 pathlib + glob 统计当前目录所有
.md文件的总行数,按文件名排序输出每个文件的行数和总计。
练习答案
# 练习 1:清理逻辑必须放 finally,否则异常穿透时"结束"打印不出来
from contextlib import contextmanager
@contextmanager
def section(name):
print(f"--- {name} 开始 ---")
try:
yield
finally:
print(f"--- {name} 结束 ---")
with section("导入数据"):
print("处理中")
raise ValueError("炸了") # 验证:"结束"仍会打印,异常继续往上抛
# 练习 2:elapsed 挂在 self 上,块外通过 t 取
import time
class Timer:
def __init__(self, label):
self.label = label
def __enter__(self):
self.start = time.perf_counter()
return self
def __exit__(self, exc_type, exc_val, exc_tb):
self.elapsed = time.perf_counter() - self.start
print(f"{self.label}: {self.elapsed:.4f} 秒")
return False
with Timer("小睡") as t:
time.sleep(0.2)
print(f"块外取 elapsed: {t.elapsed:.4f}")
# 练习 3:utf-8-sig 让 Excel 正确识别;读回来记得 int() 转换
import csv
from pathlib import Path
records = [
{"date": "2026-10-01", "item": "午饭", "amount": 22},
{"date": "2026-10-02", "item": "咖啡", "amount": 18},
{"date": "2026-10-03", "item": "书", "amount": 45},
]
path = Path("ledger.csv")
with path.open("w", newline="", encoding="utf-8-sig") as f:
writer = csv.DictWriter(f, fieldnames=["date", "item", "amount"])
writer.writeheader()
writer.writerows(records)
total = 0
with path.open("r", newline="", encoding="utf-8-sig") as f:
for row in csv.DictReader(f):
total += int(row["amount"])
print(f"总支出:{total}") # 85
# 练习 4:glob 结果固化成列表,才能既排序又反复使用
from pathlib import Path
files = sorted(Path(".").glob("*.md"))
grand = 0
for p in files:
n = len(p.read_text(encoding="utf-8").splitlines())
grand += n
print(f"{p.name}: {n} 行")
print(f"共 {len(files)} 个文件,{grand} 行")