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 版本中更改: 接受 路徑類物件。

exception gzip.BadGzipFile

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

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 的檔案位置，但它可能會更改底層檔案物件的位置（例如，如果使用 fileobj 引數構造了 GzipFile）。

在版本 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 物件 的支援。read() 方法現在接受 None 的引數。

在 3.6 版本中更改: 接受 路徑類物件。

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

在 3.12 版本中更改: 刪除 filename 屬性，請改用 name 屬性。

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

壓縮 data，返回一個包含壓縮資料的 bytes 物件。compresslevel 和 mtime 的含義與上面的 GzipFile 建構函式中的含義相同。

在版本 3.2 中新增。

在 3.8 版本中更改: 添加了用於可重複輸出的 mtime 引數。

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

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

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 模組提供了一個簡單的命令列介面來壓縮或解壓縮檔案。

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

在 3.8 版本中更改: 添加了新的命令列介面及其用法。預設情況下，當執行 CLI 時，預設壓縮級別為 6。

命令列選項

file

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

--fast

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

--best

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

-d, --decompress

解壓縮給定的檔案。

-h, --help

顯示幫助資訊。