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.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.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()الحاق شود. ممکن است بخشی از دادهی ورودی برای پردازش بعدی در بافرهای داخلی نگهداری شود.اگر پارامتر اختیاری max_length غیرصفر باشد، طول مقدار بازگشتی بیشتر از max_length نخواهد بود. این ممکن است به این معنا باشد که تمام ورودی فشرده قابل پردازش نیست؛ و داده مصرفنشده در ویژگی
unconsumed_tailذخیره میشود. اگر قرار است واگشایی ادامه یابد، این رشته بایتی باید به فراخوانی بعدیdecompress()ارسال شود. اگر max_length صفر باشد، کل ورودی واگشایی میشود وunconsumed_tailخالی است.تغییر یافته در نسخهی 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¶
رشتهی نسخهی کتابخانهی zlib که برای ساخت ماژول استفاده شده است. این ممکن است با کتابخانهی zlib که در واقع در رانتایم استفاده میشود و بهعنوان
ZLIB_RUNTIME_VERSIONدر دسترس است، متفاوت باشد.
- zlib.ZLIB_RUNTIME_VERSION¶
رشتهی نسخهی کتابخانهی zlib که در واقع توسط مفسر بارگذاریشده است.
اضافه شده در نسخهی 3.3.
- zlib.ZLIBNG_VERSION¶
رشته نسخه کتابخانه zlib-ng که در صورت استفاده از zlib-ng، برای ساخت ماژول به کار رفته است. در صورت وجود، ثابتهای
ZLIB_VERSIONوZLIB_RUNTIME_VERSIONنسخه API zlib ارائهشده توسط zlib-ng را نشان میدهند.اگر برای ساخت ماژول از zlib-ng استفاده نشده باشد، این ثابت وجود نخواهد داشت.
اضافه شده در نسخهی 3.14.
همچنین ملاحظه نمائید
- ماژول
gzip خواندن و نوشتن پروندههای با قالب gzip.
- https://www.zlib.net
صفحهی اصلی کتابخانهی zlib.
- https://www.zlib.net/manual.html
راهنمای zlib معناشناسی و کاربرد بسیاری از توابع کتابخانه را توضیح میدهد.
در صورتی که فشردهسازی/بازگشایی gzip یک گلوگاه باشد، بستهی python-isal سرعت فشردهسازی/بازگشایی را با یک API تا حد زیادی سازگار افزایش میدهد.