zlib --- فشردهسازی سازگار با gzip¶
برای برنامههایی که به فشردهسازی دادهها نیاز دارند، توابع این ماژول امکان فشردهسازی و خارجسازی از حالت فشرده را با استفاده از کتابخانه zlib فراهم میکنند.
این یک ماژول اختیاری است. اگر در نسخه CPython شما وجود ندارد، به مستندات توزیعکننده خود مراجعه کنید (یعنی هر کسی که پایتون را در اختیار شما قرار داده است). اگر شما توزیعکننده هستید، نیازمندیهای ماژولهای اختیاری را ببینید.
توابع zlib گزینههای زیادی دارند و اغلب باید به ترتیب خاصی استفاده شوند. این مستندات در پی پوشش تمام ترکیبهای ممکن نیست؛ برای اطلاعات مرجع به راهنمای zlib مراجعه کنید.
برای خواندن و نوشتن پروندههای .gz، ماژول gzip را ببینید.
استثنا و توابع موجود در این ماژول عبارتند از:
- exception zlib.error¶
استثنایی که در خطاهای فشردهسازی و واگشایی پرتاب میشود.
- zlib.adler32(data, value=1, /)¶
جمعآزما Adler-32 برای data محاسبه میشود. (جمعآزما Adler-32 تقریباً بهاندازهی CRC32 قابلاعتماد است، اما میتوان آن را بسیار سریعتر محاسبه کرد.) نتیجه یک عدد صحیح ۳۲ بیتی بدون علامت است. اگر value موجود باشد، از آن بهعنوان مقدار شروع جمعآزما استفاده میشود؛ در غیر این صورت، مقدار پیشفرض ۱ استفاده میشود. با ارسال value میتوانید جمعآزما را بهصورت جاری بر روی الحاق چندین ورودی محاسبه کنید. این الگوریتم از نظر رمزنگاری قوی نیست و نباید برای احراز هویت یا امضاهای دیجیتال استفاده شود. از آنجا که این الگوریتم برای استفاده بهعنوان الگوریتم جمعآزما طراحی شده است، برای استفاده بهعنوان یک الگوریتم هش عمومی مناسب نیست.
تغییر یافته در نسخهی 3.0: نتیجه همیشه بدون علامت است.
- zlib.adler32_combine(adler1, adler2, len2, /)¶
Combine two Adler-32 checksums into one.
Given the Adler-32 checksum adler1 of a sequence
Aand the Adler-32 checksum adler2 of a sequenceBof length len2, return the Adler-32 checksum ofAandBconcatenated.This function is typically useful to combine Adler-32 checksums that were concurrently computed. To compute checksums sequentially, use
adler32()with the running checksum as thevalueargument.اضافه شده در نسخهی 3.15.
- zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)¶
بایتهای موجود در data را فشرده میکند و یک شیء bytes حاوی دادههای فشرده را برمیگرداند. level یک عدد صحیح از
0تا9یا-1است که سطح فشردهسازی را کنترل میکند؛ برای اطلاعات بیشتر درباره این مقادیر،Z_BEST_SPEED(1)،Z_BEST_COMPRESSION(9)،Z_NO_COMPRESSION(0) و مقدار پیشفرض،Z_DEFAULT_COMPRESSION(-1) را ببینید.آرگومان wbits اندازهی بافر تاریخچه (یا «اندازهی پنجره») را که هنگام فشردهسازی دادهها استفاده میشود، و اینکه آیا سرآیند و دنباله در خروجی گنجانده میشود یا خیر، کنترل میکند. این آرگومان میتواند چندین بازه از مقادیر را بپذیرد و مقدار پیشفرض آن
15(MAX_WBITS) است:+۹ تا +۱۵: لگاریتم مبنای ۲ اندازهی پنجره؛ بنابراین اندازهی پنجره بین ۵۱۲ و ۳۲۷۶۸ قرار دارد. مقادیر بزرگتر، فشردهسازی بهتری به بهای مصرف بیشتر حافظه فراهم میکنند. خروجی حاصل شامل سرآیند و پاصفحهی ویژهی zlib خواهد بود.
−۹ تا −۱۵: از مقدار مطلق wbits بهعنوان لگاریتم اندازهی پنجره استفاده میکند، در حالی که یک جریان خروجی خام بدون سرآیند یا جمعآزما (checksum) پایانی تولید میکند.
+۲۵ تا +۳۱ = ۱۶ + (۹ تا ۱۵): از ۴ بیت کمارزش مقدار بهعنوان لگاریتم اندازهی پنجره استفاده میکند، در حالی که خروجی شامل یک سرآیند پایهی gzip و جمعآزما پایانی (checksum) است.
اگر هر خطایی رخ دهد، استثنای
errorپرتاب میشود.تغییر یافته در نسخهی 3.6: اکنون میتوان از level بهعنوان یک پارامتر کلیدواژهای استفاده کرد.
تغییر یافته در نسخهی 3.11: پارامتر wbits اکنون برای تنظیم بیتهای پنجره و نوع فشردهسازی در دسترس است.
- zlib.compressobj(level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])¶
یک شیء فشردهسازی بازمیگرداند تا برای فشردهسازی جریانهای دادهای استفاده شود که بهطور یکجا در حافظه جا نمیشوند.
level سطح فشردهسازی است — یک عدد صحیح از
0تا9یا-1. برای اطلاعات بیشتر درباره این مقادیر،Z_BEST_SPEED(1)،Z_BEST_COMPRESSION(9)،Z_NO_COMPRESSION(0) و مقدار پیشفرض،Z_DEFAULT_COMPRESSION(-1) را ببینید.method الگوریتم فشردهسازی است. در حال حاضر، تنها مقدار پشتیبانیشده
DEFLATEDاست.پارامتر wbits اندازهی بافر تاریخچه (یا «اندازهی پنجره») و قالب سرآیند و پایانی را که استفاده خواهد شد، کنترل میکند. این پارامتر همان معنایی را دارد که برای compress() توضیح داده شده است.
آرگومان memLevel میزان حافظهی استفادهشده برای وضعیت فشردهسازی داخلی را کنترل میکند. محدودهی مقادیر معتبر از
1تا9است. مقادیر بالاتر حافظهی بیشتری مصرف میکنند، اما سریعتر هستند و خروجی کوچکتری تولید میکنند.strategy برای تنظیم الگوریتم فشردهسازی به کار میرود. مقادیر ممکن عبارتند از
Z_DEFAULT_STRATEGY،Z_FILTERED،Z_HUFFMAN_ONLY،Z_RLEوZ_FIXED.zdict یک دیکشنری فشردهسازی از پیش تعریفشده است. این، دنبالهای از بایتها (مانند یک شیء
bytes) است که شامل زیردنبالههایی است که انتظار میرود در دادههایی که قرار است فشرده شوند، بهطور مکرر رخ دهند. آن زیردنبالههایی که انتظار میرود رایجترین باشند، باید در انتهای دیکشنری قرار گیرند.تغییر یافته در نسخهی 3.3: پارامتر zdict و پشتیبانی از آرگومانهای کلیدواژهای افزوده شد.
- zlib.crc32(data, value=0, /)¶
جمعآزما CRC (Cyclic Redundancy Check) برای data محاسبه میشود. نتیجه یک عدد صحیح ۳۲ بیتی بدون علامت است. اگر value موجود باشد، از آن بهعنوان مقدار آغازین جمعآزما استفاده میشود؛ در غیر این صورت، از مقدار پیشفرض ۰ استفاده میشود. ارسال value امکان محاسبهی جمعآزما جاری بر روی الحاق چندین ورودی را فراهم میکند. این الگوریتم از نظر رمزنگاری قوی نیست و نباید برای احراز هویت یا امضای دیجیتال استفاده شود. از آنجا که این الگوریتم برای استفاده بهعنوان الگوریتم جمعآزما طراحی شده است، برای استفاده بهعنوان یک الگوریتم هش عمومی مناسب نیست.
تغییر یافته در نسخهی 3.0: نتیجه همیشه بدون علامت است.
- zlib.crc32_combine(crc1, crc2, len2, /)¶
Combine two CRC-32 checksums into one.
Given the CRC-32 checksum crc1 of a sequence
Aand the CRC-32 checksum crc2 of a sequenceBof length len2, return the CRC-32 checksum ofAandBconcatenated.This function is typically useful to combine CRC-32 checksums that were concurrently computed. To compute checksums sequentially, use
crc32()with the running checksum as thevalueargument.اضافه شده در نسخهی 3.15.
- zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)¶
بایتهای موجود در data را از حالت فشرده خارج میکند و یک شیء بایتی حاوی دادههای فشردهنشده برمیگرداند. پارامتر wbits به قالب data بستگی دارد و در ادامه بیشتر توضیح داده شده است. اگر bufsize داده شود، از آن بهعنوان اندازه اولیه بافر خروجی استفاده میشود. در صورت بروز هرگونه خطا، استثنای
errorرا پرتاب میکند.پارامتر wbits اندازهی بافر تاریخچه (یا «اندازهی پنجره») و قالب مورد انتظار برای سرآیند و پابرگ را کنترل میکند. این پارامتر شبیه به پارامتر
compressobj()است، اما بازههای بیشتری از مقادیر را میپذیرد:+۸ تا +۱۵: لگاریتم مبنای دو اندازهی پنجره. ورودی باید شامل سرآیند و دنبالهی zlib باشد.
0: اندازهی پنجره بهطور خودکار از سرآیند zlib تعیین میشود. تنها از zlib 1.2.3.5 به بعد پشتیبانی میشود.
−۸ تا −۱۵: از قدر مطلق wbits بهعنوان لگاریتم اندازهی پنجره استفاده میشود. ورودی باید یک جریان خام بدون سرآیند یا پسآیند باشد.
+۲۴ تا +۳۱ = ۱۶ + (۸ تا ۱۵): از ۴ بیت کمارزش مقدار بهعنوان لگاریتم اندازهی پنجره استفاده میشود. ورودی باید شامل سرآیند و پاصفحهی gzip باشد.
+۴۰ تا +۴۷ = ۳۲ + (۸ تا ۱۵): از ۴ بیت کمارزش مقدار بهعنوان لگاریتم اندازهی پنجره استفاده میکند و بهطور خودکار یکی از قالبهای zlib یا gzip را میپذیرد.
هنگام از حالت فشرده خارج کردن یک جریان، اندازهی پنجره نباید از اندازهای که در اصل برای فشردهسازی جریان استفاده شده است کوچکتر باشد؛ استفاده از یک مقدار بیش از حد کوچک ممکن است منجر به استثنای
errorشود. مقدار پیشفرض wbits متناظر با بزرگترین اندازهی پنجره است و مستلزم گنجاندن سرآیند و پاصفحهی zlib است.bufsize اندازه اولیه بافری است که برای نگهداری دادههای واگشاییشده استفاده میشود. اگر فضای بیشتری لازم باشد، اندازه بافر در صورت نیاز افزایش مییابد، بنابراین لازم نیست این مقدار را کاملاً دقیق تنظیم کنید؛ تنظیم آن تنها باعث صرفهجویی در چند فراخوانی
malloc()میشود.تغییر یافته در نسخهی 3.6: میتوانید از wbits و bufsize بهعنوان آرگومانهای کلیدواژهای استفاده کنید.
- zlib.decompressobj(wbits=MAX_WBITS, zdict=b'')¶
یک شیء واگشایی بازمیگرداند، برای استفاده در واگشایی جریانهای دادهای که بهطور یکجا در حافظه جا نمیشوند.
پارامتر wbits اندازهی بافر تاریخچه (یا «اندازهی پنجره») و قالب مورد انتظار برای سرآیند و پایانی را کنترل میکند. این پارامتر همان معنایی را دارد که در توضیح decompress() آمده است.
پارامتر zdict یک دیکشنری فشردهسازی از پیش تعریفشده را مشخص میکند. در صورت ارائه، این باید همان دیکشنری باشد که فشردهساز برای تولید دادهای که قرار است از حالت فشرده خارج شود، از آن استفاده کرده است.
توجه
اگر zdict یک شیء تغییرپذیر باشد (مانند
bytearray)، نباید محتوای آن را بین فراخوانیdecompressobj()و نخستین فراخوانی متدdecompress()واگشا تغییر دهید.تغییر یافته در نسخهی 3.3: پارامتر zdict افزوده شد.
اشیای فشردهسازی از متدهای زیر پشتیبانی میکنند:
- Compress.compress(data, /)¶
data را فشرده میکند و یک شیء bytes حاوی دادههای فشردهشده برای حداقل بخشی از دادههای موجود در data برمیگرداند. این داده باید به خروجی تولیدشده از هر فراخوانی پیشین متد
compress()الحاق شود. ممکن است بخشی از ورودی برای پردازش بعدی در بافرهای داخلی نگه داشته شود.
- Compress.flush(mode=Z_FINISH, /)¶
تمام ورودی در انتظار، پردازش میشود و یک شیء bytes حاوی خروجی فشردهی باقیمانده برگردانده میشود. mode را میتوان از میان ثابتهای
Z_NO_FLUSH،Z_PARTIAL_FLUSH،Z_SYNC_FLUSH،Z_FULL_FLUSH،Z_BLOCKیاZ_FINISHانتخاب کرد؛ پیشفرض آنZ_FINISHاست. بهجزZ_FINISH، تمام ثابتها اجازه فشردهسازی رشتهبایتهای بیشتری از داده را میدهند، در حالی کهZ_FINISHجریان فشرده را پایان میدهد و از فشردهسازی هرگونه داده بیشتر جلوگیری میکند. پس از فراخوانیflush()با mode تنظیمشده رویZ_FINISH، دیگر نمیتوان متدcompress()را دوباره فراخوانی کرد؛ تنها اقدام واقعبینانه، حذف شیء است.
- Compress.copy()¶
یک کپی از شیء فشردهسازی برمیگرداند. از این میتوان برای فشردهسازی کارآمد مجموعهای از دادهها که پیشوند اولیه مشترکی دارند، استفاده کرد.
تغییر یافته در نسخهی 3.8: پشتیبانی از copy.copy() و copy.deepcopy() برای اشیای فشردهسازی افزوده شد.
اشیای واگشایی از متدها و ویژگیهای زیر پشتیبانی میکنند:
- Decompress.unused_data¶
یک شیء bytes که شامل بایتهای پس از پایان دادههای فشرده است. یعنی، این مقدار تا زمانی که آخرین بایت حاوی دادههای فشرده در دسترس قرار گیرد،
b""باقی میماند. اگر مشخص شود که کل رشتهبایتی حاوی دادههای فشرده است، این مقدارb""خواهد بود، یعنی یک شیء bytes خالی.
- Decompress.unconsumed_tail¶
یک شیء bytes که شامل هرگونه دادهای است که در آخرین فراخوانی
decompress()مصرفنشده است، زیرا از محدودیت بافر دادهی فشردهنشده فراتر رفته است. سازوکار zlib هنوز این داده را ندیده است، بنابراین شما باید آن را (احتمالاً همراه با دادههای بیشتری که به آن الحاقشدهاند) دوباره در یک فراخوانی بعدی متدdecompress()وارد کنید تا خروجی صحیح به دست آید.
- Decompress.eof¶
یک بولی که نشان میدهد آیا به پایان جریان دادهی فشرده رسیده است یا خیر.
این امر امکان تمایز میان یک جریان فشردهی بهدرستی تشکیلشده و یک جریان ناقص یا بریدهشده را فراهم میکند.
اضافه شده در نسخهی 3.3.
- Decompress.decompress(data, /, max_length=0)¶
data را از حالت فشرده خارج میکند و یک شیء bytes حاوی دادهی غیرفشردهی متناظر با حداقل بخشی از دادههای موجود در string برمیگرداند. این داده باید به خروجی حاصل از هر فراخوانی پیشین متد
decompress()الحاق شود. ممکن است بخشی از دادهی ورودی برای پردازش بعدی در بافرهای داخلی نگهداری شود.If the optional parameter max_length is non-zero then the return value will be no longer than max_length. This may mean that not all of the compressed input can be processed; and unconsumed data will be stored in the attribute
unconsumed_tail. This bytestring must be passed to a subsequent call todecompress()if decompression is to continue. If max_length is zero then the whole input is decompressed, andunconsumed_tailis empty. For example, the full content could be read like:process_output(d.decompress(data, max_length)) while chunk := d.decompress(d.unconsumed_tail, max_length): process_output(chunk)
تغییر یافته در نسخهی 3.6: میتوان از max_length بهعنوان آرگومان کلیدواژهای استفاده کرد.
- Decompress.flush(length=DEF_BUF_SIZE, /)¶
تمام ورودی در انتظار پردازش میشود، و یک شیء bytes شامل خروجی فشردهنشدهی باقیمانده بازگردانده میشود. پس از فراخوانی
flush()، نمیتوان متدdecompress()را دوباره فراخوانی کرد؛ تنها اقدام عملی، حذف شیء است.پارامتر اختیاری length اندازهی اولیهی بافر خروجی را تنظیم میکند.
- Decompress.copy()¶
نسخهای از شیء واگشایی را بازمیگرداند. این میتواند برای ذخیرهی وضعیت واگشا در میانهی جریان داده به کار رود تا سرعت جابهجاییهای تصادفی در جریان را در نقطهای آینده افزایش دهد.
تغییر یافته در نسخهی 3.8: پشتیبانی از copy.copy() و copy.deepcopy() به اشیای واگشایی افزوده شد.
ثابتهای زیر برای پیکربندی رفتار فشردهسازی و واگشایی در دسترس هستند:
- zlib.DEFLATED¶
روش فشردهسازی (deflate).
- zlib.MAX_WBITS¶
حداکثر اندازهی پنجره، که بهصورت توانی از ۲ بیان میشود. برای مثال، اگر
MAX_WBITSبرابر15باشد، اندازهی پنجره32 KiBخواهد بود.
- zlib.DEF_MEM_LEVEL¶
سطح حافظهی پیشفرض برای اشیای فشردهسازی.
- zlib.DEF_BUF_SIZE¶
اندازه پیشفرض بافر برای عملیاتهای واگشایی .
- zlib.Z_NO_COMPRESSION¶
سطح فشردهسازی
0؛ بدون فشردهسازی.اضافه شده در نسخهی 3.6.
- zlib.Z_BEST_SPEED¶
سطح فشردهسازی
1؛ سریعترین است و کمترین فشردهسازی را دارد.
- zlib.Z_BEST_COMPRESSION¶
سطح فشردهسازی
9؛ کندترین است و بیشترین فشردهسازی را ایجاد میکند.
- zlib.Z_DEFAULT_COMPRESSION¶
سطح فشردهسازی پیشفرض (
-1)؛ میانهای بین سرعت و فشردهسازی. در حال حاضر معادل سطح فشردهسازی6است.
- zlib.Z_DEFAULT_STRATEGY¶
استراتژی فشردهسازی پیشفرض، برای دادههای عادی.
- zlib.Z_FILTERED¶
راهبرد فشردهسازی برای دادههای تولیدشده توسط یک فیلتر (یا پیشبین).
- zlib.Z_HUFFMAN_ONLY¶
راهبرد فشردهسازی که تنها کدگذاری هافمن را اجباری میکند.
- zlib.Z_RLE¶
راهبرد فشردهسازی که فاصلههای تطبیق را به یک محدود میکند (کدگذاری طول دور).
این ثابت تنها در صورتی در دسترس است که پایتون با zlib 1.2.0.1 یا بالاتر کامپایل شده باشد.
اضافه شده در نسخهی 3.6.
- zlib.Z_FIXED¶
راهبرد فشردهسازی که از استفاده از کدهای هافمن پویا جلوگیری میکند.
این ثابت تنها در صورتی در دسترس است که پایتون با zlib نسخه 1.2.2.2 یا بالاتر کامپایل شده باشد.
اضافه شده در نسخهی 3.6.
- zlib.Z_NO_FLUSH¶
حالت تخلیه
0. هیچ رفتار خاصی برای تخلیه وجود ندارد.اضافه شده در نسخهی 3.6.
- zlib.Z_PARTIAL_FLUSH¶
حالت تخلیه
1. تا حد ممکن خروجی را تخلیه کنید.
- zlib.Z_SYNC_FLUSH¶
حالت تخلیه
2. تمام خروجی تخلیه میشود و خروجی با یک مرز بایت تراز میشود.
- zlib.Z_FULL_FLUSH¶
حالت تخلیه
3. تمام خروجی تخلیه میشود و وضعیت فشردهسازی بازنشانی میشود.
- zlib.Z_FINISH¶
حالت تخلیه
4. تمام ورودیهای در انتظار پردازش میشوند، دیگر انتظار ورودی بیشتری نمیرود.
- zlib.Z_BLOCK¶
حالت تخلیه
5. یک بلوک deflate کامل شده و صادر میشود.این ثابت تنها در صورتی در دسترس است که پایتون با zlib نسخه 1.2.2.2 یا بالاتر کامپایل شده باشد.
اضافه شده در نسخهی 3.6.
- zlib.Z_TREES¶
حالت تخلیه
6، برای عملیات inflate. به inflate دستور میدهد هنگامی که به مرز بلوک deflate بعدی میرسد، بازگشت کند.این ثابت تنها در صورتی در دسترس است که پایتون با zlib 1.2.3.4 یا بالاتر کامپایل شده باشد.
اضافه شده در نسخهی 3.6.
اطلاعات دربارهی نسخهی کتابخانهی zlib در حال استفاده، از طریق ثابتهای زیر در دسترس است:
- zlib.ZLIB_VERSION¶
The version string of the zlib library that was used for building the module. This may be different from the zlib library actually used at runtime, which is available as
zlib_version.
- zlib.ZLIB_RUNTIME_VERSION¶
- zlib.zlib_version¶
رشتهی نسخهی کتابخانهی zlib که در واقع توسط مفسر بارگذاریشده است.
اضافه شده در نسخهی 3.3: The
ZLIB_RUNTIME_VERSIONconstant.اضافه شده در نسخهی 3.16.0a0 (unreleased): The
zlib_versionalias.
- zlib.ZLIB_VERSION_INFO¶
A named tuple containing the four components of the zlib library version that was used for building the module: major, minor, revision, and subversion. All values are integers. The components can also be accessed by name, so
zlib.ZLIB_VERSION_INFO[0]is equivalent tozlib.ZLIB_VERSION_INFO.majorand so on. This may be different from the zlib library actually used at runtime, which is available aszlib_version_info.اضافه شده در نسخهی 3.16.0a0 (unreleased).
- zlib.zlib_version_info¶
A named tuple containing the version of the zlib library actually loaded by the interpreter, with the same fields as
ZLIB_VERSION_INFO.اضافه شده در نسخهی 3.16.0a0 (unreleased).
The following constants are only present if zlib-ng was used to build the module:
- zlib.ZLIBNG_VERSION¶
The version string of the zlib-ng library that was used for building the module if zlib-ng was used. When present, the
ZLIB_VERSIONandzlib_versionconstants reflect the version of the zlib API provided by zlib-ng.اضافه شده در نسخهی 3.14.
- zlib.ZLIBNG_VERSION_INFO¶
A named tuple containing the three components of the zlib-ng library version that was used for building the module: major, minor, and revision. All values are integers.
اضافه شده در نسخهی 3.16.0a0 (unreleased).
همچنین ملاحظه نمائید
- ماژول
gzip خواندن و نوشتن پروندههای با قالب gzip.
- https://www.zlib.net
صفحهی اصلی کتابخانهی zlib.
- https://www.zlib.net/manual.html
راهنمای zlib معناشناسی و کاربرد بسیاری از توابع کتابخانه را توضیح میدهد.
در صورتی که فشردهسازی/بازگشایی gzip یک گلوگاه باشد، بستهی python-isal سرعت فشردهسازی/بازگشایی را با یک API تا حد زیادی سازگار افزایش میدهد.