bz2 --- Hỗ trợ nén bzip2

Source code: Lib/bz2.py

Mô-đun này cung cấp giao diện toàn diện để nén và giải nén dữ liệu bằng thuật toán nén bzip2.

Mô-đun bz2 chứa:

Đây là một optional module. Nếu nó bị thiếu trong bản sao CPython của bạn, hãy tìm tài liệu từ nhà phân phối của bạn (nghĩa là bất kỳ ai đã cung cấp Python cho bạn). Nếu bạn là nhà phân phối, hãy xem Yêu cầu đối với các mô-đun tùy chọn.

(De)nén tập tin

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

Mở tệp nén bzip2 ở chế độ nhị phân hoặc văn bản, trả về file object.

Giống như hàm tạo cho BZ2File, đối số filename có thể là tên tệp thực tế (đối tượng str hoặc bytes) hoặc đối tượng tệp hiện có để đọc hoặc ghi vào.

Đối số mode có thể là bất kỳ 'r', 'rb', 'w', 'wb', 'x', 'xb', 'a' hoặc 'ab' cho chế độ nhị phân hoặc 'rt', 'wt', 'xt' hoặc 'at' cho chế độ văn bản. Mặc định là 'rb'.

Đối số compresslevel là một số nguyên từ 1 đến 9, giống như đối với hàm tạo BZ2File.

Đối với chế độ nhị phân, hàm này tương đương với hàm tạo BZ2File: BZ2File(filename, mode, compresslevel=compresslevel). Trong trường hợp này, không được cung cấp các đối số encoding, errors và newline.

Đối với chế độ văn bản, một đối tượng BZ2File được tạo và được gói trong một phiên bản io.TextIOWrapper với mã hóa được chỉ định, hành vi xử lý lỗi và (các) kết thúc dòng.

Added in version 3.3.

Thay đổi trong phiên bản 3.4: Chế độ 'x' (tạo độc quyền) đã được thêm vào.

Thay đổi trong phiên bản 3.6: Chấp nhận path-like object.

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

Mở tệp nén bzip2 ở chế độ nhị phân.

Nếu filename là đối tượng str hoặc bytes, hãy mở trực tiếp tệp được đặt tên. Nếu không, filename phải là file object, sẽ được sử dụng để đọc hoặc ghi dữ liệu nén.

Đối số mode có thể là 'r' để đọc (mặc định), 'w' để ghi đè, 'x' để tạo độc quyền hoặc 'a' để thêm vào. Chúng tương đương có thể được đưa ra lần lượt là 'rb', 'wb', 'xb' và 'ab'.

Nếu filename là một đối tượng tệp (chứ không phải tên tệp thực tế), chế độ của 'w' không cắt bớt tệp và thay vào đó tương đương với 'a'.

Nếu mode là 'w' hoặc 'a' thì compresslevel có thể là số nguyên nằm giữa 1 và 9 chỉ định mức độ nén: 1 tạo ra mức nén ít nhất và 9 (mặc định) tạo ra mức nén nhiều nhất.

Nếu mode là 'r', tệp đầu vào có thể là sự kết hợp của nhiều luồng nén.

BZ2File cung cấp tất cả các thành viên được chỉ định bởi io.BufferedIOBase, ngoại trừ detach() và truncate(). Lặp lại và câu lệnh with được hỗ trợ.

BZ2File cũng cung cấp các phương thức và thuộc tính sau:

peek([n])

Trả về dữ liệu được đệm mà không nâng cao vị trí tệp. Ít nhất một byte dữ liệu sẽ được trả về (trừ khi ở EOF). Số byte chính xác được trả về không được chỉ định.

Ghi chú

Mặc dù việc gọi peek() không thay đổi vị trí tệp của BZ2File nhưng nó có thể thay đổi vị trí của đối tượng tệp cơ bản (ví dụ: nếu BZ2File được tạo bằng cách truyền một đối tượng tệp cho filename).

Added in version 3.3.

fileno()

Trả về bộ mô tả tệp cho tệp cơ bản.

Added in version 3.3.

readable()

Trả về xem tập tin đã được mở để đọc hay chưa.

Added in version 3.3.

seekable()

Trả về xem tập tin có hỗ trợ tìm kiếm hay không.

Added in version 3.3.

writable()

Trả về xem tập tin đã được mở để ghi hay chưa.

Added in version 3.3.

read1(size=-1)

Đọc tối đa size byte không nén, đồng thời cố gắng tránh thực hiện nhiều lần đọc từ luồng cơ bản. Đọc tối đa giá trị dữ liệu của bộ đệm nếu kích thước âm.

Trả về b'' nếu tệp ở EOF.

Added in version 3.3.

readinto(b)

Đọc byte vào b.

Trả về số byte đã đọc (0 cho EOF).

Added in version 3.3.

mode

'rb' để đọc và 'wb' để viết.

Added in version 3.13.

name

Tên tệp bzip2. Tương đương với thuộc tính name của file object cơ bản.

Added in version 3.13.

Thay đổi trong phiên bản 3.1: Hỗ trợ cho câu lệnh with đã được thêm vào.

Thay đổi trong phiên bản 3.3: Đã thêm hỗ trợ cho filename là file object thay vì tên tệp thực tế.

Chế độ 'a' (chắp thêm) đã được thêm vào, cùng với việc hỗ trợ đọc các tệp đa luồng.

Thay đổi trong phiên bản 3.4: Chế độ 'x' (tạo độc quyền) đã được thêm vào.

Thay đổi trong phiên bản 3.5: Phương thức read() hiện chấp nhận đối số là None.

Thay đổi trong phiên bản 3.6: Chấp nhận path-like object.

Thay đổi trong phiên bản 3.9: Thông số buffering đã bị xóa. Nó đã bị bỏ qua và không được dùng nữa kể từ Python 3.0. Truyền một đối tượng tệp đang mở để kiểm soát cách mở tệp.

Tham số compresslevel trở thành chỉ có từ khóa.

Thay đổi trong phiên bản 3.10: Lớp này không an toàn khi đối mặt với nhiều người đọc hoặc người viết đồng thời, giống như các lớp tương đương của nó trong gzip và lzma luôn như vậy.

Nén (de) tăng dần

class bz2.BZ2Compressor(compresslevel=9)

Tạo một đối tượng máy nén mới. Đối tượng này có thể được sử dụng để nén dữ liệu tăng dần. Để nén một lần, thay vào đó hãy sử dụng chức năng compress().

compresslevel, nếu được cung cấp, phải là số nguyên nằm giữa 1 và 9. Mặc định là 9.

compress(data)

Cung cấp dữ liệu cho đối tượng máy nén. Trả về một đoạn dữ liệu nén nếu có thể hoặc một chuỗi byte trống nếu không.

Khi bạn cung cấp xong dữ liệu cho máy nén, hãy gọi phương thức flush() để kết thúc quá trình nén.

flush()

Kết thúc quá trình nén. Trả về dữ liệu nén còn lại trong bộ đệm bên trong.

Đối tượng máy nén có thể không được sử dụng sau khi phương thức này được gọi.

class bz2.BZ2Decompressor

Tạo một đối tượng giải nén mới. Đối tượng này có thể được sử dụng để giải nén dữ liệu tăng dần. Để nén một lần, thay vào đó hãy sử dụng chức năng decompress().

Ghi chú

Lớp này không xử lý minh bạch các đầu vào chứa nhiều luồng nén, không giống như decompress() và BZ2File. Nếu bạn cần giải nén đầu vào nhiều luồng bằng BZ2Decompressor, bạn phải sử dụng bộ giải nén mới cho mỗi luồng.

decompress(data, max_length=-1)

Giải nén data (a bytes-like object), trả về dữ liệu không nén dưới dạng byte. Một số data có thể được lưu vào bộ đệm nội bộ để sử dụng trong các lệnh gọi tới decompress() sau này. Dữ liệu trả về phải được nối với đầu ra của bất kỳ lệnh gọi nào trước đó tới decompress().

Nếu max_length không âm, trả về tối đa max_length byte dữ liệu đã giải nén. Nếu đạt đến giới hạn này và có thể tạo thêm đầu ra, thuộc tính needs_input sẽ được đặt thành False. Trong trường hợp này, lệnh gọi tiếp theo tới decompress() có thể cung cấp data dưới dạng b'' để thu được nhiều đầu ra hơn.

Nếu tất cả dữ liệu đầu vào được giải nén và trả về (do dữ liệu này nhỏ hơn max_length byte hoặc do max_length âm), thuộc tính needs_input sẽ được đặt thành True.

Cố gắng giải nén dữ liệu sau khi kết thúc luồng sẽ tăng EOFError. Mọi dữ liệu được tìm thấy sau khi kết thúc luồng sẽ bị bỏ qua và lưu trong thuộc tính unused_data.

Thay đổi trong phiên bản 3.5: Đã thêm tham số max_length.

eof

True nếu đã đạt đến điểm đánh dấu cuối luồng.

Added in version 3.3.

unused_data

Dữ liệu được tìm thấy sau khi kết thúc luồng nén.

Nếu thuộc tính này được truy cập trước khi kết thúc luồng, giá trị của nó sẽ là b''.

needs_input

False nếu phương thức decompress() có thể cung cấp nhiều dữ liệu được giải nén hơn trước khi yêu cầu đầu vào không nén mới.

Added in version 3.5.

Nén một lần (de)

bz2.compress(data, compresslevel=9)

Nén data, bytes-like object.

compresslevel, nếu được cung cấp, phải là số nguyên nằm giữa 1 và 9. Mặc định là 9.

Để nén tăng dần, thay vào đó hãy sử dụng BZ2Compressor.

bz2.decompress(data)

Giải nén data, bytes-like object.

Nếu data là phần ghép của nhiều luồng đã nén, hãy giải nén tất cả các luồng đó.

Để giải nén tăng dần, thay vào đó hãy sử dụng BZ2Decompressor.

Thay đổi trong phiên bản 3.3: Hỗ trợ cho đầu vào đa luồng đã được thêm vào.

Ví dụ về cách sử dụng

Dưới đây là một số ví dụ về cách sử dụng điển hình của mô-đun bz2.

Sử dụng compress() và decompress() để thể hiện tính năng nén khứ hồi:

>>> 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

Sử dụng BZ2Compressor để nén tăng dần:

>>> 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()

Ví dụ trên sử dụng luồng dữ liệu rất "không ngẫu nhiên" (luồng gồm các đoạn b"z"). Dữ liệu ngẫu nhiên có xu hướng nén kém, trong khi dữ liệu có thứ tự, lặp đi lặp lại thường mang lại tỷ lệ nén cao.

Viết và đọc tệp nén bzip2 ở chế độ nhị phân:

>>> 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