numpy.lib.format#

二进制序列化

NPY 格式#

一个简单的格式,用于将numpy数组连同它们的所有信息一起保存到磁盘上.

.npy 格式是 NumPy 中用于持久化 单个 任意 NumPy 数组到磁盘的标准二进制文件格式.该格式存储了重建数组所需的所有形状和数据类型信息,即使在具有不同架构的另一台机器上也能正确重建.该格式设计得尽可能简单,同时实现其有限的目标.

.npz 格式是持久化 多个 NumPy 数组到磁盘的标准格式.一个 .npz 文件是一个包含多个 .npy 文件的 zip 文件,每个文件对应一个数组.

能力#

  • 可以表示所有 NumPy 数组,包括嵌套的记录数组和对象数组.

  • 以原生二进制形式表示数据.

  • 直接支持Fortran连续数组.

  • 存储所有必要的信息以在不同架构的机器上重建数组,包括形状和数据类型.支持小端序和大端序数组,并且在小端序机器上写入的文件将在任何读取该文件的机器上产生小端序数组.类型以其实际大小描述.例如,如果一台具有64位C “long int” 的机器写出一个包含 “long ints” 的数组,那么具有32位C “long ints” 的读取机器将产生一个包含64位整数的数组.

  • 反向工程很简单.数据集通常比创建它们的程序存在时间更长.一个有能力的开发者应该能够在他们首选的编程语言中创建一个解决方案,以读取他们被给予的大多数 .npy 文件,而无需太多文档.

  • 允许内存映射数据.请参见 open_memmap.

  • 可以从类文件流对象读取,而不是实际的文件.

  • 存储对象数组,即包含任意 Python 对象的数组.包含对象数组的文件不可被内存映射,但可以读取和写入磁盘.

限制#

  • numpy.ndarray 的任意子类不能完全保留.子类将被接受用于写入,但只有数组数据将被写入.读取文件时将创建一个常规的 numpy.ndarray 对象.

警告

由于对结构化dtypes解释的限制,字段名称为空的名字将被替换为’f0’, ‘f1’等.这样的数组将无法完全准确地通过格式往返.数据是完整的;只有字段名称会有所不同.我们正在努力解决这个问题.这个修复不需要更改文件格式.具有这种结构的数组仍然可以保存和恢复,并且可以通过使用``loadedarray.view(correct_dtype)``方法恢复正确的dtype.

文件扩展名#

我们建议使用 .npy 和 .npz 扩展名来保存这种格式的文件.这绝不是一个要求;应用程序可能希望使用这些文件格式,但使用特定于应用程序的扩展名.如果没有明显的替代方案,我们建议使用 .npy 和 .npz.

版本编号#

这些格式的版本编号独立于 NumPy 版本编号.如果格式升级,`numpy.io` 中的代码仍然能够读写版本 1.0 的文件.

格式版本 1.0#

前6个字节是一个魔法字符串:确切地为 \x93NUMPY.

下一个1字节是一个无符号字节:文件格式的主版本号,例如 \x01.

下一个1字节是一个无符号字节:文件格式的次版本号,例如 \x00.注意:文件格式的版本与numpy包的版本无关.

接下来的2个字节构成一个小端无符号短整型:头数据的长度 HEADER_LEN.

接下来的 HEADER_LEN 字节构成了描述数组格式的头数据.它是一个包含 Python 字典字面表达式的 ASCII 字符串.它以换行符 (\n) 结束,并用空格 (\x20) 填充,以使 len(magic string) + 2 + len(length) + HEADER_LEN 的总和能被 64 整除,以便于对齐.

字典包含三个键:

descrdtype.descr

可以作为参数传递给 numpy.dtype 构造函数以创建数组 dtype 的对象.

fortran_orderbool

数组数据是否为Fortran连续的.由于Fortran连续数组是一种常见的非C连续形式,我们允许它们为了效率直接写入磁盘.

形状int 的元组

数组的形状.

为了可重复性和可读性,字典键按字母顺序排序.这仅是为了方便.如果可能,写入者应该实现这一点.读取者不得依赖于此.

标题之后是数组数据.如果 dtype 包含 Python 对象（即 dtype.hasobject 为 True）,那么数据是数组的 Python pickle.否则,数据是数组的连续字节（取决于 fortran_order 是 C 还是 Fortran）.消费者可以通过将形状给出的元素数量（注意 shape=() 意味着有 1 个元素）乘以 dtype.itemsize 来计算字节数.

格式版本 2.0#

版本 1.0 格式仅允许数组头部的总大小为 65535 字节.这可以通过具有大量列的结构化数组超出.版本 2.0 格式将头部大小扩展到 4 GiB.`numpy.save` 将自动在需要时保存为 2.0 格式,否则它将始终使用更兼容的 1.0 格式.

因此,标题的第四个元素的描述变为:”接下来的4个字节形成一个小端序无符号整数:标题数据长度 HEADER_LEN.”

格式版本 3.0#

此版本用 utf8 编码的字符串替换了 ASCII 字符串（实际上是 latin1）,因此支持具有任何 unicode 字段名称的结构化类型.

备注

.npy 格式,包括创建它的动机和与其他格式的比较,在 “npy-format” NEP 中有描述,然而细节随着时间演变,本文档更为当前.

函数

descr_to_dtype(descr)

返回基于给定描述的dtype.

dtype_to_descr(dtype)

从 dtype 获取一个可序列化的描述符.

header_data_from_array_1_0(array)

从 numpy.ndarray 获取头元数据的字典.

isfileobj(f)

magic(major, minor)

返回给定文件格式版本的魔法字符串.

open_memmap(filename[, mode, dtype, shape, ...])

将 .npy 文件作为内存映射数组打开.

read_array(fp[, allow_pickle, ...])

从NPY文件中读取数组.

read_array_header_1_0(fp[, max_header_size])

使用1.0文件格式版本从类文件对象中读取数组头.

read_array_header_2_0(fp[, max_header_size])

使用2.0文件格式版本从一个类文件对象中读取数组头.

read_magic(fp)

读取魔法字符串以获取文件格式的版本.

write_array(fp, array[, version, ...])

将数组写入NPY文件,包括一个头文件.

write_array_header_1_0(fp, d)

使用1.0格式编写数组的标题.

write_array_header_2_0(fp, d)

使用2.0格式编写数组的标题.
On this page