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».

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

Эта версия заменяет строку ASCII (которая на практике была latin1) на строку utf8, поэтому поддерживает структурированные типы с любыми именами полей Unicode.

Примечания

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