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 байта образуют беззнаковое целое число 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

Являются ли данные массива фортрановски упорядоченными или нет. Поскольку фортрановское упорядочение данных — распространённый вид не-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) на строку UTF-8, поэтому поддерживает структурированные типы с любыми именами полей Unicode.

Примечания

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