الصنف ZipFile()‎‎ في بايثون

تفتح هذه الدالة البانية للصنف ZipFile ملف ZIP المعطى.

البنية العامة

zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None)

‎المعاملات

‎file

الملف المراد فتحه بواسطة الدالة. يمكن أن يكون مسار الملف المطلوب (سلسلة نصية) أو كائنًا شبيهًا بالملفات file-like object أو كائنًا شبيهًا بالمسارات path-like object.

mode

يأخذ هذا المعامل إحدى القيم (الأوضاع) التالية:

'r' لقراءة ملف موجود فعلًا، أو 'w' لحذف أطراف الملف truncate والكتابة في ملف جديد، أو 'a' لإلحاق البيانات في ملف موجود فعلًا، أو 'x' لإنشاء ملف جديد والكتابة فيه. إن استخدمت القيمة 'x' وأشار المعامل file إلى ملف موجود فعلًا، فإنّ اللغة تطلق الاستثناء FileExistsError.

إن استخدم الوضع 'a' وأشار المعامل file إلى ملف ZIP موجود فعلًا، فإنّ الملفات الإضافة ستضاف إلى هذا الأرشيف، أما إن لم يشر المعامل إلى ملف ZIP فستُلحق الدالة ملف ZIP جديد إلى ذلك الملف، ويمكن استخدام هذه الطريقة لإضافة ملفات ZIP إلى ملفات أخرى (مثل python.exe).

إن استخدم الوضع 'a' وكان الملف المشار إليه في المعامل file غير موجود على الإطلاق، فإنّ الدالة ستنشئ ذلك الملف.

يجب أن يكون الملف المعطى قابلًا للبحث فيه seekable عند استخدام الوضع 'r' أو 'a'.

compression

طريقة ضغط ZIP المستخدمة عند كتابة الملفات إلى الأرشيف، وتأخذ إحدى القيم: ZIP_STORED، أو ZIP_DEFLATED، أو ZIP_BZIP2 أو ZIP_LZMA، أما القيم غير المعرّفة فستؤدي إلى إطلاق الاستثناء NotImplementedError. إن استخدمت القيمة ZIP_DEFLATED أو ZIP_BZIP2 أو ZIP_LZMA ولكن كانت الوحدة المقابلة (zlib أو bz2 أو lzma) غير متوفّرة، تطلق اللغة الاستثناء RuntimeError. القيمة الافتراضية لهذا المعامل هي ZIP_STORED.

allowZip64

إن كانت قيمة هذا المعامل هي True (وهي القيمة الافتراضية) فإن الوحدة zipfile ستُنشئ ملفات ZIP باستخدام الإضافة ZIP64 عندما يتجاوز حجم الملف ‎4 GiB. أما إن كانت قيمة هذا المعامل هي False تُطلق اللغة استثناء عندما يصل ملف ZIP إلى المرحلة التي يحتاج فيها إلى الإضافة ZIP64.

compresslevel

يتحكّم هذا المعامل بمستوى الضغط المستخدم في إضافة الملفات إلى أرشيف ZIP. لا تأثير لهذا المعامل عندما تكون قيمة المعامل compression هي ZIP_STORED أو ZIP_LZMA. عند استخدام القيمة ZIP_DEFLATED للمعامل compression يكون المعامل compresslevel عددًا صحيحًا يتدرّج من 0 إلى 9 (راجع وحدة zlib للمزيد من المعلومات). وعند استخدام القيمة ZIP_BZIP2 للمعامل compression يكون المعامل compresslevel عددًا صحيحًا يتدرّج من 0 إلى 9 (راجع وحدة bz2 للمزيد من المعلومات).

إن أنشئ ملف الأرشيف باستخدام أحد الأوضاع 'w' أو 'x' أو 'a' ثم إغلق الأرشيف دون إضافة أي ملفات إليه فسيجري كتابة بنية ZIP المناسبة لملفات الأرشيف الفارغة في ذلك الأرشيف.

يمكن استخدام كائنات ZipFile كمدير للسياق وهذا يعني إمكانية استخدامها مع عبارات with. في المثال التالي يُغلق الملف myzip بعد إنتهاء عمل العبارة with حتى لو حدث أي استثناء:

with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')

ملاحظات:

• أضيفت قابلية استخدام كائن ZipFile كمدير للسياق في الإصدار 3.2 من بايثون.
• أضيف دعم الضغط بخوارزميتي bzip2 و lzma في الإصدار 3.3 من بايثون.
• أصبحت الإضافات ZIP64 مفعّلة تلقائيًا.
• أضيف دعم الكتابة في تدفّقات البيانات التي لا يمكن البحث فيها unseekable، وكذلك أضيف دعم الوضع 'x'.
• قبل الإصدار 3.6 من بايثون كانت اللغة تطلق استثناءً RuntimeError مع قيم المعامل compression غير المعرّفة.
• أصبح المعامل file يستقبل كائنات شبيهة بالمسارات في الإصدار 3.6.2 من بايثون.
• أضيف المعامل compresslevel في الإصدار 3.7 من بايثون.

أمثلة

يبين المثال التالي طريقة إنشاء كائن ZipFile يدعم الكتابة:

>>> import zipfile
>>> zip = zipfile.ZipFile('files.zip', 'w')
>>> print(zip)
<zipfile.ZipFile filename='files.zip' mode='w'>

انظر أيضًا

• الصنف PyZipFile: يستخدم هذا الصنف لإنشاء ملفات ZIP تتضمّن مكتبات بايثون.
• الصنف ZipInfo: يستخدم هذا الصنف لعرض المعلومات الخاصّة بعضو من أعضاء ملف الأرشيف. 

مصادر

• صفحة Work with ZIP archives في توثيق بايثون الرسمي.