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 байта образуют беззнаковое целое число типа short int в формате 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 байта составляют беззнаковое целое число типа int в формате little-endian: длина данных заголовка HEADER_LEN».

Примечания

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