numpy.lib.format#

二进制序列化

NPY 格式#

用于将 numpy 数组保存到磁盘并包含有关它们的完整信息的简单格式.

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

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

功能#

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

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

  • 直接支持 Fortran 连续数组.

  • 存储重建数组所需的所有必要信息,包括在不同架构的机器上的形状和 dtype.支持小端和大端数组,并且带有小端数字的文件将在任何读取该文件的机器上产生一个小端数组.这些类型根据它们的实际大小来描述.例如,如果具有 64 位 C "long int"的机器写出一个带有"long ints" 的数组,则具有 32 位 C "long ints" 的读取机器将产生一个带有 64 位整数的数组.

  • 易于逆向工程.数据集的寿命通常比创建它们的程序更长.一个有能力的开发人员应该能够用他们喜欢的编程语言创建一个解决方案,在没有太多文档的情况下读取他们收到的大部分 .npy 文件.

  • 允许对数据进行内存映射.请参阅 open_memmap .

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

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

局限性#

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

警告

由于结构化 dtypes 解释的限制,具有空名称字段的 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 字节形成描述数组格式的头部数据.它是一个 ASCII 字符串,其中包含字典的 Python 字面表达式.它以换行符 ( \n ) 结尾,并用空格 ( \x20 ) 填充,以使 len(magic string) + 2 + len(length) + HEADER_LEN 的总和能够被 64 整除,以实现对齐.

该字典包含三个键:

“descr”]dtype.descr

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

“fortran_order”bool

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

“shape”int 元组

数组的形状.

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

在头部之后是数组数据.如果 dtype 包含 Python 对象(即 dtype.hasobject is True ),则 data 是数组的 Python pickle.否则,data 是数组的连续字节(取决于 fortran_order ,可以是 C-order 或 Fortran-order).消费者可以通过将形状给出的元素数量(注意 shape=() 表示有 1 个元素)乘以 dtype.itemsize 来计算出字节数.

格式版本 2.0#

1.0 版本格式仅允许数组头部的总大小为 65535 字节.对于具有大量列的结构化数组,这可能会超出限制.如果数据需要, numpy.save 将自动以 2.0 格式保存,否则它将始终使用更兼容的 1.0 格式.

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

格式版本 3.0#

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

注释#

.npy 格式,包括创建它的动机以及替代方案的比较,在 “npy-format” NEP 中进行了描述,但是细节随时间推移而演变,并且本文档是最新的.

函数

descr_to_dtype (descr)

返回基于给定描述的 dtype.

drop_metadata (dtype, /)

如果 dtype 不包含任何元数据,则返回 dtype 不变;如果它(或它的任何结构 dtypes)包含元数据,则返回 dtype 的副本.

dtype_to_descr (dtype)

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

header_data_from_array_1_0 (array)

Get the dictionary of header metadata from a 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