اشیای 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.3: پشتیبانی از فشرده‌سازی bzip2 و lzma افزوده شد.

تغییر یافته در نسخه‌ی 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 نوشته می‌شود.

ZipFile.comment¶

کامنت مرتبط با پرونده ZIP به‌عنوان یک شیء bytes. اگر به یک نمونه‌ی ZipFile ایجادشده با حالت 'w'، 'x' یا 'a' توضیحی اختصاص می‌دهید، نباید طول آن بیشتر از ۶۵۵۳۵ بایت باشد. کامنت‌های طولانی‌تر از این مقدار کوتاه خواهند شد.

اشیای 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.stem¶

آخرین کامپوننت مسیر، بدون پسوند آن.

اضافه شده در نسخه‌ی 3.11: ویژگی Path.stem افزوده شد.

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.comment¶

کامنت برای عضو منفرد آرشیو به‌صورت یک شیء bytes.

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

دام‌های واگشایی¶

استخراج در ماژول zipfile ممکن است به دلیل برخی دام‌های فهرست‌شده در زیر با شکست مواجه شود.