الفرق بين المراجعتين لصفحة: «Python/TarFile»
لا ملخص تعديل |
|||
| (6 مراجعات متوسطة بواسطة نفس المستخدم غير معروضة) | |||
| سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE: | <noinclude>{{DISPLAYTITLE:الصنف <code>TarFile</code> في بايثون}}</noinclude> | ||
وظيفة هذا الصنف هي قراءة ملفات الأرشيف من نوع tar والكتابة فيها. لا تستخدم هذا الصنف مباشرة، بل استخدم الدالة <code>[[Python/tarfile/open| | وظيفة هذا الصنف هي قراءة ملفات الأرشيف من نوع tar والكتابة فيها. لا تستخدم هذا الصنف مباشرة، بل استخدم الدالة <code>[[Python/tarfile/open|tarfile.open()]]</code> عوضًا عنه. | ||
يقدّم كائن <code>TarFile</code> واجهة لملفات الأرشيف من نوع tar. يتكوّن أرشيف tar من تسلسل من الكتل، ويتكوّن عضو الأرشيف (الملفّ المخزّن) من كتلة الترويسة header block متبوعة بكتل البيانات. يمكن تخزين ملف معيّن في أرشيف tar عدّة مرات، ويُمثّل كل عضو في الأرشيف بواسطة كائن <code>[[Python/TarInfo|TarInfo]]</code> (راجع قسم كائنات <code>[[Python/TarInfo|TarInfo]]</code> للمزيد من التفاصيل). | يقدّم كائن <code>TarFile</code> واجهة لملفات الأرشيف من نوع <code>tar.</code> يتكوّن أرشيف tar من تسلسل من الكتل، ويتكوّن عضو الأرشيف (الملفّ المخزّن) من كتلة الترويسة header block متبوعة بكتل البيانات. يمكن تخزين ملف معيّن في أرشيف tar عدّة مرات، ويُمثّل كل عضو في الأرشيف بواسطة كائن <code>[[Python/TarInfo|TarInfo]]</code> (راجع قسم كائنات <code>[[Python/TarInfo|TarInfo]]</code> للمزيد من التفاصيل). | ||
يمكن استخدام كائن <code>TarFile</code> كمدير للسياق context manager في عبارة <code>with</code>، وسيُغلق الكائن تلقائيًا عند الوصول إلى نهاية الكتلة البرمجية. ويجدر التنبيه هنا إلى أنّه في حال حدوث أي استثناء فإنّ الأرشيف المفتوح للكتابة لن يجري إنهاؤه، ولكن ما سيحدث هو إغلاق كائن الملف الداخلي فقط | يمكن استخدام كائن <code>TarFile</code> كمدير للسياق context manager في عبارة <code>with</code>، وسيُغلق الكائن تلقائيًا عند الوصول إلى نهاية الكتلة البرمجية. ويجدر التنبيه هنا إلى أنّه في حال حدوث أي استثناء فإنّ الأرشيف المفتوح للكتابة لن يجري إنهاؤه، ولكن ما سيحدث هو إغلاق كائن الملف الداخلي فقط. | ||
ملاحظة: أضيف دعم بروتوكول إدارة السياق في الإصدار 3.2 من بايثون. | |||
'''ملاحظة:''' أضيف دعم بروتوكول إدارة السياق في الإصدار 3.2 من بايثون. | |||
== البنية العامة == | == البنية العامة == | ||
| سطر 65: | سطر 66: | ||
== توابع الصنف <code>TarFile</code> == | == توابع الصنف <code>TarFile</code> == | ||
=== التابع <code>[[Python/TarFile/open|TarFile.open()]] | === التابع <code>[[Python/TarFile/open|TarFile.open()]]</code> === | ||
يعدّ تابع الصنف هذا بمثابة دالة بانية لكائنات <code>TarFile</code>. | |||
=== التابع <code>[[Python/TarFile/getmember|TarFile.getmember()]]</code> === | === التابع <code>[[Python/TarFile/getmember|TarFile.getmember()]]</code> === | ||
يعيد التابع كائن <code>[[Python/TarInfo|TarInfo]]</code> لعضو ملف الأرشيف المعطى. | |||
=== التابع <code>[[Python/TarFile/getmembers|TarFile.getmembers()]]</code> === | === التابع <code>[[Python/TarFile/getmembers|TarFile.getmembers()]]</code> === | ||
يعيد التابع أعضاء الأرشيف على هيئة قائمة من كائنات <code>[[Python/TarInfo|TarInfo]]</code> | |||
=== التابع <code>[[Python/TarFile/getnames|TarFile.getnames()]]</code> === | === التابع <code>[[Python/TarFile/getnames|TarFile.getnames()]]</code> === | ||
يعيد التابع قائمة بأسماء الأعضاء في الأرشيف | |||
=== التابع <code>[[Python/TarFile/list|TarFile.list()]]</code> === | === التابع <code>[[Python/TarFile/list|TarFile.list()]]</code> === | ||
يطبع التابع جدولًا بمحتويات كائن <code>TarFile</code> إلى <code>sys.stdout</code>. | |||
=== التابع <code>[[Python/TarFile/next|TarFile.next()]]</code> === | === التابع <code>[[Python/TarFile/next|TarFile.next()]]</code> === | ||
يعيد التابع العضو التالي في الأرشيف على هيئة كائن <code>[[Python/TarInfo|TarInfo]]</code> وذلك عند فتح كائن <code>TarFile</code> للقراءة. | |||
=== التابع <code>[[Python/TarFile/extractall|TarFile.extractall()]]</code> === | === التابع <code>[[Python/TarFile/extractall|TarFile.extractall()]]</code> === | ||
يستخرج التابع جميع الأعضاء من ملف الأرشيف إلى المجلد الحالي أو المسار المعطى. | |||
=== التابع <code>[[Python/TarFile/extract|TarFile.extract()]]</code> === | === التابع <code>[[Python/TarFile/extract|TarFile.extract()]]</code> === | ||
يستخرج التابع عضوًا من ملف الأرشيف إلى المجلد الحالي مستخدمًا اسمه الكامل. | |||
=== التابع <code>[[Python/TarFile/extractfile|TarFile.extractfile()]]</code> === | === التابع <code>[[Python/TarFile/extractfile|TarFile.extractfile()]]</code> === | ||
يستخرج التابع العضو المحدّد في المعاملات من ملف الأرشيف ككائن ملف. | |||
=== التابع <code>[[Python/TarFile/add|TarFile.add()]]</code> === | === التابع <code>[[Python/TarFile/add|TarFile.add()]]</code> === | ||
يضيف التابع الملف المعطى إلى ملف الأرشيف. | |||
=== التابع <code>[[Python/TarFile/addfile|TarFile.addfile()]]</code> === | === التابع <code>[[Python/TarFile/addfile|TarFile.addfile()]]</code> === | ||
يضيف التابع كائن <code>[[Python/TarInfo|TarInfo]]</code> المعطى إلى ملف الأرشيف. | |||
=== التابع <code>[[Python/TarFile/gettarinfo|TarFile.gettarinfo()]]</code> === | === التابع <code>[[Python/TarFile/gettarinfo|TarFile.gettarinfo()]]</code> === | ||
ينشئ التابع كائن <code>[[Python/TarInfo|TarInfo]]</code> من نتيجة استدعاء الدالة <code>[[Python/os/stat|os.stat()]]</code> أو ما يكافئها على ملف موجود فعلًا. | |||
=== التابع <code>[[Python/TarFile/close|TarFile.close()]]</code> === | === التابع <code>[[Python/TarFile/close|TarFile.close()]]</code> === | ||
يغلق التابع كائن <code>TarFile</code>. | |||
< | |||
</ | |||
== انظر أيضًا == | == انظر أيضًا == | ||
* كائنات <code>[[Python/TarInfo|TarInfo]]</code>: يمثّل كائن [[Python/TarInfo|<code>TarInfo</code>]] عضوًا واحدًا في كائن <code>TarFile</code>. يحفظ هذا الكائن جميع الخصائص المطلوبة في الملف (مثل نوع الملف، وحجمه، ووقت التعديل، والأذونات، ومالك الملف وغيرها)، إلى جانب أنّه يقدّم بعض التوابع المفيدة لتحديد نوع الملف، ولا يحتوي هذا الكائن على بيانات الملف. | * كائنات <code>[[Python/TarInfo|TarInfo]]</code>: يمثّل كائن [[Python/TarInfo|<code>TarInfo</code>]] عضوًا واحدًا في كائن <code>TarFile</code>. يحفظ هذا الكائن جميع الخصائص المطلوبة في الملف (مثل نوع الملف، وحجمه، ووقت التعديل، والأذونات، ومالك الملف وغيرها)، إلى جانب أنّه يقدّم بعض التوابع المفيدة لتحديد نوع الملف، ولا يحتوي هذا الكائن على بيانات الملف. | ||
المراجعة الحالية بتاريخ 20:22، 14 نوفمبر 2018
وظيفة هذا الصنف هي قراءة ملفات الأرشيف من نوع tar والكتابة فيها. لا تستخدم هذا الصنف مباشرة، بل استخدم الدالة tarfile.open() عوضًا عنه.
يقدّم كائن TarFile واجهة لملفات الأرشيف من نوع tar. يتكوّن أرشيف tar من تسلسل من الكتل، ويتكوّن عضو الأرشيف (الملفّ المخزّن) من كتلة الترويسة header block متبوعة بكتل البيانات. يمكن تخزين ملف معيّن في أرشيف tar عدّة مرات، ويُمثّل كل عضو في الأرشيف بواسطة كائن TarInfo (راجع قسم كائنات TarInfo للمزيد من التفاصيل).
يمكن استخدام كائن TarFile كمدير للسياق context manager في عبارة with، وسيُغلق الكائن تلقائيًا عند الوصول إلى نهاية الكتلة البرمجية. ويجدر التنبيه هنا إلى أنّه في حال حدوث أي استثناء فإنّ الأرشيف المفتوح للكتابة لن يجري إنهاؤه، ولكن ما سيحدث هو إغلاق كائن الملف الداخلي فقط.
ملاحظة: أضيف دعم بروتوكول إدارة السياق في الإصدار 3.2 من بايثون.
البنية العامة
tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=0)
المعاملات
جميع المعاملات في الدالة البانية اختيارية ويمكن الوصول إليها كخصائص لنسخ الصنف أيضًا.
name
مسار ملف الأرشيف، ويمكن أن يكون المعامل كائنًا شبيهًا بالمسار path-like object. يمكن حذف هذا المعامل إن كان المعامل fileobj يحمل قيمة، وفي مثل هذه الحالة تستخدم خاصية name في كائن الملف إن كانت موجودة.
mode
يأخذ هذا المعامل القيمة 'r' للقراءة من ملف أرشيف موجودًا فعلًا، أو 'a' لإلحاق البيانات بملف موجود فعلًا، أو 'w' لإنشاء ملف جديد والكتابة فوق ملف موجود أصلًا، أو 'x' لإنشاء ملف جديد في حال إذا لم يكن الملف موجودًا.
fileobj
يستخدم هذا المعامل -في حال تعريفه- لقراءة البيانات وكتابتها. إن كان بالإمكان تحديد هذا قيمة هذا المعامل فإنّ قيمة المعامل mode ستتغير إلى الوضع المستخدم مع fileobj. سيستخدم الملف fileobj من الموقع 0.
ملاحظة: لا يُغلَق كائن الملف fileobj عند إغلاق الكائن TarFile.
format
يتحكّم هذا المعامل بصيغة ملف الأرشيف. يجب أن يأخذ هذا المعامل إحد القيم الثابتة USTAR_FORMAT أو GNU_FORMAT أو PAX_FORMAT والمعرّفة على مستوى الوحدة.
tarinfo
يمكن استخدام المعامل tarinfo لاستبدال كائن TarInfo الافتراضي بكائن آخر.
dereference
إن أخذ هذا المعامل القيمة False فستضاف وصلات رمزية symbolic وصلبة hard إلى ملف الأرشيف. أما إن أخذ القيمة True فستضاف محتويات الملف المستهدف إلى ملف الأرشيف. لا تأثير لهذا المعامل في الأنظمة التي لا تدعم الوصلات الرمزية.
ignore_zeros
إن أخذ هذا المعامل القيمة False فستعامل الكتل الفارغة على أنّها نهاية ملف الأرشيف. أما إن أخذ القيمة True فسيجري تجاوز الكتل الفارغة (وغير الصالحة) وستحاول الدالة الحصول على أكبر عدد ممكن من أعضاء ملف الأرشيف. هذا المعامل مفيد فقط في عند القراءة من ملفات الأرشيف المترابطة أو المتضرّرة.
debug
يمكن أن يأخذ المعامل قيمًا تتدرج من 0 (لا رسائل تنقيح) إلى 3 (عرض جميع رسائل التنقيح). تكتب الرسائل إلى sys.stderr.
errorlevel
إن أخذ هذا المعامل القيمة 0 فسيجري تجاهل جميع الأخطاء عند استخدام التابع TarFile.extract(). ومع ذلك فإنّها ستظهر كرسائل أخطاء في مخرجات التنقيح، عندما يكون التنقيح مفعّلًا. أما لو أخذ المعامل القيمة 1 فإن جميع الأخطاء المميتة ستطلق كاستثناءات من نوع OSError. ولو أخذ القيمة 2 فإنّ جميع الأخطاء غير المميتة ستُطلق كاستثناءات من نوع TarError.
encoding و errors
يعرّف هذا المعاملان ترميز الحروف الذي سيستخدم للقراءة من ملفات الأرشيف والكتابة فيها، وكيف سيجري التعامل مع أخطاء التحويل. عادة ما تكون الإعدادات الافتراضية مناسبة لأغلب المستخدمين. راجع قسم مشاكل Unicode للاطلاع على معلومات تفصيلية حول هذا الأمر.
pax_headers
قاموس اختياري يضمّ سلاسل نصية ستضاف كترويسة pax عامة إن كانت قيمة المعامل format هي PAX_FORMAT.
ملاحظات:
- في الإصدار 3.2 من بايثون تستخدم القيمة
'surrogateescape'كقيمة افتراضية للمعاملerrors. - في الإصدار 3.5 من بايثون أضيف الوضع
'x'(الإنشاء الخاص). - في الإصدار 3.6 من بايثون أصبح بالإمكان استخدام الكائنات الشبيهة بالمسارات path-like objects مع المعامل
name.
خصائص الصنف TarFile
الخاصية TarFile.pax_headers
قاموس يحتوي على أزواج مفتاح-قيمة لترويسات pax العامة.
توابع الصنف TarFile
التابع TarFile.open()
يعدّ تابع الصنف هذا بمثابة دالة بانية لكائنات TarFile.
التابع TarFile.getmember()
يعيد التابع كائن TarInfo لعضو ملف الأرشيف المعطى.
التابع TarFile.getmembers()
يعيد التابع أعضاء الأرشيف على هيئة قائمة من كائنات TarInfo
التابع TarFile.getnames()
يعيد التابع قائمة بأسماء الأعضاء في الأرشيف
التابع TarFile.list()
يطبع التابع جدولًا بمحتويات كائن TarFile إلى sys.stdout.
التابع TarFile.next()
يعيد التابع العضو التالي في الأرشيف على هيئة كائن TarInfo وذلك عند فتح كائن TarFile للقراءة.
التابع TarFile.extractall()
يستخرج التابع جميع الأعضاء من ملف الأرشيف إلى المجلد الحالي أو المسار المعطى.
التابع TarFile.extract()
يستخرج التابع عضوًا من ملف الأرشيف إلى المجلد الحالي مستخدمًا اسمه الكامل.
التابع TarFile.extractfile()
يستخرج التابع العضو المحدّد في المعاملات من ملف الأرشيف ككائن ملف.
التابع TarFile.add()
يضيف التابع الملف المعطى إلى ملف الأرشيف.
التابع TarFile.addfile()
يضيف التابع كائن TarInfo المعطى إلى ملف الأرشيف.
التابع TarFile.gettarinfo()
ينشئ التابع كائن TarInfo من نتيجة استدعاء الدالة os.stat() أو ما يكافئها على ملف موجود فعلًا.
التابع TarFile.close()
يغلق التابع كائن TarFile.
انظر أيضًا
- كائنات
TarInfo: يمثّل كائنTarInfoعضوًا واحدًا في كائنTarFile. يحفظ هذا الكائن جميع الخصائص المطلوبة في الملف (مثل نوع الملف، وحجمه، ووقت التعديل، والأذونات، ومالك الملف وغيرها)، إلى جانب أنّه يقدّم بعض التوابع المفيدة لتحديد نوع الملف، ولا يحتوي هذا الكائن على بيانات الملف.
مصادر
صفحة Read and write tar archive files في توثيق بايثون الرسمي.