zlib --- Tương thích nén với gzip

---

Đối với các ứng dụng yêu cầu nén dữ liệu, các chức năng trong mô-đun này cho phép nén và giải nén bằng cách sử dụng zlib library.

Đâ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.

Các hàm của zlib có nhiều tùy chọn và thường cần được sử dụng theo một thứ tự cụ thể. Tài liệu này không cố gắng đề cập đến tất cả các hoán vị; tham khảo zlib manual để biết thông tin có thẩm quyền.

Để đọc và ghi tệp .gz, hãy xem mô-đun gzip.

Các ngoại lệ và chức năng có sẵn trong mô-đun này là:

exception zlib.error

Ngoại lệ nảy sinh do lỗi nén và giải nén.

zlib.adler32(data[, value])

Tính tổng kiểm tra Adler-32 của data. (Tổng kiểm tra Adler-32 gần như đáng tin cậy như CRC32 nhưng có thể được tính toán nhanh hơn nhiều.) Kết quả là một số nguyên 32 bit không dấu. Nếu có value, nó được sử dụng làm giá trị bắt đầu của tổng kiểm tra; mặt khác, giá trị mặc định là 1 sẽ được sử dụng. Việc truyền vào value cho phép tính toán tổng kiểm tra đang chạy qua việc nối một số đầu vào. Thuật toán này không mạnh về mặt mật mã và không nên sử dụng để xác thực hoặc chữ ký số. Vì thuật toán được thiết kế để sử dụng làm thuật toán tổng kiểm tra nên nó không phù hợp để sử dụng làm thuật toán băm chung.

Thay đổi trong phiên bản 3.0: Kết quả luôn không được ký.

zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)

Nén các byte trong data, trả về một đối tượng byte chứa dữ liệu đã nén. level là số nguyên từ 0 đến 9 hoặc -1 kiểm soát mức độ nén; Xem Z_BEST_SPEED (1), Z_BEST_COMPRESSION (9), Z_NO_COMPRESSION (0) và mặc định, Z_DEFAULT_COMPRESSION (-1) để biết thêm thông tin về các giá trị này.

Đối số wbits kiểm soát kích thước của bộ đệm lịch sử (hoặc "kích thước cửa sổ") được sử dụng khi nén dữ liệu và liệu tiêu đề và đoạn giới thiệu có được bao gồm trong đầu ra hay không. Nó có thể có nhiều phạm vi giá trị, mặc định là 15 (MAX_WBITS):

• +9 đến +15: Logarit cơ số hai của kích thước cửa sổ, do đó nằm trong khoảng từ 512 đến 32768. Giá trị lớn hơn tạo ra khả năng nén tốt hơn nhưng phải trả giá bằng việc sử dụng bộ nhớ nhiều hơn. Kết quả đầu ra sẽ bao gồm tiêu đề và đoạn giới thiệu dành riêng cho zlib.

• −9 đến −15: Sử dụng giá trị tuyệt đối của wbits làm logarit kích thước cửa sổ, đồng thời tạo ra luồng đầu ra thô không có tổng kiểm tra tiêu đề hoặc cuối.

• +25 đến +31 = 16 + (9 đến 15): Sử dụng 4 bit thấp của giá trị làm logarit kích thước cửa sổ, đồng thời bao gồm tiêu đề gzip cơ bản và tổng kiểm tra cuối trong đầu ra.

Tăng ngoại lệ error nếu có lỗi xảy ra.

Thay đổi trong phiên bản 3.6: level hiện có thể được sử dụng làm thông số từ khóa.

Thay đổi trong phiên bản 3.11: Tham số wbits hiện có sẵn để đặt bit cửa sổ và kiểu nén.

zlib.compressobj(level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

Trả về một đối tượng nén, được sử dụng để nén các luồng dữ liệu không vừa với bộ nhớ cùng một lúc.

level là mức nén -- một số nguyên từ 0 đến 9 hoặc -1. Xem Z_BEST_SPEED (1), Z_BEST_COMPRESSION (9), Z_NO_COMPRESSION (0) và mặc định, Z_DEFAULT_COMPRESSION (-1) để biết thêm thông tin về các giá trị này.

method là thuật toán nén. Hiện tại, giá trị được hỗ trợ duy nhất là DEFLATED.

Tham số wbits kiểm soát kích thước của bộ đệm lịch sử (hoặc "kích thước cửa sổ") và định dạng tiêu đề và đoạn giới thiệu nào sẽ được sử dụng. Nó có ý nghĩa tương tự như described for compress().

Đối số memLevel kiểm soát lượng bộ nhớ được sử dụng cho trạng thái nén bên trong. Các giá trị hợp lệ nằm trong khoảng từ 1 đến 9. Giá trị cao hơn sử dụng nhiều bộ nhớ hơn nhưng nhanh hơn và tạo ra đầu ra nhỏ hơn.

strategy được sử dụng để điều chỉnh thuật toán nén. Các giá trị có thể là Z_DEFAULT_STRATEGY, Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE và Z_FIXED.

zdict là một từ điển nén được xác định trước. Đây là một chuỗi byte (chẳng hạn như đối tượng bytes) chứa các chuỗi con dự kiến ​​sẽ xuất hiện thường xuyên trong dữ liệu sẽ được nén. Những dãy tiếp theo được cho là phổ biến nhất sẽ nằm ở cuối từ điển.

Thay đổi trong phiên bản 3.3: Đã thêm tham số zdict và hỗ trợ đối số từ khóa.

zlib.crc32(data[, value])

Tính toán tổng kiểm tra CRC (Kiểm tra dự phòng theo chu kỳ) của data. Kết quả là một số nguyên 32 bit không dấu. Nếu có value, nó được sử dụng làm giá trị bắt đầu của tổng kiểm tra; mặt khác, giá trị mặc định là 0 sẽ được sử dụng. Việc truyền vào value cho phép tính toán tổng kiểm tra đang chạy qua việc nối một số đầu vào. Thuật toán này không mạnh về mặt mật mã và không nên sử dụng để xác thực hoặc chữ ký số. Vì thuật toán được thiết kế để sử dụng làm thuật toán tổng kiểm tra nên nó không phù hợp để sử dụng làm thuật toán băm chung.

Thay đổi trong phiên bản 3.0: Kết quả luôn không được ký.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Giải nén các byte trong data, trả về một đối tượng byte chứa dữ liệu không nén. Tham số wbits phụ thuộc vào định dạng của data và sẽ được thảo luận thêm bên dưới. Nếu bufsize được cung cấp, nó sẽ được sử dụng làm kích thước ban đầu của bộ đệm đầu ra. Tăng ngoại lệ error nếu có lỗi xảy ra.

Tham số wbits kiểm soát kích thước của bộ đệm lịch sử (hoặc "kích thước cửa sổ") cũng như định dạng tiêu đề và đoạn giới thiệu dự kiến. Nó tương tự như tham số cho compressobj(), nhưng chấp nhận nhiều phạm vi giá trị hơn:

• +8 đến +15: Logarit cơ số hai của kích thước cửa sổ. Đầu vào phải bao gồm tiêu đề và đoạn giới thiệu zlib.

• 0: Tự động xác định kích thước cửa sổ từ tiêu đề zlib. Chỉ được hỗ trợ kể từ zlib 1.2.3.5.

• −8 đến −15: Sử dụng giá trị tuyệt đối của wbits làm logarit kích thước cửa sổ. Đầu vào phải là luồng thô không có tiêu đề hoặc đoạn giới thiệu.

• +24 đến +31 = 16 + (8 đến 15): Sử dụng 4 bit thấp của giá trị làm logarit kích thước cửa sổ. Đầu vào phải bao gồm tiêu đề và đoạn giới thiệu gzip.

• +40 đến +47 = 32 + (8 đến 15): Sử dụng 4 bit thấp của giá trị làm logarit kích thước cửa sổ và tự động chấp nhận định dạng zlib hoặc gzip.

Khi giải nén luồng, kích thước cửa sổ không được nhỏ hơn kích thước ban đầu được sử dụng để nén luồng; sử dụng giá trị quá nhỏ có thể dẫn đến ngoại lệ error. Giá trị wbits mặc định tương ứng với kích thước cửa sổ lớn nhất và yêu cầu phải bao gồm tiêu đề và đoạn giới thiệu zlib.

bufsize là kích thước ban đầu của bộ đệm dùng để chứa dữ liệu được giải nén. Nếu cần nhiều dung lượng hơn, kích thước bộ đệm sẽ tăng lên khi cần thiết, do đó bạn không cần phải lấy giá trị này một cách chính xác; điều chỉnh nó sẽ chỉ lưu một vài cuộc gọi đến malloc().

Thay đổi trong phiên bản 3.6: wbits và bufsize có thể được sử dụng làm đối số từ khóa.

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

Trả về một đối tượng giải nén, được sử dụng để giải nén các luồng dữ liệu không vừa với bộ nhớ cùng một lúc.

Tham số wbits kiểm soát kích thước của bộ đệm lịch sử (hoặc "kích thước cửa sổ") cũng như định dạng tiêu đề và đoạn giới thiệu dự kiến. Nó có ý nghĩa tương tự như described for decompress().

Tham số zdict chỉ định một từ điển nén được xác định trước. Nếu được cung cấp, đây phải là từ điển giống như từ điển được sử dụng bởi máy nén tạo ra dữ liệu cần giải nén.

Ghi chú

Nếu zdict là một đối tượng có thể thay đổi (chẳng hạn như bytearray), bạn không được sửa đổi nội dung của nó giữa lệnh gọi tới decompressobj() và lệnh gọi đầu tiên tới phương thức decompress() của bộ giải nén.

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

Các đối tượng nén hỗ trợ các phương pháp sau:

Compress.compress(data)

Nén data, trả về một đối tượng byte chứa dữ liệu đã nén cho ít nhất một phần dữ liệu trong data. Dữ liệu này phải được nối với đầu ra được tạo bởi bất kỳ lệnh gọi nào trước đó tới phương thức compress(). Một số đầu vào có thể được lưu giữ trong bộ đệm bên trong để xử lý sau.

Compress.flush([mode])

Tất cả đầu vào đang chờ xử lý sẽ được xử lý và trả về một đối tượng byte chứa đầu ra nén còn lại. mode có thể được chọn từ các hằng số Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_BLOCK hoặc Z_FINISH, mặc định là Z_FINISH. Ngoại trừ Z_FINISH, tất cả các hằng số đều cho phép nén thêm các chuỗi dữ liệu, trong khi Z_FINISH hoàn thành luồng nén và ngăn chặn việc nén thêm bất kỳ dữ liệu nào. Sau khi gọi flush() với mode được đặt thành Z_FINISH, phương thức compress() không thể gọi lại được; hành động thực tế duy nhất là xóa đối tượng.

Compress.copy()

Trả về một bản sao của đối tượng nén. Điều này có thể được sử dụng để nén một cách hiệu quả một tập hợp dữ liệu có chung tiền tố ban đầu.

Thay đổi trong phiên bản 3.8: Đã thêm hỗ trợ copy.copy() và copy.deepcopy() cho các đối tượng nén.

Các đối tượng giải nén hỗ trợ các phương thức và thuộc tính sau:

Decompress.unused_data

Một đối tượng byte chứa bất kỳ byte nào ở cuối dữ liệu nén. Nghĩa là, nó vẫn là b"" cho đến khi có sẵn byte cuối cùng chứa dữ liệu nén. Nếu toàn bộ chuỗi byte chứa dữ liệu nén thì đây là b"", một đối tượng byte trống.

Decompress.unconsumed_tail

Đối tượng bytes chứa bất kỳ dữ liệu nào chưa được sử dụng bởi lệnh gọi decompress() cuối cùng vì nó vượt quá giới hạn cho bộ đệm dữ liệu không nén. Máy zlib chưa nhìn thấy dữ liệu này, vì vậy bạn phải cung cấp dữ liệu đó (có thể với dữ liệu khác được nối với nó) trở lại lệnh gọi phương thức decompress() tiếp theo để có được đầu ra chính xác.

Decompress.eof

Một boolean cho biết liệu luồng dữ liệu nén đã đến cuối hay chưa.

Điều này giúp có thể phân biệt giữa luồng nén được hình thành đúng và luồng không đầy đủ hoặc bị cắt bớt.

Added in version 3.3.

Decompress.decompress(data, max_length=0)

Giải nén data, trả về một đối tượng byte chứa dữ liệu chưa nén tương ứng với ít nhất một phần dữ liệu trong string. Dữ liệu này phải được nối với đầu ra được tạo bởi bất kỳ lệnh gọi nào trước đó tới phương thức decompress(). Một số dữ liệu đầu vào có thể được lưu giữ trong bộ đệm bên trong để xử lý sau.

Nếu tham số tùy chọn max_length khác 0 thì giá trị trả về sẽ không dài hơn max_length. Điều này có thể có nghĩa là không phải tất cả đầu vào nén đều có thể được xử lý; và dữ liệu chưa được sử dụng sẽ được lưu trữ trong thuộc tính unconsumed_tail. Chuỗi byte này phải được chuyển cho lệnh gọi tiếp theo tới decompress() nếu quá trình giải nén tiếp tục. Nếu max_length bằng 0 thì toàn bộ đầu vào sẽ được giải nén và unconsumed_tail trống.

Thay đổi trong phiên bản 3.6: max_length có thể được sử dụng làm đối số từ khóa.

Decompress.flush([length])

Tất cả đầu vào đang chờ xử lý sẽ được xử lý và một đối tượng byte chứa đầu ra chưa nén còn lại sẽ được trả về. Sau khi gọi flush(), phương thức decompress() không thể gọi lại được; hành động thực tế duy nhất là xóa đối tượng.

Tham số tùy chọn length đặt kích thước ban đầu của bộ đệm đầu ra.

Decompress.copy()

Trả về một bản sao của đối tượng giải nén. Điều này có thể được sử dụng để lưu trạng thái của bộ giải nén ở giữa luồng dữ liệu nhằm tăng tốc độ tìm kiếm ngẫu nhiên trong luồng tại một điểm trong tương lai.

Thay đổi trong phiên bản 3.8: Đã thêm hỗ trợ copy.copy() và copy.deepcopy() cho các đối tượng giải nén.

Các hằng số sau có sẵn để định cấu hình hành vi nén và giải nén:

zlib.DEFLATED

Phương pháp nén xì hơi.

zlib.MAX_WBITS

Kích thước cửa sổ tối đa, được biểu thị bằng lũy thừa của 2. Ví dụ: nếu MAX_WBITS là 15 thì kết quả là kích thước cửa sổ là 32 KiB.

zlib.DEF_MEM_LEVEL

Mức bộ nhớ mặc định cho các đối tượng nén.

zlib.DEF_BUF_SIZE

Kích thước bộ đệm mặc định cho các hoạt động giải nén.

zlib.Z_NO_COMPRESSION

Mức nén 0; không nén.

Added in version 3.6.

zlib.Z_BEST_SPEED

Mức nén 1; nhanh nhất và tạo ra độ nén ít nhất.

zlib.Z_BEST_COMPRESSION

Mức nén 9; chậm nhất và tạo ra lực nén nhiều nhất.

zlib.Z_DEFAULT_COMPRESSION

Mức nén mặc định (-1); một sự thỏa hiệp giữa tốc độ và nén. Hiện tại tương đương với mức nén 6.

zlib.Z_DEFAULT_STRATEGY

Chiến lược nén mặc định cho dữ liệu thông thường.

zlib.Z_FILTERED

Chiến lược nén dữ liệu được tạo bởi bộ lọc (hoặc bộ dự đoán).

zlib.Z_HUFFMAN_ONLY

Chiến lược nén chỉ buộc mã hóa Huffman.

zlib.Z_RLE

Chiến lược nén giới hạn khoảng cách khớp ở mức một (mã hóa độ dài chạy).

Hằng số này chỉ khả dụng nếu Python được biên dịch bằng zlib 1.2.0.1 trở lên.

Added in version 3.6.

zlib.Z_FIXED

Chiến lược nén ngăn chặn việc sử dụng mã Huffman động.

Hằng số này chỉ khả dụng nếu Python được biên dịch bằng zlib 1.2.2.2 trở lên.

Added in version 3.6.

zlib.Z_NO_FLUSH

Chế độ xả 0. Không có hành vi xả nước đặc biệt.

Added in version 3.6.

zlib.Z_PARTIAL_FLUSH

Chế độ xả 1. Xả càng nhiều đầu ra càng tốt.

zlib.Z_SYNC_FLUSH

Chế độ xả 2. Tất cả đầu ra được xóa và đầu ra được căn chỉnh theo ranh giới byte.

zlib.Z_FULL_FLUSH

Chế độ xả 3. Tất cả đầu ra bị xóa và trạng thái nén được đặt lại.

zlib.Z_FINISH

Chế độ xả 4. Tất cả đầu vào đang chờ xử lý đều được xử lý, không cần thêm đầu vào nào nữa.

zlib.Z_BLOCK

Chế độ xả 5. Khối giảm phát được hoàn thành và phát ra.

Hằng số này chỉ khả dụng nếu Python được biên dịch bằng zlib 1.2.2.2 trở lên.

Added in version 3.6.

zlib.Z_TREES

Chế độ xả 6, dành cho hoạt động thổi phồng. Hướng dẫn lạm phát quay trở lại khi đến ranh giới khối giảm phát tiếp theo.

Hằng số này chỉ khả dụng nếu Python được biên dịch bằng zlib 1.2.3.4 trở lên.

Added in version 3.6.

Thông tin về phiên bản của thư viện zlib đang sử dụng có sẵn thông qua các hằng số sau:

zlib.ZLIB_VERSION

Chuỗi phiên bản của thư viện zlib được sử dụng để xây dựng mô-đun. Điều này có thể khác với thư viện zlib thực sự được sử dụng trong thời gian chạy, có sẵn dưới dạng ZLIB_RUNTIME_VERSION.

zlib.ZLIB_RUNTIME_VERSION

Chuỗi phiên bản của thư viện zlib thực sự được trình thông dịch tải.

Added in version 3.3.

zlib.ZLIBNG_VERSION

Chuỗi phiên bản của thư viện zlib-ng được sử dụng để xây dựng mô-đun nếu zlib-ng được sử dụng. Khi hiện diện, các hằng số ZLIB_VERSION và ZLIB_RUNTIME_VERSION phản ánh phiên bản của zlib API do zlib-ng cung cấp.

Nếu zlib-ng không được sử dụng để xây dựng mô-đun thì hằng số này sẽ không có.

Added in version 3.14.

Xem thêm

Mô-đun gzip

Đọc và ghi các tập tin định dạng gzip-.

https://www.zlib.net

Trang chủ thư viện zlib.

https://www.zlib.net/manual.html

Hướng dẫn sử dụng zlib giải thích ngữ nghĩa và cách sử dụng nhiều chức năng của thư viện.

Trong trường hợp quá trình nén gzip (de) bị tắc nghẽn, gói python-isal sẽ tăng tốc độ nén (de) bằng API gần như tương thích.