lzma --- فشردهسازی با استفاده از الگوریتم LZMA¶
اضافه شده در نسخهی 3.3.
کد منبع: Lib/lzma.py
این ماژول کلاسها و توابع کمکی را برای فشردهسازی دادهها و خارج کردن آنها از حالت فشرده با استفاده از الگوریتم فشردهسازی LZMA فراهم میکند. همچنین یک رابط پرونده نیز گنجانده شده است که از قالبهای پروندهای .xz و قالب قدیمی .lzma که توسط ابزار xz استفاده میشوند، و نیز جریانهای فشرده خام پشتیبانی میکند.
رابط ارائهشده توسط این ماژول بسیار شبیه به رابط ماژول bz2 است. توجه داشته باشید که LZMAFile و bz2.BZ2File نخایمن نیستند، بنابراین اگر نیاز دارید از یک نمونهی LZMAFile از چندین نخ استفاده کنید، لازم است آن را با یک قفل محافظت کنید.
این یک ماژول اختیاری است. اگر در نسخهی CPython شما وجود ندارد، برای یافتن مستندات به توزیعکننده خود (یعنی هر کسی که پایتون را در اختیار شما قرار داده است) مراجعه کنید. اگر شما توزیعکننده هستید، نیازمندیهای ماژولهای اختیاری را ببینید.
- exception lzma.LZMAError¶
این استثنا زمانی پرتاب میشود که خطایی در حین فشردهسازی یا واگشایی، یا هنگام مقداردهی اولیه وضعیت فشردهساز/واگشا رخ دهد.
خواندن و نوشتن پروندههای فشرده¶
- lzma.open(filename, mode='rb', *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)¶
یک پرونده فشردهشده با LZMA را در حالت دودویی یا متنی باز میکند و یک file object برمیگرداند.
آرگومان filename میتواند یا یک نام پرونده واقعی باشد (که بهصورت یک شیء
str،bytesیا path-like داده شده باشد)، که در این صورت پرونده نامبرده باز میشود، یا یک شیء پرونده موجود برای خواندن از آن یا نوشتن در آن باشد.آرگومان mode میتواند هر یک از
"r"،"rb"،"w"،"wb"،"x"،"xb"،"a"یا"ab"برای حالت دودویی، یا"rt"،"wt"،"xt"یا"at"برای حالت متنی باشد. مقدار پیشفرض"rb"است.هنگام باز کردن یک پرونده برای خواندن، آرگومانهای format و filters همان معنای خود در
LZMADecompressorرا دارند. در این حالت، نباید از آرگومانهای check و preset استفاده شود.هنگام باز کردن یک پرونده برای نوشتن، آرگومانهای format، check، preset و filters همان معانی را دارند که برای
LZMACompressorدارند.برای حالت دودویی، این تابع معادل سازندهی
LZMAFileاست:LZMAFile(filename, mode, ...). در این حالت، آرگومانهای encoding، errors و newline نباید ارائه شوند.برای حالت متنی، یک شیء
LZMAFileایجاد میشود و در یک نمونهio.TextIOWrapperبا کدگذاری، رفتار مدیریت خطا و پایانهای خط مشخصشده قرار میگیرد.تغییر یافته در نسخهی 3.4: پشتیبانی از حالتهای
"x"،"xb"و"xt"اضافه شد.تغییر یافته در نسخهی 3.6: یک path-like object میپذیرد.
- class lzma.LZMAFile(filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)¶
باز کردن یک پرونده فشردهشده با LZMA در حالت دودویی.
یک
LZMAFileمیتواند یک شیء پرونده از پیش باز را پوشش دهد، یا مستقیماً روی یک پرونده با نام مشخص عمل کند. آرگومان filename یا شیء پرونده برای پوشش دادن را مشخص میکند، یا نام پروندهای را که باید باز شود (بهعنوان یک شیءstr،bytesیا مسیرمانند). هنگام پوشش دادن یک شیء پرونده موجود، با بسته شدنLZMAFile، پرونده پوششدادهشده بسته نخواهد شد.آرگومان mode میتواند
"r"برای خواندن (پیشفرض)،"w"برای بازنویسی،"x"برای ایجاد انحصاری، یا"a"برای الحاق باشد. اینها را میتوان بهترتیب و بهطور معادل بهصورت"rb"،"wb"،"xb"و"ab"نیز مشخص کرد.اگر filename یک شیء پرونده باشد (نه یک نام پرونده واقعی)، حالت
"w"پرونده را کوتاه نمیکند و در عوض معادل"a"است.هنگام باز کردن یک پرونده برای خواندن، ممکن است پرونده ورودی حاصل الحاق چند جریان فشردهی جداگانه باشد. این جریانها بهصورت شفاف بهعنوان یک جریان منطقی واحد کدگشایی میشوند.
هنگام باز کردن یک پرونده برای خواندن، آرگومانهای format و filters همان معنای خود در
LZMADecompressorرا دارند. در این حالت، نباید از آرگومانهای check و preset استفاده شود.هنگام باز کردن یک پرونده برای نوشتن، آرگومانهای format، check، preset و filters همان معانی را دارند که برای
LZMACompressorدارند.LZMAFileاز تمام اعضای مشخصشده توسطio.BufferedIOBaseپشتیبانی میکند، بهجزdetach()وtruncate(). پیمایش و دستورwithپشتیبانی میشوند.متد و ویژگیهای زیر نیز ارائه شدهاند:
- peek(size=-1)¶
دادهی بافرشده را بدون جلو بردن موقعیت پرونده برمیگرداند. حداقل یک بایت داده برگردانده خواهد شد، مگر اینکه به EOF رسیده باشد. تعداد دقیق بایتهای برگرداندهشده مشخص نیست (آرگومان size نادیده گرفته میشود).
- mode¶
'rb'برای خواندن و'wb'برای نوشتن.اضافه شده در نسخهی 3.13.
- name¶
نام پرونده lzma. معادل ویژگی
nameدر شیء پرونده زیربنایی است.اضافه شده در نسخهی 3.13.
تغییر یافته در نسخهی 3.4: پشتیبانی از حالتهای
"x"و"xb"اضافه شد.تغییر یافته در نسخهی 3.5: متد
read()اکنونNoneرا بهعنوان آرگومان میپذیرد.تغییر یافته در نسخهی 3.6: یک path-like object میپذیرد.
فشردهسازی و بازگشایی دادهها در حافظه¶
- class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)¶
یک شیء فشردهساز ایجاد کنید، که میتوان از آن برای فشردهسازی دادهها بهصورت تدریجی استفاده کرد.
برای فشردهسازی یک تکه داده به روشی راحتتر،
compress()را ببینید.آرگومان format تعیین میکند که از چه قالب ظرفی باید استفاده شود. مقادیر ممکن عبارتند از
FORMAT_XZ(پیشفرض)،FORMAT_ALONEوFORMAT_RAW.آرگومان check نوع بررسی یکپارچگی برای گنجاندن در داده فشردهشده را مشخص میکند. این بررسی هنگام واگشایی برای اطمینان از اینکه داده آسیب ندیده باشد، استفاده میشود. مقادیر ممکن عبارتند از
CHECK_NONE،CHECK_CRC32،CHECK_CRC64(پیشفرض برایFORMAT_XZ) وCHECK_SHA256.اگر بررسی مشخصشده پشتیبانی نشود، یک
LZMAErrorپرتاب میشود.تنظیمات فشردهسازی را میتوان یا بهعنوان یک سطح فشردهسازی از پیش تعیینشده (با آرگومان preset)، یا با جزئیات بهعنوان یک زنجیره فیلتر سفارشی (با آرگومان filters) مشخص کرد.
آرگومان preset (در صورت ارائه) باید عدد صحیحی بین
0و9(شامل هر دو) باشد، و میتواند بهاختیار با ثابتPRESET_EXTREMEاز طریق OR بیتی ترکیب شود. اگر هیچکدام از preset و filters ارائه نشوند، رفتار پیشفرض استفاده ازPRESET_DEFAULT(سطح پیشتنظیم6) است. پیشتنظیمهای بالاتر خروجی کوچکتری تولید میکنند، اما فرایند فشردهسازی را کندتر میکنند.توجه
فشردهسازی با پیشتنظیمهای بالاتر، علاوه بر اینکه به پردازنده بیشتری نیاز دارد، به حافظهی بسیار بیشتری نیز نیاز دارد (و خروجیای تولید میکند که برای کدگشایی به حافظهی بیشتری نیاز دارد). برای مثال، با پیشتنظیم
9، سربار یک شیءLZMACompressorمیتواند تا ۸۰۰ MiB باشد. به همین دلیل، معمولاً بهتر است به پیشتنظیم پیشفرض پایبند باشید.آرگومان filters (در صورت ارائه) باید یک مشخصکننده زنجیره فیلتر (filter chain specifier) باشد. برای جزئیات، تعیین زنجیرههای فیلتر سفارشی را ببینید.
- compress(data)¶
data (یک شیء
bytes) را فشرده میکند و یک شیءbytesحاوی داده فشردهشده برای دستکم بخشی از ورودی را برمیگرداند. ممکن است بخشی از data بهصورت داخلی در بافر ذخیره شود تا در فراخوانیهای بعدیcompress()وflush()استفاده شود. داده برگرداندهشده باید به خروجی فراخوانیهای قبلیcompress()الحاق شود.
- class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)¶
یک شیء واگشا (decompressor) ایجاد کنید، که میتوان از آن برای واگشایی دادهها بهصورت افزایشی استفاده کرد.
برای واگشایی راحتترِ یک جریان فشردهی کامل بهصورت یکجا،
decompress()را ببینید.آرگومان format قالب ظرف (container format) را که باید استفاده شود مشخص میکند. مقدار پیشفرض
FORMAT_AUTOاست، که میتواند هر دو پرونده.xzو.lzmaرا از حالت فشرده خارج کند. سایر مقادیر ممکن عبارتند ازFORMAT_XZ،FORMAT_ALONEوFORMAT_RAW.آرگومان memlimit محدودیتی (بر حسب بایت) برای میزان حافظهای که واگشا میتواند استفاده کند، مشخص میکند. هنگامی که از این آرگومان استفاده شود، اگر واگشایی ورودی در محدوده حافظه دادهشده ممکن نباشد، واگشایی با یک
LZMAErrorشکست میخورد.آرگومان filters زنجیره فیلتری را مشخص میکند که برای ایجاد جریانی که واگشایی میشود، استفاده شده است. این آرگومان در صورتی لازم است که format برابر
FORMAT_RAWباشد، اما نباید برای قالبهای دیگر استفاده شود. برای اطلاعات بیشتر درباره زنجیرههای فیلتر، تعیین زنجیرههای فیلتر سفارشی را ببینید.توجه
این کلاس برخلاف
decompress()وLZMAFile، ورودیهای حاوی چندین جریان فشرده را بهصورت شفاف مدیریت نمیکند. برای واگشایی یک ورودی چندجریانی باLZMADecompressor، باید برای هر جریان یک واگشای جدید (decompressor) ایجاد کنید.- decompress(data, max_length=-1)¶
data (یک bytes-like object) را واگشایی میکند و دادهی فشردهنشده را بهصورت بایت برمیگرداند. ممکن است بخشی از data بهصورت داخلی در بافر ذخیره شود تا در فراخوانیهای بعدی
decompress()استفاده شود. دادهی برگرداندهشده باید با خروجی فراخوانیهای قبلیdecompress()الحاق شود.اگر max_length نامنفی باشد، حداکثر max_length بایت از دادهی واگشاییشده را برمیگرداند. اگر به این محدودیت رسیده باشد و امکان تولید خروجی بیشتری وجود داشته باشد، ویژگی
needs_inputرویFalseتنظیم میشود. در این حالت، در فراخوانی بعدیdecompress()میتوانید data را بهصورتb''ارائه دهید تا بخش بیشتری از خروجی را دریافت کنید.اگر تمام دادههای ورودی واگشایی شده و برگردانده شده باشند (چه به این دلیل که این دادهها کمتر از max_length بایت بودند، چه به این دلیل که max_length منفی بود)، ویژگی
needs_inputرویTrueتنظیم خواهد شد.تلاش برای واگشایی دادهها پس از رسیدن به پایان جریان، باعث پرتاب یک
EOFErrorمیشود. هر دادهای که پس از پایان جریان یافت شود، نادیده گرفته میشود و در ویژگیunused_dataذخیره میشود.تغییر یافته در نسخهی 3.5: پارامتر max_length اضافه شد.
- check¶
شناسهی بررسی یکپارچگیای که جریان ورودی از آن استفاده میکند. این ممکن است
CHECK_UNKNOWNباشد، تا زمانی که بهاندازهی کافی از ورودی کدگشایی شود تا مشخص شود جریان ورودی از چه بررسی یکپارچگی استفاده میکند.
- eof¶
Trueاگر به نشانگر پایان جریان رسیده شده باشد.
- unused_data¶
دادههایی پس از پایان جریان فشرده یافت شد.
پیش از رسیدن به انتهای جریان، این
b""خواهد بود.
- needs_input¶
Falseاگر متدdecompress()بتواند دادههای واگشاییشدهی بیشتری را پیش از نیاز به ورودی فشردهنشدهی جدید فراهم کند.اضافه شده در نسخهی 3.5.
- lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)¶
data (یک شیء
bytes) را فشردهسازی میکند و داده فشردهشده را بهعنوان یک شیءbytesبرمیگرداند.برای شرح آرگومانهای format، check، preset و filters، به
LZMACompressorدر بالا مراجعه کنید.
- lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)¶
واگشایی data (یک شیء
bytes)، که دادهی فشردهنشده را بهصورت یک شیءbytesبرمیگرداند.اگر data الحاق چندین جریان فشردهی متمایز باشد، همهی این جریانها را از حالت فشرده خارج میکند و الحاق نتایج را برمیگرداند.
برای دیدن توضیح آرگومانهای format، memlimit و filters،
LZMADecompressorرا در بالا ببینید.
متفرقه¶
- lzma.is_check_supported(check)¶
اگر بررسی یکپارچگی دادهشده در این سیستم پشتیبانی شود،
Trueرا برمیگرداند.CHECK_NONEوCHECK_CRC32همیشه پشتیبانی میشوند.CHECK_CRC64وCHECK_SHA256ممکن است در دسترس نباشند اگر از نسخهای از liblzma استفاده میکنید که با مجموعهای محدود از قابلیتها کامپایل شده است.
تعیین زنجیرههای فیلتر سفارشی¶
یک مشخصکننده زنجیره فیلتر، دنبالهای از دیکشنریها است، که هر دیکشنری شامل شناسه و گزینههایی برای یک فیلتر واحد است. هر دیکشنری باید شامل کلید "id" باشد و میتواند شامل کلیدهای اضافی برای مشخص کردن گزینههای وابسته به فیلتر باشد. شناسههای معتبر فیلتر به شرح زیر هستند:
فیلترهای فشردهسازی:
FILTER_LZMA1(برای استفاده باFORMAT_ALONE)FILTER_LZMA2(برای استفاده باFORMAT_XZوFORMAT_RAW)
فیلتر دلتا:
فیلترهای Branch-Call-Jump (BCJ):
FILTER_X86FILTER_IA64FILTER_ARMFILTER_ARMTHUMBFILTER_POWERPCFILTER_SPARC
یک زنجیرهی فیلتر میتواند شامل حداکثر ۴ فیلتر باشد و نمیتواند خالی باشد. آخرین فیلتر در زنجیره باید فیلتر فشردهسازی باشد و سایر فیلترها باید فیلترهای delta یا BCJ باشند.
فیلترهای فشردهسازی از گزینههای زیر پشتیبانی میکنند (که بهصورت ورودیهای اضافی در دیکشنری نشاندهندهی فیلتر مشخص میشوند):
preset: یک پیشتنظیم فشردهسازی برای استفاده بهعنوان منبع مقادیر پیشفرض برای گزینههایی که بهصراحت مشخص نشدهاند.dict_size: اندازهی دیکشنری بر حسب بایت. این مقدار باید بین ۴ KiB و ۱٫۵ GiB (شامل هر دو) باشد.lc: تعداد بیتهای زمینهی literal.lp: تعداد بیتهای موقعیت لفظی . مجموعlc + lpباید حداکثر ۴ باشد.pb: تعداد بیتهای موقعیت؛ باید حداکثر ۴ باشد.mode:MODE_FASTیاMODE_NORMAL.nice_len: آنچه باید بهعنوان «طول مناسب» برای یک تطابق در نظر گرفته شود. این مقدار باید ۲۷۳ یا کمتر باشد.mf: اینکه از کدام تطبیقیاب (match finder) استفاده شود --MF_HC3،MF_HC4،MF_BT2،MF_BT3یاMF_BT4.depth: حداکثر عمق جستجوی مورد استفادهی تطبیقیاب (match finder). ۰ (پیشفرض) به معنای انتخاب خودکار بر اساس سایر گزینههای فیلتر است.
فیلتر دلتا تفاوتهای بین بایتها را ذخیره میکند و در شرایط خاص، ورودی با تکرار بیشتری برای فشردهساز تولید میکند. این فیلتر از یک گزینه پشتیبانی میکند: dist. این گزینه فاصله بین بایتهایی را نشان میدهد که از یکدیگر کم میشوند. پیشفرض ۱ است، یعنی تفاوتهای بین بایتهای مجاور در نظر گرفته میشود.
فیلترهای BCJ برای اعمال روی کد ماشینی در نظر گرفته شدهاند. آنها شاخهها، فراخوانیها و پرشهای نسبی درون کد را بهگونهای تبدیل میکنند که از آدرسدهی مطلق استفاده شود، با این هدف که افزونگیای را که فشردهساز میتواند از آن بهره ببرد افزایش دهند. این فیلترها از یک گزینه، start_offset، پشتیبانی میکنند. این گزینه نشانیای را مشخص میکند که باید به ابتدای داده ورودی نگاشت شود. مقدار پیشفرض ۰ است.
ثابتها¶
ثابتهای سطح ماژول زیر برای استفاده بهعنوان آرگومانهای format، check، preset و filters در کلاسها و توابع بالا ارائه شدهاند.
قالبهای ظرف:
- lzma.FORMAT_XZ¶
قالب ظرف
.xz.
- lzma.FORMAT_ALONE¶
قالب ظرف قدیمی
.lzma. این قالب محدودتر از.xzاست — از بررسیهای یکپارچگی یا فیلترهای چندگانه پشتیبانی نمیکند.
- lzma.FORMAT_RAW¶
یک جریان دادهی خام، بدون استفاده از هیچ قالب ظرفی (container format). این مشخصکنندهی قالب از بررسیهای یکپارچگی پشتیبانی نمیکند و نیاز دارد که شما همیشه یک زنجیرهی فیلتر سفارشی (هم برای فشردهسازی و هم برای رفع فشردگی) را مشخص کنید. علاوه بر این، داده فشردهشده به این روش، با استفاده از
FORMAT_AUTOرفع فشردگی نمیشود.
- lzma.FORMAT_AUTO¶
فقط برای واگشایی استفاده میشود. قالب ظرف (container format) بهصورت خودکار شناسایی میشود، بنابراین میتوان هر دو پرونده
.xzو.lzmaرا واگشایی کرد.
بررسیهای یکپارچگی:
- lzma.CHECK_NONE¶
بدون بررسی یکپارچگی. این مقدار پیشفرض (و تنها مقدار قابلقبول) برای
FORMAT_ALONEوFORMAT_RAWاست.
- lzma.CHECK_CRC32¶
یک بررسی افزونگی چرخهای ۳۲ بیتی (Cyclic Redundancy Check).
- lzma.CHECK_SHA256¶
یک الگوریتم هش امن ۲۵۶ بیتی.
- lzma.CHECK_UNKNOWN¶
بررسی یکپارچگی مورد استفاده توسط یک جریان هنوز قابل تعیین نیست. این ممکن است مقدار ویژگی
LZMADecompressor.checkباشد تا زمانی که به اندازه کافی از ورودی کدگشاییشده باشد.
- lzma.CHECK_ID_MAX¶
بزرگترین شناسهی پشتیبانیشدهی بررسی یکپارچگی (integrity-check ID).
پیشتنظیمهای فشردهسازی:
- lzma.PRESET_DEFAULT¶
پیشتنظیم فشردهسازی پیشفرض، معادل سطح پیشتنظیم
6.
- lzma.PRESET_EXTREME¶
پرچمی که میتوان آن را با یک سطح از پیش تعیینشده (
0تا9) با OR بیتبهبیت ترکیب کرد تا گونهای کندتر اما دقیقتر از آن پیشتنظیم انتخاب شود.
شناسهها و گزینههای فیلتر:
- lzma.FILTER_LZMA1¶
- lzma.FILTER_LZMA2¶
فیلترهای فشردهسازی LZMA1 و LZMA2.
FILTER_LZMA1برای استفاده باFORMAT_ALONEاست، در حالی کهFILTER_LZMA2برای استفاده باFORMAT_XZوFORMAT_RAWاست.
- lzma.FILTER_DELTA¶
فیلتر دلتا.
- lzma.MODE_FAST¶
- lzma.MODE_NORMAL¶
حالتهای فشردهسازی که میتوان از آنها بهعنوان گزینه
modeیک مشخصکننده فیلتر استفاده کرد (به تعیین زنجیرههای فیلتر سفارشی مراجعه کنید).
مثالها¶
خواندن از یک پرونده فشرده:
import lzma
with lzma.open("file.xz") as f:
file_content = f.read()
ایجاد یک پرونده فشرده:
import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
f.write(data)
فشردهسازی دادهها در حافظه:
import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)
فشردهسازی افزایشی:
import lzma
lzc = lzma.LZMACompressor()
out1 = lzc.compress(b"Some data\n")
out2 = lzc.compress(b"Another piece of data\n")
out3 = lzc.compress(b"Even more data\n")
out4 = lzc.flush()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])
نوشتن دادههای فشرده در پروندهای که از قبل باز است:
import lzma
with open("file.xz", "wb") as f:
f.write(b"This data will not be compressed\n")
with lzma.open(f, "w") as lzf:
lzf.write(b"This *will* be compressed\n")
f.write(b"Not compressed\n")
ایجاد یک پرونده فشرده با استفاده از زنجیره فیلتر سفارشی:
import lzma
my_filters = [
{"id": lzma.FILTER_DELTA, "dist": 5},
{"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},
]
with lzma.open("file.xz", "w", filters=my_filters) as f:
f.write(b"blah blah blah")