gzip — 對 gzip 檔案的支援

原始碼: Lib/gzip.py

---

此模組提供了一個簡單的介面，可以像 GNU 程式 gzip 和 gunzip 那樣壓縮和解壓縮檔案。

資料壓縮由 zlib 模組提供。

gzip 模組提供了 GzipFile 類，以及 open()、compress() 和 decompress() 方便函式。GzipFile 類讀取和寫入 gzip 格式檔案，自動壓縮或解壓縮資料，使其看起來像一個普通的 檔案物件。

請注意，此模組不支援 gzip 和 gunzip 程式可以解壓縮的其他檔案格式，例如由 compress 和 pack 生成的檔案。

該模組定義了以下專案

gzip.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

以二進位制或文字模式開啟 gzip 壓縮檔案，返回一個 檔案物件。

filename 引數可以是實際的檔名（str 或 bytes 物件），也可以是用於讀寫現有檔案物件。

mode 引數可以是二進位制模式的 'r'、'rb'、'a'、'ab'、'w'、'wb'、'x' 或 'xb'，或者文字模式的 'rt'、'at'、'wt' 或 'xt'。預設值為 'rb'。

compresslevel 引數是一個介於 0 到 9 之間的整數，與 GzipFile 建構函式相同。

對於二進位制模式，此函式等同於 GzipFile 建構函式：GzipFile(filename, mode, compresslevel)。在這種情況下，不得提供 encoding、errors 和 newline 引數。

對於文字模式，會建立一個 GzipFile 物件，並將其包裝在具有指定編碼、錯誤處理行為和行尾的 io.TextIOWrapper 例項中。

版本 3.3 中有修改: 增加了對 filename 作為檔案物件的支援，對文字模式的支援，以及 encoding、errors 和 newline 引數。

版本 3.4 中有修改: 增加了對 'x'、'xb' 和 'xt' 模式的支援。

在 3.6 版本發生變更: 接受 path-like object。

exception gzip.BadGzipFile

針對無效 gzip 檔案引發的異常。它繼承自 OSError。對於無效的 gzip 檔案，也可能引發 EOFError 和 zlib.error。

在 3.8 版本加入。

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

GzipFile 類的建構函式，它模擬了 檔案物件 的大部分方法，除了 truncate() 方法。fileobj 和 filename 中至少有一個必須給定一個非平凡的值。

新的類例項基於 fileobj，它可以是普通檔案、io.BytesIO 物件或任何其他模擬檔案的物件。它預設為 None，在這種情況下會開啟 filename 以提供檔案物件。

當 fileobj 不為 None 時，filename 引數僅用於包含在 gzip 檔案頭中，其中可能包含未壓縮檔案的原始檔名。如果可以識別，它預設為 fileobj 的檔名；否則，它預設為空字串，在這種情況下，原始檔名不包含在檔案頭中。

mode 引數可以是 'r'、'rb'、'a'、'ab'、'w'、'wb'、'x' 或 'xb' 中的任何一個，具體取決於檔案是將被讀取還是寫入。如果可以識別，預設值為 fileobj 的模式；否則，預設值為 'rb'。在未來的 Python 版本中，將不再使用 fileobj 的模式。最好始終為寫入指定 mode。

請注意，檔案始終以二進位制模式開啟。要以文字模式開啟壓縮檔案，請使用 open()（或將您的 GzipFile 包裝在 io.TextIOWrapper 中）。

compresslevel 引數是一個介於 0 到 9 之間的整數，控制壓縮級別；1 最快，壓縮率最低，9 最慢，壓縮率最高。0 表示不壓縮。預設值為 9。

可選的 mtime 引數是 gzip 請求的時間戳。時間採用 Unix 格式，即自 1970 年 1 月 1 日 00:00:00 UTC 以來的秒數。如果省略 mtime 或將其設定為 None，則使用當前時間。使用 mtime = 0 可生成不依賴於建立時間的壓縮流。

有關解壓縮時設定的 mtime 屬性，請參見下文。

呼叫 GzipFile 物件的 close() 方法不會關閉 fileobj，因為您可能希望在壓縮資料之後追加更多內容。這也允許您將一個開啟用於寫入的 io.BytesIO 物件作為 fileobj 傳遞，並使用 io.BytesIO 物件的 getvalue() 方法檢索結果記憶體緩衝區。

GzipFile 支援 io.BufferedIOBase 介面，包括迭代和 with 語句。僅 truncate() 方法未實現。

GzipFile 還提供了以下方法和屬性

peek(n)

讀取 n 個未壓縮位元組，而不移動檔案位置。返回的位元組數可能多於或少於請求的位元組數。

備註

雖然呼叫 peek() 不會改變 GzipFile 的檔案位置，但它可能會改變底層檔案物件的位置（例如，如果 GzipFile 是使用 fileobj 引數構造的）。

在 3.2 版本加入。

mode

讀取時為 'rb'，寫入時為 'wb'。

版本 3.13 中有修改: 在以前的版本中，它是一個整數 1 或 2。

mtime

解壓縮時，此屬性設定為最近讀取的頭部中的最新時間戳。它是一個整數，儲存自 Unix 紀元（1970 年 1 月 1 日 00:00:00 UTC）以來的秒數。讀取任何頭部之前的初始值為 None。

name

磁碟上 gzip 檔案的路徑，作為 str 或 bytes。等同於 os.fspath() 對原始輸入路徑的輸出，沒有其他標準化、解析或擴充套件。

版本 3.1 中有修改: 增加了對 with 語句的支援，以及 mtime 建構函式引數和 mtime 屬性。

版本 3.2 中有修改: 增加了對零填充和不可查詢檔案的支援。

版本 3.3 中有修改: 現在實現了 io.BufferedIOBase.read1() 方法。

版本 3.4 中有修改: 增加了對 'x' 和 'xb' 模式的支援。

版本 3.5 中有修改: 增加了對寫入任意 bytes-like objects 的支援。read() 方法現在接受 None 引數。

在 3.6 版本發生變更: 接受 path-like object。

自版本 3.9 起已棄用: 不指定 mode 引數開啟 GzipFile 進行寫入已棄用。

版本 3.12 中有修改: 移除 filename 屬性，請改用 name 屬性。

gzip.compress(data, compresslevel=9, *, mtime=0)

壓縮 data，返回一個包含壓縮資料的 bytes 物件。compresslevel 和 mtime 的含義與上面的 GzipFile 建構函式相同，但為了可重現的輸出，mtime 預設為 0。

在 3.2 版本加入。

版本 3.8 中有修改: 增加了 mtime 引數以實現可重現的輸出。

版本 3.11 中有修改: 透過一次性壓縮所有資料而不是流式壓縮來提高速度。將 mtime 設定為 0 的呼叫委託給 zlib.compress() 以獲得更好的速度。在這種情況下，輸出可能包含一個 gzip 頭部“OS”位元組值，而不是底層 zlib 實現提供的 255“未知”。

版本 3.13 中有修改: 當使用此函式時，gzip 頭部 OS 位元組保證設定為 255，就像 3.10 及更早版本一樣。

版本 3.14 中有修改: mtime 引數現在預設為 0 以實現可重現的輸出。對於使用當前時間的先前行為，請將 None 傳遞給 mtime。

gzip.decompress(data)

解壓縮 data，返回一個包含未壓縮資料的 bytes 物件。此函式能夠解壓縮多成員 gzip 資料（多個 gzip 塊連線在一起）。當資料確定只包含一個成員時，將 wbits 設定為 31 的 zlib.decompress() 函式速度更快。

在 3.2 版本加入。

版本 3.11 中有修改: 透過一次性在記憶體中解壓縮成員而不是流式解壓縮來提高速度。

用法示例

如何讀取壓縮檔案的示例

import gzip
with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
    file_content = f.read()

如何建立壓縮 GZIP 檔案的示例

import gzip
content = b"Lots of content here"
with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
    f.write(content)

如何 GZIP 壓縮現有檔案的示例

import gzip
import shutil
with open('/home/joe/file.txt', 'rb') as f_in:
    with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
        shutil.copyfileobj(f_in, f_out)

如何 GZIP 壓縮二進位制字串的示例

import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)

參見

模組 zlib

支援 gzip 檔案格式所需的基本資料壓縮模組。

如果 gzip（解）壓縮是瓶頸，python-isal 包以大多相容的 API 加速（解）壓縮。

命令列介面

gzip 模組提供了一個簡單的命令列介面來壓縮或解壓縮檔案。

一旦執行，gzip 模組會保留輸入檔案。

版本 3.8 中有修改: 添加了一個帶有用法的新的命令列介面。預設情況下，當您執行 CLI 時，預設壓縮級別為 6。

命令列選項

file

如果未指定 file，則從 sys.stdin 讀取。

--fast

指示最快的壓縮方法（壓縮率較低）。

--best

指示最慢的壓縮方法（最佳壓縮率）。

-d, --decompress

解壓縮給定檔案。

-h, --help

顯示幫助訊息。