numpy.lib.format#

二進位序列化

NPY 格式#

一種用於將 numpy 陣列儲存到磁碟的簡單格式，其中包含關於它們的完整資訊。

.npy 格式是 NumPy 中用於將單個任意 NumPy 陣列持久儲存到磁碟的標準二進位檔案格式。此格式儲存重建陣列所需的所有形狀和 dtype 資訊，即使在具有不同架構的另一台機器上也是如此。此格式的設計盡可能簡單，同時實現其有限的目標。

.npz 格式是用於將多個 NumPy 陣列持久儲存到磁碟的標準格式。.npz 檔案是一個 zip 檔案，其中包含多個 .npy 檔案，每個陣列一個檔案。

功能#

  • 可以表示所有 NumPy 陣列，包括巢狀記錄陣列和物件陣列。

  • 以其原生二進位形式表示資料。

  • 直接支援 Fortran 相鄰陣列。

  • 儲存重建陣列所需的所有資訊，包括在具有不同架構的機器上的形狀和 dtype。支援小端和大端陣列，並且具有小端數字的檔案將在任何讀取該檔案的機器上產生小端陣列。這些型別根據它們的實際大小進行描述。例如，如果具有 64 位元 C "long int" 的機器寫出具有 "long int" 的陣列，則具有 32 位元 C "long int" 的讀取機器將產生具有 64 位元整數的陣列。

  • 易於逆向工程。資料集通常比建立它們的程式壽命更長。一個稱職的開發人員應該能夠用他們首選的程式語言建立一個解決方案，以讀取他們獲得的大多數 .npy 檔案，而無需太多文件。

  • 允許對資料進行記憶體映射。請參閱 open_memmap。

  • 可以從類似檔案的流物件而不是實際檔案中讀取。

  • 儲存物件陣列，即包含作為任意 Python 物件的元素的陣列。具有物件陣列的檔案不可記憶體映射，但可以讀取和寫入到磁碟。

限制#

  • numpy.ndarray 的任意子類別無法完全保留。子類別將被接受用於寫入，但只會寫出陣列資料。在讀取檔案時，將建立常規的 numpy.ndarray 物件。

警告

由於對結構化 dtype 的解釋存在限制，具有空名稱欄位的 dtype 將會把名稱替換為 'f0'、'f1' 等。此類陣列將無法完全準確地通過格式往返。資料是完整的；只有欄位名稱會有所不同。我們正在努力修復這個問題。此修復不需要更改檔案格式。具有此類結構的陣列仍然可以儲存和還原，並且可以使用 loadedarray.view(correct_dtype) 方法還原正確的 dtype。

檔案副檔名#

我們建議對於以此格式儲存的檔案使用 .npy 和 .npz 副檔名。這絕不是一項要求；應用程式可能希望使用這些檔案格式，但使用特定於應用程式的副檔名。但是，在沒有明顯替代方案的情況下，我們建議使用 .npy 和 .npz。

版本編號#

這些格式的版本編號與 NumPy 版本編號無關。如果格式升級，numpy.io 中的程式碼仍然能夠讀取和寫入版本 1.0 檔案。

格式版本 1.0#

前 6 個位元組是魔術字串：正好是 \x93NUMPY。

接下來的 1 個位元組是一個無號位元組：檔案格式的主要版本號，例如 \x01。

接下來的 1 個位元組是一個無號位元組：檔案格式的次要版本號，例如 \x00。注意：檔案格式的版本與 numpy 套件的版本無關。

接下來的 2 個位元組形成一個小端無號短整數：標頭資料 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

陣列資料是否為 Fortran 相鄰。由於 Fortran 相鄰陣列是非 C 相鄰的常見形式，我們允許將它們直接寫入磁碟以提高效率。

“shape”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 GiB。numpy.save 如果資料需要，將自動以 2.0 格式儲存，否則它將始終使用更相容的 1.0 格式。

因此，標頭的第四個元素的描述已變為：「接下來的 4 個位元組形成一個小端無號整數：標頭資料 HEADER_LEN 的長度。」

格式版本 3.0#

此版本將 ASCII 字串（實際上是 latin1）替換為 utf8 編碼的字串，因此支援具有任何 unicode 欄位名稱的結構化型別。

註解#

.npy 格式，包括建立它的動機以及替代方案的比較，在 “npy-format” NEP 中進行了描述，但是細節隨著時間的推移而演變，並且本文檔是最新的。

函式

descr_to_dtype(descr)

根據給定的描述傳回 dtype。

drop_metadata(dtype, /)

如果 dtype 不包含任何元資料，則傳回未更改的 dtype；如果它（或其任何結構 dtype）包含元資料，則傳回 dtype 的副本。

dtype_to_descr(dtype)

從 dtype 取得可序列化的描述符。

header_data_from_array_1_0(array)

從 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 格式寫入陣列的標頭。