numpy.lib.формат

Бинарная сериализация

Формат NPY

Простой формат для сохранения массивов NumPy на диске с полной информацией о них.

Формат .npy является стандартным бинарным форматом файлов в NumPy для сохранения одного произвольного массива NumPy на диске. Формат хранит всю информацию о форме и типе данных, необходимую для правильной реконструкции массива даже на другой машине с другой архитектурой. Формат разработан для максимальной простоты при достижении ограниченных целей.

Формат .npz является стандартным форматом для сохранения нескольких массивов NumPy на диске. Файл .npz представляет собой zip-архив, содержащий несколько файлов .npy, по одному для каждого массива.

Возможности

• Может представлять все массивы NumPy, включая вложенные массивы с записями и объектами.
• Представляет данные в их исходном бинарном виде.
• Поддерживает массивы, хранящиеся в формате Fortran.
• Хранит всю необходимую информацию для реконструкции массива, включая форму и тип данных на машине с другой архитектурой. Поддерживаются как little-endian, так и big-endian массивы, и файл с little-endian числами даст массив little-endian на любой машине, читающей файл. Типы описываются в терминах их фактических размеров. Например, если машина с 64-битным C «long int» записывает массив с «long int», машина с 32-битным C «long int» получит массив с 64-битными целыми числами.
• Легко поддаётся обратной инжинирингу. Наборы данных часто живут дольше программ, которые их создали. Компетентный разработчик должен быть способен создать решение на своём предпочтительном языке программирования для чтения большинства файлов .npy без большого количества документации.
• Поддерживает размещение данных в памяти. Смотрите open_memmep.
• Может читаться из объекта потока файлов вместо фактического файла.
• Хранит массивы объектов, т.е. массивы, содержащие элементы, которые являются произвольными Python-объектами. Файлы с массивами объектов не могут быть отображены в памяти, но могут быть читаны и записаны на диск.

Ограничения

• Произвольные подклассы numpy.ndarray не сохраняются полностью. Подклассы будут приняты для записи, но будут записаны только данные массива. При чтении файла будет создан обычный объект numpy.ndarray.

Расширения файлов

Мы рекомендуем использовать расширения .npy и .npz для файлов, сохранённых в этом формате. Это ни в коем случае не является требованием; приложения могут использовать эти форматы файлов, но использовать расширение, специфичное для приложения. Однако, в отсутствие очевидной альтернативы, мы рекомендуем использовать .npy и .npz.

Нумерация версий

Нумерация версий этих форматов независима от нумерации версий NumPy. Если формат обновляется, код в numpy.io по-прежнему сможет читать и записывать файлы версии 1.0.

Формат версии 1.0

Первые 6 байтов — магическая строка: ровно \x93NUMPY.

Следующий 1 байт — беззнаковое целое число: номер основной версии формата файла, например, \x01.

Следующий 1 байт — беззнаковое целое число: номер дополнительной версии формата файла, например, \x00. Примечание: версия формата файла не связана с версией пакета numpy.

Следующие 2 байта образуют беззнаковое целое число типа little-endian: длина заголовка данных HEADER_LEN.

Следующие HEADER_LEN байтов составляют данные заголовка, описывающие формат массива. Это строка ASCII, содержащая выражение Python-литерала словаря. Она завершается новой строкой (\n) и заполняется пробелами (\x20) для того, чтобы общее количество len(magic string) + 2 + len(length) + HEADER_LEN было кратно 64 для выравнивания.

Словарь содержит три ключа:

“descr” : dtype.descr

Объект, который может быть передан в качестве аргумента конструктору numpy.dtype для создания типа данных массива.

“fortran_order” : bool

Являются ли данные массива Fortran-непрерывными или нет. Поскольку Fortran-непрерывные массивы являются распространённой формой не C-непрерывности, мы позволяем записывать их непосредственно на диск для повышения эффективности.

“shape” : tuple of int

Форма массива.

Для повторяемости и удобочитаемости ключи словаря сортируются в алфавитном порядке. Это сделано только для удобства. Пишущий ДОЛЖЕН реализовать это, если это возможно. Читающий НЕ ДОЛЖЕН полагаться на это.

После заголовка идут данные массива. Если тип данных содержит Python-объекты (т.е. dtype.hasobject is True), то данные представляют собой Python-пикль массива. В противном случае данные представляют собой непрерывные (либо C-, либо Fortran-, в зависимости от fortran_order) байты массива. Потребители могут определить количество байтов, умножив количество элементов, заданное формой (примечание, что shape=() означает 1 элемент), на dtype.itemsize.

Формат версии 2.0

Формат версии 1.0 разрешал заголовку массива иметь общий размер всего 65535 байт. Это может быть превышено структурированными массивами с большим количеством столбцов. Формат версии 2.0 расширяет размер заголовка до 4 ГБ. numpy.save автоматически сохранит данные в формате 2.0, если это необходимо, в противном случае он всегда будет использовать более совместимый формат 1.0.

Поэтому описание четвёртого элемента заголовка стало следующим: «Следующие 4 байта образуют беззнаковое целое число типа little-endian: длина заголовка данных HEADER_LEN».

Примечания

Формат .npy, включая мотивацию для его создания и сравнение альтернатив, описан в “npy-format” NEP, однако детали со временем изменились, и этот документ более актуальный.