zipfile --- کار با بایگانیهای ZIP¶
کد منبع: Lib/zipfile/
قالب پرونده ZIP یک استاندارد رایج برای بایگانی و فشردهسازی است. این ماژول ابزارهایی را برای ایجاد، خواندن، نوشتن، الحاق به و فهرست کردن یک پرونده ZIP فراهم میکند. هرگونه استفاده پیشرفته از این ماژول نیازمند درک این قالب، همانگونه که در PKZIP Application Note تعریف شده است، خواهد بود.
این ماژول از پروندههای ZIP چندبخشی پشتیبانی نمیکند. این ماژول میتواند پروندههای ZIP که از افزونههای ZIP64 استفاده میکنند (یعنی پروندههای ZIP با حجم بیش از ۴ GiB) را پردازش کند. این ماژول از رمزگشایی پروندههای رمزگذاریشده در آرشیوهای ZIP پشتیبانی میکند، اما نمیتواند پرونده رمزگذاریشده ایجاد کند. رمزگشایی بسیار کند است، زیرا بهجای C در پایتون خالص پیادهسازی شده است.
مدیریت بایگانیهای فشرده به ماژولهای اختیاری مانند zlib، bz2، lzma و compression.zstd نیاز دارد. اگر هر یک از آنها در نسخهی CPython شما موجود نیست، به مستندات توزیعکننده خود مراجعه کنید (یعنی هر کسی که پایتون را در اختیار شما قرار داده است). اگر شما توزیعکننده هستید، نیازمندیهای ماژولهای اختیاری را ببینید.
این ماژول آیتمهای زیر را تعریف میکند:
- exception zipfile.BadZipFile¶
خطای پرتابشده برای پروندههای ZIP نامعتبر.
اضافه شده در نسخهی 3.2.
- exception zipfile.BadZipfile¶
نام مستعار
BadZipFile، برای سازگاری با نسخههای قدیمیتر پایتون.منسوخ شده از نسخهی 3.2.
- exception zipfile.LargeZipFile¶
خطایی که زمانی پرتاب میشود که یک پرونده ZIP به قابلیت ZIP64 نیاز داشته باشد، اما این قابلیت فعال نشده باشد.
- class zipfile.ZipFile
کلاسی برای خواندن و نوشتن پروندههای ZIP. برای جزئیات سازنده، بخش اشیای ZipFile را ببینید.
- class zipfile.Path
کلاسی که زیرمجموعهای از رابط ارائهشده توسط
pathlib.Path، شامل رابط کاملimportlib.resources.abc.Traversable، را پیادهسازی میکند.اضافه شده در نسخهی 3.8.
- class zipfile.PyZipFile
کلاسی برای ساخت بایگانیهای ZIP حاوی کتابخانههای پایتون.
- class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))¶
کلاسی که برای نمایش اطلاعات مربوط به یک عضو بایگانی استفاده میشود. نمونههای این کلاس توسط متدهای
getinfo()وinfolist()از اشیایZipFileبرگردانده میشوند. بیشتر کاربران ماژولzipfileنیازی به ایجاد این نمونهها ندارند، بلکه تنها از نمونههای ایجادشده توسط این ماژول استفاده میکنند. filename باید نام کامل عضو بایگانی باشد و date_time باید تاپلی شامل ۶ فیلد باشد که زمان آخرین تغییر پرونده را توصیف میکنند؛ این فیلدها در بخش اشیای ZipInfo توضیح داده شدهاند.تغییر یافته در نسخهی 3.13: یک ویژگی عمومی
compress_levelافزوده شده است تا_compresslevelرا که پیشتر محافظتشده بود، در دسترس قرار دهد. نام محافظتشدهی قدیمیتر همچنان برای سازگاری با نسخههای پیشین بهعنوان یک پراپرتی کار میکند.- _for_archive(archive)¶
date_time، ویژگیهای فشردهسازی و ویژگیهای خارجی را به پیشفرضهای مناسبی تنظیم کنید که
ZipFile.writestr()از آنها استفاده میکند.self را برای زنجیرهسازی برمیگرداند.
اضافه شده در نسخهی 3.14.
- zipfile.is_zipfile(filename)¶
اگر filename بر اساس شماره جادویی (magic number) خود یک پرونده ZIP معتبر باشد،
Trueرا برمیگرداند، در غیر این صورتFalseرا برمیگرداند. filename همچنین میتواند یک پرونده یا شیء شبهپرونده باشد.تغییر یافته در نسخهی 3.1: پشتیبانی از پرونده و اشیای شبهپرونده.
- zipfile.ZIP_STORED¶
ثابت عددی برای یک عضو آرشیو فشردهنشده.
- zipfile.ZIP_BZIP2¶
ثابت عددی برای روش فشردهسازی BZIP2. این به ماژول
bz2نیاز دارد.اضافه شده در نسخهی 3.3.
- zipfile.ZIP_LZMA¶
ثابت عددی برای روش فشردهسازی LZMA. این به ماژول
lzmaنیاز دارد.اضافه شده در نسخهی 3.3.
- zipfile.ZIP_ZSTANDARD¶
ثابت عددی برای فشردهسازی Zstandard. این نیازمند ماژول
compression.zstdاست.توجه
در APPNOTE 6.3.7، شناسه روش
20به فشردهسازی Zstandard اختصاص داده شده بود. این شناسه در APPNOTE 6.3.8 برای جلوگیری از تعارض به شناسه روش93تغییر یافت و شناسه روش20منسوخ شد. برای سازگاری، ماژولzipfileهر دو شناسه روش را میخواند، اما دادهها را فقط با شناسه روش93مینویسد.اضافه شده در نسخهی 3.14.
توجه
مشخصات قالب پرونده ZIP از سال ۲۰۰۱ پشتیبانی از فشردهسازی bzip2، از سال ۲۰۰۶ پشتیبانی از فشردهسازی LZMA و از سال ۲۰۲۰ پشتیبانی از فشردهسازی Zstandard را در بر داشته است. با این حال، برخی ابزارها (از جمله نسخههای قدیمیتر پایتون) از این روشهای فشردهسازی پشتیبانی نمیکنند و ممکن است بهطور کامل از پردازش پرونده ZIP امتناع کنند یا در استخراج پروندههای منفرد ناموفق باشند.
همچنین ملاحظه نمائید
- PKZIP Application Note
مستنداتی در مورد قالب پرونده ZIP اثر فیل کاتز، خالق این قالب و الگوریتمهای بهکاررفته.
- صفحهی اصلی Info-ZIP
اطلاعات دربارهی برنامههای بایگانی ZIP و کتابخانههای توسعهی پروژهی Info-ZIP.
اشیای ZipFile¶
- class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)¶
یک پرونده ZIP را باز کنید، که در آن file میتواند مسیری به یک پرونده (یک رشته)، یک شیء شبهپرونده یا یک path-like object باشد.
پارامتر mode باید
'r'باشد تا یک پرونده موجود خوانده شود،'w'برای تهی کردنو نوشتن یک پرونده جدید،'a'برای الحاق به یک پرونده موجود، یا'x'برای ایجاد و نوشتن یک پرونده جدید بهصورت انحصاری. اگر mode برابر'x'باشد و file به یک پرونده موجود اشاره کند، یکFileExistsErrorپرتاب خواهد شد. اگر mode برابر'a'باشد و file به یک پرونده ZIP موجود اشاره کند، پروندههای اضافی به آن افزوده میشوند. اگر file به یک پرونده ZIP اشاره نکند، یک آرشیو ZIP جدید به پرونده الحاق میشود. این برای افزودن یک آرشیو ZIP به پروندهای دیگر (مانندpython.exe) در نظر گرفته شده است. اگر mode برابر'a'باشد و پرونده اصلاً وجود نداشته باشد، ایجاد میشود. اگر mode برابر'r'یا'a'باشد، پرونده باید قابل تغییر موقعیت (seekable) باشد.compression روش فشردهسازی ZIP برای استفاده هنگام نوشتن آرشیو است و باید یکی از
ZIP_STORED،ZIP_DEFLATED،ZIP_BZIP2،ZIP_LZMAیاZIP_ZSTANDARDباشد؛ مقادیر ناشناخته باعث پرتابNotImplementedErrorمیشوند. اگرZIP_DEFLATED،ZIP_BZIP2،ZIP_LZMAیاZIP_ZSTANDARDتعیین شده باشد اما ماژول مربوطه (zlib،bz2،lzmaیاcompression.zstd) در دسترس نباشد،RuntimeErrorپرتاب میشود. مقدار پیشفرضZIP_STOREDاست.اگر allowZip64
Trueباشد (پیشفرض)، zipfile پروندههای ZIP را ایجاد میکند که در صورت بزرگتر بودن پرونده ZIP از ۴ GiB از افزونههای ZIP64 استفاده میکنند. اگر مقدار آنfalseباشد،zipfileدر صورتی که پرونده ZIP به افزونههای ZIP64 نیاز داشته باشد، یک استثنا پرتاب میکند.پارامتر compresslevel سطح فشردهسازی مورد استفاده هنگام نوشتن پروندهها در بایگانی را کنترل میکند. هنگام استفاده از
ZIP_STOREDیاZIP_LZMA، این پارامتر تأثیری ندارد. هنگام استفاده ازZIP_DEFLATED، اعداد صحیح0تا9پذیرفته میشوند (برای اطلاعات بیشترzlibرا ببینید). هنگام استفاده ازZIP_BZIP2، اعداد صحیح1تا9پذیرفته میشوند (برای اطلاعات بیشترbz2را ببینید). هنگام استفاده ازZIP_ZSTANDARD، اعداد صحیح-131072تا22معمولاً پذیرفته میشوند (برای اطلاعات بیشتر دربارهی بازیابی مقادیر معتبر و معنای آنهاCompressionParameter.compression_levelرا ببینید).آرگومان strict_timestamps، هنگامی که روی
Falseتنظیم شود، امکان زیپ کردن پروندههای قدیمیتر از ۱۹۸۰-۰۱-۰۱ را به بهای تنظیم مهر زمانی روی ۱۹۸۰-۰۱-۰۱ فراهم میکند. رفتار مشابهی برای پروندههای جدیدتر از ۲۱۰۷-۱۲-۳۱ رخ میدهد؛ مهر زمانی نیز روی همان حد تنظیم میشود.هنگامی که mode برابر
'r'باشد، میتوان metadata_encoding را روی نام یک کدک تنظیم کرد، که برای کدگشایی فرادادهای مانند نام اعضا و کامنتها ZIP استفاده خواهد شد.اگر پرونده با حالت
'w'،'x'یا'a'ایجاد شود و سپس بدون افزودن هیچ پروندهای به بایگانی،closedشود، ساختارهای ZIP مناسب برای یک بایگانی خالی در پرونده نوشته خواهند شد.ZipFile همچنین یک مدیر زمینه است و بنابراین از دستور
withپشتیبانی میکند. در این مثال، myzip پس از پایان یافتن بدنهی دستورwithبسته میشود---حتی اگر استثنایی رخ دهد:with ZipFile('spam.zip', 'w') as myzip: myzip.write('eggs.txt')
توجه
metadata_encoding یک تنظیم در سطح کل نمونه برای ZipFile است. امکان تنظیم آن برای هر عضو بهصورت جداگانه وجود ندارد.
این ویژگی یک راهحل موقت برای پیادهسازیهای قدیمی است که بایگانیهایی با نامهایی در کدگذاری یا صفحه کد زبان locale فعلی ایجاد میکنند (عمدتاً در ویندوز). طبق استاندارد .ZIP، کدگذاری فراداده میتواند با پرچمی در سرآیند بایگانی بهصورت صفحه کد IBM (پیشفرض) یا UTF-8 مشخص شود. این پرچم بر metadata_encoding، که افزونهای مخصوص پایتون است، اولویت دارد.
تغییر یافته در نسخهی 3.2: توانایی استفاده از
ZipFileبهعنوان یک مدیر زمینه افزوده شد.تغییر یافته در نسخهی 3.4: افزونههای ZIP64 بهطور پیشفرض فعال هستند.
تغییر یافته در نسخهی 3.5: پشتیبانی از نوشتن در جریانهای غیرقابل مکانیابی (unseekable streams) افزوده شد. پشتیبانی از حالت
'x'افزوده شد.تغییر یافته در نسخهی 3.6: پیشتر، برای مقادیر ناشناختهی فشردهسازی، یک
RuntimeErrorساده پرتاب میشد.تغییر یافته در نسخهی 3.6.2: پارامتر file یک path-like object را میپذیرد.
تغییر یافته در نسخهی 3.7: افزودن پارامتر compresslevel.
تغییر یافته در نسخهی 3.8: پارامتر فقط کلیدواژهای strict_timestamps.
تغییر یافته در نسخهی 3.11: پشتیبانی برای تعیین کدگذاری نام عضو جهت خواندن فراداده در سرآیندهای پوشه و فایلِ zipfile افزوده شد.
- ZipFile.close()¶
پرونده آرشیو را ببندید. شما باید پیش از خروج از برنامهتان
close()را فراخوانی کنید، در غیر این صورت رکوردهای ضروری نوشته نخواهند شد.
- ZipFile.getinfo(name)¶
یک شیء
ZipInfoبا اطلاعاتی درباره عضو آرشیو name برمیگرداند. فراخوانیgetinfo()برای نامی که در حال حاضر در آرشیو وجود ندارد، یکKeyErrorرا پرتاب خواهد کرد.
- ZipFile.infolist()¶
فهرستی را برمیگرداند که شامل یک شیء
ZipInfoبرای هر عضو از بایگانی است. اگر یک بایگانی موجود باز شده باشد، اشیاء همان ترتیب ورودیهای خود در پرونده ZIP واقعی روی دیسک را دارند.
- ZipFile.namelist()¶
فهرستی از اعضای بایگانی را بر اساس نام برمیگرداند.
- ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)¶
به عضوی از بایگانی بهعنوان یک شیء شبهپرونده دودویی دسترسی پیدا کنید. name میتواند نام پروندهای در بایگانی یا یک شیء
ZipInfoباشد. پارامتر mode، در صورت وجود، باید'r'(پیشفرض) یا'w'باشد. pwd گذرواژهای است که بهعنوان یک شیءbytesبرای رمزگشایی پروندههای ZIP رمزنگاریشده استفاده میشود.open()همچنین یک مدیر زمینه است و بنابراین از دستورwithپشتیبانی میکند:with ZipFile('spam.zip') as myzip: with myzip.open('eggs.txt') as myfile: print(myfile.read())
با mode
'r'شیء شبهپرونده (ZipExtFile) فقط خواندنی است و متدهای زیر را فراهم میکند:read()،readline()،readlines()،seek()،tell()،__iter__()،__next__(). این اشیاء میتوانند مستقل از ZipFile عمل کنند.با
mode='w'، یک دسته پرونده قابل نوشتن بازگردانده میشود که از متدwrite()پشتیبانی میکند. تا زمانی که یک دسته پرونده قابل نوشتن باز است، تلاش برای خواندن یا نوشتن سایر پروندههای درون پرونده ZIP باعث پرتابValueErrorمیشود.در هر دو حالت، شیء شبهپرونده همچنین دارای ویژگیهای
nameوmodeاست؛ name معادل نام یک پرونده درون بایگانی است و mode بسته به حالت ورودی'rb'یا'wb'است.هنگام نوشتن یک پرونده، اگر اندازه پرونده از پیش مشخص نیست اما ممکن است از ۲ GiB فراتر برود،
force_zip64=Trueرا ارسال کنید تا اطمینان حاصل شود که قالب سرآیند توانایی پشتیبانی از پروندههای بزرگ را دارد. اگر اندازه پرونده از پیش مشخص است، یک شیءZipInfoایجاد کنید کهfile_sizeآن تنظیمشده باشد و از آن بهعنوان پارامتر name استفاده کنید.توجه
متدهای
open()،read()وextract()میتوانند یک نام پرونده یا یک شیءZipInfoرا بپذیرند. هنگام تلاش برای خواندن یک پرونده ZIP که شامل اعضایی با نامهای تکراری است، قدردان این موضوع خواهید بود.تغییر یافته در نسخهی 3.6: پشتیبانی از
mode='U'حذف شد. برای خواندن پروندههای متنی فشرده در حالت universal newlines ازio.TextIOWrapperاستفاده کنید.تغییر یافته در نسخهی 3.6: اکنون میتوان از
ZipFile.open()برای نوشتن پروندهها در بایگانی با گزینهmode='w'استفاده کرد.تغییر یافته در نسخهی 3.6: فراخوانی
open()بر روی یک ZipFile بسته باعث پرتاب یکValueErrorمیشود. پیش از این، یکRuntimeErrorپرتاب میشد.تغییر یافته در نسخهی 3.13: ویژگیهای
nameوmodeبرای شیء فایلماند قابل نوشتن اضافه شد. مقدار ویژگیmodeبرای شیء فایلماند قابل خواندن از'r'به'rb'تغییر کرد.
- ZipFile.extract(member, path=None, pwd=None)¶
یک عضو را از بایگانی به پوشه کاری فعلی استخراج کنید؛ member باید نام کامل آن یا یک شیء
ZipInfoباشد. اطلاعات پرونده آن تا حد ممکن بهدقت استخراج میشود. path پوشه متفاوتی را برای استخراج در آن مشخص میکند. member میتواند یک نام پرونده یا یک شیءZipInfoباشد. pwd رمز عبور استفادهشده برای پروندههای رمزگذاریشده بهصورت یک شیءbytesاست.مسیر نرمالشدهی ایجادشده (یک پوشه یا پرونده جدید) را برمیگرداند.
توجه
اگر نام پرونده یک عضو یک مسیر مطلق باشد، درایو/نقطه اشتراک UNC و اسلشها/بکاسلشهای ابتدایی حذف میشوند، برای مثال:
///foo/barدر یونیکس بهfoo/barتبدیل میشود وC:\foo\barدر ویندوز بهfoo\barتبدیل میشود. و تمام کامپوننتهای".."در نام پرونده یک عضو حذف میشوند، برای مثال:../../foo../../ba..rبهfoo../ba..rتبدیل میشود. در ویندوز، نویسههای غیرمجاز (:،<،>،|،"،?و*) با زیرخط (_) جایگزین میشوند.تغییر یافته در نسخهی 3.6: فراخوانی
extract()روی یک ZipFile بسته باعث پرتاب یکValueErrorمیشود. پیش از این، یکRuntimeErrorپرتاب میشد.تغییر یافته در نسخهی 3.6.2: پارامتر path یک path-like object را میپذیرد.
- ZipFile.extractall(path=None, members=None, pwd=None)¶
همهی اعضا را از بایگانی به پوشهی کاری جاری استخراج میکند. path پوشهی دیگری را برای استخراج مشخص میکند. members اختیاری است و باید زیرمجموعهای از فهرست بازگشتی
namelist()باشد. pwd گذرواژهی مورد استفاده برای پروندههای رمزگذاریشده، بهصورت یک شیءbytesاست.هشدار
هرگز بایگانیها را از منابع نامطمئن بدون بررسی پیشین استخراج نکنید. ممکن است پروندهها خارج از path ایجاد شوند، برای مثال، اعضایی که نام پرونده آنها مطلق است یا دارای اجزای ".." است. این ماژول تلاش میکند از آن جلوگیری کند. به نکته
extract()مراجعه کنید.تغییر یافته در نسخهی 3.6: فراخوانی
extractall()روی یک ZipFile بسته باعث پرتاب یکValueErrorمیشود. پیش از این، یکRuntimeErrorپرتاب میشد.تغییر یافته در نسخهی 3.6.2: پارامتر path یک path-like object را میپذیرد.
- ZipFile.printdir()¶
فهرست مطالب آرشیو را در
sys.stdoutچاپ میکند.
- ZipFile.setpassword(pwd)¶
pwd (یک شیء
bytes) را بهعنوان گذرواژه پیشفرض برای استخراج پروندههای رمزگذاریشده تنظیم کنید.
- ZipFile.read(name, pwd=None)¶
بایتهای پرونده name در بایگانی را برمیگرداند. name نام پرونده در بایگانی، یا یک شیء
ZipInfoاست. بایگانی باید برای خواندن یا افزودن باز باشد. pwd گذرواژه مورد استفاده برای پروندههای رمزگذاریشده بهصورت یک شیءbytesاست و در صورت مشخصشدن، گذرواژه پیشفرض تنظیمشده باsetpassword()را نادیده میگیرد. فراخوانیread()روی یک ZipFile که از روش فشردهسازی دیگری بهجزZIP_STORED،ZIP_DEFLATED،ZIP_BZIP2،ZIP_LZMAیاZIP_ZSTANDARDاستفاده میکند، موجب پرتابNotImplementedErrorمیشود. اگر ماژول فشردهسازی مربوطه در دسترس نباشد نیز یک خطا پرتاب خواهد شد.تغییر یافته در نسخهی 3.6: فراخوانی
read()بر روی یک ZipFile بسته، باعث پرتاب یکValueErrorمیشود. پیش از این، یکRuntimeErrorپرتاب میشد.
- ZipFile.testzip()¶
تمام پروندههای موجود در بایگانی را میخواند و CRCها و سرآیندهای پروندهها را بررسی میکند. نام اولین پرونده خراب را برمیگرداند، در غیر این صورت
Noneرا برمیگرداند.تغییر یافته در نسخهی 3.6: فراخوانی
testzip()روی یک ZipFile بسته باعث پرتاب یکValueErrorمیشود. پیشتر، یکRuntimeErrorپرتاب میشد.
- ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)¶
پروندهای با نام filename را در بایگانی بنویسید و نام بایگانی آن را arcname قرار دهید (بهطور پیشفرض، این مقدار با filename یکسان خواهد بود، اما حرف درایو و جداکنندههای مسیر آغازین از آن حذف میشوند). اگر داده شود، compress_type مقدار دادهشده برای پارامتر compression در سازنده را برای ورودی جدید بازنویسی میکند. بهطور مشابه، compresslevel نیز در صورت داده شدن، مقدار سازنده را بازنویسی میکند. بایگانی باید با حالت
'w'،'x'یا'a'باز باشد.توجه
استاندارد پرونده ZIP از نظر تاریخی کدگذاری فراداده را مشخص نمیکرد، اما برای تعاملپذیری بهشدت CP437 (کدگذاری IBM PC اصلی) را توصیه میکرد. نسخههای اخیر فقط اجازه استفاده از UTF-8 را میدهند. در این ماژول، اگر نام اعضا شامل نویسههای غیر ASCII باشد، برای نوشتن آنها بهطور خودکار از UTF-8 استفاده خواهد شد. نوشتن نام اعضا با هیچ کدگذاری دیگری غیر از ASCII یا UTF-8 امکانپذیر نیست.
توجه
نامهای بایگانی باید نسبت به ریشه بایگانی نسبی باشند، یعنی نباید با جداکنندهی مسیر شروع شوند.
توجه
اگر
arcname(یاfilename، اگرarcnameداده نشده باشد) حاوی بایت تهی باشد، نام پرونده در بایگانی در محل بایت تهی بریده خواهد شد.توجه
وجود یک اسلش (slash) در ابتدای نام پرونده ممکن است باز کردن بایگانی را در برخی برنامههای zip روی سیستمهای ویندوزی غیرممکن کند.
تغییر یافته در نسخهی 3.6: فراخوانی
write()روی یک ZipFile ایجادشده با حالت'r'یا یک ZipFile بستهشده، یکValueErrorرا پرتاب میکند. پیش از این، یکRuntimeErrorپرتاب میشد.
- ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)¶
یک پرونده را در بایگانی مینویسد. محتوا data است، که میتواند یک نمونه از
strیاbytesباشد؛ اگر یکstrباشد، ابتدا بهصورت UTF-8 کدگذاری میشود. zinfo_or_arcname یا نام پروندهای است که در بایگانی به آن داده خواهد شد، یا یک نمونه ازZipInfoاست. اگر یک نمونه باشد، حداقل باید نام پرونده، تاریخ و زمان داده شده باشند. اگر یک نام باشد، تاریخ و زمان به تاریخ و زمان جاری تنظیم میشود. بایگانی باید با حالت'w'،'x'یا'a'باز شده باشد.در صورت ارائه، compress_type بر مقداری که برای پارامتر compression به سازندهی ورودی جدید داده شده است، یا بر مقداری که در zinfo_or_arcname وجود دارد (اگر آن یک نمونه از
ZipInfoباشد) تقدم دارد. بهطور مشابه، compresslevel نیز در صورت ارائه، بر سازنده تقدم دارد.توجه
هنگامی که یک نمونه
ZipInfoرا بهعنوان پارامتر zinfo_or_arcname ارسال میکنید، روش فشردهسازی استفادهشده همان روشی خواهد بود که در ویژگی compress_type نمونهZipInfoدادهشده تعیین شده است. بهطور پیشفرض، سازندهیZipInfoاین ویژگی را رویZIP_STOREDتنظیم میکند.تغییر یافته در نسخهی 3.2: آرگومان compress_type.
تغییر یافته در نسخهی 3.6: فراخوانی
writestr()روی یک ZipFile ساختهشده با حالت'r'یا یک ZipFile بسته، یکValueErrorرا پرتاب میکند. پیش از این، یکRuntimeErrorپرتاب میشد.تغییر یافته در نسخهی 3.14: اکنون متغیر محیطی
SOURCE_DATE_EPOCHرا رعایت میکند. اگر تنظیم شده باشد، بهجای استفاده از زمان فعلی، از این مقدار بهعنوان برچسب زمانی تغییر برای پرونده نوشتهشده در آرشیو ZIP استفاده میکند.
- ZipFile.mkdir(zinfo_or_directory, mode=511)¶
یک پوشه درون بایگانی ایجاد کنید. اگر zinfo_or_directory یک رشته باشد، یک پوشه با حالت مشخصشده در آرگومان mode درون بایگانی ایجاد میشود. اما اگر zinfo_or_directory یک نمونه از
ZipInfoباشد، آرگومان mode نادیده گرفته میشود.بایگانی باید با حالت
'w'،'x'یا'a'باز شود.اضافه شده در نسخهی 3.11.
ویژگیهای داده زیر نیز در دسترس هستند:
- ZipFile.filename¶
نام پرونده ZIP.
- ZipFile.debug¶
سطح خروجی اشکالزدایی برای استفاده. این مقدار میتواند از
0(پیشفرض، بدون خروجی) تا3(بیشترین خروجی) تنظیم شود. اطلاعات اشکالزدایی درsys.stdoutنوشته میشود.
اشیای Path¶
- class zipfile.Path(root, at='')¶
یک شیء Path از یک پرونده فشردهی
rootبسازید (که ممکن است یک نمونهیZipFileیا یکfileمناسب برای ارسال به سازندهیZipFileباشد).atمحل این Path درون پرونده zip را مشخص میکند، برای مثال 'dir/file.txt'، 'dir/'، یا ''. پیشفرض آن رشتهی خالی است که ریشه را نشان میدهد.توجه
کلاس
Pathنام پروندههای درون بایگانی ZIP را پالایش نمیکند. برخلاف متدهایZipFile.extract()وZipFile.extractall()، مسئولیت اعتبارسنجی یا پالایش نام پروندهها برای پیشگیری از آسیبپذیریهای پیمایش مسیر (برای مثال، مسیرهای مطلق یا مسیرهای دارای اجزای "..") بر عهده فراخواننده است. هنگام کار با بایگانیهای غیرقابلاعتماد، در نظر داشته باشید که نام پروندهها را با استفاده ازos.path.abspath()حل کنید و آنها را باos.path.commonpath()نسبت به پوشه هدف بررسی کنید.
اشیای Path، قابلیتهای زیر اشیای pathlib.Path را در دسترس قرار میدهند:
اشیای Path با استفاده از عملگر / یا joinpath قابلپیمایش هستند.
- Path.name¶
آخرین کامپوننت مسیر.
- Path.open(mode='r', *, pwd, **)¶
ZipFile.open()را روی مسیر فعلی فراخوانی میکند. امکان باز کردن برای خواندن یا نوشتن، بهصورت متنی یا دودویی، از طریق حالتهای پشتیبانیشده: 'r'، 'w'، 'rb'، 'wb' را فراهم میکند. آرگومانهای جایگاهی و کلیدواژهای هنگام باز شدن بهصورت متنی، بهio.TextIOWrapperمنتقل میشوند و در غیر این صورت نادیده گرفته میشوند.pwdهمان پارامترpwdبرایZipFile.open()است.تغییر یافته در نسخهی 3.9: پشتیبانی از حالتهای متنی و دودویی برای open افزوده شد. حالت پیشفرض اکنون متنی است.
تغییر یافته در نسخهی 3.11.2: پارامتر
encodingرا میتوان بهعنوان یک آرگومان جایگاهی ارسال کرد، بدون آنکهTypeErrorایجاد شود؛ همانطور که در 3.9 امکانپذیر بود. کدی که باید با نسخههای وصلهنشده 3.10 و 3.11 سازگار باشد، باید تمام آرگومانهایio.TextIOWrapper، از جملهencoding، را بهصورت آرگومانهای کلیدواژهای ارسال کند.
- Path.iterdir()¶
فرزندان پوشه جاری را فهرست کنید.
- Path.is_dir()¶
اگر زمینهی فعلی به یک پوشه ارجاع دارد،
Trueرا برمیگرداند.
- Path.is_file()¶
اگر زمینهی فعلی به یک پرونده ارجاع داشته باشد،
Trueرا برمیگرداند.
- Path.is_symlink()¶
اگر زمینهی جاری به یک پیوند نمادین ارجاع داشته باشد،
Trueبرمیگرداند.اضافه شده در نسخهی 3.12.
تغییر یافته در نسخهی 3.13: پیشتر،
is_symlinkبدون هیچ شرطیFalseرا برمیگرداند.
- Path.exists()¶
اگر زمینه فعلی به یک پرونده یا پوشه در پرونده zip اشاره کند،
Trueرا برمیگرداند.
- Path.suffix¶
آخرین بخش جداشده با نقطه از آخرین کامپوننت، در صورت وجود. این بخش معمولاً پسوند پرونده نامیده میشود.
اضافه شده در نسخهی 3.11: ویژگی
Path.suffixافزوده شد.
- Path.suffixes¶
فهرستی از پسوندهای مسیر، که عموماً پسوندهای پرونده نامیده میشوند.
اضافه شده در نسخهی 3.11: ویژگی
Path.suffixesافزوده شد.
- Path.read_text(*, **)¶
پرونده جاری را بهعنوان متن یونیکد بخوانید. آرگومانهای جایگاهی و کلیدواژهای به
io.TextIOWrapperارسال میشوند (بهجزbuffer، که بهطور ضمنی از زمینه گرفته میشود).تغییر یافته در نسخهی 3.11.2: پارامتر
encodingرا میتوان بهعنوان یک آرگومان جایگاهی ارسال کرد، بدون آنکهTypeErrorایجاد شود؛ همانطور که در 3.9 امکانپذیر بود. کدی که باید با نسخههای وصلهنشده 3.10 و 3.11 سازگار باشد، باید تمام آرگومانهایio.TextIOWrapper، از جملهencoding، را بهصورت آرگومانهای کلیدواژهای ارسال کند.
- Path.read_bytes()¶
پرونده جاری را بهصورت بایت میخواند.
- Path.joinpath(*other)¶
یک شیء Path جدید برمیگرداند که هر یک از آرگومانهای other به آن الحاق شدهاند. موارد زیر معادل هستند:
>>> Path(...).joinpath('child').joinpath('grandchild') >>> Path(...).joinpath('child', 'grandchild') >>> Path(...) / 'child' / 'grandchild'
تغییر یافته در نسخهی 3.10: پیش از 3.10،
joinpathمستندنشده بود و دقیقاً یک پارامتر میپذیرفت.
پروژهی zipp بکپورتهایی (backports) از جدیدترین قابلیتهای شیء مسیر را برای نسخههای قدیمیتر پایتون فراهم میکند. برای دسترسی زودهنگام به تغییرات، از zipp.Path بهجای zipfile.Path استفاده کنید.
اشیای PyZipFile¶
سازندهی PyZipFile همان پارامترهای سازندهی ZipFile را بههمراه یک پارامتر اضافی، optimize، میپذیرد.
- class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)¶
تغییر یافته در نسخهی 3.2: پارامتر optimize اضافه شد.
تغییر یافته در نسخهی 3.4: افزونههای ZIP64 بهطور پیشفرض فعال هستند.
نمونهها یک متد علاوه بر متدهای اشیاء
ZipFileدارند:- writepy(pathname, basename='', filterfunc=None)¶
پروندههای
*.pyرا جستجو کنید و پرونده متناظر را به بایگانی اضافه کنید.اگر پارامتر optimize برای
PyZipFileداده نشود یا-1باشد، پرونده متناظر یک پرونده*.pycاست و در صورت لزوم کامپایل میشود.اگر پارامتر optimize برای
PyZipFileبرابر0،1یا2باشد، فقط پروندههای دارای آن سطح بهینهسازی (بهcompile()مراجعه کنید) به آرشیو افزوده میشوند و در صورت لزوم کامپایل میشوند.اگر pathname یک پرونده باشد، نام پرونده باید به
.pyختم شود، و تنها پرونده متناظر (*.pyc) در سطح بالایی اضافه میشود (بدون اطلاعات مسیر). اگر pathname پروندهای باشد که پسوند.pyندارد، یکRuntimeErrorپرتاب خواهد شد. اگر یک پوشه باشد، و پوشه، پوشهی بسته نباشد، آنگاه تمام پروندههای*.pycدر سطح بالایی اضافه میشوند. اگر پوشه، پوشهی بسته باشد، آنگاه تمام*.pycزیر نام بسته بهعنوان یک مسیر پرونده اضافه میشوند، و اگر هر یک از زیرپوشهها پوشهی بسته باشند، تمام اینها بهصورت بازگشتی به ترتیب مرتبشده اضافه میشوند.basename تنها برای استفادهی داخلی در نظر گرفته شده است.
filterfunc، در صورت داده شدن، باید تابعی باشد که تنها یک آرگومان رشتهای میپذیرد. هر مسیر (از جمله هر مسیر کامل پرونده بهصورت جداگانه) پیش از آنکه به آرشیو افزوده شود، به این تابع داده میشود. اگر filterfunc یک مقدار نادرست برگرداند، مسیر به آرشیو اضافه نخواهد شد، و اگر یک پوشه باشد، محتویات آن نادیده گرفته میشود. برای مثال، اگر همه پروندههای آزمایشی ما یا در پوشههای
testقرار دارند یا با رشتهtest_شروع میشوند، میتوانیم از یک filterfunc برای مستثنی کردن آنها استفاده کنیم:>>> zf = PyZipFile('myprog.zip') >>> def notests(s): ... fn = os.path.basename(s) ... return (not (fn == 'test' or fn.startswith('test_'))) ... >>> zf.writepy('myprog', filterfunc=notests)
متد
writepy()بایگانیهایی با نام پروندههایی مانند این میسازد:string.pyc # Top level name test/__init__.pyc # Package directory test/testall.pyc # Module test.testall test/bogus/__init__.pyc # Subpackage directory test/bogus/myfile.pyc # Submodule test.bogus.myfile
تغییر یافته در نسخهی 3.4: پارامتر filterfunc افزوده شد.
تغییر یافته در نسخهی 3.6.2: پارامتر pathname یک شیء شبهمسیر را میپذیرد.
تغییر یافته در نسخهی 3.7: بازگشت، ورودیهای پوشه را مرتب میکند.
اشیای ZipInfo¶
نمونههای کلاس ZipInfo توسط متدهای getinfo() و infolist() از اشیاء ZipFile بازگردانده میشوند. هر شیء اطلاعات مربوط به یک عضو واحد از بایگانی ZIP را ذخیره میکند.
یک classmethod (classmethod) برای ایجاد یک نمونه ZipInfo برای یک پرونده در سامانه فایلبندی وجود دارد:
- classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)¶
یک نمونه
ZipInfoبرای یک پرونده در سامانه فایلبندی بسازید، تا برای افزودن آن به یک پرونده zip آماده شوید.filename باید مسیر یک پرونده یا پوشه در سامانه فایلبندی باشد.
اگر arcname مشخص شده باشد، از آن بهعنوان نام درون بایگانی استفاده میشود. اگر arcname مشخص نشده باشد، نام همان filename خواهد بود، اما هر حرف درایو و جداکنندههای آغازین مسیر از آن حذف میشوند.
آرگومان strict_timestamps، هنگامی که روی
Falseتنظیم شود، امکان زیپ کردن پروندههای قدیمیتر از ۱۹۸۰-۰۱-۰۱ را به بهای تنظیم مهر زمانی روی ۱۹۸۰-۰۱-۰۱ فراهم میکند. رفتار مشابهی برای پروندههای جدیدتر از ۲۱۰۷-۱۲-۳۱ رخ میدهد؛ مهر زمانی نیز روی همان حد تنظیم میشود.اضافه شده در نسخهی 3.6.
تغییر یافته در نسخهی 3.6.2: پارامتر filename یک path-like object را میپذیرد.
تغییر یافته در نسخهی 3.8: پارامتر فقط کلیدواژهای strict_timestamps اضافه شد.
نمونهها دارای متدها و ویژگیهای زیر هستند:
- ZipInfo.is_dir()¶
اگر این عضو آرشیو یک پوشه باشد،
Trueرا برمیگرداند.این از نام ورودی استفاده میکند: پوشهها باید همیشه با
/پایان یابند.اضافه شده در نسخهی 3.6.
- ZipInfo.filename¶
نام پرونده در بایگانی.
- ZipInfo.date_time¶
زمان و تاریخ آخرین تغییر عضو آرشیو. این یک تاپل از شش مقدار است که فیلدهای «last [modified] file time» و «last [modified] file date» را از فهرست مرکزی پرونده ZIP نشان میدهد.
این تاپل شامل موارد زیر است:
اندیس
مقدار
0سال (>= ۱۹۸۰)
1ماه (یکپایه)
2روز ماه (یکمبنا)
3ساعتها (بر پایه صفر)
4دقیقهها (صفرپایه)
5ثانیهها (صفرپایه)
توجه
قالب ZIP از چندین فیلد برچسب زمانی در مکانهای مختلف (پوشه مرکزی، فیلدهای اضافی برای سیستمهای NTFS/UNIX و غیره) پشتیبانی میکند. این ویژگی بهطور مشخص برچسب زمانی را از پوشه مرکزی برمیگرداند. قالب برچسب زمانی پوشه مرکزی در پروندههای ZIP از برچسبهای زمانی پیش از ۱۹۸۰ پشتیبانی نمیکند. اگرچه برخی قالبهای فیلد اضافی (مانند برچسبهای زمانی UNIX) میتوانند تاریخهای قدیمیتر را نمایش دهند، این ویژگی فقط برچسب زمانی پوشه مرکزی را برمیگرداند.
برچسب زمانی پوشهی مرکزی (central directory) بهعنوان زمان محلی تفسیر میشود، نه زمان UTC، تا با رفتار سایر ابزارهای zip مطابقت داشته باشد.
- ZipInfo.compress_type¶
نوع فشردهسازی برای عضو بایگانی.
- ZipInfo.extra¶
دادههای فیلد توسعه (Expansion field). سند PKZIP Application Note شامل برخی کامنتها دربارهی ساختار داخلی دادههای موجود در این شیء
bytesاست.
- ZipInfo.create_system¶
سامانهای که بایگانی ZIP را ایجاد کرده است.
- ZipInfo.create_version¶
نسخهی PKZIP که آرشیو ZIP را ایجاد کرده است.
- ZipInfo.extract_version¶
نسخهی PKZIP موردنیاز برای استخراج بایگانی.
- ZipInfo.reserved¶
باید صفر باشد.
- ZipInfo.flag_bits¶
بیتهای پرچم ZIP.
- ZipInfo.volume¶
شمارهی جلد سرآیند پرونده.
- ZipInfo.internal_attr¶
ویژگیهای داخلی.
- ZipInfo.external_attr¶
ویژگیهای خارجی پرونده.
- ZipInfo.header_offset¶
آفست بر حسب بایت تا سرآیند پرونده.
- ZipInfo.CRC¶
CRC-32 پرونده فشردهنشده.
- ZipInfo.compress_size¶
اندازهی دادهی فشرده.
- ZipInfo.file_size¶
اندازهی پرونده فشردهنشده.
رابط خط فرمان¶
ماژول zipfile یک رابط خط فرمان ساده برای تعامل با بایگانیهای ZIP فراهم میکند.
اگر میخواهید یک بایگانی ZIP جدید ایجاد کنید، نام آن را پس از گزینه -c مشخص کنید و سپس نام پروندههایی را که باید گنجانده شوند فهرست کنید:
$ python -m zipfile -c monty.zip spam.txt eggs.txt
ارسال یک پوشه نیز قابلقبول است:
$ python -m zipfile -c monty.zip life-of-brian_1979/
اگر میخواهید یک آرشیو ZIP را در پوشهی مشخصشده استخراج کنید، از گزینهی -e استفاده کنید:
$ python -m zipfile -e monty.zip target-dir/
برای فهرست پروندههای یک آرشیو ZIP، از گزینه -l استفاده کنید:
$ python -m zipfile -l monty.zip
گزینههای خط فرمان¶
- -c <zipfile> <source1> ... <sourceN>¶
- --create <zipfile> <source1> ... <sourceN>¶
ایجاد پرونده زیپ از پروندههای منبع.
دامهای واگشایی¶
استخراج در ماژول zipfile ممکن است به دلیل برخی دامهای فهرستشده در زیر با شکست مواجه شود.
از خود پرونده¶
ممکن است واگشایی به دلیل گذرواژه / جمعآزما (CRC checksum) / قالب ZIP نادرست یا روش فشردهسازی / رمزگشایی پشتیبانینشده ناموفق باشد.
محدودیتهای سامانه فایلبندی¶
فراتر رفتن از محدودیتها در سیستمهای پرونده مختلف میتواند باعث شکست در واگشایی شود؛ برای نمونه، نویسههای مجاز در ورودیهای پوشه، طول نام پرونده، طول مسیر، اندازهی یک پرونده، و تعداد پروندهها و غیره.
محدودیتهای منابع¶
کمبود حافظه یا حجم دیسک منجر به شکست در واگشایی میشود. برای مثال، بمبهای واگشایی (معروف به ZIP bomb) میتوانند در مورد کتابخانهی zipfile صدق کنند و باعث اتمام حجم دیسک شوند.
وقفه¶
وقفه در حین واگشایی، مانند فشار دادن control-C یا کشتن فرایند واگشایی، ممکن است منجر به واگشایی ناقص آرشیو شود.
رفتارهای پیشفرض استخراج¶
ندانستن رفتارهای پیشفرض استخراج میتواند باعث نتایج غیرمنتظرهی واگشایی شود. برای مثال، هنگامی که یک بایگانی را دو بار استخراج میکنید، پروندهها بدون پرسش بازنویسی میشوند.