compression.zstd --- فشرده‌سازی سازگار با قالب Zstandard

اضافه شده در نسخه‌ی 3.14.

کد منبع: Lib/compression/zstd/__init__.py

---

این ماژول کلاس‌ها و توابعی را برای فشرده‌سازی و از حالت فشرده خارج کردن داده‌ها با استفاده از الگوریتم فشرده‌سازی Zstandard (یا zstd) ارائه می‌دهد. راهنمای zstd، Zstandard را این‌گونه توصیف می‌کند: «الگوریتم فشرده‌سازی سریع و بدون اتلاف که سناریوهای فشرده‌سازی بلادرنگ را با نسبت‌های فشرده‌سازی در سطح zlib و بهتر هدف قرار می‌دهد.» همچنین یک رابط پرونده نیز گنجانده شده است که از خواندن و نوشتن محتوای پرونده‌های .zst ایجادشده توسط ابزار zstd و نیز جریان‌های فشرده خام zstd پشتیبانی می‌کند.

ماژول compression.zstd شامل موارد زیر است:

• تابع open() و کلاس ZstdFile برای خواندن و نوشتن پرونده‌های فشرده.

• کلاس‌های ZstdCompressor و ZstdDecompressor برای فشرده‌سازی/واگشایی تدریجی.

• توابع compress() و decompress() برای فشرده‌سازی/واگشایی یک‌باره.

• توابع train_dict() و finalize_dict() و کلاس ZstdDict برای آموزش و مدیریت دیکشنری‌های Zstandard.

• کلاس‌های CompressionParameter، DecompressionParameter و Strategy برای تنظیم پارامترهای پیشرفته‌ی فشرده‌سازی و واگشایی.

این یک ماژول اختیاری است. اگر در نسخه‌ی CPython شما وجود ندارد، به مستندات توزیع‌کننده‌ی خود مراجعه کنید (یعنی هر کسی که پایتون را در اختیار شما قرار داده است). اگر شما توزیع‌کننده هستید، نیازمندی‌های ماژول‌های اختیاری را ببینید.

استثناها

exception compression.zstd.ZstdError

این استثنا زمانی پرتاب می‌شود که خطایی در حین فشرده‌سازی یا رفع فشردگی، یا هنگام مقداردهی اولیه‌ی وضعیت فشرده‌ساز/بازکننده رخ دهد.

خواندن و نوشتن پرونده‌های فشرده

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

یک پرونده فشرده‌شده با Zstandard را در حالت دودویی یا متنی باز می‌کند و یک شیء پرونده بازمی‌گرداند.

آرگومان file می‌تواند یک نام پرونده (داده‌شده به‌صورت یک شیء str، bytes یا path-like) باشد، که در این صورت پرونده نام‌برده باز می‌شود، یا می‌تواند یک شیء پرونده موجود برای خواندن از آن یا نوشتن در آن باشد.

آرگومان حالت می‌تواند 'rb' برای خواندن (پیش‌فرض)، 'wb' برای بازنویسی، 'ab' برای الحاق، یا 'xb' برای ایجاد انحصاری باشد. این موارد را می‌توان به‌ترتیب و به‌طور معادل به‌صورت 'r'، 'w'، 'a' و 'x' نیز مشخص کرد. همچنین می‌توانید برای باز کردن در حالت متنی، به‌ترتیب از 'rt'، 'wt'، 'at' و 'xt' استفاده کنید.

هنگام خواندن، آرگومان options می‌تواند یک دیکشنری باشد که پارامترهای پیشرفته‌ی واگشایی را فراهم می‌کند؛ برای اطلاعات دقیق درباره‌ی پارامترهای پشتیبانی‌شده، DecompressionParameter را ببینید. آرگومان zstd_dict یک نمونه از ZstdDict است که در حین واگشایی استفاده می‌شود. هنگام خواندن، اگر آرگومان level برابر None نباشد، یک TypeError پرتاب خواهد شد.

هنگام نوشتن، آرگومان options می‌تواند دیکشنری باشد که پارامترهای فشرده‌سازی پیشرفته را ارائه می‌کند؛ برای اطلاعات دقیق درباره پارامترهای پشتیبانی‌شده، CompressionParameter را ببینید. آرگومان level سطح فشرده‌سازی برای استفاده هنگام نوشتن داده‌های فشرده است. فقط یکی از level یا options می‌تواند غیر None باشد. آرگومان zstd_dict یک نمونه ZstdDict است که در طول فشرده‌سازی استفاده می‌شود.

در حالت دودویی، این تابع معادل سازنده‌ی ZstdFile است: ZstdFile(file, mode, ...). در این حالت، نباید پارامترهای encoding، errors و newline ارائه شوند.

در حالت متنی، یک شیء ZstdFile ایجاد می‌شود و یک نمونه io.TextIOWrapper با کدگذاری، رفتار مدیریت خطا و پایان‌های خط مشخص‌شده، آن را در بر می‌گیرد.

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

باز کردن یک پرونده فشرده‌شده با Zstandard در حالت دودویی.

یک ZstdFile می‌تواند یک file object از پیش باز را دربرگیرد، یا به‌طور مستقیم روی یک پرونده نام‌دار عمل کند. آرگومان file یا شیء پرونده برای دربرگرفتن، یا نام پرونده برای باز کردن را مشخص می‌کند (به‌صورت یک str، bytes یا شیء path-like). در صورت دربرگرفتن یک شیء پرونده موجود، پرونده دربرگرفته‌شده هنگام بستن ZstdFile بسته نمی‌شود.

آرگومان mode می‌تواند یکی از 'rb' برای خواندن (پیش‌فرض)، 'wb' برای بازنویسی، 'xb' برای ایجاد انحصاری، یا 'ab' برای الحاق باشد. این موارد می‌توانند به‌طور معادل به‌ترتیب به‌صورت 'r'، 'w'، 'x' و 'a' نیز داده شوند.

اگر file یک شیء پرونده باشد (نه یک نام پرونده واقعی)، حالت 'w' پرونده را کوتاه نمی‌کند، بلکه معادل 'a' است.

هنگام خواندن، آرگومان options می‌تواند یک دیکشنری باشد که پارامترهای پیشرفته‌ی واگشایی را فراهم می‌کند؛ برای اطلاعات دقیق درباره‌ی پارامترهای پشتیبانی‌شده، DecompressionParameter را ببینید. آرگومان zstd_dict یک نمونه از ZstdDict است که در حین واگشایی استفاده می‌شود. هنگام خواندن، اگر آرگومان level برابر None نباشد، یک TypeError پرتاب خواهد شد.

هنگام نوشتن، آرگومان options می‌تواند یک دیکشنری باشد که پارامترهای پیشرفته فشرده‌سازی را ارائه می‌دهد؛ برای اطلاعات دقیق درباره پارامترهای پشتیبانی‌شده، CompressionParameter را ببینید. آرگومان level سطح فشرده‌سازی مورد استفاده هنگام نوشتن داده‌های فشرده است. فقط یکی از level یا options را می‌توان ارسال کرد. آرگومان zstd_dict یک نمونه از ZstdDict است که در حین فشرده‌سازی استفاده می‌شود.

ZstdFile از همه‌ی اعضای مشخص‌شده توسط io.BufferedIOBase پشتیبانی می‌کند، به‌جز detach() و truncate(). از تکرار و دستور with پشتیبانی می‌شود.

متد و ویژگی‌های زیر نیز ارائه شده‌اند:

peek(size=-1)

داده‌ی بافرشده را بدون پیش‌بردن موقعیت پرونده برمی‌گرداند. حداقل ۱ بایت داده برگردانده خواهد شد، مگر اینکه به EOF رسیده باشیم. تعداد دقیق بایت‌های برگردانده‌شده نامشخص است (آرگومان size نادیده گرفته می‌شود).

توجه

اگرچه فراخوانی peek() موقعیت پرونده در ZstdFile را تغییر نمی‌دهد، اما ممکن است موقعیت شیء پرونده زیربنایی را تغییر دهد (برای مثال، اگر ZstdFile با ارسال یک شیء پرونده برای file ساخته شده باشد).

mode

'rb' برای خواندن و 'wb' برای نوشتن.

name

نام پرونده Zstandard. معادل ویژگی name در file object زیرین است.

فشرده‌سازی و از حالت فشرده خارج کردن داده‌ها در حافظه

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

data (یک bytes-like object) را فشرده می‌کند و داده فشرده‌شده را به‌صورت یک شیء bytes برمی‌گرداند.

آرگومان level یک عدد صحیح است که سطح فشرده‌سازی را کنترل می‌کند. level جایگزینی برای تنظیم CompressionParameter.compression_level در options است. برای دریافت مقادیری که می‌توان برای level ارسال کرد، از bounds() روی compression_level استفاده کنید. اگر به گزینه‌های پیشرفته‌ی فشرده‌سازی نیاز باشد، آرگومان level باید حذف شود و در دیکشنری options پارامتر CompressionParameter.compression_level باید تنظیم شود.

آرگومان options یک دیکشنری پایتون است که حاوی پارامترهای پیشرفته فشرده‌سازی است. کلیدها و مقدارهای معتبر برای پارامترهای فشرده‌سازی، به‌عنوان بخشی از مستندات CompressionParameter مستند شده‌اند.

آرگومان zstd_dict یک نمونه از ZstdDict است که حاوی داده‌های آموزش‌دیده برای بهبود کارایی فشرده‌سازی است. می‌توان از تابع train_dict() برای تولید یک دیکشنری Zstandard استفاده کرد.

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

data (یک bytes-like object) را از حالت فشرده خارج می‌کند و داده‌ی فشرده‌نشده را به‌صورت یک شیء bytes برمی‌گرداند.

آرگومان options یک دیکشنری پایتون شامل پارامترهای پیشرفته‌ی ازفشرده‌سازی است. کلیدها و مقدارهای معتبر برای پارامترهای فشرده‌سازی به‌عنوان بخشی از مستندات DecompressionParameter مستند شده‌اند.

آرگومان zstd_dict نمونه‌ای از ZstdDict است که حاوی داده‌های آموزش‌دیده‌ی مورد استفاده در حین فشرده‌سازی است. این باید همان دیکشنری Zstandard مورد استفاده در حین فشرده‌سازی باشد.

اگر data حاصل الحاق چندین فریم فشرده‌ی متمایز باشد، همه‌ی این فریم‌ها را از حالت فشرده خارج کنید و حاصل الحاق نتایج را برگردانید.

class compression.zstd.ZstdCompressor(level=None, options=None, zstd_dict=None)

یک شیء فشرده‌ساز ایجاد کنید که می‌توان از آن برای فشرده‌سازی تدریجی داده‌ها استفاده کرد.

برای فشرده‌سازی یک تکه‌ی داده به‌شکلی آسان‌تر، تابع سطح ماژول compress() را ببینید.

آرگومان level یک عدد صحیح است که سطح فشرده‌سازی را کنترل می‌کند. level جایگزینی برای تنظیم CompressionParameter.compression_level در options است. برای دریافت مقادیری که می‌توان برای level ارسال کرد، از bounds() روی compression_level استفاده کنید. اگر به گزینه‌های پیشرفته‌ی فشرده‌سازی نیاز باشد، آرگومان level باید حذف شود و در دیکشنری options پارامتر CompressionParameter.compression_level باید تنظیم شود.

آرگومان options یک دیکشنری پایتون است که حاوی پارامترهای پیشرفته فشرده‌سازی است. کلیدها و مقدارهای معتبر برای پارامترهای فشرده‌سازی، به‌عنوان بخشی از مستندات CompressionParameter مستند شده‌اند.

آرگومان zstd_dict یک نمونه اختیاری از ZstdDict است که حاوی داده‌های آموزش‌دیده برای بهبود بهره‌وری فشرده‌سازی است. برای تولید یک دیکشنری Zstandard می‌توانید از تابع train_dict() استفاده کنید.

compress(data, mode=ZstdCompressor.CONTINUE)

data (یک bytes-like object) را فشرده می‌کند و در صورت امکان، یک شیء bytes حاوی داده‌های فشرده، یا در غیر این صورت یک شیء خالی bytes را برمی‌گرداند. ممکن است بخشی از data به‌صورت داخلی در بافر نگهداری شود، تا در فراخوانی‌های بعدی compress() و flush() مورد استفاده قرار گیرد. داده‌های برگردانده‌شده باید با خروجی تمام فراخوانی‌های پیشین compress() الحاق شوند.

آرگومان mode یک ویژگی از ZstdCompressor است که می‌تواند یکی از CONTINUE، FLUSH_BLOCK یا FLUSH_FRAME باشد.

هنگامی که همه‌ی داده‌ها به فشرده‌ساز ارائه شد، برای پایان دادن به فرآیند فشرده‌سازی، متد flush() را فراخوانی کنید. اگر compress() در حالی فراخوانی شود که mode روی FLUSH_FRAME تنظیم شده باشد، نباید flush() فراخوانی شود، زیرا یک فریمخالی جدید می‌نویسد.

flush(mode=ZstdCompressor.FLUSH_FRAME)

فرآیند فشرده‌سازی را به پایان می‌رساند و یک شیء bytes را برمی‌گرداند که حاوی هرگونه داده‌ای است که در بافرهای داخلی فشرده‌ساز ذخیره‌شده است.

آرگومان mode یک ویژگی از ZstdCompressor است و می‌تواند FLUSH_BLOCK یا FLUSH_FRAME باشد.

set_pledged_input_size(size)

اندازه‌ی داده‌ی فشرده‌نشده size را که برای فریم بعدی ارائه خواهد شد، مشخص کنید. size در سرآیند فریم بعدی نوشته خواهد شد، مگر اینکه CompressionParameter.content_size_flag برابر False یا 0 باشد. اندازه‌ی 0 به این معناست که فریم خالی است. اگر size برابر None باشد، سرآیند فریم شامل اندازه‌ی فریم نخواهد بود. فریم‌هایی که شامل اندازه‌ی داده‌ی فشرده‌نشده هستند، برای خارج کردن از حالت فشرده به حافظه‌ی کمتری نیاز دارند، به‌ویژه در سطوح فشرده‌سازی بالاتر.

اگر last_mode برابر با FLUSH_FRAME نباشد، استثنای ValueError پرتاب می‌شود، زیرا فشرده‌ساز در ابتدای یک فریم نیست. اگر اندازه متعهدشده با اندازه واقعی داده ارائه‌شده به compress() مطابقت نداشته باشد، فراخوانی‌های بعدی compress() یا flush() ممکن است استثنای ZstdError را پرتاب کنند و ممکن است آخرین تکه داده از دست برود.

پس از فراخوانی flush() یا compress() با حالت FLUSH_FRAME، فریم بعدی شامل اندازه فریم در سرآیند نخواهد بود، مگر اینکه set_pledged_input_size() دوباره فراخوانی شود.

CONTINUE

داده‌های بیشتری برای فشرده‌سازی جمع‌آوری می‌کند، که ممکن است خروجی را بلافاصله تولید کند یا نکند. این حالت با بیشینه‌سازی مقدار داده به ازای هر بلوک و فریم، نسبت فشرده‌سازی را بهینه می‌کند.

FLUSH_BLOCK

یک بلوک را کامل کنید و آن را در جریان داده بنویسید. داده‌های برگردانده‌شده تاکنون را می‌توان بلافاصله از حالت فشرده خارج کرد. هنوز می‌توان به داده‌های پیشین در بلوک‌های آینده‌ای که با فراخوانی‌های compress() تولید می‌شوند، ارجاع داد و فشرده‌سازی را بهبود بخشید.

FLUSH_FRAME

یک فریم را کامل کرده و بنویسید. داده‌های بعدی ارائه‌شده به compress()، در یک فریم جدید نوشته خواهند شد و نمی‌توانند به داده‌های گذشته ارجاع دهند.

last_mode

آخرین حالت ارسال‌شده به compress() یا flush(). این مقدار می‌تواند یکی از CONTINUE، FLUSH_BLOCK یا FLUSH_FRAME باشد. مقدار اولیه FLUSH_FRAME است که نشان می‌دهد فشرده‌ساز در آغاز یک فریم جدید قرار دارد.

class compression.zstd.ZstdDecompressor(zstd_dict=None, options=None)

یک شیء واگشا (decompressor) ایجاد کنید، که می‌توان از آن برای واگشایی داده‌ها به‌صورت تدریجی استفاده کرد.

برای روشی راحت‌تر جهت واگشایی از کل یک جریان فشرده به‌صورت یکجا، تابع سطح ماژول decompress() را ببینید.

آرگومان options یک دیکشنری پایتون شامل پارامترهای پیشرفته‌ی ازفشرده‌سازی است. کلیدها و مقدارهای معتبر برای پارامترهای فشرده‌سازی به‌عنوان بخشی از مستندات DecompressionParameter مستند شده‌اند.

آرگومان zstd_dict نمونه‌ای از ZstdDict است که حاوی داده‌های آموزش‌دیده‌ی مورد استفاده در حین فشرده‌سازی است. این باید همان دیکشنری Zstandard مورد استفاده در حین فشرده‌سازی باشد.

توجه

این کلاس، برخلاف تابع decompress() و کلاس ZstdFile، ورودی‌های حاوی چند فریم فشرده را به‌صورت شفاف مدیریت نمی‌کند. برای خارج کردن یک ورودی حاوی چند فریم از حالت فشرده، باید از decompress()، یا اگر با یک file object کار می‌کنید از ZstdFile، یا از چند نمونه ZstdDecompressor استفاده کنید.

decompress(data, max_length=-1)

data (یک شیء شبه‌بایت) را واگشایی می‌کند و داده‌ی فشرده‌نشده را به‌صورت بایت برمی‌گرداند. ممکن است بخشی از data به‌صورت داخلی در حافظه‌ی موقت ذخیره شود تا در فراخوانی‌های بعدی decompress() استفاده شود. داده‌ی برگردانده‌شده باید با خروجی هر یک از فراخوانی‌های قبلی decompress() الحاق شود.

اگر max_length نامنفی باشد، این متد حداکثر max_length بایت از داده‌ی خارج‌شده از حالت فشرده را برمی‌گرداند. اگر این حد حاصل شود و امکان تولید خروجی بیشتر وجود داشته باشد، ویژگی needs_input روی False تنظیم می‌شود. در این حالت، در فراخوانی بعدی decompress() می‌توان data را به‌صورت b'' ارائه کرد تا بخش بیشتری از خروجی به دست آید.

اگر تمام داده‌های ورودی واگشایی و برگردانده شده باشند (خواه به این دلیل که کمتر از max_length بایت بودند، خواه به این دلیل که max_length منفی بود)، ویژگی needs_input روی True تنظیم خواهد شد.

Attempting to decompress data after the end of a frame will raise a EOFError. Any data found after the end of the frame is ignored and saved in the unused_data attribute.

eof

True اگر به نشانگر پایان جریان رسیده باشد.

unused_data

داده‌ای پس از پایان جریان فشرده یافت شد.

پیش از رسیدن به پایان جریان، این b'' خواهد بود.

needs_input

False اگر متد decompress() بتواند پیش از آنکه به ورودی فشرده‌ی جدید نیاز داشته باشد، داده‌ی واگشایی‌شده‌ی بیشتری را ارائه دهد.

دیکشنری‌های Zstandard

compression.zstd.train_dict(samples, dict_size)

یک دیکشنری Zstandard را آموزش می‌دهد و یک نمونه ZstdDict را برمی‌گرداند. دیکشنری‌های Zstandard امکان فشرده‌سازی کارآمدتر داده‌هایی با اندازه‌های کوچک‌تر را فراهم می‌کنند، که به‌طور سنتی به دلیل تکرار کمتر، فشرده‌سازی آن‌ها دشوار است. اگر در حال فشرده‌سازی چندین گروه مشابه از داده‌ها هستید (مانند پرونده‌های مشابه)، دیکشنری‌های Zstandard می‌توانند نسبت‌های فشرده‌سازی و سرعت را به‌طور قابل‌توجهی بهبود بخشند.

آرگومان samples (یک تکرارپذیر از اشیای bytes)، مجموعه‌ای از نمونه‌های استفاده‌شده برای آموزش دیکشنری Zstandard است.

آرگومان dict_size، یک عدد صحیح، حداکثر اندازه‌ای (بر حسب بایت) است که دیکشنری Zstandard باید داشته باشد. مستندات Zstandard پیشنهاد می‌دهد که حداکثر مطلق بیشتر از ۱۰۰ KB نباشد، اما این حداکثر اغلب می‌تواند بسته به داده‌ها کوچک‌تر باشد. دیکشنری‌های بزرگ‌تر معمولاً فشرده‌سازی را کند می‌کنند، اما نسبت‌های فشرده‌سازی را بهبود می‌بخشند. دیکشنری‌های کوچک‌تر به فشرده‌سازی سریع‌تر منجر می‌شوند، اما نسبت فشرده‌سازی را کاهش می‌دهند.

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

یک تابع پیشرفته برای تبدیل یک دیکشنری Zstandard با «محتوای خام» به یک دیکشنری Zstandard معمولی. دیکشنری‌های «محتوای خام» دنباله‌ای از بایت‌ها هستند که نیازی نیست از ساختار یک دیکشنری Zstandard عادی پیروی کنند.

آرگومان zstd_dict یک نمونه از ZstdDict است که dict_content آن حاوی محتویات خام دیکشنری است.

آرگومان samples (یک پیمایش‌پذیر از اشیای bytes)، شامل داده‌های نمونه برای تولید دیکشنری Zstandard است.

آرگومان dict_size، یک عدد صحیح، حداکثر اندازه‌ای (بر حسب بایت) است که دیکشنری Zstandard باید داشته باشد. برای پیشنهادها درباره حداکثر اندازه دیکشنری، به train_dict() مراجعه کنید.

آرگومان level (یک عدد صحیح) سطح فشرده‌سازی است که انتظار می‌رود به فشرده‌سازهایی که از این دیکشنری استفاده می‌کنند، ارسال شود. اطلاعات دیکشنری برای هر سطح فشرده‌سازی متفاوت است، بنابراین تنظیم برای سطح فشرده‌سازی مناسب می‌تواند فشرده‌سازی را کارآمدتر کند.

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

پوششی برای دیکشنری‌های Zstandard. می‌توان از دیکشنری‌ها برای بهبود فشرده‌سازی بسیاری از تکه‌های کوچک داده استفاده کرد. اگر نیاز دارید یک دیکشنری جدید را از داده‌های نمونه آموزش دهید، از train_dict() استفاده کنید.

آرگومان dict_content (یک شیء شبه‌بایت)، اطلاعات دیکشنری از پیش آموزش‌دیده‌شده است.

آرگومان is_raw، یک بولی، پارامتر پیشرفته‌ای است که معنای dict_content را کنترل می‌کند. True یعنی dict_content یک دیکشنری «محتوای خام» است، بدون هیچ محدودیت قالبی. False یعنی dict_content یک دیکشنری معمولی Zstandard است که از توابع Zstandard ایجاد شده است، برای مثال، train_dict() یا CLI خارجی zstd.

هنگام ارسال یک ZstdDict به یک تابع، می‌توانید با ارسال ویژگی‌های as_digested_dict و as_undigested_dict به‌عنوان آرگومان zstd_dict، نحوه بارگذاری دیکشنری را کنترل کنید؛ برای مثال، compress(data, zstd_dict=zd.as_digested_dict). پردازش یک دیکشنری (digesting) عملیات پرهزینه‌ای است که هنگام بارگذاری یک دیکشنری Zstandard رخ می‌دهد. هنگام انجام چندین فراخوانی فشرده‌سازی یا رفع فشردگی، ارسال یک دیکشنری پردازش‌شده، سربار بارگذاری دیکشنری را کاهش می‌دهد.

تفاوت برای فشرده‌سازی

	دیکشنری پردازش‌شده	دیکشنری پردازش‌نشده
پارامترهای پیشرفته‌ی فشرده‌ساز که ممکن است توسط پارامترهای دیکشنری بازنویسی شوند	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 و برخی پارامترهای غیرعمومی.	None
ZstdDict دیکشنری را به‌صورت داخلی در نهانگاه ذخیره می‌کند	بله. بارگذاری مجدد یک دیکشنری پردازش‌شده با همان سطح فشرده‌سازی، سریع‌تر است.	خیر. اگر می‌خواهید یک دیکشنری پردازش‌نشده را چندین بار بارگذاری کنید، استفاده‌ی مجدد از یک شیء فشرده‌ساز را در نظر بگیرید.

اگر یک ZstdDict بدون هیچ ویژگی‌ای ارسال شود، هنگام فشرده‌سازی به‌طور پیش‌فرض یک دیکشنری پردازش‌نشده (undigested) ارسال می‌شود و هنگام واگشایی، در صورت نیاز یک دیکشنری پردازش‌شده (digested) تولید و به‌طور پیش‌فرض ارسال می‌شود.

dict_content

محتوای دیکشنری Zstandard، یک شیء bytes. این همان آرگومان dict_content در متد __init__ است. می‌توان از آن با برنامه‌های دیگر، مانند برنامه‌ی خط فرمان zstd استفاده کرد.

dict_id

شناسه‌ی دیکشنری Zstandard، یک مقدار عدد صحیح غیرمنفی.

غیرصفر به این معناست که دیکشنری معمولی است، توسط توابع Zstandard ایجاد شده و از قالب Zstandard پیروی می‌کند.

0 به معنای یک دیکشنری «محتوای خام» است، بدون هیچ محدودیت قالبی، و برای کاربران پیشرفته در نظر گرفته شده است.

توجه

معنای 0 برای ZstdDict.dict_id با ویژگی dictionary_id در تابع get_frame_info() متفاوت است.

as_digested_dict

به‌صورت یک دیکشنری پردازش‌شده بارگذاری کنید.

as_undigested_dict

به‌صورت یک دیکشنری پردازش‌نشده بارگذاری شود.

کنترل پیشرفته پارامتر

class compression.zstd.CompressionParameter

یک IntEnum شامل کلیدهای پارامترهای فشرده‌سازی پیشرفته است که می‌توان هنگام فشرده‌سازی داده‌ها از آن‌ها استفاده کرد.

می‌توان از متد bounds() برای هر ویژگی استفاده کرد تا مقادیر معتبر آن پارامتر به دست آید.

پارامترها اختیاری هستند؛ مقدار هر پارامتری که حذف شود، به‌طور خودکار انتخاب می‌شود.

مثال دریافت کران پایین و بالای compression_level:

lower, upper = CompressionParameter.compression_level.bounds()

مثال تنظیم window_log بر روی بیشترین اندازه:

_lower, upper = CompressionParameter.window_log.bounds()
options = {CompressionParameter.window_log: upper}
compress(b'venezuelan beaver cheese', options=options)

bounds()

تاپل کرانه‌های عدد صحیح یک پارامتر فشرده‌سازی، (lower, upper)، را برمی‌گرداند. این متد باید روی ویژگی‌ای فراخوانی شود که می‌خواهید کرانه‌های آن را بازیابی کنید. برای مثال، برای به‌دست آوردن مقادیر معتبر compression_level، می‌توانید نتیجه‌ی CompressionParameter.compression_level.bounds() را بررسی کنید.

هر دو کران پایین و بالا شامل می‌شوند.

compression_level

یک راهکار سطح بالا برای تنظیم سایر پارامترهای فشرده‌سازی که بر سرعت و نسبت فشرده‌سازی داده‌ها اثر می‌گذارند.

سطح‌های فشرده‌سازی معمولی بزرگ‌تر از 0 هستند. مقادیر بزرگ‌تر از 20 به‌عنوان فشرده‌سازی «فوق‌العاده» (ultra) در نظر گرفته می‌شوند و به حافظه بیشتری نسبت به سایر سطح‌ها نیاز دارند. می‌توان از مقادیر منفی برای به دست آوردن فشرده‌سازی سریع‌تر به قیمت نسبت‌های فشرده‌سازی بدتر استفاده کرد.

با تنظیم سطح روی ۰، از COMPRESSION_LEVEL_DEFAULT استفاده می‌شود.

window_log

حداکثر فاصله‌ی مجاز ارجاع به عقب (back-reference) که فشرده‌ساز می‌تواند هنگام فشرده‌سازی داده‌ها از آن استفاده کند، به صورت توانی از دو، 1 << window_log بایت. این پارامتر تا حد زیادی بر مصرف حافظه‌ی فشرده‌سازی تأثیر می‌گذارد. مقادیر بالاتر به حافظه‌ی بیشتری نیاز دارند، اما مقادیر فشرده‌سازی بهتری به دست می‌دهند.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

hash_log

اندازه‌ی جدول پروب اولیه (probe table)، به‌صورت توانی از ۲. میزان مصرف حافظه‌ی حاصل، 1 << (hash_log+2) بایت است. جدول‌های بزرگ‌تر، نسبت فشرده‌سازی برای راهبردهای <= dfast و سرعت فشرده‌سازی برای راهبردهای > dfast را بهبود می‌دهند.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

chain_log

اندازه‌ی جدول جست‌وجوی multi-probe، به‌صورت توانی از ۲. میزان حافظه‌ی مصرفی حاصل 1 << (chain_log+2) بایت است. جدول‌های بزرگ‌تر منجر به فشرده‌سازی بهتر و کندتر می‌شوند. این پارامتر برای راهبرد fast تأثیری ندارد. این پارامتر همچنان هنگام استفاده از راهبرد dfast مفید است، که در این حالت یک جدول probe ثانویه را تعریف می‌کند.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

search_log

تعداد تلاش‌های جست‌وجو، به‌صورت توانی از ۲. تلاش‌های بیشتر منجر به فشرده‌سازی بهتر و کندتر می‌شود. این پارامتر برای راهبردهای fast و dfast بی‌فایده است.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

min_match

حداقل اندازه‌ی تطابق‌های مورد جستجو. مقادیر بزرگ‌تر سرعت فشرده‌سازی و واگشایی را افزایش می‌دهند، اما نسبت فشرده‌سازی را کاهش می‌دهند. توجه داشته باشید که Zstandard همچنان می‌تواند تطابق‌هایی با اندازه‌ی کوچک‌تر پیدا کند، فقط الگوریتم جستجوی خود را تنظیم می‌کند تا به دنبال این اندازه و اندازه‌های بزرگ‌تر بگردد. برای همه‌ی راهبردهای کوچک‌تر از btopt، حداقل مؤثر 4 است؛ برای همه‌ی راهبردهای بزرگ‌تر از fast، حداکثر مؤثر 6 است.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

target_length

تأثیر این فیلد به Strategy انتخاب‌شده بستگی دارد.

برای راهبردهای btopt، btultra و btultra2، مقدار، طول تطابقی است که «به‌اندازه کافی خوب» برای توقف جستجو در نظر گرفته می‌شود. مقادیر بزرگ‌تر نسبت‌های فشرده‌سازی را بهتر می‌کنند، اما فشرده‌سازی کندتر می‌شود.

برای راهبرد fast، این فاصله بین نمونه‌برداری تطابق است. مقادیر بزرگ‌تر فشرده‌سازی را سریع‌تر می‌کنند، اما با نسبت فشرده‌سازی بدتر.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

strategy

هرچه مقدار راهبرد انتخاب‌شده بالاتر باشد، روش فشرده‌سازی استفاده‌شده توسط zstd پیچیده‌تر می‌شود و به نسبت‌های فشرده‌سازی بالاتر اما فشرده‌سازی کندتر منجر می‌شود.

همچنین ملاحظه نمائید

Strategy

enable_long_distance_matching

تطبیق با فاصله‌ی طولانی (long distance matching) می‌تواند با یافتن تطبیق‌های بزرگ در فاصله‌های دورتر، فشرده‌سازی ورودی‌های بزرگ را بهبود بخشد. این قابلیت مصرف حافظه و اندازه‌ی پنجره را افزایش می‌دهد.

True یا 1 تطبیق با فاصله‌ی طولانی (long distance matching) را فعال می‌کند، در حالی که False یا 0 آن را غیرفعال می‌کند.

فعال‌سازی این پارامتر، مقدار پیش‌فرض window_log را به ۱۲۸ MiB افزایش می‌دهد، مگر آنکه صریحاً مقدار دیگری برای آن تنظیم شده باشد. این تنظیم در صورتی به‌صورت پیش‌فرض فعال می‌شود که window_log >= ۱۲۸ MiB و راهبرد فشرده‌سازی >= btopt باشد (سطح فشرده‌سازی ۱۶+).

ldm_hash_log

اندازه‌ی جدول برای تطبیق فاصله‌ی طولانی، به‌صورت توانی از ۲. مقادیر بزرگ‌تر مصرف حافظه و نسبت فشرده‌سازی را افزایش می‌دهند، اما سرعت فشرده‌سازی را کاهش می‌دهند.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

ldm_min_match

حداقل اندازه‌ی تطبیق برای تطبیق‌دهنده‌ی فاصله‌ی بلند (long distance matcher). مقادیر بزرگ‌تر یا بیش از حد کوچک اغلب می‌توانند نسبت فشرده‌سازی را کاهش دهند.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

ldm_bucket_size_log

لگاریتم اندازه‌ی هر سطل از جدول هش تطبیق‌گر فاصله‌ی بلند (long distance matcher) برای حل برخورد. مقادیر بزرگ‌تر، حل برخورد را بهبود می‌بخشند اما سرعت فشرده‌سازی را کاهش می‌دهند.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

ldm_hash_rate_log

بسامد درج/جست‌وجوی آیتم‌ها در جدول هش تطبیق‌گر فاصله بلند (long distance matcher). مقادیر بزرگ‌تر سرعت فشرده‌سازی را بهبود می‌بخشند. انحراف زیاد از مقدار پیش‌فرض احتمالاً باعث کاهش نسبت فشرده‌سازی می‌شود.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

content_size_flag

در صورتی که اندازه‌ی داده‌هایی که باید فشرده شوند پیش از فشرده‌سازی مشخص باشد، آن را در سرآیند فریم Zstandard بنویسید.

این پرچم تنها در سناریوهای زیر اعمال می‌شود:

• فراخوانی compress() برای فشرده‌سازی یک‌باره

• ارائه‌ی تمام داده‌هایی که باید در فریمفشرده شوند، در یک فراخوانی ZstdCompressor.compress()، با حالت ZstdCompressor.FLUSH_FRAME.

• فراخوانی ZstdCompressor.set_pledged_input_size() با مقدار دقیق داده‌ای که برای فریم جاری به فشرده‌ساز ارائه خواهد شد، پیش از هر فراخوانی ZstdCompressor.compress(). ZstdCompressor.set_pledged_input_size() باید برای هر فریم جدید فراخوانی شود.

تمام سایر فراخوانی‌های فشرده‌سازی ممکن است اطلاعات اندازه را در سرآیند فریم (frame header) ننویسند.

True یا 1 پرچم اندازه‌ی محتوا را فعال می‌کند، در حالی که False یا 0 آن را غیرفعال می‌کند.

checksum_flag

یک جمع‌آزما ۴ بایتی از محتوای فشرده‌نشده با استفاده از XXHash64 در پایان هر فریم نوشته می‌شود. کد واگشایی Zstandard این جمع‌آزما را تأیید می‌کند. در صورت عدم تطابق، استثنای ZstdError پرتاب می‌شود.

True یا 1 تولید جمع‌آزما (checksum) را فعال می‌کند، در حالی که False یا 0 آن را غیرفعال می‌کند.

dict_id_flag

هنگام فشرده‌سازی با یک ZstdDict، شناسه‌ی دیکشنری در سرآیند فریم (frame header) نوشته می‌شود.

True یا 1 ذخیره‌سازی شناسه دیکشنری را فعال می‌کند، در حالی که False یا 0 آن را غیرفعال می‌کند.

nb_workers

تعداد نخ‌هایی را که برای فشرده‌سازی به‌صورت موازی ایجاد خواهند شد، انتخاب کنید. هنگامی که nb_workers > ۰ باشد، فشرده‌سازی چند نخی فعال می‌شود؛ مقدار 1 به معنای «حالت چند نخی با یک نخ» است. کارگرهای بیشتر سرعت را بهبود می‌بخشند، اما مصرف حافظه را نیز افزایش می‌دهند و نسبت فشرده‌سازی را کمی کاهش می‌دهند.

مقدار صفر، چندنخی را غیرفعال می‌کند.

job_size

اندازه‌ی یک کار فشرده‌سازی، بر حسب بایت. این مقدار تنها زمانی اعمال می‌شود که nb_workers بزرگ‌تر یا مساوی ۱ باشد. هر کار فشرده‌سازی به‌صورت موازی تکمیل می‌شود، بنابراین این مقدار می‌تواند به‌طور غیرمستقیم بر تعداد نخ‌های فعال تأثیر بگذارد.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

overlap_log

تعیین می‌کند که چه مقدار داده از کارهای پیشین (نخ‌ها) برای کارهای جدید بارگذاری مجدد می‌شود تا در حین فشرده‌سازی توسط پنجره‌ی نگاه به عقب مورد استفاده قرار گیرد. این مقدار فقط زمانی استفاده می‌شود که nb_workers بزرگ‌تر یا مساوی ۱ باشد. مقادیر قابل‌قبول از ۰ تا ۹ متغیر است.

• ۰ به این معناست که میزان هم‌پوشانی به‌صورت پویا تنظیم می‌شود

• ۱ به معنای عدم هم‌پوشانی است

• ۹ یعنی استفاده از اندازه‌ی کامل پنجره (window size) از کار پیشین

هر افزایش، اندازه همپوشانی را نصف/دو برابر می‌کند. «۸» به معنای همپوشانی window_size/2 است، «۷» به معنای همپوشانی window_size/4 است، و غیره.

class compression.zstd.DecompressionParameter

یک IntEnum شامل کلیدهای پارامترهای پیشرفته‌ی واگشایی که می‌توان هنگام واگشایی داده‌ها از آن‌ها استفاده کرد. پارامترها اختیاری هستند؛ مقدار هر پارامتری که ارائه نشود، به‌طور خودکار انتخاب می‌شود.

می‌توان از متد bounds() برای هر ویژگی استفاده کرد تا مقادیر معتبر آن پارامتر به دست آید.

مثالی برای تنظیم window_log_max روی بیشینه اندازه:

data = compress(b'Some very long buffer of bytes...')

_lower, upper = DecompressionParameter.window_log_max.bounds()

options = {DecompressionParameter.window_log_max: upper}
decompress(data, options=options)

bounds()

تاپل کران‌های عدد صحیح، (lower, upper)، برای یک پارامتر از حالت فشرده خارج کردن را برمی‌گرداند. این متد باید بر روی ویژگی‌ای فراخوانی شود که می‌خواهید کران‌های آن را بازیابی کنید.

هر دو کران پایین و بالا شامل می‌شوند.

window_log_max

لگاریتم مبنای ۲ حداکثر اندازه‌ی پنجره‌ی استفاده‌شده در حین واگشایی. این می‌تواند برای محدود کردن مقدار حافظه‌ی استفاده‌شده هنگام واگشایی داده‌ها مفید باشد. بزرگ‌تر بودن حداکثر اندازه‌ی پنجره باعث واگشایی سریع‌تر می‌شود.

مقدار صفر باعث می‌شود مقدار به‌صورت خودکار انتخاب شود.

class compression.zstd.Strategy

یک IntEnum که شامل راهبردهایی برای فشرده‌سازی است. راهبردهای با شماره بالاتر، فشرده‌سازی پیچیده‌تر و کندتری دارند.

توجه

مقادیر ویژگی‌های Strategy لزوماً در نسخه‌های مختلف zstd پایدار نیستند. تنها می‌توان به ترتیب ویژگی‌ها اتکا کرد. ویژگی‌ها در زیر به ترتیب فهرست شده‌اند.

راهبردهای زیر در دسترس هستند:

fast

dfast

greedy

lazy

lazy2

btlazy2

btopt

btultra

btultra2

متفرقه

compression.zstd.get_frame_info(frame_buffer)

یک شیء FrameInfo حاوی فراداده در مورد یک فریم Zstandard را بازیابی کنید. فریم‌ها حاوی فراداده مربوط به داده‌های فشرده‌ای هستند که در خود نگه می‌دارند.

class compression.zstd.FrameInfo

فراداده‌ی مربوط به یک فریم Zstandard.

decompressed_size

اندازه‌ی محتوای غیرفشرده‌ی فریم.

dictionary_id

یک عدد صحیح که شناسه‌ی دیکشنری Zstandard موردنیاز برای واگشایی فریم را نشان می‌دهد. 0 یعنی شناسه‌ی دیکشنری در سرآیند فریم ثبت نشده است. این ممکن است به این معنا باشد که به دیکشنری Zstandard نیازی نیست، یا شناسه‌ی یک دیکشنری موردنیاز ثبت نشده است.

compression.zstd.COMPRESSION_LEVEL_DEFAULT

سطح فشرده‌سازی پیش‌فرض برای Zstandard: 3.

compression.zstd.zstd_version_info

شماره نسخه کتابخانه zstd در ران‌تایم به‌صورت یک تاپل از اعداد صحیح (major, minor, release).

مثال‌ها

خواندن از یک پرونده فشرده:

from compression import zstd

with zstd.open("file.zst") as f:
    file_content = f.read()

ایجاد یک پرونده فشرده:

from compression import zstd

data = b"Insert Data Here"
with zstd.open("file.zst", "w") as f:
    f.write(data)

فشرده‌سازی داده‌ها در حافظه:

from compression import zstd

data_in = b"Insert Data Here"
data_out = zstd.compress(data_in)

فشرده‌سازی تدریجی:

from compression import zstd

comp = zstd.ZstdCompressor()
out1 = comp.compress(b"Some data\n")
out2 = comp.compress(b"Another piece of data\n")
out3 = comp.compress(b"Even more data\n")
out4 = comp.flush()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])

نوشتن داده‌های فشرده در پرونده‌ای که از قبل باز است:

from compression import zstd

with open("myfile", "wb") as f:
    f.write(b"This data will not be compressed\n")
    with zstd.open(f, "w") as zstf:
        zstf.write(b"This *will* be compressed\n")
    f.write(b"Not compressed\n")

ایجاد یک پرونده فشرده با استفاده از پارامترهای فشرده‌سازی:

from compression import zstd

options = {
   zstd.CompressionParameter.checksum_flag: 1
}
with zstd.open("file.zst", "w", options=options) as f:
    f.write(b"Mind if I squeeze in?")