lzma --- Nén bằng thuật toán LZMA

Added in version 3.3.

Source code: Lib/lzma.py

Mô-đun này cung cấp các lớp và chức năng tiện lợi để nén và giải nén dữ liệu bằng thuật toán nén LZMA. Ngoài ra còn có giao diện tệp hỗ trợ các định dạng tệp .xz và .lzma cũ được tiện ích xz sử dụng, cũng như các luồng nén thô.

Giao diện được cung cấp bởi mô-đun này rất giống với giao diện của mô-đun bz2. Lưu ý rằng LZMAFile và bz2.BZ2File là not an toàn cho luồng, vì vậy nếu bạn cần sử dụng một phiên bản LZMAFile duy nhất từ ​​nhiều luồng thì cần phải bảo vệ nó bằng khó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.

exception lzma.LZMAError

Ngoại lệ này được nêu ra khi xảy ra lỗi trong quá trình nén hoặc giải nén hoặc trong khi khởi tạo trạng thái máy nén/giải nén.

Đọc và ghi file nén

lzma.open(filename, mode='rb', *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)

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

Đối số filename có thể là tên tệp thực tế (được cung cấp dưới dạng đối tượng str, bytes hoặc path-like), trong trường hợp đó tệp được đặt tên sẽ được mở hoặc có thể là đố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".

Khi mở tệp để đọc, các đối số format và filters có cùng ý nghĩa như đối với LZMADecompressor. Trong trường hợp này, không nên sử dụng đối số check và preset.

Khi mở tệp để ghi, các đối số format, check, preset và filters có cùng ý nghĩa như đối với LZMACompressor.

Đối với chế độ nhị phân, hàm này tương đương với hàm tạo LZMAFile: LZMAFile(filename, mode, ...). 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 LZMAFile đượ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.

Thay đổi trong phiên bản 3.4: Đã thêm hỗ trợ cho các chế độ "x", "xb" và "xt".

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

class lzma.LZMAFile(filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)

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

Một LZMAFile có thể bao bọc một file object đã mở hoặc hoạt động trực tiếp trên một tệp được đặt tên. Đối số filename chỉ định đối tượng tệp cần bọc hoặc tên của tệp cần mở (dưới dạng đối tượng str, bytes hoặc path-like). Khi gói một đối tượng tệp hiện có, tệp được gói sẽ không bị đóng khi đóng LZMAFile.

Đố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".

Khi mở một file để đọc, file đầu vào có thể là sự ghép nối của nhiều luồng nén riêng biệt. Chúng được giải mã minh bạch dưới dạng một luồng logic duy nhất.

Khi mở tệp để đọc, các đối số format và filters có cùng ý nghĩa như đối với LZMADecompressor. Trong trường hợp này, không nên sử dụng đối số check và preset.

Khi mở tệp để ghi, các đối số format, check, preset và filters có cùng ý nghĩa như đối với LZMACompressor.

LZMAFile hỗ trợ 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ợ.

Các phương thức và thuộc tính sau đây cũng được cung cấp:

peek(size=-1)

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 đạt tới EOF. Số byte chính xác được trả về không được chỉ định (đối số size bị bỏ qua).

Ghi chú

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

mode

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

Added in version 3.13.

name

Tên tệp lzma. 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.4: Đã thêm hỗ trợ cho chế độ "x" và "xb".

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.

Nén và giải nén dữ liệu trong bộ nhớ

class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)

Tạo một đối tượng máy nén, có thể được sử dụng để nén dữ liệu tăng dần.

Để biết cách nén một đoạn dữ liệu thuận tiện hơn, hãy xem compress().

Đối số format chỉ định định dạng vùng chứa nào sẽ được sử dụng. Các giá trị có thể là:

  • FORMAT_XZ: Định dạng vùng chứa .xz.

    Đây là định dạng mặc định.

  • FORMAT_ALONE: Định dạng vùng chứa .lzma cũ.

    Định dạng này bị hạn chế hơn .xz -- nó không hỗ trợ kiểm tra tính toàn vẹn hoặc nhiều bộ lọc.

  • FORMAT_RAW: Luồng dữ liệu thô, không sử dụng bất kỳ định dạng vùng chứa nào.

    Công cụ xác định định dạng này không hỗ trợ kiểm tra tính toàn vẹn và yêu cầu bạn luôn chỉ định chuỗi bộ lọc tùy chỉnh (cho cả nén và giải nén). Ngoài ra, dữ liệu được nén theo cách này không thể được giải nén bằng FORMAT_AUTO (xem LZMADecompressor).

Đối số check chỉ định loại kiểm tra tính toàn vẹn để đưa vào dữ liệu nén. Việc kiểm tra này được sử dụng khi giải nén, để đảm bảo dữ liệu không bị hỏng. Các giá trị có thể là:

  • CHECK_NONE: Không kiểm tra tính toàn vẹn. Đây là giá trị mặc định (và giá trị duy nhất được chấp nhận) cho FORMAT_ALONE và FORMAT_RAW.

  • CHECK_CRC32: Kiểm tra dự phòng theo chu kỳ 32-bit.

  • CHECK_CRC64: Kiểm tra dự phòng theo chu kỳ 64-bit. Đây là mặc định cho FORMAT_XZ.

  • CHECK_SHA256: Thuật toán băm an toàn 256-bit.

Nếu kiểm tra đã chỉ định không được hỗ trợ, LZMAError sẽ được nâng lên.

Cài đặt nén có thể được chỉ định dưới dạng mức nén đặt trước (với đối số preset) hoặc chi tiết dưới dạng chuỗi bộ lọc tùy chỉnh (với đối số filters).

Đối số preset (nếu được cung cấp) phải là số nguyên nằm giữa 0 và 9 (bao gồm), tùy chọn OR-ed với hằng số PRESET_EXTREME. Nếu cả preset và filters đều không được cung cấp thì hành vi mặc định là sử dụng PRESET_DEFAULT (mức đặt trước 6). Giá trị đặt trước cao hơn tạo ra đầu ra nhỏ hơn nhưng làm cho quá trình nén chậm hơn.

Ghi chú

Ngoài việc tốn nhiều CPU hơn, việc nén với giá trị đặt trước cao hơn cũng đòi hỏi nhiều bộ nhớ hơn (và tạo ra đầu ra cần nhiều bộ nhớ hơn để giải nén). Ví dụ: với 9 cài sẵn, chi phí chung cho đối tượng LZMACompressor có thể lên tới 800 MiB. Vì lý do này, tốt nhất bạn nên sử dụng cài đặt sẵn mặc định.

Đối số filters (nếu được cung cấp) phải là một thông số xác định chuỗi bộ lọc. Xem Chỉ định chuỗi bộ lọc tùy chỉnh để biết chi tiết.

compress(data)

Nén data (đối tượng bytes), trả về đối tượng bytes chứa dữ liệu đã nén cho ít nhất một phần đầu vào. 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 compress() và flush() 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 compress().

flush()

Kết thúc quá trình nén, trả về đối tượng bytes chứa bất kỳ dữ liệu nào được lưu trữ trong bộ đệm bên trong của máy nén.

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

class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)

Tạo một đối tượng giải nén, có thể được sử dụng để giải nén dữ liệu tăng dần.

Để biết cách giải nén toàn bộ luồng nén cùng lúc thuận tiện hơn, hãy xem decompress().

Đối số format chỉ định định dạng vùng chứa sẽ được sử dụng. Mặc định là FORMAT_AUTO, có thể giải nén cả file .xz và .lzma. Các giá trị khác có thể có là FORMAT_XZ, FORMAT_ALONE và FORMAT_RAW.

Đối số memlimit chỉ định giới hạn (tính bằng byte) trên dung lượng bộ nhớ mà bộ giải nén có thể sử dụng. Khi đối số này được sử dụng, quá trình giải nén sẽ không thành công với LZMAError nếu không thể giải nén đầu vào trong giới hạn bộ nhớ nhất định.

Đối số filters chỉ định chuỗi bộ lọc được sử dụng để tạo luồng được giải nén. Đối số này là bắt buộc nếu format là FORMAT_RAW nhưng không nên sử dụng cho các định dạng khác. Xem Chỉ định chuỗi bộ lọc tùy chỉnh để biết thêm thông tin về chuỗi bộ lọc.

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à LZMAFile. Để giải nén đầu vào nhiều luồng bằng LZMADecompressor, bạn phải tạo 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.

check

ID của quá trình kiểm tra tính toàn vẹn được luồng đầu vào sử dụng. Đây có thể là CHECK_UNKNOWN cho đến khi đủ số lượng đầu vào được giải mã để xác định xem nó sử dụng tính năng kiểm tra tính toàn vẹn nào.

eof

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

unused_data

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

Trước khi kết thúc luồng, đây 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.

lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)

Nén data (đối tượng bytes), trả về dữ liệu đã nén dưới dạng đối tượng bytes.

Xem LZMACompressor ở trên để biết mô tả về các đối số format, check, preset và filters.

lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)

Giải nén data (đối tượng bytes), trả về dữ liệu không nén dưới dạng đối tượng bytes.

Nếu data là phép nối của nhiều luồng nén riêng biệt, hãy giải nén tất cả các luồng này và trả về phép nối của kết quả.

Xem LZMADecompressor ở trên để biết mô tả về các đối số format, memlimit và filters.

Linh tinh

lzma.is_check_supported(check)

Trả về True nếu kiểm tra tính toàn vẹn đã cho được hỗ trợ trên hệ thống này.

CHECK_NONE và CHECK_CRC32 luôn được hỗ trợ. CHECK_CRC64 và CHECK_SHA256 có thể không khả dụng nếu bạn đang sử dụng phiên bản liblzma được biên soạn với một bộ tính năng hạn chế.

Chỉ định chuỗi bộ lọc tùy chỉnh

Công cụ xác định chuỗi bộ lọc là một chuỗi các từ điển, trong đó mỗi từ điển chứa ID và các tùy chọn cho một bộ lọc. Mỗi từ điển phải chứa khóa "id" và có thể chứa các khóa bổ sung để chỉ định các tùy chọn phụ thuộc vào bộ lọc. ID bộ lọc hợp lệ như sau:

  • Bộ lọc nén:

    • FILTER_LZMA1 (để sử dụng với FORMAT_ALONE)

    • FILTER_LZMA2 (để sử dụng với FORMAT_XZ và FORMAT_RAW)

  • Bộ lọc Delta:

    • FILTER_DELTA

  • Bộ lọc Chi nhánh-Gọi-Nhảy (BCJ):

    • FILTER_X86

    • FILTER_IA64

    • FILTER_ARM

    • FILTER_ARMTHUMB

    • FILTER_POWERPC

    • FILTER_SPARC

Chuỗi bộ lọc có thể bao gồm tối đa 4 bộ lọc và không được để trống. Bộ lọc cuối cùng trong chuỗi phải là bộ lọc nén và mọi bộ lọc khác phải là bộ lọc delta hoặc BCJ.

Bộ lọc nén hỗ trợ các tùy chọn sau (được chỉ định dưới dạng các mục bổ sung trong từ điển đại diện cho bộ lọc):

  • preset: Giá trị nén đặt sẵn để sử dụng làm nguồn giá trị mặc định cho các tùy chọn không được chỉ định rõ ràng.

  • dict_size: Kích thước từ điển tính bằng byte. Giá trị này phải nằm trong khoảng từ 4 KiB đến 1,5 GiB (đã bao gồm).

  • lc: Số bit ngữ cảnh theo nghĩa đen.

  • lp: Số bit vị trí bằng chữ. Tổng lc + lp tối đa phải bằng 4.

  • pb: Số bit vị trí; tối đa phải là 4.

  • mode: MODE_FAST hoặc MODE_NORMAL.

  • nice_len: Điều gì được coi là "độ dài vừa phải" cho một trận đấu. Giá trị này phải là 273 hoặc ít hơn.

  • mf: Sử dụng công cụ tìm đối sánh nào -- MF_HC3, MF_HC4, MF_BT2, MF_BT3 hoặc MF_BT4.

  • depth: Độ sâu tìm kiếm tối đa được sử dụng bởi công cụ tìm kết quả phù hợp. 0 (mặc định) có nghĩa là chọn tự động dựa trên các tùy chọn bộ lọc khác.

Bộ lọc delta lưu trữ sự khác biệt giữa các byte, tạo ra nhiều đầu vào lặp lại hơn cho bộ nén trong một số trường hợp nhất định. Nó hỗ trợ một tùy chọn, dist. Điều này cho biết khoảng cách giữa các byte bị trừ. Giá trị mặc định là 1, tức là lấy sự khác biệt giữa các byte liền kề.

Bộ lọc BCJ được thiết kế để áp dụng cho mã máy. Họ chuyển đổi các nhánh tương đối, các lệnh gọi và nhảy mã để sử dụng địa chỉ tuyệt đối, nhằm mục đích tăng độ dư thừa mà máy nén có thể khai thác. Các bộ lọc này hỗ trợ một tùy chọn, start_offset. Điều này chỉ định địa chỉ sẽ được ánh xạ tới phần đầu của dữ liệu đầu vào. Mặc định là 0.

Ví dụ

Đọc trong tệp nén:

nhập khẩu lzma
với lzma.open("file.xz") là f:
    file_content = f.read()

Tạo một tập tin nén:

nhập khẩu lzma
data = b"Chèn dữ liệu vào đây"
với lzma.open("file.xz", "w") là f:
    f.write(dữ liệu)

Nén dữ liệu trong bộ nhớ:

nhập khẩu lzma
data_in = b"Chèn dữ liệu vào đây"
data_out = lzma.compress(data_in)

Nén tăng dần:

nhập khẩu lzma
lzc = lzma.LZMACompressor()
out1 = lzc.compress(b"Một số dữ liệu\n")
out2 = lzc.compress(b"Một phần dữ liệu khác\n")
out3 = lzc.compress(b"Thêm dữ liệu\n")
out4 = lzc.flush()
# Concatenate tất cả các kết quả một phần:
kết quả = b"".join([out1, out2, out3, out4])

Ghi dữ liệu nén vào một tệp đã mở:

nhập khẩu lzma
với open("file.xz", "wb") là f:
    f.write(b"Dữ liệu này sẽ không được nén\n")
    với lzma.open(f, "w") là lzf:
        lzf.write(b"Z000zz này sẽ được nén\n")
    f.write(b"Không được nén\n")

Tạo tệp nén bằng chuỗi bộ lọc tùy chỉnh

nhập khẩu lzma
my_filters = [
    {"id": lzma.FILTER_DELTA, "dist": 5},
    {"id": lzma.FILTER_LZMA2, "đặt trước": 7 | lzma.PRESET_EXTREME},
]
với lzma.open("file.xz", "w", bộ lọc=my_filters) là f:
    f.write(b"blah blah blah")