gzip --- پشتیبانی از پرونده‌های gzip¶

کد منبع: Lib/gzip.py

این ماژول رابط ساده‌ای برای فشرده‌سازی و از حالت فشرده خارج کردن پرونده‌ها فراهم می‌کند، درست مانند برنامه‌های GNU gzip و gunzip.

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

فشرده‌سازی داده توسط ماژول zlib فراهم می‌شود.

ماژول gzip کلاس GzipFile و همچنین توابع سهولت‌بخش open()، compress() و decompress() را فراهم می‌کند. کلاس GzipFile پرونده‌های با قالب gzip را می‌خواند و می‌نویسد و داده‌ها را به‌طور خودکار فشرده‌سازی یا از حالت فشرده خارج می‌کند، به‌گونه‌ای که مانند یک file object معمولی به نظر برسد.

توجه داشته باشید که قالب‌های پرونده دیگری که می‌توانند توسط برنامه‌های gzip و gunzip از حالت فشرده خارج شوند، مانند آن‌هایی که توسط compress و pack تولید می‌شوند، در این ماژول پشتیبانی نمی‌شوند.

این ماژول آیتم‌های زیر را تعریف می‌کند:

gzip.open(filename, mode='rb', compresslevel=6, encoding=None, errors=None, newline=None)¶

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

آرگومان filename می‌تواند یک نام پرونده واقعی (یک شیء str یا bytes)، یا یک شیء پرونده موجود برای خواندن از آن یا نوشتن در آن باشد.

آرگومان mode می‌تواند یکی از 'r'، 'rb'، 'a'، 'ab'، 'w'، 'wb'، 'x' یا 'xb' برای حالت دودویی، یا 'rt'، 'at'، 'wt' یا 'xt' برای حالت متنی باشد. مقدار پیش‌فرض 'rb' است.

آرگومان compresslevel یک عدد صحیح از ۰ تا ۹ است، همان‌طور که برای سازنده‌ی GzipFile وجود دارد.

برای حالت دودویی، این تابع معادل سازنده‌ی GzipFile است: GzipFile(filename, mode, compresslevel). در این حالت، آرگومان‌های encoding، errors و newline نباید ارائه شوند.

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

تغییر یافته در نسخه‌ی 3.3: پشتیبانی از filename به‌عنوان یک شیء پرونده، پشتیبانی از حالت متنی، و آرگومان‌های encoding، errors و newline افزوده شد.

تغییر یافته در نسخه‌ی 3.4: پشتیبانی از حالت‌های 'x'، 'xb' و 'xt' اضافه شد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.15: سطح فشرده‌سازی پیش‌فرض به ۶ (کاهش‌یافته از ۹) کاهش یافت. این سطح پیش‌فرضی است که توسط بیشتر ابزارهای فشرده‌سازی استفاده می‌شود و توازن بهتری بین سرعت و کارایی برقرار می‌کند.

exception gzip.BadGzipFile¶

استثنایی که برای پرونده‌های gzip نامعتبر پرتاب می‌شود. این استثنا از OSError ارث‌بری می‌کند. EOFError و zlib.error نیز ممکن است برای پرونده‌های gzip نامعتبر پرتاب شوند.

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

class gzip.GzipFile(filename=None, mode=None, compresslevel=6, fileobj=None, mtime=None)¶

سازنده‌ای برای کلاس GzipFile، که بیشتر متدهای یک شیء پرونده را شبیه‌سازی می‌کند، به استثنای متد truncate(). حداقل یکی از fileobj و filename باید یک مقدار غیربدیهی به آن داده شود.

نمونه‌ی کلاس جدید بر پایه‌ی fileobj است که می‌تواند یک پرونده معمولی، یک شیء io.BytesIO یا هر شیء دیگری باشد که یک پرونده را شبیه‌سازی می‌کند. مقدار پیش‌فرض آن None است، که در این صورت filename باز می‌شود تا یک شیء پرونده فراهم کند.

هنگامی که fileobj برابر None نباشد، آرگومان filename فقط برای گنجانده شدن در سرآیند پرونده gzip استفاده می‌شود، که ممکن است شامل نام پرونده اصلیِ پرونده فشرده‌نشده باشد. مقدار پیش‌فرض آن نام فایلِ fileobj است، اگر قابل تشخیص باشد؛ در غیر این صورت، پیش‌فرض آن رشته‌ی خالی است و در این حالت نام پرونده اصلی در سرآیند گنجانده نمی‌شود.

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

توجه داشته باشید که پرونده همیشه در حالت دودویی باز می‌شود. برای باز کردن یک پرونده فشرده در حالت متنی، از open() استفاده کنید (یا GzipFile خود را با یک io.TextIOWrapper بپیچید).

آرگومان compresslevel یک عدد صحیح از 0 تا 9 است که سطح فشرده‌سازی را کنترل می‌کند؛ 1 سریع‌ترین است و کمترین فشرده‌سازی را تولید می‌کند، و 9 کندترین است و بیشترین فشرده‌سازی را تولید می‌کند. 0 بدون فشرده‌سازی است. پیش‌فرض 6 است.

آرگومان اختیاری mtime برچسب زمانی درخواست‌شده توسط gzip است. زمان در قالب یونیکس است، یعنی تعداد ثانیه‌های سپری‌شده از 00:00:00 UTC، ۱ ژانویه‌ی ۱۹۷۰. برای تولید یک جریان فشرده‌شده که به زمان ایجاد وابسته نباشد، mtime را روی 0 تنظیم کنید. اگر mtime حذف شود یا None باشد، از زمان فعلی استفاده می‌شود؛ با این حال، اگر زمان فعلی خارج از بازه‌ی 00:00:00 UTC، ۱ ژانویه‌ی ۱۹۷۰ تا 06:28:15 UTC، ۷ فوریه‌ی ۲۱۰۶ باشد، یا آرگومان mtime به‌طور صریح خارج از بازه‌ی 0 تا 2**32-1 داده شود، به‌جای آن از مقدار 0 استفاده می‌شود.

در زیر ویژگی mtime را ببینید که هنگام از حالت فشرده خارج کردن تنظیم می‌شود.

فراخوانی متد close() یک شیء GzipFile، fileobj را نمی‌بندد، زیرا ممکن است بخواهید محتوای بیشتری را پس از داده‌های فشرده اضافه کنید. این موضوع همچنین به شما امکان می‌دهد که یک شیء io.BytesIO را که برای نوشتن باز شده است به‌عنوان fileobj ارسال کنید و با استفاده از متد getvalue() همان شیء io.BytesIO، بافر حافظه‌ی حاصل را بازیابی کنید.

GzipFile از رابط io.BufferedIOBase پشتیبانی می‌کند، از جمله تکرار و دستور with. فقط متد truncate() پیاده‌سازی نشده است.

GzipFile همچنین متد و ویژگی زیر را فراهم می‌کند:

peek(n)¶

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

نکته

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

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

mode¶

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

تغییر یافته در نسخه‌ی 3.13: در نسخه‌های قبلی، یک عدد صحیح 1 یا 2 بود.

mtime¶

هنگام واگشایی، این ویژگی روی آخرین برچسب زمانی در آخرین سرآیند‌ی خوانده‌شده تنظیم می‌شود. این یک عدد صحیح است و تعداد ثانیه‌ها از مبدأ زمان یونیکس (۰۰:۰۰:۰۰ UTC، ۱ ژانویه ۱۹۷۰) را نگه می‌دارد. مقدار اولیه پیش از خواندن هر سرآیند‌ای None است.

name¶

مسیر پرونده gzip روی دیسک، به‌صورت str یا bytes. معادل خروجی os.fspath() برای مسیر ورودی اصلی، بدون هیچ‌گونه نرمال‌سازی، حل یا بسط دیگری.

تغییر یافته در نسخه‌ی 3.1: پشتیبانی از دستور with، به‌همراه آرگومان سازنده‌ی mtime و ویژگی mtime افزوده شد.

تغییر یافته در نسخه‌ی 3.2: پشتیبانی از پرونده‌های پرشده با صفر (zero-padded) و غیرقابل مکان‌یابی (unseekable) اضافه شد.

تغییر یافته در نسخه‌ی 3.3: متد io.BufferedIOBase.read1() اکنون پیاده‌سازی شده است.

تغییر یافته در نسخه‌ی 3.4: پشتیبانی از حالت‌های 'x' و 'xb' اضافه شد.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از نوشتن هرگونه شیء شبه‌بایت افزوده شد. متد read() اکنون None را به‌عنوان آرگومان می‌پذیرد.

تغییر یافته در نسخه‌ی 3.6: یک path-like object را می‌پذیرد.

منسوخ شده از نسخه‌ی 3.9: باز کردن GzipFile برای نوشتن بدون تعیین آرگومان mode منسوخ شده است.

تغییر یافته در نسخه‌ی 3.12: ویژگی filename را حذف کنید و به‌جای آن از ویژگی name استفاده کنید.

تغییر یافته در نسخه‌ی 3.15: سطح فشرده‌سازی پیش‌فرض به ۶ (کاهش‌یافته از ۹) کاهش یافت. این سطح پیش‌فرضی است که توسط بیشتر ابزارهای فشرده‌سازی استفاده می‌شود و توازن بهتری بین سرعت و کارایی برقرار می‌کند.

gzip.compress(data, compresslevel=6, *, mtime=0)¶

data را فشرده می‌کند و یک شیء bytes حاوی داده فشرده‌شده برمی‌گرداند. compresslevel و mtime همان معنایی را دارند که در سازنده GzipFile در بالا آمده است، اما مقدار پیش‌فرض mtime برابر ۰ است تا خروجی قابل بازتولید باشد.

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

تغییر یافته در نسخه‌ی 3.8: پارامتر mtime برای خروجی قابل‌تکرار افزوده شد.

تغییر یافته در نسخه‌ی 3.11: سرعت با فشرده‌سازی همه داده‌ها به‌صورت یکجا به‌جای روش جریانی بهبود می‌یابد. فراخوانی‌هایی که mtime آن‌ها روی 0 تنظیم شده است، برای سرعت بهتر به zlib.compress() واگذار می‌شوند. در این شرایط، ممکن است خروجی شامل مقداری برای بایت «OS» سرآیند gzip باشد که غیر از ۲۵۵ («نامشخص») است و توسط پیاده‌سازی زیربنایی zlib ارائه می‌شود.

تغییر یافته در نسخه‌ی 3.13: هنگام استفاده از این تابع، تضمین می‌شود که بایت OS سرآیند gzip روی 255 تنظیم شود، همان‌گونه که در 3.10 و نسخه‌های پیش‌تر نیز چنین بود.

تغییر یافته در نسخه‌ی 3.14: پارامتر mtime اکنون برای خروجی قابل تولید مجدد، به‌طور پیش‌فرض مقدار ۰ را دارد. برای رفتار پیشین که از زمان جاری استفاده می‌کرد، None را به mtime بدهید.

تغییر یافته در نسخه‌ی 3.15: سطح فشرده‌سازی پیش‌فرض به ۶ (کاهش‌یافته از ۹) کاهش یافت. این سطح پیش‌فرضی است که توسط بیشتر ابزارهای فشرده‌سازی استفاده می‌شود و توازن بهتری بین سرعت و کارایی برقرار می‌کند.

gzip.decompress(data)¶

data را واگشایی می‌کند و یک شیء bytes حاوی داده‌ی غیرفشرده را برمی‌گرداند. این تابع قادر به واگشایی داده‌ی gzip چندعضوی (چند بلوک gzip که به هم الحاق شده‌اند) است. هنگامی که مطمئن هستید داده فقط شامل یک عضو است، تابع zlib.decompress() با wbits تنظیم‌شده روی ۳۱ سریع‌تر است.

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

تغییر یافته در نسخه‌ی 3.11: سرعت با واگشایی یکجای اعضا در حافظه، به‌جای انجام این کار به‌صورت جریانی، بهبود می‌یابد.

import gzip
with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
    file_content = f.read()

import gzip
content = b"Lots of content here"
with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
    f.write(content)

import gzip
import shutil
with open('/home/joe/file.txt', 'rb') as f_in:
    with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
        shutil.copyfileobj(f_in, f_out)

import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)