NumPy 输入输出(I/O)例程完全指南:npy/npz 二进制、文本文件与内存映射的读写实践
NumPy 输入输出(I/O)例程完全指南:npy/npz 二进制、文本文件与内存映射的读写实践
本文以 NumPy 官方参考手册中的 routines.io 例程索引 为主线,系统讲解 NumPy 的全部输入输出能力:从 save/load 与 npz 归档的二进制持久化、loadtxt/savetxt/genfromtxt 的文本读写,到 memmap 内存映射、打印格式控制与进制表示等工具函数。读完本文,你将掌握 NumPy 各种 I/O 场景下正确的 API 选型、关键参数语义与安全约束,并能结合源码理解其底层实现机制。
一、I/O 例程总览:八大功能域
numpy 的 I/O 例程按用途可分为以下类别(对应 routines.io.rst 的小节结构):
| 类别 | 核心函数 | 典型场景 |
|---|---|---|
| NumPy 二进制文件(npy/npz) | load、save、savez、savez_compressed、lib.npyio.NpzFile |
数值数据的快速、无损持久化 |
| 文本文件 | loadtxt、savetxt、genfromtxt、fromregex、fromstring、ndarray.tofile、ndarray.tolist |
与外部工具交换的 CSV/表格数据 |
| 原始二进制文件 | fromfile、ndarray.tofile |
无头部的裸数据流 |
| 字符串格式化 | array2string、array_repr、array_str、format_float_positional、format_float_scientific |
数组到字符串的展示与控制 |
| 内存映射文件 | memmap、lib.format.open_memmap |
超大数组的按需分片访问 |
| 文本格式化选项 | set_printoptions、get_printoptions、printoptions |
全局/上下文打印参数 |
| Base-n 表示 | binary_repr、base_repr |
整数到二进制/任意进制字符串 |
| 数据源 | lib.npyio.DataSource |
本地/远程文件的统一抽象访问 |
下文按类别逐一深入。
二、NumPy 二进制文件:.npy 与 .npz
2.1 save:单个数组的 .npy 二进制保存
save(file, arr, allow_pickle=True) 将数组以 NumPy 自有的 .npy 格式写入二进制文件。从 numpy/lib/_npyio_impl.py 的实现看:
- 传入字符串/
Path时,若文件名缺少.npy后缀会被自动补上(save内部执行file + '.npy'); - 传入已打开的文件对象时,数据追加到文件末尾,因此可在同一句柄上连续保存多个数组,再通过连续
load依次读出; - 保存前会先经
np.asanyarray(arr)归一化为 ndarray,再调用format.write_array写入。
allow_pickle=True 允许保存对象数组(object dtype),但官方文档明确警告:pickle 反序列化可能执行任意代码,且不同 Python 环境/版本间可能无法互相加载,因此仅应在可信环境下启用。
import numpy as np
# 保存到文件(自动补 .npy 后缀)
np.save('data/arr', np.array([[1, 2, 3], [4, 5, 6]]))
# 在同一个句柄上追加保存多个数组
with open('multi.npy', 'wb') as f:
np.save(f, np.array([1, 2]))
np.save(f, np.array([1, 3]))
with open('multi.npy', 'rb') as f:
a = np.load(f)
b = np.load(f)
print(a, b) # [1 2] [1 3]
2.2 savez / savez_compressed:多数组归档
savez 将多个数组打包进一个 未压缩 的 .npz 归档(ZIP 容器),savez_compressed 则使用 zipfile.ZIP_DEFLATED 压缩。两者底层都汇聚到 _savez()(numpy/lib/_npyio_impl.py):
- 命名规则:位置参数自动命名为
arr_0、arr_1…;关键字参数以其键名作为归档内文件名(键必须是合法文件名,避免以/开头或包含.);归档内每个文件是一个独立.npy数组。 - 注意不能使用关键字
file命名数组(会与file参数冲突)。 - 内部强制开启 ZIP64(
force_zip64=True,对应 issue gh-10776),以支持超大文件。
a = np.arange(10)
b = np.sin(a)
# 未压缩归档,位置参数命名
np.savez('out.npz', a, b)
npzfile = np.load('out.npz')
npzfile.files # ['arr_0', 'arr_1']
# 压缩归档,关键字命名
np.savez_compressed('out2', x=a, y=b)
loaded = np.load('out2.npz')
np.array_equal(loaded['x'], a) # True
2.3 load:统一读取入口
load(file, mmap_mode=None, allow_pickle=False, fix_imports=True, encoding='ASCII', *, max_header_size=...) 能自动识别文件类型(numpy/lib/_npyio_impl.py):
- 读取文件头魔数:
PK\x03\x04/PK\x05\x06判定为.npz(返回NpzFile);等于 NumPy 魔数MAGIC_PREFIX判定为.npy;否则按 pickle 处理; .npz返回字典式NpzFile对象,可用data['key']取数组,也可用with上下文管理器自动关闭底层文件描述符;mmap_mode取值{None, 'r+', 'r', 'w+', 'c'}:非 None 时以内存映射方式加载,适合只访问大文件局部片段;'c'表示 copy-on-write;allow_pickle默认为False——这是 NumPy 2.x 起的安全默认值,加载含对象数组的文件必须显式打开;fix_imports/encoding仅用于加载 Python 2 生成的 pickle 数据,且encoding只允许'ASCII'、'latin1'、'bytes'(源码 433-445 行直接校验,其他值会抛ValueError,防止静默损坏数值数据);max_header_size限制头部最大字节数,防止恶意构造的超大头;当allow_pickle=True时该限制自动失效(此时文件被视为可信)。
# 常规加载
data = np.load('data/arr.npy')
# 内存映射方式加载并取第二行(不读入整个文件)
X = np.load('huge.npy', mmap_mode='r')
row = X[1, :]
# npz 上下文管理,避免文件描述符泄漏
with np.load('out.npz') as d:
x = d['x']
NpzFile 类定义于同一文件(numpy/lib/_npyio_impl.py,公开入口为 numpy.lib.npyio.NpzFile),支持 files、keys()、values() 等类字典接口,并实现上下文管理器协议。
2.4 底层格式:numpy.lib.format
.npy/.npz 的二进制格式由 numpy.lib.format 模块描述与实现(numpy/lib/_format_impl.py)。其文件结构为:魔数(MAGIC_PREFIX,含版本号)→ 头部(dict 形式的 ASCII 描述,含 descr dtype 描述、fortran_order、shape)→ 紧凑的原始数组数据。dtype_to_descr 与 _read_array_header 负责头部序列化/解析,read_array/write_array 完成数据读写。这意味着 .npy 天然是平台无关、无损、未压缩的存储格式,读写开销极低。
三、文本文件读写
3.1 loadtxt:高性能规整文本读取
loadtxt(fname, dtype=float, comments='#', delimiter=None, converters=None, skiprows=0, usecols=None, unpack=False, ndmin=0, encoding=None, max_rows=None, *, quotechar=None, like=None)(numpy/lib/_npyio_impl.py)是简单规整文本的快速读取器。关键参数:
fname:文件、文件名、pathlib.Path、字符串列表或生成器;.gz/.bz2后缀会自动解压;dtype:默认float;传入结构化 dtype 时每行按字段解析,输出一维结构化数组;comments:可为单个字符、字符列表或None(禁用注释),默认'#';delimiter:分隔符;None表示任意连续空白。自 1.23 起仅支持单字符分隔符,换行符不可用作分隔符;converters:dict(列号 → 解析函数)或单个可调用对象(1.23 起应用于所有列),用于预处理原始文本;内部每个值以字节串形式传入;skiprows:跳过的行数(包含注释行);max_rows:读取的最大内容行数(不含空行与注释行)——两者对注释行的计数规则不同,使用时需注意;usecols:选择读取的列(0 起始),可解决"各行列数不齐"的读入问题;unpack=True:返回转置结果,便于x, y, z = loadtxt(...)解包;ndmin:合法值仅 0/1/2(源码中_ensure_ndmin_ndarray_check_param直接校验),控制最小维度并 squeeze 单例轴;quotechar(1.23 新增):引号包裹字段时,分隔符与注释符在引号内被忽略,两个连续引号视为转义;encoding:默认None(2.0 起,之前为'bytes'),'bytes'为向后兼容的字节模式。
from io import StringIO
# 基础用法:空白分隔
c = StringIO("0 1\n2 3")
np.loadtxt(c) # array([[0., 1.], [2., 3.]])
# 结构化 dtype + 引号字段
s = StringIO('"alpha, #42", 10.0\n"beta, #64", 2.0\n')
dt = np.dtype([("label", "U12"), ("value", float)])
np.loadtxt(s, dtype=dt, delimiter=",", quotechar='"')
# converters 对全部列生效(十六进制解析)
import functools
s = StringIO("0xDE 0xAD\n0xC0 0xDE")
np.loadtxt(s, converters=functools.partial(int, base=16))
# array([[222., 173.], [192., 222.]])
从源码结构看,loadtxt 的核心解析在 _read() 辅助函数(同文件 861 行起),采用约 50000 行(_loadtxt_chunksize)分块读取的迭代器设计,注释剥离由 _preprocess_comments 完成。
3.2 savetxt:文本写出与 fmt 格式微语言
savetxt(fname, X, fmt='%.18e', delimiter=' ', newline='\n', header='', footer='', comments='# ', encoding=None)(numpy/lib/_npyio_impl.py):
fname以.gz结尾时自动 gzip 压缩,loadtxt可透明读取;X仅支持 1D 或 2D 数组(源码直接对 0D/>2D 抛ValueError);1D 数组被转置为列向量写出;fmt支持三种形式:单个格式符(如'%10.5f')、每列一个格式符的序列、或含多个%的完整字符串(此时忽略delimiter)。复数数组有专门规则:单格式符会被展开为' (%s+%sj)',也可提供完整格式串或每列列表;header/footer分别写于文件首尾,前面自动加上comments前缀(默认'# ',与loadtxt的注释识别对齐);encoding默认'latin1',若使用其他编码则旧版 NumPy(< 1.14)无法加载。
fmt 遵循 Python 百分号格式微语言 %[flag]width[.precision]specifier:flag 支持 -(左对齐)、+(强制符号)、0(零填充);precision 对整数是最小位数、对 e/E/f 是小数位数、对 g/G 是有效数字数;specifier 支持 c/d/i/e/E/f/g/G/o/s/u/x/X。savetxt 写出时会自动将 '+-' 替换为 '-',避免复数虚部出现 +- 形态。
x = y = z = np.arange(0.0, 5.0, 1.0)
np.savetxt('test.out', x, delimiter=',') # 1D 数组
np.savetxt('test.out', (x, y, z)) # 多个等长 1D 数组
np.savetxt('test.out', x, fmt='%1.4e') # 科学计数法
np.savetxt('test.out', x, header='header line', comments='## ')
3.3 genfromtxt:缺失值感知的高级读取
genfromtxt(...)(numpy/lib/_npyio_impl.py)是 loadtxt 的增强版,专为含缺失值、表头、字段名的真实数据设计。与 loadtxt 相比的独有能力:
dtype=None时逐列自动推断 dtype(源码通过easy_dtype与NameValidator实现字段名清洗);delimiter除字符串外,还可传整数或整数序列表示定宽列;skip_header/skip_footer跳过首尾行(skiprows与missing参数已在 1.10 移除,勿再用);names:True表示从首行读字段名;序列或逗号分隔字符串则直接指定字段名;None且 dtype 非结构化时输出普通数组;missing_values/filling_values:定义缺失标记字符串与其填充值,缺失数据也可由converters提供默认值(如{3: lambda s: float(s or 0)});usemask=True返回掩码数组(numpy.ma.MaskedArray),缺失值以掩码标记而非填充值;loose/invalid_raise控制列数不一致时的行为(抛异常或警告并跳过);excludelist/deletechars/replace_space/case_sensitive/defaultfmt控制字段名清洗规则;默认排除['return','file','print'];max_rows不能与skip_footer同时使用(源码显式校验);ndmin语义与loadtxt一致;encoding默认None(2.0 起),'bytes'进入字节兼容模式。
from io import StringIO
# 混合类型 + 显式结构化 dtype
s = StringIO("1,1.3,abcde")
data = np.genfromtxt(s, dtype=[('myint','i8'),('myfloat','f8'),
('mystring','S5')], delimiter=",")
# dtype=None 自动推断 + 指定字段名
data = np.genfromtxt(s, dtype=None,
names=['myint','myfloat','mystring'], delimiter=",")
# 定宽列解析
s = StringIO("11.3abcde")
data = np.genfromtxt(s, dtype=None, names=['intvar','fltvar','strvar'],
delimiter=[1,3,5])
需要注意的实践要点(源码 Notes 明确):空白分隔且无显式 delimiter 时两字段间不能有缺失数据;指定字段名后文件不能再带表头;值默认不自动 strip 空白,自定义 converter 需自行处理空格;由于 dtype 推断机制,自定义 converter 可能收到意外类型。
3.4 fromregex:正则表达式结构化解析
fromregex(file, regexp, dtype, encoding=None)(numpy/lib/_npyio_impl.py)用正则表达式对文本全文做匹配,正则分组对应结构化数组的字段,返回结果始终是结构化数组。实现上:dtype 必须为结构化 dtype(否则抛 TypeError),内部用 regexp.findall 提取所有匹配,单分组时构造单字段结构化视图。
from io import StringIO
text = StringIO("1312 foo\n1534 bar\n444 qux")
regexp = r"(\d+)\s+(...)"
output = np.fromregex(text, regexp,
[('num', np.int64), ('key', 'S3')])
# array([(1312, b'foo'), (1534, b'bar'), (444, b'qux')],
# dtype=[('num', '<i8'), ('key', 'S3')])
output['num'] # array([1312, 1534, 444])
3.5 fromstring 与 ndarray.tolist / ndarray.tofile
fromstring(string, dtype=float, count=-1, *, sep, like=None):从字符串或类字节对象解析一维数组;sep指定分隔符,缺省时输入须为二进制串(定长元素,按 dtype 字节宽度切分)。类型签名见 numpy/_core/multiarray.pyi;ndarray.tolist():将数组递归转换为 Python 标量/列表/嵌套列表(dtype 标量转为 Python 类型);ndarray.tofile(fid, sep="", format="%s"):将数组原始数据写入文件;sep为空时按二进制写入,非空时以文本写入(配合format指定文本格式)。
四、原始二进制文件:fromfile 与 tofile
fromfile(file, dtype=float, count=-1, *, sep='', offset=0, like=None) 从文件读取原始二进制数据,不解析任何头部,直接按 dtype 的字节布局连续解释(类型签名见 numpy/_core/multiarray.pyi)。与之配套的是 ndarray.tofile。这对函数适合与 C/C++ 等外部程序交换裸数据缓冲区;若需要跨平台自描述的二进制格式,应优先选用 save/load(.npy 自带头部与端序信息)。
五、数组到字符串的格式化
array2string(a, max_line_width=None, precision=None, suppress_small=None, separator=' ', prefix="", suffix="", style=None, formatter=None, sign=None, floatmode=None, legacy=None)(numpy/_core/arrayprint.py):数组的底层字符串渲染入口,array_str/array_repr均基于它;array_str(a, max_line_width=None, precision=None, suppress_small=None):去类型信息的简洁展示(等价于str(arr));array_repr(arr, ...):含类型与形状信息的完整展示(等价于repr(arr));format_float_scientific(x, precision=None, unique=True, trim='k', sign=False, pad_left=None, exp_digits=None)与format_float_positional(x, ...):对单个浮点标量分别生成科学计数法与定点法字符串,trim控制尾部零/小数点的修剪('k'表示保留至少一位有效数字),unique=True时打印足以唯一区分该值的最少位数。
六、内存映射:memmap 与 open_memmap
numpy.memmap(filename, dtype=..., mode='r+', offset=0, shape=None, order='C'):将磁盘文件映射为数组视图,数据按需换页,不一次性载入内存。mode支持'r'(只读)、'r+'(读写,默认)、'w+'(覆盖创建)、'c'(copy-on-write)。公开实现位于 numpy/core/memmap.py;numpy.lib.format.open_memmap(filename, mode='r+', dtype=None, shape=None, fortran_order=False, version=None, *, max_header_size=...)(numpy/lib/_format_impl.py):专门操作.npy文件的内存映射——mode含'w'时创建新文件(须提供shape,dtype 默认为float64,可指定fortran_order与格式version);读取模式则先解析头部得到 shape/dtype 再映射数据区。不能传文件对象,只接受路径(源码直接抛ValueError),且对象数组(dtype.hasobject)无法内存映射。
# 创建并映射一个 3x3 的新 .npy 文件
m = np.lib.format.open_memmap('mm.npy', mode='w+', dtype=np.float64,
shape=(3, 3))
m[:, 0] = 1.0 # 修改直接写回磁盘
# 只读映射既有文件
X = np.load('huge.npy', mmap_mode='r') # 内部即调用 open_memmap
七、文本格式化选项:set_printoptions / get_printoptions / printoptions
三个函数管理数组与浮点数的展示方式(numpy/_core/arrayprint.py):
set_printoptions(precision=None, threshold=None, edgeitems=None, linewidth=None, suppress=None, nanstr=None, infstr=None, formatter=None, sign=None, floatmode=None, *, legacy=None, override_repr=None):全局设置;get_printoptions():返回当前选项字典;printoptions(*args, **kwargs):上下文管理器,块内临时覆盖选项、退出自动恢复。
主要选项语义:precision 默认 8;threshold 默认 1000(元素数超过则摘要显示,传 sys.maxsize 可强制完整显示);edgeitems 默认 3(摘要首尾各显示的元素数);linewidth 默认 75;suppress 控制是否始终用定点表示(默认当最小值绝对值 < 1e-4 或最大/最小绝对值比 > 1e3 时自动切换科学计数法);nanstr/infstr 自定义 NaN/Inf 显示;sign 取 '-'/'+'/' '(2.0 起支持整数类型);formatter 提供按类型注册的自定义格式化回调(键可为 'bool'、'int'、'float'、'complexfloat'、'numpystr'、'object' 及组键 'all'、'int_kind'、'float_kind'、'complex_kind'、'str_kind');floatmode 取值 'fixed'/'unique'/'maxprec'/'maxprec_equal'(默认)控制精度解释方式;legacy 支持 '1.13'、'1.21'、'1.25'、'2.1'、'2.2' 等旧版显示模式或 False 关闭。
值得特别强调的是:这些打印设置存储于 context variable 中(原文档 .. _text_formatting_options: 小节注明),而非模块级全局单例。这意味着不同线程或异步任务可以各自持有独立的打印配置互不干扰(详见文档交叉引用 :ref:context_local``),在多线程/异步服务场景下打印大数组时尤其重要。
import sys, numpy as np
# 上下文临时修改,退出自动恢复
with np.printoptions(precision=3, suppress=True):
print(np.array([1.23456789, 1e-5]))
# 与 np.set_printoptions + 手动恢复 等价,但异常安全
八、Base-n 表示:binary_repr 与 base_repr
binary_repr(num, width=None):整数转二进制字符串;width不足时自动补零,width足够大且num为负时可得到二进制的补码表示;base_repr(number, base=2, padding=0):整数转任意进制(2~36)字符串,padding控制最小位数补零。两者适合位操作调试、协议报文构造与进制转换工具。
九、数据源抽象:numpy.lib.npyio.DataSource
DataSource(destpath=None)(实现见 numpy/lib/_datasource.py)是 loadtxt/savetxt/genfromtxt/fromregex 等函数底层使用的统一文件打开器(源码中大量调用 np.lib._datasource.open(...)):它把本地文件与带 http://、ftp:// 等协议的远程 URL 统一抽象为文件句柄,远程文件会被下载到本地临时/缓存目录后打开。因此 loadtxt('https://example.com/data.csv') 这类用法得以成立,也解释了为什么上述文本函数接受 URL 形式路径。
十、实践选型建议
| 需求 | 推荐 API | 理由 |
|---|---|---|
| 跨平台无损保存单个数值数组 | save / load |
.npy 自描述、无精度损失 |
| 保存多个相关数组 | savez_compressed |
单文件归档 + 压缩 |
| 只读超大数组的局部切片 | load(mmap_mode='r') 或 open_memmap |
按需分页,省内存 |
| 与外部工具交换规整表格 | savetxt / loadtxt |
速度快、格式简单 |
| 含表头/缺失值的复杂文本 | genfromtxt |
字段名清洗、缺失填充、掩码 |
| 非结构化日志/文本抽取 | fromregex |
正则分组直接映射字段 |
| 与 C 程序交换裸缓冲区 | tofile / fromfile |
零头部开销 |
| 多线程各自打印格式 | printoptions + contextvars |
线程/异步隔离 |
安全提醒:load 的 allow_pickle 在 NumPy 2.x 默认关闭;对不可信来源的文件务必保持默认,避免反序列化执行任意代码。更多格式细节可继续阅读仓库中的 lib/format.py(.npy 格式规范)与 core/memmap.py(内存映射语义),配套测试见 numpy/lib/tests 目录下的相关用例。