الوحدة tarfile‎ في بايثون

وظيفة هذا الصنف هي قراءة ملفات الأرشيف من نوع 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.

أمثلة

يبين المثال التالي طريقة استخراج جميع الملفات الموجودة في أرشيف tar إلى المجلّد الحالي:

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall()
tar.close()

انظر أيضًا

• كائنات TarInfo: يمثّل كائن TarInfo عضوًا واحدًا في كائن TarFile. يحفظ هذا الكائن جميع الخصائص المطلوبة في الملف (مثل نوع الملف، وحجمه، ووقت التعديل، والأذونات، ومالك الملف وغيرها)، إلى جانب أنّه يقدّم بعض التوابع المفيدة لتحديد نوع الملف، ولا يحتوي هذا الكائن على بيانات الملف.

مصادر

صفحة Read and write tar archive files في توثيق بايثون الرسمي.