الدالة tarfile.open() في بايثون
تفتح الدالة ملف tar المعطى وتعيد الدالة كائن TarFile للمسار المعطى. راجع قسم كائنات TarFile للاطلاع على المزيد من المعلومات حول هذه الكائنات والمعاملات المفتاحية المتاحة للاستخدام.
البنية العامة
tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)
المعاملات
name
مسار ملف الأرشيف tar المراد فتحه.
ملاحظة: في الإصدار 3.6 من بايثون أصبح المعامل name يستقبل كائنات شبيهة بالمسارات path-like objects.
mode
يجب أن يكون هذا المعامل سلسلة نصية بالصيغة 'filemode[:compression]'، ويأخذ القيمة الافتراضية 'r'. يعرض الجدول التالي قائمة كامل بالقيم المتاحة للاستخدام مع هذا المعامل:
ملاحظة: في الإصدار 3.5 من بايثون أضيف الوضع 'x' (الإنشاء الخاص exclusive creation).
لاحظ أنّه ليس بالإمكان استخدام 'a:gz' أو 'a:bz2' أو 'a:xz'. إن كان الوضع mode غير مناسب لفتح ملف (مضغوط) معين للقراءة، تطلق الدالة الاستثناء ReadError، ويمكن تجنب ذلك باستخدام الوضع 'r'. أما إذا كانت طريقة الضغط غير مدعومة، فستطلق الدالة الاستثناء CompressionError.
هناك صيغة أخرى للمعامل mode وتستخدم لأغراض خاصة، وهذه الصيغة هي: 'filemode|[compression]'. ستعيد الدالة tarfile.open() كائن TarFile يعالج بدوره بياناته كتدفق من الكتل stream of blocks، ولن تُجرى عمليات بحث عشوائية على الملف. يمكن استخدام هذه الصيغة مع sys.stdin مثلًا، أو مع كائن ملف مَنْفَذْ socket file object أو مع مشغّل أشرطة tape device. ولكن تكون كائنات TarFile محدودة ولا تسمح بالوصول العشوائي. يوضّح الجدول التالي الأوضاع المتاحة في الوقت الحاضر:
| الوضع | الحدث |
|---|---|
'r' or 'r:*'
|
يُفتح الأرشيف للقراءة مع إجراء عملية ضغط واضحة transparent compression (ينصح به). |
'r:'
|
يُفتح الأرشيف للقراءة بشكل خاص exclusively دون إجراء عملية ضغط. |
'r:gz'
|
يُفتح الأرشيف للقراءة مع الضغط بخوارزمية gzip. |
'r:bz2'
|
يُفتح الأرشيف للقراءة مع الضغط بخوارزمية bzip2. |
'r:xz'
|
يُفتح الأرشيف للقراءة مع الضغط بخوارزمية lzma. |
'x' or 'x:'
|
تُنشئ الدالة ملف tar بشكل خاص دون إجراء عملية ضغط. تُطلق الدالة الاستثناء FileExistsError إن كان الملف موجودًا فعلًا.
|
'x:gz'
|
تُنشئ الدالة ملف tar مع الضغط بخوارزمية gzip. تُطلق الدالة الاستثناء FileExistsError إن كان الملف موجودًا فعلًا.
|
'x:bz2'
|
تُنشئ الدالة ملف tar مع الضغط بخوارزمية bzip2. تُطلق الدالة الاستثناء FileExistsError إن كان الملف موجودًا فعلًا.
|
'x:xz'
|
تُنشئ الدالة ملف tar مع الضغط بخوارزمية lzma. تُطلق الدالة الاستثناء FileExistsError إن كان الملف موجودًا فعلًا.
|
'a' or 'a:'
|
تفتح الدالة الملف في نمط الإلحاق appending دون إجراء عملية ضغط. تُنشئ الدالة الملف إن لم يكن موجودًا. |
'w' or 'w:'
|
تفتح الدالة الملف للكتابة فيه دون إجراء عملية ضغط. |
'w:gz'
|
تفتح الدالة الملف للكتابة فيه مع إلضغط بخورازمية gzip. |
'w:bz2'
|
تفتح الدالة الملف للكتابة فيه مع إلضغط بخورازمية bzip2. |
'w:xz'
|
تفتح الدالة الملف للكتابة فيه مع إلضغط بخورازمية lzma. |
fileobj
إن جرى تحديد قيمة للمعامل fileobj فإنها ستستخدم كبديل عن كائن الملف المفتوح في النمط الثنائي للمعامل name، ويفترض أن يكون في الموقع 0.
يمكن أن يكون المعامل fileobj أي نوع من الكائنات التي تمتلك أحد التابعين read() أو write() (بالاعتماد على قيمة المعامل mode المستخدمة).
bufsize
يحدّد المعامل bufsize حجم الكتلة blocksize ويأخذ القيمة الافتراضية 20 *512 بايت.
معاملات مفتاحية **kwargs
عند استخدام الأوضاع 'w:gz'، 'r:gz'، 'w:bz2'، 'r:bz2'، 'x:gz'، 'x:bz2'، تستقبل الدالة tarfile.open() المعامل المفتاحي compresslevel (قيمته الافتراضية 9) وذلك لتحديد مستوى الضغط للملف الحالي.
القيمة المعادة
تعيد الدالة كائن TarFile للمسار المعطى.
أمثلة
يبين المثال التالي طريقة استخراج جميع الملفات الموجودة في أرشيف tar إلى المجلّد الحالي:
import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall()
tar.close()