compression.zstd --- Tương thích nén với định dạng Zstandard

Added in version 3.14.

Source code: Lib/compression/zstd/__init__.py

Mô-đun này cung cấp các lớp và chức năng để nén và giải nén dữ liệu bằng thuật toán nén Zstandard (hoặc zstd). zstd manual mô tả Zstandard là "thuật toán nén không mất dữ liệu nhanh, nhắm mục tiêu các kịch bản nén thời gian thực ở cấp độ zlib và tỷ lệ nén tốt hơn". Ngoài ra còn có giao diện tệp hỗ trợ đọc và ghi nội dung của tệp .zst được tạo bởi tiện ích zstd, cũng như các luồng nén zstd thô.

Mô-đun compression.zstd 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.

Ngoại lệ

exception compression.zstd.ZstdError

Ngoại lệ này xuất hiện 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 (de)nén.

Đọc và ghi file nén

compression.zstd.open(file, /, mode='rb', *, level=None, options=None, zstd_dict=None, encoding=None, errors=None, newline=None)

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

Đối số file có thể là tên tệp (đượ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ố chế độ có thể là 'rb' để đọc (mặc định), 'wb' để ghi đè, 'ab' để nối thêm hoặc 'xb' để tạo độc quyền. Chúng tương đương có thể được đưa ra lần lượt là 'r', 'w', 'a' và 'x'. Bạn cũng có thể mở ở chế độ văn bản với 'rt', 'wt', 'at' và 'xt' tương ứng.

Khi đọc, đối số options có thể là một từ điển cung cấp các tham số giải nén nâng cao; xem DecompressionParameter để biết thông tin chi tiết về các thông số được hỗ trợ. Đối số zstd_dict là một phiên bản ZstdDict được sử dụng trong quá trình giải nén. Khi đọc, nếu đối số level không phải là Không, TypeError sẽ được nâng lên.

Khi viết, đối số options có thể là một từ điển cung cấp các tham số nén nâng cao; xem CompressionParameter để biết thông tin chi tiết về các thông số được hỗ trợ. Đối số level là mức nén được sử dụng khi ghi dữ liệu nén. Chỉ một trong số level hoặc options có thể không phải là Không. Đối số zstd_dict là một phiên bản ZstdDict được sử dụng trong quá trình nén.

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

Ở chế độ văn bản, một đối tượng ZstdFile đượ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à kết thúc dòng.

class compression.zstd.ZstdFile(file, /, mode='rb', *, level=None, options=None, zstd_dict=None)

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

Zz000zz 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ố file 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). Nếu gói một đối tượng tệp hiện có, tệp được gói sẽ không bị đóng khi đóng ZstdFile.

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

Nếu file 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 đọc, đối số options có thể là một từ điển cung cấp các tham số giải nén nâng cao; xem DecompressionParameter để biết thông tin chi tiết về các thông số được hỗ trợ. Đối số zstd_dict là một phiên bản ZstdDict được sử dụng trong quá trình giải nén. Khi đọc, nếu đối số level không phải là Không, TypeError sẽ được nâng lên.

Khi viết, đối số options có thể là một từ điển cung cấp các tham số nén nâng cao; xem CompressionParameter để biết thông tin chi tiết về các thông số được hỗ trợ. Đối số level là mức nén được sử dụng khi ghi dữ liệu nén. Chỉ một trong số level hoặc options có thể được thông qua. Đối số zstd_dict là một phiên bản ZstdDict được sử dụng trong quá trình nén.

ZstdFile 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 ZstdFile nhưng nó có thể thay đổi vị trí của đối tượng tệp cơ bản (ví dụ: nếu ZstdFile được tạo bằng cách truyền một đối tượng tệp cho file).

mode

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

name

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

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

compression.zstd.compress(data, level=None, options=None, zstd_dict=None)

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

Đối số level là một số nguyên kiểm soát mức độ nén. level là một giải pháp thay thế cho việc cài đặt CompressionParameter.compression_level trong options. Sử dụng bounds() trên compression_level để nhận các giá trị có thể được chuyển cho level. Nếu cần các tùy chọn nén nâng cao, đối số level phải được bỏ qua và trong từ điển options, tham số CompressionParameter.compression_level phải được đặt.

Đối số options là một từ điển Python chứa các tham số nén nâng cao. Các khóa và giá trị hợp lệ cho các tham số nén được ghi lại như một phần của tài liệu CompressionParameter.

Đối số zstd_dict là một phiên bản của ZstdDict chứa dữ liệu được đào tạo để cải thiện hiệu quả nén. Hàm train_dict() có thể được sử dụng để tạo từ điển Zstandard.

compression.zstd.decompress(data, zstd_dict=None, options=None)

Giải nén data (a bytes-like object), trả về dữ liệu chưa nén dưới dạng đối tượng bytes.

Đối số options là một từ điển Python chứa các tham số giải nén nâng cao. Các khóa và giá trị hợp lệ cho các tham số nén được ghi lại như một phần của tài liệu DecompressionParameter.

Đối số zstd_dict là một phiên bản của ZstdDict chứa dữ liệu đã huấn luyện được sử dụng trong quá trình nén. Đây phải là từ điển Zstandard được sử dụng trong quá trình nén.

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

class compression.zstd.ZstdCompressor(level=None, options=None, zstd_dict=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 hàm cấp mô-đun compress().

Đối số level là một số nguyên kiểm soát mức độ nén. level là một giải pháp thay thế cho việc cài đặt CompressionParameter.compression_level trong options. Sử dụng bounds() trên compression_level để nhận các giá trị có thể được chuyển cho level. Nếu cần các tùy chọn nén nâng cao, đối số level phải được bỏ qua và trong từ điển options, tham số CompressionParameter.compression_level phải được đặt.

Đối số options là một từ điển Python chứa các tham số nén nâng cao. Các khóa và giá trị hợp lệ cho các tham số nén được ghi lại như một phần của tài liệu CompressionParameter.

Đối số zstd_dict là một phiên bản tùy chọn của ZstdDict chứa dữ liệu đã được huấn luyện để cải thiện hiệu quả nén. Hàm train_dict() có thể được sử dụng để tạo từ điển Zstandard.

compress(data, mode=ZstdCompressor.CONTINUE)

Nén data (a bytes-like object), trả về đối tượng bytes với dữ liệu nén nếu có thể hoặc nói cách khác là đối tượng bytes trống. 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().

Đối số mode là thuộc tính ZstdCompressor, CONTINUE, FLUSH_BLOCK hoặc FLUSH_FRAME.

Khi tất cả dữ liệu đã được cung cấp cho máy nén, hãy gọi phương thức flush() để kết thúc quá trình nén. Nếu compress() được gọi với mode được đặt thành FLUSH_FRAME thì không nên gọi flush() vì nó sẽ ghi ra một khung trống mới.

flush(mode=ZstdCompressor.FLUSH_FRAME)

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.

Đối số mode là thuộc tính ZstdCompressor, FLUSH_BLOCK hoặc FLUSH_FRAME.

set_pledged_input_size(size)

Chỉ định lượng dữ liệu không nén size sẽ được cung cấp cho khung tiếp theo. size sẽ được ghi vào tiêu đề khung của khung tiếp theo trừ khi CompressionParameter.content_size_flag là False hoặc 0. Kích thước 0 có nghĩa là khung trống. Nếu size là None, tiêu đề khung sẽ bỏ qua kích thước khung. Các khung bao gồm kích thước dữ liệu không nén cần ít bộ nhớ hơn để giải nén, đặc biệt ở mức nén cao hơn.

Nếu last_mode không phải là FLUSH_FRAME, thì ValueError sẽ được nâng lên do bộ nén không ở đầu khung. Nếu kích thước cam kết không khớp với kích thước thực tế của dữ liệu được cung cấp cho compress() thì các lệnh gọi tới compress() hoặc flush() trong tương lai có thể tăng ZstdError và đoạn dữ liệu cuối cùng có thể bị mất.

Sau khi flush() hoặc compress() được gọi với chế độ FLUSH_FRAME, khung tiếp theo sẽ không đưa kích thước khung vào tiêu đề trừ khi set_pledged_input_size() được gọi lại.

CONTINUE

Thu thập thêm dữ liệu để nén, có thể tạo hoặc không tạo đầu ra ngay lập tức. Chế độ này tối ưu hóa tỷ lệ nén bằng cách tối đa hóa lượng dữ liệu trên mỗi khối và khung.

FLUSH_BLOCK

Hoàn thành và ghi một khối vào luồng dữ liệu. Dữ liệu được trả về cho đến nay có thể được giải nén ngay lập tức. Dữ liệu trong quá khứ vẫn có thể được tham chiếu trong các khối trong tương lai được tạo bởi các lệnh gọi tới compress(), cải thiện khả năng nén.

FLUSH_FRAME

Hoàn thành và viết ra một khung. Dữ liệu trong tương lai được cung cấp cho compress() sẽ được ghi vào một khung mới và tham chiếu đến dữ liệu trong quá khứ của cannot.

last_mode

Chế độ cuối cùng được chuyển tới compress() hoặc flush(). Giá trị có thể là một trong CONTINUE, FLUSH_BLOCK hoặc FLUSH_FRAME. Giá trị ban đầu là FLUSH_FRAME, biểu thị rằng bộ nén đang ở đầu khung mới.

class compression.zstd.ZstdDecompressor(zstd_dict=None, options=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.

Để có 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 hàm cấp mô-đun decompress().

Đối số options là một từ điển Python chứa các tham số giải nén nâng cao. Các khóa và giá trị hợp lệ cho các tham số nén được ghi lại như một phần của tài liệu DecompressionParameter.

Đối số zstd_dict là một phiên bản của ZstdDict chứa dữ liệu đã huấn luyện được sử dụng trong quá trình nén. Đây phải là từ điển Zstandard được sử dụng trong quá trình nén.

Ghi chú

Lớp này không xử lý một cách minh bạch các đầu vào chứa nhiều khung nén, không giống như hàm decompress() và lớp ZstdFile. Để giải nén đầu vào nhiều khung, bạn nên sử dụng decompress(), ZstdFile nếu làm việc với file object hoặc nhiều phiên bản ZstdDecompressor.

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, phương thức 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 khung sẽ tạo ra ZstdError. Mọi dữ liệu được tìm thấy sau khi kết thúc khung sẽ bị bỏ qua và lưu trong thuộc tính unused_data.

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 nén mới.

Từ điển Zstandard

compression.zstd.train_dict(samples, dict_size)

Huấn luyện từ điển Zstandard, trả về phiên bản ZstdDict. Từ điển Zstandard cho phép nén hiệu quả hơn các kích thước dữ liệu nhỏ hơn, vốn khó nén do ít lặp lại. Nếu bạn đang nén nhiều nhóm dữ liệu tương tự (chẳng hạn như các tệp tương tự), từ điển Zstandard có thể cải thiện đáng kể tỷ lệ nén và tốc độ.

Đối số samples (có thể lặp lại các đối tượng bytes), là tập hợp các mẫu được sử dụng để huấn luyện từ điển Zstandard.

Đối số dict_size, một số nguyên, là kích thước tối đa (tính bằng byte) mà từ điển Zstandard phải có. Tài liệu Zstandard đề xuất mức tối đa tuyệt đối không quá 100 KB, nhưng mức tối đa thường có thể nhỏ hơn tùy thuộc vào dữ liệu. Từ điển lớn hơn thường làm chậm quá trình nén nhưng cải thiện tỷ lệ nén. Từ điển nhỏ hơn dẫn đến nén nhanh hơn nhưng lại giảm tỷ lệ nén.

compression.zstd.finalize_dict(zstd_dict, /, samples, dict_size, level)

Một chức năng nâng cao để chuyển đổi từ điển Zstandard "nội dung thô" thành từ điển Zstandard thông thường. Từ điển "nội dung thô" là một chuỗi byte không cần tuân theo cấu trúc của từ điển Zstandard thông thường.

Đối số zstd_dict là một phiên bản ZstdDict với dict_content chứa nội dung từ điển thô.

Đối số samples (có thể lặp lại các đối tượng bytes), chứa dữ liệu mẫu để tạo từ điển Zstandard.

Đối số dict_size, một số nguyên, là kích thước tối đa (tính bằng byte) mà từ điển Zstandard phải có. Xem train_dict() để biết gợi ý về kích thước từ điển tối đa.

Đối số level (một số nguyên) là mức nén dự kiến ​​sẽ được chuyển tới bộ nén bằng từ điển này. Thông tin từ điển thay đổi theo từng mức nén, do đó việc điều chỉnh mức nén phù hợp có thể giúp việc nén hiệu quả hơn.

class compression.zstd.ZstdDict(dict_content, /, *, is_raw=False)

Một trình bao bọc xung quanh các từ điển Zstandard. Từ điển có thể được sử dụng để cải thiện khả năng nén nhiều khối dữ liệu nhỏ. Sử dụng train_dict() nếu bạn cần huấn luyện một từ điển mới từ dữ liệu mẫu.

Đối số dict_content (a bytes-like object), là thông tin từ điển đã được đào tạo.

Đối số is_raw, một boolean, là một tham số nâng cao kiểm soát ý nghĩa của dict_content. True có nghĩa là dict_content là một từ điển "nội dung thô", không có bất kỳ hạn chế nào về định dạng. False có nghĩa là dict_content là một từ điển Zstandard thông thường, được tạo từ các hàm Zstandard, ví dụ: train_dict() hoặc zstd CLI bên ngoài.

Khi truyền ZstdDict cho một hàm, thuộc tính as_digested_dict và as_undigested_dict có thể kiểm soát cách tải từ điển bằng cách chuyển chúng dưới dạng đối số zstd_dict, ví dụ: compress(data, zstd_dict=zd.as_digested_dict). Việc xử lý từ điển là một hoạt động tốn kém xảy ra khi tải từ điển Zstandard. Khi thực hiện nhiều lệnh gọi để nén hoặc giải nén, việc chuyển một từ điển đã được tóm tắt sẽ giảm chi phí tải từ điển.

Sự khác biệt để nén

Từ điển tiêu hóa

Từ điển khó hiểu

Các tham số nâng cao của bộ nén có thể bị ghi đè bởi các tham số của từ điển

window_log, hash_log, chain_log, search_log, min_match, target_length, strategy, enable_long_distance_matching, ldm_hash_log, ldm_min_match, ldm_bucket_size_log, ldm_hash_rate_log và một số thông số không công khai.

không có

ZstdDict lưu trữ nội bộ từ điển

Vâng. Sẽ nhanh hơn khi tải lại từ điển đã được tóm tắt với cùng mức độ nén.

Không. Nếu bạn muốn tải một từ điển chưa được tiêu hóa nhiều lần, hãy cân nhắc việc sử dụng lại đối tượng nén.

Nếu truyền ZstdDict mà không có bất kỳ thuộc tính nào, thì một từ điển chưa được tiêu hóa sẽ được chuyển theo mặc định khi nén và một từ điển đã được tóm tắt sẽ được tạo nếu cần thiết và được chuyển theo mặc định khi giải nén.

dict_content

Nội dung của từ điển Zstandard, một đối tượng bytes. Nó giống như đối số dict_content trong phương thức __init__. Nó có thể được sử dụng với các chương trình khác, chẳng hạn như chương trình zstd CLI.

dict_id

Mã định danh của từ điển Zstandard, giá trị int không âm.

Khác không có nghĩa là từ điển là thông thường, được tạo bởi các hàm Zstandard và tuân theo định dạng Zstandard.

0 nghĩa là từ điển "nội dung thô", không có bất kỳ hạn chế định dạng nào, được sử dụng cho người dùng nâng cao.

Ghi chú

Ý nghĩa của 0 đối với ZstdDict.dict_id khác với thuộc tính dictionary_id với hàm get_frame_info().

as_digested_dict

Tải như một từ điển tiêu hóa.

as_undigested_dict

Tải dưới dạng từ điển chưa tiêu hóa.

Kiểm soát tham số nâng cao

class compression.zstd.CompressionParameter

Một IntEnum chứa các phím tham số nén nâng cao có thể được sử dụng khi nén dữ liệu.

Phương thức bounds() có thể được sử dụng trên bất kỳ thuộc tính nào để nhận các giá trị hợp lệ cho tham số đó.

Các thông số là tùy chọn; bất kỳ tham số nào bị bỏ qua sẽ có giá trị được chọn tự động.

Ví dụ về giới hạn dưới và giới hạn trên của compression_level:

dưới, trên = CompressionParameter.compression_level.bounds()

Ví dụ đặt window_log ở kích thước tối đa:

_dưới, trên = CompressionParameter.window_log.bounds()
tùy chọn = {CompressionParameter.window_log: trên}
nén(b'phô mai hải ly Venezuela', options=options)
bounds()

Trả về bộ giới hạn int, (lower, upper), của tham số nén. Phương thức này nên được gọi trên thuộc tính mà bạn muốn truy xuất giới hạn. Ví dụ: để nhận các giá trị hợp lệ cho compression_level, người ta có thể kiểm tra kết quả của CompressionParameter.compression_level.bounds().

Cả giới hạn dưới và giới hạn trên đều bao gồm.

compression_level

Một phương tiện cấp cao để thiết lập các tham số nén khác ảnh hưởng đến tốc độ và tỷ lệ nén dữ liệu.

Mức nén thông thường lớn hơn 0. Giá trị lớn hơn 20 được coi là nén "siêu" và yêu cầu nhiều bộ nhớ hơn các mức khác. Các giá trị âm có thể được sử dụng để đánh đổi việc nén nhanh hơn để có tỷ lệ nén kém hơn.

Đặt mức về 0 sử dụng COMPRESSION_LEVEL_DEFAULT.

window_log

Khoảng cách tham chiếu ngược tối đa được phép mà máy nén có thể sử dụng khi nén dữ liệu, được biểu thị bằng lũy thừa của hai byte 1 << window_log. Tham số này ảnh hưởng lớn đến việc sử dụng bộ nhớ nén. Giá trị cao hơn yêu cầu nhiều bộ nhớ hơn nhưng đạt được giá trị nén tốt hơn.

Giá trị bằng 0 khiến giá trị được chọn tự động.

hash_log

Kích thước của bảng thăm dò ban đầu, theo lũy thừa của hai. Việc sử dụng bộ nhớ kết quả là 1 << (hash_log+2) byte. Các bảng lớn hơn cải thiện tỷ lệ nén của các chiến lược <= dfast và cải thiện tốc độ nén của các chiến lược > dfast.

Giá trị bằng 0 khiến giá trị được chọn tự động.

chain_log

Kích thước của bảng tìm kiếm nhiều đầu dò, là lũy thừa của hai. Việc sử dụng bộ nhớ kết quả là 1 << (chain_log+2) byte. Các bảng lớn hơn sẽ nén tốt hơn và chậm hơn. Tham số này không có tác dụng đối với chiến lược fast. Nó vẫn hữu ích khi sử dụng chiến lược dfast, trong trường hợp đó nó xác định bảng thăm dò phụ.

Giá trị bằng 0 khiến giá trị được chọn tự động.

search_log

Số lần thử tìm kiếm, là lũy thừa của hai. Nhiều lần thử hơn sẽ dẫn đến khả năng nén tốt hơn và chậm hơn. Tham số này vô dụng đối với chiến lược fast và dfast.

Giá trị bằng 0 khiến giá trị được chọn tự động.

min_match

Kích thước tối thiểu của kết quả tìm kiếm. Giá trị lớn hơn sẽ tăng tốc độ nén và giải nén nhưng giảm tỷ lệ. Lưu ý rằng Zstandard vẫn có thể tìm thấy các kết quả có kích thước nhỏ hơn, nó chỉ điều chỉnh thuật toán tìm kiếm của mình để tìm kích thước này và lớn hơn. Đối với tất cả các chiến lược < btopt, mức tối thiểu hiệu quả là 4; đối với tất cả các chiến lược > fast, mức tối đa hiệu quả là 6.

Giá trị bằng 0 khiến giá trị được chọn tự động.

target_length

Tác động của trường này phụ thuộc vào Strategy đã chọn.

Đối với các chiến lược btopt, btultra và btultra2, giá trị là độ dài của trận đấu được coi là "đủ tốt" để ngừng tìm kiếm. Giá trị lớn hơn làm cho tỷ lệ nén tốt hơn nhưng nén chậm hơn.

Đối với chiến lược fast, đó là khoảng cách giữa các mẫu đối sánh. Giá trị lớn hơn giúp nén nhanh hơn nhưng có tỷ lệ nén kém hơn.

Giá trị bằng 0 khiến giá trị được chọn tự động.

strategy

Giá trị của chiến lược đã chọn càng cao thì kỹ thuật nén được zstd sử dụng càng phức tạp, dẫn đến tỷ lệ nén cao hơn nhưng nén chậm hơn.

Xem thêm

Strategy

enable_long_distance_matching

Kết hợp khoảng cách xa có thể được sử dụng để cải thiện khả năng nén cho đầu vào lớn bằng cách tìm kết quả phù hợp lớn ở khoảng cách lớn hơn. Nó làm tăng mức sử dụng bộ nhớ và kích thước cửa sổ.

True hoặc 1 cho phép kết hợp khoảng cách xa trong khi False hoặc 0 tắt nó.

Việc bật tham số này sẽ tăng window_log mặc định lên 128 MiB trừ khi được đặt rõ ràng thành một giá trị khác. Cài đặt này được bật theo mặc định nếu window_log >= 128 MiB và chiến lược nén >= btopt (mức nén 16+).

ldm_hash_log

Kích thước của bàn để so sánh khoảng cách xa, là lũy thừa của hai. Giá trị lớn hơn sẽ tăng mức sử dụng bộ nhớ và tỷ lệ nén nhưng làm giảm tốc độ nén.

Giá trị bằng 0 khiến giá trị được chọn tự động.

ldm_min_match

Kích thước khớp tối thiểu cho trình so khớp đường dài. Giá trị lớn hơn hoặc quá nhỏ thường có thể làm giảm tỷ lệ nén.

Giá trị bằng 0 khiến giá trị được chọn tự động.

ldm_bucket_size_log

Kích thước nhật ký của mỗi nhóm trong bảng băm so khớp đường dài để giải quyết xung đột. Giá trị lớn hơn cải thiện độ phân giải va chạm nhưng giảm tốc độ nén.

Giá trị bằng 0 khiến giá trị được chọn tự động.

ldm_hash_rate_log

Tần suất chèn/tra cứu các mục vào bảng băm so khớp đường dài. Giá trị lớn hơn cải thiện tốc độ nén. Sai lệch quá xa so với giá trị mặc định có thể sẽ làm giảm tỷ lệ nén.

Giá trị bằng 0 khiến giá trị được chọn tự động.

content_size_flag

Ghi kích thước của dữ liệu sẽ được nén vào tiêu đề khung Zstandard khi biết trước khi nén.

Cờ này chỉ có hiệu lực trong các trường hợp sau:

Tất cả các lệnh nén khác có thể không ghi thông tin kích thước vào tiêu đề khung.

True hoặc 1 bật cờ kích thước nội dung trong khi False hoặc 0 tắt nó.

checksum_flag

Tổng kiểm tra bốn byte sử dụng XXHash64 của nội dung chưa nén được ghi ở cuối mỗi khung. Mã giải nén của Zstandard xác minh tổng kiểm tra. Nếu có sự không khớp, ngoại lệ ZstdError sẽ được đưa ra.

True hoặc 1 cho phép tạo tổng kiểm tra trong khi False hoặc 0 tắt nó.

dict_id_flag

Khi nén bằng ZstdDict, ID của từ điển sẽ được ghi vào tiêu đề khung.

True hoặc 1 cho phép lưu trữ ID từ điển trong khi False hoặc 0 vô hiệu hóa nó.

nb_workers

Chọn số lượng luồng sẽ được sinh ra để nén song song. Khi nb_workers > 0, cho phép nén đa luồng, giá trị 1 có nghĩa là "chế độ đa luồng một luồng". Nhiều công nhân hơn sẽ cải thiện tốc độ nhưng cũng tăng mức sử dụng bộ nhớ và giảm một chút tỷ lệ nén.

Giá trị bằng 0 sẽ vô hiệu hóa đa luồng.

job_size

Kích thước của công việc nén, tính bằng byte. Giá trị này chỉ được thực thi khi nb_workers >= 1. Mỗi công việc nén được hoàn thành song song, do đó giá trị này có thể tác động gián tiếp đến số lượng luồng hoạt động.

Giá trị bằng 0 khiến giá trị được chọn tự động.

overlap_log

Đặt lượng dữ liệu được tải lại từ các công việc (luồng) trước đó cho các công việc mới sẽ được cửa sổ giao diện sử dụng trong quá trình nén. Giá trị này chỉ được sử dụng khi nb_workers >= 1. Các giá trị được chấp nhận thay đổi từ 0 đến 9.

  • 0 có nghĩa là tự động đặt số lượng chồng chéo

  • 1 có nghĩa là không chồng chéo

  • 9 có nghĩa là sử dụng kích thước cửa sổ đầy đủ từ công việc trước đó

Mỗi lần tăng sẽ giảm một nửa/nhân đôi kích thước chồng chéo. "8" có nghĩa là sự chồng chéo của window_size/2, "7" có nghĩa là sự chồng chéo của window_size/4, v.v.

class compression.zstd.DecompressionParameter

Một IntEnum chứa các phím tham số giải nén nâng cao có thể được sử dụng khi giải nén dữ liệu. Các thông số là tùy chọn; bất kỳ tham số nào bị bỏ qua sẽ có giá trị được chọn tự động.

Phương thức bounds() có thể được sử dụng trên bất kỳ thuộc tính nào để nhận các giá trị hợp lệ cho tham số đó.

Ví dụ đặt window_log_max ở kích thước tối đa:

data = nén(b'Một số byte đệm rất dài...')

_dưới, trên = DecompressionParameter.window_log_max.bounds()

tùy chọn = {DecompressionParameter.window_log_max: trên}
giải nén(dữ liệu, tùy chọn=tùy chọn)
bounds()

Trả về bộ giới hạn int, (lower, upper), của tham số giải nén. Phương thức này nên được gọi trên thuộc tính mà bạn muốn truy xuất giới hạn.

Cả giới hạn dưới và giới hạn trên đều bao gồm.

window_log_max

Logarit cơ số hai của kích thước tối đa của cửa sổ được sử dụng trong quá trình giải nén. Điều này có thể hữu ích để hạn chế dung lượng bộ nhớ được sử dụng khi giải nén dữ liệu. Kích thước cửa sổ tối đa lớn hơn dẫn đến giải nén nhanh hơn.

Giá trị bằng 0 khiến giá trị được chọn tự động.

class compression.zstd.Strategy

Một IntEnum chứa các chiến lược nén. Các chiến lược được đánh số cao hơn tương ứng với việc nén phức tạp hơn và chậm hơn.

Ghi chú

Giá trị thuộc tính của Strategy không nhất thiết phải ổn định trên các phiên bản zstd. Chỉ có thể dựa vào thứ tự của các thuộc tính. Các thuộc tính được liệt kê dưới đây theo thứ tự.

Các chiến lược sau đây có sẵn:

fast
dfast
greedy
lazy
lazy2
btlazy2
btopt
btultra
btultra2

Linh tinh

compression.zstd.get_frame_info(frame_buffer)

Truy xuất đối tượng FrameInfo chứa siêu dữ liệu về khung Zstandard. Các khung chứa siêu dữ liệu liên quan đến dữ liệu nén mà chúng chứa.

class compression.zstd.FrameInfo

Siêu dữ liệu liên quan đến khung Zstandard.

decompressed_size

Kích thước của nội dung được giải nén của khung.

dictionary_id

Một số nguyên biểu thị ID từ điển Zstandard cần thiết để giải nén khung. 0 có nghĩa là ID từ điển không được ghi trong tiêu đề khung. Điều này có thể có nghĩa là không cần đến từ điển Zstandard hoặc ID của từ điển được yêu cầu không được ghi lại.

compression.zstd.COMPRESSION_LEVEL_DEFAULT

Mức nén mặc định cho Zstandard: 3.

compression.zstd.zstd_version_info

Số phiên bản của thư viện zstd thời gian chạy dưới dạng một bộ số nguyên (chính, phụ, phát hành).

Ví dụ

Đọc trong một tập tin nén:

từ nhập nén zstd

với zstd.open("file.zst") là f:
    file_content = f.read()

Tạo file nén:

từ nhập nén zstd

data = b"Chèn dữ liệu vào đây"
với zstd.open("file.zst", "w") là f:
    f.write(dữ liệu)

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

từ nhập nén zstd

data_in = b"Chèn dữ liệu vào đây"
data_out = zstd.compress(data_in)

Nén tăng dần:

từ nhập nén zstd

comp = zstd.ZstdCompressor()
out1 = comp.compress(b"Một số dữ liệu\n")
out2 = comp.compress(b"Một phần dữ liệu khác\n")
out3 = comp.compress(b"Thậm chí nhiều dữ liệu hơn\n")
out4 = comp.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ở:

từ nhập nén zstd

với open("myfile", "wb") là f:
    f.write(b"Dữ liệu này sẽ không được nén\n")
    với zstd.open(f, "w") là zstf:
        zstf.write(b"Z000zz này sẽ được nén\n")
    f.write(b"Không được nén\n")

Tạo file nén sử dụng các thông số nén:

từ nhập nén zstd

tùy chọn = {
   zstd.CompressionParameter.checksum_flag: 1
}
với zstd.open("file.zst", "w", options=options) là f:
    f.write(b"Tôi có thể chen vào được không?")