الفرق بين المراجعتين لصفحة: «Python/ZipFile»

مراجعة 19:19، 15 نوفمبر 2018

تفتح هذه الدالة البانية للصنف 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 في توثيق بايثون الرسمي.

@@ سطر 1: / سطر 1: @@
 <noinclude>{{DISPLAYTITLE:الصنف <code>ZipFile()‎‎</code> في بايثون}}</noinclude>
-تفتح هذه الدالة البانية للصنف ZipFile ملف ZIP المعطى.
+تفتح هذه الدالة البانية للصنف <code>ZipFile</code> ملف ZIP المعطى.
 == البنية العامة ==
@@ سطر 8: / سطر 8: @@
 zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None)
 </syntaxhighlight>
-‎
-== المعاملات ==
-=== ‎file ===
-الملف المراد فتحه بواسطة الدالة. يمكن أن يكون مسار الملف المطلوب (سلسلة نصية) أو كائنًا شبيهًا بالملفات file-like object أو كائنًا شبيهًا بالمسارات path-like object.
-=== mode ===
+== ‎المعاملات ==
+=== ‎<code>file</code> ===
+الملف المراد فتحه بواسطة الدالة. يمكن أن يكون مسار الملف المطلوب ([[Python/str|سلسلة نصية]]) أو كائنًا شبيهًا بالملفات file-like object أو كائنًا شبيهًا بالمسارات path-like object.
+=== <code>mode</code> ===
 يأخذ هذا المعامل إحدى القيم (الأوضاع) التالية:
-'r' لقراءة ملف موجود فعلًا، أو 'w' لحذف أطراف الملف truncate والكتابة في ملف جديد، أو 'a' لإلحاق البيانات في ملف موجود فعلًا، أو 'x' لإنشاء ملف جديد والكتابة فيه. إن استخدمت القيمة 'x' وأشار المعامل file إلى ملف موجود فعلًا، فإنّ اللغة تطلق الاستثناء FileExistsError.
-إن استخدم الوضع 'a' وأشار المعامل file إلى ملف ZIP موجود فعلًا، فإنّ الملفات الإضافة ستضاف إلى هذا الأرشيف، أما إن لم يشر المعامل إلى ملف ZIP فستُلحق الدالة ملف ZIP جديد إلى ذلك الملف، ويمكن استخدام هذه الطريقة لإضافة ملفات ZIP إلى ملفات أخرى (مثل python.exe).
+<code>'r'</code> لقراءة ملف موجود فعلًا، أو <code>'w'</code> لحذف أطراف الملف truncate والكتابة في ملف جديد، أو <code>'a'</code> لإلحاق البيانات في ملف موجود فعلًا، أو <code>'x'</code> لإنشاء ملف جديد والكتابة فيه. إن استخدمت القيمة <code>'x'</code> وأشار المعامل <code>file</code> إلى ملف موجود فعلًا، فإنّ اللغة تطلق الاستثناء <code>FileExistsError</code>.
+إن استخدم الوضع <code>'a'</code> وأشار المعامل <code>file</code> إلى ملف ZIP موجود فعلًا، فإنّ الملفات الإضافة ستضاف إلى هذا الأرشيف، أما إن لم يشر المعامل إلى ملف ZIP فستُلحق الدالة ملف ZIP جديد إلى ذلك الملف، ويمكن استخدام هذه الطريقة لإضافة ملفات ZIP إلى ملفات أخرى (مثل python.exe).
-إن استخدم الوضع 'a' وكان الملف المشار إليه في المعامل file غير موجود على الإطلاق، فإنّ الدالة ستنشئ ذلك الملف.
+إن استخدم الوضع <code>'a'</code> وكان الملف المشار إليه في المعامل <code>file</code> غير موجود على الإطلاق، فإنّ الدالة ستنشئ ذلك الملف.
-يجب أن يكون الملف المعطى قابلًا للبحث فيه seekable عند استخدام الوضع 'r' أو 'a'.
+يجب أن يكون الملف المعطى قابلًا للبحث فيه seekable عند استخدام الوضع <code>'r'</code> أو <code>'a'</code>.
-=== compression ===
+=== <code>compression</code> ===
-طريقة ضغط ZIP المستخدمة عند كتابة الملفات إلى الأرشيف، وتأخذ إحدى القيم: ZIP_STORED، أو ZIP_DEFLATED، أو ZIP_BZIP2 أو ZIP_LZMA، أما القيم غير المعرّفة فستؤدي إلى إطلاق الاستثناء NotImplementedError. إن استخدمت القيمة ZIP_DEFLATED أو ZIP_BZIP2 أو ZIP_LZMA ولكن كانت الوحدة المقابلة (zlib أو bz2 أو lzma) غير متوفّرة، تطلق اللغة الاستثناء RuntimeError. القيمة الافتراضية لهذا المعامل هي ZIP_STORED.
+طريقة ضغط ZIP المستخدمة عند كتابة الملفات إلى الأرشيف، وتأخذ إحدى القيم: <code>ZIP_STORED</code>، أو <code>ZIP_DEFLATED</code>، أو <code>ZIP_BZIP2</code> أو <code>ZIP_LZMA</code>، أما القيم غير المعرّفة فستؤدي إلى إطلاق الاستثناء <code>NotImplementedError</code>. إن استخدمت القيمة <code>ZIP_DEFLATED</code> أو <code>ZIP_BZIP2</code> أو <code>ZIP_LZMA</code> ولكن كانت الوحدة المقابلة (<code>[[Python/zlib|zlib]]</code> أو <code>[[Python/bz2|bz2]]</code> أو <code>[[Python/lzma|lzma]]</code>) غير متوفّرة، تطلق اللغة الاستثناء <code>RuntimeError</code>. القيمة الافتراضية لهذا المعامل هي <code>ZIP_STORED</code>.
-=== allowZip64 ===
+=== <code>allowZip64</code> ===
-إن كانت قيمة هذا المعامل هي True (وهي القيمة الافتراضية) فإن الوحدة zipfile ستُنشئ ملفات ZIP باستخدام الإضافة ZIP64 عندما يتجاوز حجم الملف ‎4 GiB. أما إن كانت قيمة هذا المعامل هي False تُطلق اللغة استثناء عندما يصل ملف ZIP إلى المرحلة التي يحتاج فيها إلى الإضافة ZIP64.
+إن كانت قيمة هذا المعامل هي <code>True</code> (وهي القيمة الافتراضية) فإن الوحدة <code>zipfile</code> ستُنشئ ملفات ZIP باستخدام الإضافة ZIP64 عندما يتجاوز حجم الملف ‎<code>4 GiB</code>. أما إن كانت قيمة هذا المعامل هي <code>False</code> تُطلق اللغة استثناء عندما يصل ملف ZIP إلى المرحلة التي يحتاج فيها إلى الإضافة ZIP64.
-=== compresslevel ===
+=== <code>compresslevel</code> ===
-يتحكّم هذا المعامل بمستوى الضغط المستخدم في إضافة الملفات إلى أرشيف ZIP. لا تأثير لهذا المعامل عندما تكون قيمة المعامل compression هي ZIP_STORED أو ZIP_LZMA. عند استخدام القيمة ZIP_DEFLATED للمعامل compression يكون المعامل compresslevel عددًا صحيحًا يتدرّج من 0 إلى 9 (راجع وحدة zlib للمزيد من المعلومات). وعند استخدام القيمة ZIP_BZIP2 للمعامل compression يكون المعامل compresslevel عددًا صحيحًا يتدرّج من 0 إلى 9 (راجع وحدة bz2 للمزيد من المعلومات).
+يتحكّم هذا المعامل بمستوى الضغط المستخدم في إضافة الملفات إلى أرشيف ZIP. لا تأثير لهذا المعامل عندما تكون قيمة المعامل <code>compression</code> هي <code>ZIP_STORED</code> أو <code>ZIP_LZMA</code>. عند استخدام القيمة <code>ZIP_DEFLATED</code> للمعامل <code>compression</code> يكون المعامل <code>compresslevel</code> عددًا صحيحًا يتدرّج من <code>0</code> إلى <code>9</code> (راجع [[Python/zlib|وحدة <code>zlib</code>]] للمزيد من المعلومات). وعند استخدام القيمة <code>ZIP_BZIP2</code> للمعامل <code>compression</code> يكون المعامل <code>compresslevel</code> عددًا صحيحًا يتدرّج من <code>0</code> إلى <code>9</code> (راجع [[Python/bz2|وحدة <code>bz2</code>]] للمزيد من المعلومات).
-إن أنشئ ملف الأرشيف باستخدام أحد الأوضاع 'w' أو 'x' أو 'a' ثم إغلق الأرشيف دون إضافة أي ملفات إليه فسيجري كتابة بنية ZIP المناسبة لملفات الأرشيف الفارغة في ذلك الأرشيف.
+إن أنشئ ملف الأرشيف باستخدام أحد الأوضاع <code>'w'</code> أو <code>'x'</code> أو <code>'a'</code> ثم إغلق الأرشيف دون إضافة أي ملفات إليه فسيجري كتابة بنية ZIP المناسبة لملفات الأرشيف الفارغة في ذلك الأرشيف.
-يمكن استخدام كائنات ZipFile كمدير للسياق وهذا يعني إمكانية استخدامها مع عبارات with.  في المثال التالي يُغلق الملف myzip بعد إنتهاء عمل العبارة with حتى لو حدث أي استثناء:
+يمكن استخدام كائنات <code>ZipFile</code> كمدير للسياق وهذا يعني إمكانية استخدامها مع عبارات <code>with</code>.  في المثال التالي يُغلق الملف <code>myzip</code> بعد إنتهاء عمل العبارة <code>with</code> حتى لو حدث أي استثناء:
 <syntaxhighlight lang="python3">
@@ سطر 43: / سطر 45: @@
 '''ملاحظات:'''
-* أضيفت قابلية استخدام كائن ZipFile كمدير للسياق في الإصدار 3.2 من بايثون.
+* أضيفت قابلية استخدام كائن <code>ZipFile</code> كمدير للسياق في الإصدار 3.2 من بايثون.
-* أضيف دعم الضغط بخوارزميتي bzip2 و lzma في الإصدار 3.3 من بايثون.
+* أضيف دعم الضغط بخوارزميتي <code>bzip2</code> و <code>lzma</code> في الإصدار 3.3 من بايثون.
 * أصبحت الإضافات ZIP64 مفعّلة تلقائيًا.
-* أضيف دعم الكتابة في تدفّقات البيانات التي لا يمكن البحث فيها unseekable، وكذلك أضيف دعم الوضع 'x'.
+* أضيف دعم الكتابة في تدفّقات البيانات التي لا يمكن البحث فيها <code>unseekable</code>، وكذلك أضيف دعم الوضع <code>'x'</code>.
-* قبل الإصدار 3.6 من بايثون كانت اللغة تطلق استثناءً RuntimeError مع قيم المعامل compression غير المعرّفة.
+* قبل الإصدار 3.6 من بايثون كانت اللغة تطلق استثناءً <code>RuntimeError</code> مع قيم المعامل <code>compression</code> غير المعرّفة.
-* أصبح المعامل file يستقبل كائنات شبيهة بالمسارات في الإصدار 3.6.2 من بايثون.
+* أصبح المعامل <code>file</code> يستقبل كائنات شبيهة بالمسارات في الإصدار 3.6.2 من بايثون.
-* أضيف المعامل compresslevel في الإصدار 3.7 من بايثون.
+* أضيف المعامل <code>compresslevel</code> في الإصدار 3.7 من بايثون.
 == أمثلة ==
-يبين المثال التالي طريقة إنشاء كائن ZipFile يدعم الكتابة:
+يبين المثال التالي طريقة إنشاء كائن <code>ZipFile</code> يدعم الكتابة:
 <syntaxhighlight lang="python3">
@@ سطر 64: / سطر 66: @@
 == انظر أيضًا ==
-* كائنات PyZipFile:
+* الصنف <code>[[Python/PyZipFile|PyZipFile]]</code>: يستخدم هذا الصنف لإنشاء ملفات ZIP تتضمّن مكتبات بايثون.
-* كائنات ZipInfo:
+* الصنف <code>[[Python/ZipInfo|ZipInfo]]</code>: يستخدم هذا الصنف لعرض المعلومات الخاصّة بعضو من أعضاء ملف الأرشيف.
 == مصادر ==
-[https://docs.python.org/3/library/zipfile.html#zipfile.ZipFile صفحة Work with ZIP archives في توثيق بايثون الرسمي.]
+* [https://docs.python.org/3/library/zipfile.html#zipfile.ZipFile صفحة Work with ZIP archives في توثيق بايثون الرسمي.]
 [[تصنيف:Python]]
 [[تصنيف:Python Modules]]