numpy.lib.format#

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

Формат NPY#

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

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

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

Возможности#

  • Может представлять все массивы NumPy, включая вложенные записи массивов и объектные массивы.

  • Представляет данные в их родной двоичной форме.

  • Поддерживает непосредственно массивы с порядком Fortran.

  • Хранит всю необходимую информацию для восстановления массива, включая форму и dtype, на машине с другой архитектурой. Поддерживаются как little-endian, так и big-endian массивы, и файл с little-endian числами будет давать little-endian массив на любой машине, читающей файл. Типы описываются в терминах их фактических размеров. Например, если машина с 64-битным C "long int" записывает массив с "long ints", читающая машина с 32-битными C "long ints" получит массив с 64-битными целыми числами.

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

  • Позволяет memory-mapping данных. См. open_memmap.

  • Может быть прочитан из потокового объекта, подобного файлу, вместо фактического файла.

  • Хранит массивы объектов, т.е. массивы, содержащие элементы, которые являются произвольными объектами Python. Файлы с массивами объектов не могут быть отображены в память, но могут быть прочитаны и записаны на диск.

Ограничения#

  • Произвольные подклассы numpy.ndarray не сохраняются полностью. Подклассы будут приняты для записи, но только данные массива будут записаны. Обычный объект numpy.ndarray будет создан при чтении файла.

Предупреждение

Из-за ограничений в интерпретации структурированных типов данных, типы данных с полями, имеющими пустые имена, будут иметь имена, заменённые на 'f0', 'f1' и т.д. Такие массивы не будут полностью точно сохраняться при сериализации. Данные остаются нетронутыми; различаться будут только имена полей. Мы работаем над исправлением этой проблемы. Это исправление не потребует изменения формата файла. Массивы с такими структурами всё ещё можно сохранять и восстанавливать, а правильный тип данных может быть восстановлен с использованием loadedarray.view(correct_dtype) метод.

Расширения файлов#

Мы рекомендуем использовать .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 конструктор для создания dtype массива.

“fortran_order”bool

Являются ли данные массива фортран-непрерывными или нет. Поскольку фортран-непрерывные массивы являются распространенной формой не-C-непрерывности, мы позволяем им записываться непосредственно на диск для эффективности.

“форма”кортеж из int

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

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

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

Примечания#

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

Функции

descr_to_dtype(descr)

Возвращает dtype на основе заданного описания.

drop_metadata(dtype, /)

Возвращает dtype без изменений, если он не содержал метаданных, или копию dtype, если он (или любой из его структурных dtype) содержал метаданные.

dtype_to_descr(dtype)

Получить сериализуемый дескриптор из типа данных.

header_data_from_array_1_0(массив)

Получите словарь метаданных заголовка из numpy.ndarray.

isfileobj(f)

magic(major, minor)

Возвращает магическую строку для указанной версии формата файла.

open_memmap(filename[, mode, dtype, shape, ...])

Открыть файл .npy как массив с отображением в память.

read_array(fp[, allow_pickle, ...])

Прочитать массив из файла NPY.

read_array_header_1_0(fp[, max_header_size])

Прочитать заголовок массива из файлоподобного объекта с использованием версии формата файла 1.0.

read_array_header_2_0(fp[, max_header_size])

Прочитать заголовок массива из файлоподобного объекта, используя версию формата файла 2.0.

read_magic(fp)

Прочитайте магическую строку, чтобы получить версию формата файла.

write_array(fp, array[, version, ...])

Записать массив в файл NPY, включая заголовок.

write_array_header_1_0(fp, d)

Запишите заголовок для массива, используя формат 1.0.

write_array_header_2_0(fp, d)

Запишите заголовок для массива, используя формат 2.0.