numpy.lib.format

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

Формат NPY

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

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

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

Возможности

• Может представлять все массивы NumPy, включая вложенные массивы записей и массивы объектов.
• Представляет данные в их родном двоичном виде.
• Поддерживает массивы, упорядоченные по Фортрану, непосредственно.
• Хранит всю необходимую информацию для реконструкции массива, включая форму и тип данных на машине с другой архитектурой. Поддерживаются как массивы с порядком байт 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-непрерывным или нет. Поскольку массивы, упорядоченные по Фортрану, являются распространённой формой непрерывности, отличной от C, мы позволяем записывать их непосредственно на диск для повышения эффективности.

“shape”кортеж из целых чисел

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

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

За заголовком следуют данные массива. Если тип данных содержит объекты 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, включая мотивацию для его создания и сравнение альтернатив, описан в NEP «npy-формата», однако детали со временем эволюционировали, и этот документ более современный.

Функции