numpy.lib.format #

二进制序列化

NPY 格式#

一种将 numpy 数组及其完整信息保存到磁盘的简单格式。

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

该格式是在磁盘上持久保存多个.npzNumPy 数组的标准格式。文件是包含多个文件的 zip 文件 ，每个文件对应一个数组。.npz.npy

能力#

  • 可以表示所有 NumPy 数组，包括嵌套记录数组和对象数组。

  • 以本机二进制形式表示数据。

  • 直接支持 Fortran 连续数组。

  • 存储在不同架构的机器上重建数组所需的所有信息，包括形状和数据类型。支持小端和大端数组，并且具有小端数字的文件将在读取该文件的任何机器上生成小端数组。这些类型是根据其实际尺寸来描述的。例如，如果具有 64 位 C“long int”的机器写出具有“long int”的数组，则具有 32 位 C“long int”的读取机器将生成具有 64 位整数的数组。

  • 可以直接进行逆向工程。数据集通常比创建它们的程序寿命更长。一个有能力的开发人员应该能够用他们喜欢的编程语言创建一个解决方案，以读取.npy他们在没有太多文档的情况下获得的大多数文件。

  • 允许数据的内存映射。看open_memmap。

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

  • 存储对象数组，即包含任意 Python 对象元素的数组。具有对象数组的文件不可映射，但可以读取和写入磁盘。

限制#

  • numpy.ndarray 的任意子类未完全保留。子类将被接受写入，但只会写出数组数据。读取文件时将创建一个常规的 numpy.ndarray 对象。

警告

由于结构化数据类型解释的限制，具有空名称字段的数据类型将用“f0”、“f1”等替换名称。此类数组不会完全准确地往返格式。数据完好；只有字段名称会有所不同。我们正在努力解决这个问题。此修复不需要更改文件格式。这种结构的数组仍然可以被保存和恢复，并且使用该 loadedarray.view(correct_dtype)方法可以恢复正确的数据类型。

文件扩展名#

我们建议对以此格式保存的文件使用.npy和扩展名。.npz这绝不是一个要求；应用程序可能希望使用这些文件格式，但使用特定于应用程序的扩展名。然而，在没有明显替代方案的情况下，我们建议使用.npy和.npz。

版本编号#

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

格式版本 1.0 #

前 6 个字节是一个神奇的字符串：exactly \x93NUMPY。

接下来的 1 个字节是无符号字节：文件格式的主版本号，例如\x01.

接下来的 1 个字节是无符号字节：文件格式的次版本号，例如\x00.注意：文件格式的版本与 numpy 包的版本无关。

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

接下来的 HEADER_LEN 字节形成描述数组格式的标头数据。它是一个 ASCII 字符串，其中包含字典的 Python 文字表达式。它以换行符 ( ) 结尾\n，并用空格 ( \x20) 填充，以使总数 可以被 64 整除，以便对齐。len(magic string) + 2 + len(length) + HEADER_LEN

该字典包含三个键：

“descr” dtype.descr

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

“fortran_order”布尔值

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

int 的“shape”元组

阵列的形状。

为了可重复性和可读性，字典键按字母顺序排序。这只是为了方便。如果可能的话，作家应该实现这一点。读者绝不能依赖于此。

标题后面是数组数据。如果 dtype 包含 Python 对象（即），则数据是数组的 Python pickle。否则，数据是数组的连续（C 或 Fortran，具体取决于）字节。消费者可以通过将形状给出的元素数量（注意这意味着有 1 个元素）乘以 来计算出字节数。dtype.hasobject is Truefortran_ordershape=()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（描述）

根据给定的描述返回数据类型。

dtype_to_descr（数据类型）

从数据类型获取可序列化描述符。

header_data_from_array_1_0（大批）

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

magic（主要次要）

返回给定文件格式版本的魔术字符串。

open_memmap（文件名[，模式，数据类型，形状，...]）

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

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

从 NPY 文件读取数组。

read_array_header_1_0(fp[, 最大标头大小])

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

read_array_header_2_0(fp[, 最大标头大小])

使用 2.0 文件格式版本从类文件对象读取数组头。

read_magic（FP）

读取魔术字符串以获取文件格式的版本。

write_array(fp, 数组[, 版本, ...])

将数组写入 NPY 文件，包括标头。

write_array_header_1_0（fp，d）

使用 1.0 格式编写数组的标头。

write_array_header_2_0（fp，d）

使用 2.0 格式编写数组的标头。