numpy.lib.format

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

Формат 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».

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

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

Примечания

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

Функции