الصنف 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
تقدّم كائنات ZipFile الخصائص التالية:
ZipFile.filename
اسم ملف ZIP.
ZipFile.debug
مستوى مخرجات التنقيح. تتدرّج القيمة التي يمكن تعيينها لهذه الخاصية من 0 (القيمة الافتراضية، لا مخرجات) إلى 3 (عرض المخرجات كاملة). تُكتب معلومات التنقيح إلى مخرجات النظام القياسية sys.stdout.
ZipFile.comment
نص التعليق المرافق لملف ZIP. يجب أن يكون التعليق المراد إرفاقه بملف ZIP سلسلة نصية لا يتجاوز طولها 65535 بايت إن كانت نسخة الصنف ZipFile قد أُنشئت في الوضع 'w' أو 'x' أو 'a'، وإن كان التعليق أطول من هذا المقدار فإنّه سيقتطع عند إضافته إلى ملف الأرشيف لدى استدعاء التابع close().
توابع الصنف ZipFile
التابع ZipFile.close()
يغلق التابع ملف الأرشيف.
التابع ZipFile.getinfo()
يعيد التابع كائن ZipFile مع معلومات حول عضو الأرشيف المعطى.
التابع ZipFile.infolist()
يعيد التابع قائمة تتضمّن كائن ZipFile لكل عضو من أعضاء الأرشيف.
التابع ZipFile.namelist()
يعيد التابع قائمة بأسماء الأعضاء في ملف الأرشيف.
التابع ZipFile.open()
يتيح التابع الوصول إلى عضو في الأرشيف ككائن ثنائي شبيه بالملفات.
التابع ZipFile.extract()
يستخرج التابع الملف العضو المعطى من الأرشيف إلى المجلد الحالي.
التابع ZipFile.extractall()
يستخرج التابع جميع الأعضاء في ملف الأرشيف إلى المجلد الحالي.
التابع ZipFile.printdir()
يطبع التابع جدولًا بمحتويات ملف الأرشيف إلى مخرجات النظام القياسية sys.stdout.
التابع ZipFile.setpassword()
يعيّن التابع كلمة المرور المعطاة ككلمة المرور الافتراضية لاستخراج الملفات المعمّاة من الأرشيف.
التابع ZipFile.read()
يعيد التابع البايتات التابعة للملف المعطى في الأرشيف.
التابع ZipFile.testzip()
يقرأ التابع جميع الملفات في الأرشيف ويفحص ترويساتها وCRC الخاصة بها.
التابع ZipFile.write()
يكتب التابع الملف المعطى في ملف الأرشيف.
التابع ZipFile.writestr()
يكتب التابع البيانات النصية المعطاة في الأرشيف.
أمثلة
يبين المثال التالي طريقة إنشاء كائن ZipFile يدعم الكتابة:
>>> import zipfile
>>> zip = zipfile.ZipFile('files.zip', 'w')
>>> print(zip)
<zipfile.ZipFile filename='files.zip' mode='w'>
انظر أيضًا
- الصنف
PyZipFile: يستخدم هذا الصنف لإنشاء ملفات ZIP تتضمّن مكتبات بايثون. - الصنف
ZipInfo: يستخدم هذا الصنف لعرض المعلومات الخاصّة بعضو من أعضاء ملف الأرشيف.