bz2 — bzip2 壓縮支援

原始碼: Lib/bz2.py

此模組提供了使用 bzip2 壓縮演算法壓縮和解壓縮資料的全面介面。

bz2 模組包含

檔案（解）壓縮

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

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

與 BZ2File 的建構函式一樣，*filename* 引數可以是實際檔名（一個 str 或 bytes 物件），也可以是現有檔案物件用於讀取或寫入。

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

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

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

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

在 3.3 版本加入。

在 3.4 版本發生變更: 添加了 'x'（獨佔建立）模式。

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

class bz2.BZ2File(filename, mode='r', *, compresslevel=9)

以二進位制模式開啟 bzip2 壓縮檔案。

如果 *filename* 是 str 或 bytes 物件，則直接開啟指定檔案。否則，*filename* 應該是一個 檔案物件，它將用於讀取或寫入壓縮資料。

*mode* 引數可以是 'r' 用於讀取（預設），'w' 用於覆蓋，'x' 用於獨佔建立，或 'a' 用於追加。這些也可以等效地表示為 'rb'、'wb'、'xb' 和 'ab'。

如果 *filename* 是檔案物件（而不是實際檔名），則模式 'w' 不會截斷檔案，而是等同於 'a'。

如果 *mode* 是 'w' 或 'a'，*compresslevel* 可以是介於 1 和 9 之間的整數，指定壓縮級別：1 產生最小壓縮，9（預設）產生最大壓縮。

如果 *mode* 是 'r'，則輸入檔案可以是多個壓縮流的串聯。

BZ2File 提供了 io.BufferedIOBase 指定的所有成員，除了 detach() 和 truncate()。支援迭代和 with 語句。

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

peek([n])

返回緩衝資料，而不移動檔案位置。至少返回一個位元組的資料（除非到達檔案末尾）。返回位元組的確切數量未指定。

備註

雖然呼叫 peek() 不會改變 BZ2File 的檔案位置，但它可能會改變底層檔案物件的位置（例如，如果 BZ2File 是透過將檔案物件作為 *filename* 傳遞來構造的）。

在 3.3 版本加入。

fileno()

返回底層檔案的檔案描述符。

在 3.3 版本加入。

readable()

返回檔案是否以讀取模式開啟。

在 3.3 版本加入。

seekable()

返回檔案是否支援查詢。

在 3.3 版本加入。

writable()

返回檔案是否以寫入模式開啟。

在 3.3 版本加入。

read1(size=-1)

讀取最多 *size* 個未壓縮位元組，同時儘量避免從底層流進行多次讀取。如果 *size* 為負，則讀取緩衝區大小的資料。

如果檔案已到達檔案末尾，則返回 b''。

在 3.3 版本加入。

readinto(b)

將位元組讀入 *b*。

返回讀取的位元組數（檔案末尾為 0）。

在 3.3 版本加入。

mode

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

在 3.13 版本加入。

name

bzip2 檔名。等同於底層 檔案物件 的 name 屬性。

在 3.13 版本加入。

在 3.1 版本發生變更: 添加了對 with 語句的支援。

在 3.3 版本發生變更: 添加了對 *filename* 作為 檔案物件 而不是實際檔名的支援。

添加了 'a'（追加）模式，以及對讀取多流檔案的支援。

在 3.4 版本發生變更: 添加了 'x'（獨佔建立）模式。

在 3.5 版本發生變更: read() 方法現在接受 None 引數。

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

在 3.9 版本發生變更: *buffering* 引數已被移除。自 Python 3.0 以來，它已被忽略和棄用。傳遞一個開啟的檔案物件以控制檔案如何開啟。

*compresslevel* 引數變為僅限關鍵字。

在 3.10 版本發生變更: 此類別在面對多個併發讀取或寫入者時是執行緒不安全的，就像 gzip 和 lzma 中等效的類始終一樣。

增量（解）壓縮

class bz2.BZ2Compressor(compresslevel=9)

建立一個新的壓縮器物件。此物件可用於增量壓縮資料。對於一次性壓縮，請改用 compress() 函式。

如果給出 *compresslevel*，則它必須是介於 1 和 9 之間的整數。預設值為 9。

compress(data)

向壓縮器物件提供資料。如果可能，返回一個壓縮資料塊，否則返回一個空位元組串。

當你完成向壓縮器提供資料後，呼叫 flush() 方法以完成壓縮過程。

flush()

完成壓縮過程。返回內部緩衝區中剩餘的壓縮資料。

呼叫此方法後，壓縮器物件不能再使用。

class bz2.BZ2Decompressor

建立一個新的解壓縮器物件。此物件可用於增量解壓縮資料。對於一次性壓縮，請改用 decompress() 函式。

備註

與 decompress() 和 BZ2File 不同，此類別不會透明地處理包含多個壓縮流的輸入。如果你需要使用 BZ2Decompressor 解壓縮多流輸入，則必須為每個流使用一個新的解壓縮器。

decompress(data, max_length=-1)

解壓縮 *data*（一個 bytes-like object），以位元組形式返回未壓縮資料。部分 *data* 可能會在內部緩衝，用於後續呼叫 decompress()。返回的資料應與之前對 decompress() 的任何呼叫的輸出連線起來。

如果 *max_length* 為非負數，則最多返回 *max_length* 位元組的解壓縮資料。如果達到此限制並且可以產生更多輸出，則 needs_input 屬性將設定為 False。在這種情況下，下次呼叫 decompress() 可以將 *data* 作為 b'' 提供以獲取更多輸出。

如果所有輸入資料都已解壓縮並返回（無論是由於小於 *max_length* 位元組，還是因為 *max_length* 為負），則 needs_input 屬性將設定為 True。

在流末尾到達後嘗試解壓縮資料會引發 EOFError。在流末尾之後找到的任何資料都將被忽略並儲存在 unused_data 屬性中。

在 3.5 版本發生變更: 添加了 *max_length* 引數。

eof

如果已到達流末尾標記，則為 True。

在 3.3 版本加入。

unused_data

壓縮流結束後發現的資料。

如果在到達流末尾之前訪問此屬性，其值將為 b''。

needs_input

如果 decompress() 方法可以在需要新的未壓縮輸入之前提供更多解壓縮資料，則為 False。

在 3.5 版本加入。

一次性（解）壓縮

bz2.compress(data, compresslevel=9)

壓縮 *data*，一個 bytes-like object。

如果給出 *compresslevel*，則它必須是介於 1 和 9 之間的整數。預設值為 9。

對於增量壓縮，請改用 BZ2Compressor。

bz2.decompress(data)

解壓縮 *data*，一個 bytes-like object。

如果 *data* 是多個壓縮流的串聯，則解壓縮所有流。

對於增量解壓縮，請改用 BZ2Decompressor。

在 3.3 版本發生變更: 添加了對多流輸入的支援。

使用示例

以下是一些 bz2 模組的典型用法示例。

使用 compress() 和 decompress() 演示往返壓縮

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c)  # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d  # Check equality to original object after round-trip
True

使用 BZ2Compressor 進行增量壓縮

>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
...     """Yield incremental blocks of chunksize bytes."""
...     for _ in range(chunks):
...         yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
...     # Provide data to the compressor object
...     out = out + comp.compress(chunk)
...
>>> # Finish the compression process.  Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()

上面的例子使用了一個非常“非隨機”的資料流（由 b"z" 塊組成的流）。隨機資料通常壓縮效果不佳，而有序的重複資料通常能產生高壓縮比。

以二進位制模式讀寫 bzip2 壓縮檔案

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
...     # Write compressed data to file
...     unused = f.write(data)
...
>>> with bz2.open("myfile.bz2", "rb") as f:
...     # Decompress data from file
...     content = f.read()
...
>>> content == data  # Check equality to original object after round-trip
True