跳转到主要内容

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:语法桥 的总装与自测清单。

小练习

  1. 用 @contextmanager 写一个 section(name):进入时打印 --- name 开始 ---,退出时打印 --- name 结束 ---。要求:块内抛异常时,“结束”那行也必须打印。
  2. 写类版计时器 Timer:with Timer("任务名") as t: 块内 time.sleep(0.2),块外打印 t.elapsed(秒,保留 4 位小数)。
  3. 把三笔账(含中文备注)写成 ledger.csv 再读回来打印总支出,要求 Excel 打开不乱码。
  4. 用 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} 行")