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=9, 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 را میپذیرد.
- exception gzip.BadGzipFile¶
استثنایی که برای پروندههای gzip نامعتبر پرتاب میشود. این استثنا از
OSErrorارثبری میکند.EOFErrorوzlib.errorنیز ممکن است برای پروندههای gzip نامعتبر پرتاب شوند.اضافه شده در نسخهی 3.8.
- class gzip.GzipFile(filename=None, mode=None, compresslevel=9, 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بدون فشردهسازی است. مقدار پیشفرض9است.آرگومان اختیاری mtime برچسب زمانی است که gzip درخواست میکند. این زمان در قالب Unix است، یعنی ثانیههای سپریشده از ۰۰:۰۰:۰۰ UTC، ۱ ژانویه ۱۹۷۰. اگر mtime حذف شود یا
Noneباشد، از زمان جاری استفاده میشود. برای تولید یک جریان فشرده که به زمان ایجاد وابسته نباشد، از mtime = 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استفاده کنید.
- gzip.compress(data, compresslevel=9, *, 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 بدهید.
- 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()
مثالی از چگونگی ایجاد یک پرونده GZIP فشرده:
import gzip
content = b"Lots of content here"
with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
f.write(content)
مثالی از نحوه فشردهسازی یک پرونده موجود با GZIP:
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)
مثالی از نحوهی فشردهسازی GZIP یک رشتهی دودویی:
import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)
همچنین ملاحظه نمائید
- ماژول
zlib ماژول پایهی فشردهسازی داده که برای پشتیبانی از قالب پرونده gzip مورد نیاز است.
در صورتی که فشردهسازی و واگشایی gzip گلوگاه باشد، بسته python-isal سرعت فشردهسازی و واگشایی را با یک API عمدتاً سازگار افزایش میدهد.
رابط خط فرمان¶
ماژول gzip یک رابط خط فرمان ساده برای فشردهسازی یا از حالت فشرده خارج کردن پروندهها ارائه میدهد.
پس از اجرا، ماژول gzip پرونده(های) ورودی را نگه میدارد.
تغییر یافته در نسخهی 3.8: یک رابط خط فرمان جدید به همراه یک کاربرد اضافه کنید. بهطور پیشفرض، هنگامی که CLI را اجرا کنید، سطح فشردهسازی پیشفرض ۶ است.
گزینههای خط فرمان¶
- --fast¶
نشاندهندهی سریعترین روش فشردهسازی (فشردهسازی کمتر) است.
- --best¶
نشاندهندهی کندترین روش فشردهسازی (بهترین فشردهسازی) است.
- -d, --decompress¶
پرونده دادهشده را از حالت فشرده خارج کنید.
- -h, --help¶
نمایش پیام راهنما.