numpy.lib.format

Возможности

• Может представлять все массивы NumPy, включая вложенные массивы записей и массивы объектов.
• Представляет данные в их родном двоичном виде.
• Поддерживает массивы, размеченные в стиле Fortran, напрямую.
• Хранит всю необходимую информацию для восстановления массива, включая форму и тип данных на машине с другой архитектурой. Поддерживаются как массивы little-endian, так и big-endian, и файл с little-endian числами даст массив little-endian на любой машине, считывающей файл. Типы описываются в терминах их фактических размеров. Например, если машина с 64-битным C «long int» записывает массив с «long int», машина чтения с 32-битным C «long int» получит массив с 64-битными целыми числами.
• Легко обращается для анализа. Наборы данных часто живут дольше программ, которые их создали. Компетентный разработчик должен уметь создать решение на предпочитаемом языке программирования для чтения большинства файлов .npy без значительного объёма документации.
• Позволяет отобразить данные в памяти. См. open_memmap.
• Может считываться из объекта потокового ввода-вывода вместо фактического файла.
• Хранит массивы объектов, т. е. массивы, содержащие элементы, являющиеся произвольными объектами 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”кортеж целых чисел

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

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

За заголовком следуют данные массива. Если тип данных содержит объекты Python (т. е. dtype.hasobject is True), то данные являются сериализованным представлением (pickle) массива. В противном случае данные представляют собой непрерывный (либо 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) на строку UTF-8, поэтому поддерживает структурированные типы с именами полей любого юникода.

Примечания

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