الدالة 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'. يعرض الجدول التالي قائمة كامل بالقيم المتاحة للاستخدام مع هذا المعامل:
| الوضع | الإجراء |
|---|---|
'r' أو 'r:*'
|
يُفتح الأرشيف للقراءة مع إجراء عملية ضغط غير محدّدة transparent compression (ينصح به). |
'r:'
|
يُفتح الأرشيف للقراءة بشكل خاص exclusively دون إجراء عملية ضغط. |
'r:gz'
|
يُفتح الأرشيف للقراءة مع الضغط بخوارزمية gzip. |
'r:bz2'
|
يُفتح الأرشيف للقراءة مع الضغط بخوارزمية bzip2. |
'r:xz'
|
يُفتح الأرشيف للقراءة مع الضغط بخوارزمية lzma. |
'x' أو 'x:'
|
تُنشئ الدالة ملف tar بشكل خاص دون إجراء عملية ضغط. تُطلق الدالة الاستثناء FileExistsError إن كان الملف موجودًا فعلًا.
|
'x:gz'
|
تُنشئ الدالة ملف tar مع الضغط بخوارزمية gzip. تُطلق الدالة الاستثناء FileExistsError إن كان الملف موجودًا فعلًا.
|
'x:bz2'
|
تُنشئ الدالة ملف tar مع الضغط بخوارزمية bzip2. تُطلق الدالة الاستثناء FileExistsError إن كان الملف موجودًا فعلًا.
|
'x:xz'
|
تُنشئ الدالة ملف tar مع الضغط بخوارزمية lzma. تُطلق الدالة الاستثناء FileExistsError إن كان الملف موجودًا فعلًا.
|
'a' أو 'a:'
|
تفتح الدالة الملف في نمط الإلحاق appending دون إجراء عملية ضغط. تُنشئ الدالة الملف إن لم يكن موجودًا. |
'w' أو 'w:'
|
تفتح الدالة الملف للكتابة فيه دون إجراء عملية ضغط. |
'w:gz'
|
تفتح الدالة الملف للكتابة فيه مع إلضغط بخورازمية gzip. |
'w:bz2'
|
تفتح الدالة الملف للكتابة فيه مع إلضغط بخورازمية bzip2. |
'w:xz'
|
تفتح الدالة الملف للكتابة فيه مع إلضغط بخورازمية lzma. |
ملاحظة: في الإصدار 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|*'
|
تفتح الدالة تدفّقًا من كتل tar للقراءة مع إجراء عملية ضغط غير محدّدة transparent compression. |
'r|'
|
تفتح الدالة تدفقًا من كتل tar غير المضغوطة للقراءة. |
'r|gz'
|
تفتح الدالة تدفقًا من كتل tar المضغوطة بخوارزمية gzip للقراءة. |
'r|bz2'
|
تفتح الدالة تدفقًا من كتل tar المضغوطة بخوارزمية bzip2 للقراءة. |
'r|xz'
|
تفتح الدالة تدفقًا من كتل tar المضغوطة بخوارزمية lzma للقراءة. |
'w|'
|
تفتح الدالة تدفقًا من كتل tar غير المضغوطة للكتابة. |
'w|gz'
|
تفتح الدالة تدفقًا من كتل tar المضغوطة بخوارزمية gzip للكتابة. |
'w|bz2'
|
تفتح الدالة تدفقًا من كتل tar المضغوطة بخوارزمية bzip2 للكتابة. |
'w|xz'
|
تفتح الدالة تدفقًا من كتل tar المضغوطة بخوارزمية 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()