Python csv.QUOTE_NOTNULL 怎么保留空值语义：写入规则、读取差异与兼容回退

CSV 导入最容易被忽略的一件事，是“没有值”和“值为空字符串”经常被写成同一个字段。Python 3.12 起，csv.QUOTE_NOTNULL 可以把这两种状态保留下来：None 写成未加引号的空字段，字符串即使为空也按字符串规则处理。真正上线前，还要检查读取端的 Python 版本，因为 3.12 的 reader 行为存在已记录的缺陷。

如果 CSV 要在 Python 3.13 及以上读写，优先用 QUOTE_NOTNULL；如果仍需支持 Python 3.12 或更早版本，先做能力探测，再回退到显式空值标记或自定义转换，别把空字符串直接当成缺失值。

先看清 CSV 中的三种字段状态

假设订单导入表有 remark 列。None 表示数据库里没有备注，'' 表示用户明确提交了空备注，而 '待回访' 是普通文本。使用默认的 QUOTE_MINIMAL 时，前两者都可能变成相同的空字段，接收端就无法恢复原意。

QUOTE_NOTNULL 的关键不是“所有字段都加引号”，而是把 None 作为未加引号的空字段写出，把非 None 字段按 QUOTE_ALL 方式处理。这样写出的 CSV 才带有可逆的空值信号。

最小写法：写入后马上读回核对

文件对象要用 newline='' 打开，这是官方文档特别强调的边界。下面的验收样例不依赖数据库，直接把三种状态写进内存，再检查读回列表。

import csv
import io

buffer = io.StringIO(newline='')
writer = csv.writer(buffer, quoting=csv.QUOTE_NOTNULL)
writer.writerow(['order_id', 'remark', 'operator'])
writer.writerow(['A-1001', None, 'Lin'])
writer.writerow(['A-1002', '', 'Lin'])
writer.writerow(['A-1003', '待回访', 'Lin'])

raw = buffer.getvalue()
print(repr(raw))

buffer.seek(0)
rows = list(csv.reader(buffer, quoting=csv.QUOTE_NOTNULL))
assert rows[1][1] is None
assert rows[2][1] == ''
assert rows[3][1] == '待回访'

可见结果应满足三条：表头和普通文本带引号；None 对应的字段是连续分隔符之间的未加引号空位；读回后第二行备注是 None，第三行备注仍是空字符串。只看 CSV 文本外观不够，断言读回类型更可靠。

版本检查要放在导入入口

QUOTE_NOTNULL 从 Python 3.12 才出现。官方 3.12 文档还说明，这个常量对 reader 的行为有缺陷，并在 3.13 修复。因此应用不能只在开发机上检查常量是否存在，还要把运行版本纳入导入门禁。

import csv
import sys

def read_nullable_csv(file_obj):
    if sys.version_info >= (3, 13) and hasattr(csv, 'QUOTE_NOTNULL'):
        return csv.reader(file_obj, quoting=csv.QUOTE_NOTNULL)
    raise RuntimeError(
        '当前解释器不满足 QUOTE_NOTNULL 的空值读取验收，请走兼容解析'
    )

这里的失败是有意为之：如果生产环境低于目标版本，宁可阻止无声的数据转换，也不要让导入继续并把缺失值变成空字符串。上线检查可以记录 sys.version_info、CSV 方言和三行样例的断言结果；不满足条件时明确进入“兼容回退”路径。

旧版本怎么回退才不丢语义

如果必须运行在 Python 3.12 或更早版本，回退方案要让缺失值和空字符串拥有不同的外部表示。例如在写入前把 None 转成约定标记 ，读回后只把这个精确标记还原为 None，其他空字符串保持原样。

NULL_MARKER = ''

def encode_nullable(value):
    return NULL_MARKER if value is None else value

def decode_nullable(value):
    return None if value == NULL_MARKER else value

标记必须经过业务字段审查：如果用户可以合法输入同样的文本，就不能直接采用。更稳妥的做法是增加一列状态，或在上下游都升级后再切回 QUOTE_NOTNULL。回退不是把所有空字段都转成 None，而是显式保留转换规则。

导入前的复查清单

• 写文件和读文件都使用 newline='' ，没有让文本层二次处理换行。
• 样例同时覆盖 None、空字符串和普通字符串，并对读回类型做断言。
• 运行环境达到 Python 3.13 及以上时，才把 QUOTE_NOTNULL 作为默认 reader 行为。
• 旧解释器使用经过业务确认的显式标记或状态列，不把任意空字段猜成缺失值。
• 升级后重新检查下游导入器，因为“空字段”在不同系统里可能仍有自己的约定。

相关问题

QUOTE_NOTNULL 会自动把数字转换成数字吗？

不会。它主要改变引号和空值的处理。普通 csv.reader 返回字符串；只有使用 QUOTE_NONNUMERIC 等模式时，才会触发对应的数值转换规则。

为什么一定要写 newline=''？

CSV 模块自己处理通用换行。如果外层文本层先改写换行，带引号的多行字段可能被错误解析，Windows 写出时还可能出现额外空行。

Python 3.12 能不能直接使用这个常量？

常量在 3.12 已加入，但官方文档记录了 reader 行为缺陷。若导入结果依赖 None 与空字符串的区分，应在目标环境完成三类字段读回测试，不能只检查代码能否运行。

这项设置解决的是数据语义，不是 CSV 格式本身的全部兼容问题。把版本门禁、三类字段验收和旧环境回退一起放进导入流程，后续换解释器或接入新系统时才不会靠猜。