الفرق بين المراجعتين لصفحة: «Python/ZipFile»
أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الصنف <code>ZipFile()</code> في بايثون}}</noinclude> تفتح هذه الدالة البانية للصنف ZipFile ملف...' |
طلا ملخص تعديل |
||
(4 مراجعات متوسطة بواسطة مستخدم واحد آخر غير معروضة) | |||
سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:الصنف <code>ZipFile()</code> في بايثون}}</noinclude> | <noinclude>{{DISPLAYTITLE:الصنف <code>ZipFile()</code> في بايثون}}</noinclude> | ||
تفتح هذه الدالة البانية للصنف <code>ZipFile</code> ملف ZIP المعطى. | |||
تفتح هذه الدالة البانية للصنف ZipFile ملف ZIP المعطى. | |||
== البنية العامة == | == البنية العامة == | ||
سطر 8: | سطر 7: | ||
zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None) | zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== mode === | == المعاملات == | ||
=== <code>file</code> === | |||
الملف المراد فتحه بواسطة الدالة. يمكن أن يكون مسار الملف المطلوب ([[Python/str|سلسلة نصية]]) أو كائنًا شبيهًا بالملفات file-like object أو كائنًا شبيهًا بالمسارات path-like object. | |||
=== <code>mode</code> === | |||
يأخذ هذا المعامل إحدى القيم (الأوضاع) التالية: | يأخذ هذا المعامل إحدى القيم (الأوضاع) التالية: | ||
إن استخدم الوضع '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 المستخدمة عند كتابة الملفات إلى الأرشيف، وتأخذ إحدى القيم: <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 عندما يتجاوز حجم الملف | إن كانت قيمة هذا المعامل هي <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"> | <syntaxhighlight lang="python3"> | ||
سطر 43: | سطر 44: | ||
'''ملاحظات:''' | '''ملاحظات:''' | ||
* أضيفت قابلية استخدام كائن ZipFile كمدير للسياق في الإصدار 3.2 من بايثون. | * أضيفت قابلية استخدام كائن <code>ZipFile</code> كمدير للسياق في الإصدار 3.2 من بايثون. | ||
* أضيف دعم الضغط بخوارزميتي bzip2 و lzma في الإصدار 3.3 من بايثون. | * أضيف دعم الضغط بخوارزميتي <code>bzip2</code> و <code>lzma</code> في الإصدار 3.3 من بايثون. | ||
* أصبحت الإضافات ZIP64 مفعّلة تلقائيًا. | * أصبحت الإضافات ZIP64 مفعّلة تلقائيًا. | ||
* أضيف دعم الكتابة في تدفّقات البيانات التي لا يمكن البحث فيها | * أضيف دعم الكتابة في تدفّقات البيانات التي لا يمكن البحث فيها <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 من بايثون. | ||
== خصائص الصنف <code>ZipFile</code> == | |||
تقدّم كائنات <code>ZipFile</code> الخصائص التالية: | |||
=== <code>ZipFile.filename</code> === | |||
اسم ملف ZIP. | |||
=== <code>ZipFile.debug</code> === | |||
مستوى مخرجات التنقيح. تتدرّج القيمة التي يمكن تعيينها لهذه الخاصية من <code>0</code> (القيمة الافتراضية، لا مخرجات) إلى <code>3</code> (عرض المخرجات كاملة). تُكتب معلومات التنقيح إلى مخرجات النظام القياسية <code>sys.stdout</code>. | |||
=== <code>ZipFile.comment</code> === | |||
نص التعليق المرافق لملف ZIP. يجب أن يكون التعليق المراد إرفاقه بملف ZIP [[Python/str|سلسلة نصية]] لا يتجاوز طولها <code>65535</code> بايت إن كانت نسخة الصنف <code>ZipFile</code> قد أُنشئت في الوضع <code>'w'</code> أو <code>'x'</code> أو <code>'a'</code>، وإن كان التعليق أطول من هذا المقدار فإنّه سيقتطع عند إضافته إلى ملف الأرشيف لدى استدعاء التابع <code>[[Python/ZipFile/close|close()]]</code>. | |||
== توابع الصنف <code>ZipFile</code> == | |||
=== التابع <code>[[Python/ZipFile/close|ZipFile.close()]]</code> === | |||
يغلق التابع ملف الأرشيف. | |||
=== التابع <code>[[Python/ZipFile/getinfo|ZipFile.getinfo()]]</code> === | |||
يعيد التابع كائن <code>ZipFile</code> مع معلومات حول عضو الأرشيف المعطى. | |||
=== التابع <code>[[Python/ZipFile/infolist|ZipFile.infolist()]]</code> === | |||
يعيد التابع قائمة تتضمّن كائن <code>ZipFile</code> لكل عضو من أعضاء الأرشيف. | |||
=== التابع <code>[[Python/ZipFile/namelist|ZipFile.namelist()]]</code> === | |||
يعيد التابع قائمة بأسماء الأعضاء في ملف الأرشيف. | |||
=== التابع <code>[[Python/ZipFile/open|ZipFile.open()]]</code> === | |||
يتيح التابع الوصول إلى عضو في الأرشيف ككائن ثنائي شبيه بالملفات. | |||
=== التابع <code>[[Python/ZipFile/extract|ZipFile.extract()]]</code> === | |||
يستخرج التابع الملف العضو المعطى من الأرشيف إلى المجلد الحالي. | |||
=== التابع <code>[[Python/ZipFile/extractall|ZipFile.extractall()]]</code> === | |||
يستخرج التابع جميع الأعضاء في ملف الأرشيف إلى المجلد الحالي. | |||
=== التابع <code>[[Python/ZipFile/printdir|ZipFile.printdir()]]</code> === | |||
يطبع التابع جدولًا بمحتويات ملف الأرشيف إلى مخرجات النظام القياسية <code>sys.stdout</code>. | |||
=== التابع <code>[[Python/ZipFile/setpassword|ZipFile.setpassword()]]</code> === | |||
يعيّن التابع كلمة المرور المعطاة ككلمة المرور الافتراضية لاستخراج الملفات المعمّاة من الأرشيف. | |||
=== التابع <code>[[Python/ZipFile/read|ZipFile.read()]]</code> === | |||
يعيد التابع البايتات التابعة للملف المعطى في الأرشيف. | |||
=== التابع <code>[[Python/ZipFile/testzip|ZipFile.testzip()]]</code> === | |||
يقرأ التابع جميع الملفات في الأرشيف ويفحص ترويساتها وCRC الخاصة بها. | |||
=== التابع <code>[[Python/ZipFile/write|ZipFile.write()]]</code> === | |||
يكتب التابع الملف المعطى في ملف الأرشيف. | |||
=== التابع <code>[[Python/ZipFile/writestr|ZipFile.writestr()]]</code> === | |||
يكتب التابع البيانات النصية المعطاة في الأرشيف. | |||
== أمثلة == | == أمثلة == | ||
يبين المثال التالي طريقة إنشاء كائن ZipFile يدعم الكتابة: | يبين المثال التالي طريقة إنشاء كائن <code>ZipFile</code> يدعم الكتابة: | ||
<syntaxhighlight lang="python3"> | <syntaxhighlight lang="python3"> | ||
سطر 64: | سطر 107: | ||
== انظر أيضًا == | == انظر أيضًا == | ||
* | * الصنف <code>[[Python/PyZipFile|PyZipFile]]</code>: يستخدم هذا الصنف لإنشاء ملفات ZIP تتضمّن مكتبات بايثون. | ||
* | * الصنف <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]] | ||
[[تصنيف:Python Modules]] | [[تصنيف:Python Modules]] |
المراجعة الحالية بتاريخ 12:02، 13 سبتمبر 2021
تفتح هذه الدالة البانية للصنف 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
: يستخدم هذا الصنف لعرض المعلومات الخاصّة بعضو من أعضاء ملف الأرشيف.