Python/tarfile

تتيح وحدة tarfile القدرة على قراءة ملفات الأرشيف tar والكتابة فيها، ومن ضمن ذلك تلك التي تستخدم خوارزمية gzip و bz2 و lzma لإجراء عملية الضغط.

استخدم وحدة zipfile لقراءة الملفات ذات الامتداد ‎.zip والكتابة فيها، أو استخدم الدوال ذات المستوى الأعلى في shutil.

وقبل الدخول في تفاصيل هذه الوحدة يجدر التنبيه إلى النقاط التالية:

• تقرأ الوحدة وتكتب ملفات gzip و bz2 و lzma المضغوطة إن كانت الوحدات المقابلة لكل نوع متوفرة.
• تدعم الوحدة القراءة والكتابة للصيغة POSIX.1-1988 ‏(ustar).
• تدعم الوحدة القراءة والكتابة للصيغة Gnu tar ومن ضمنها ملحقات longname و longlink، ودعم القراءة فقط لمختلف أنواع الملحق sparse بما في ذلك استعادة restoration ملفات spares.
• تتعامل الوحدة مع المجلدات والملفات العادية والوصلات الصلبة hard links، والوصلات الرمزية symbolic links، و fifos، الأجهزة الطرفية المحرفية character devices والأجهزة الطرفية الكتلية block devices، وللوحدة القدرة على استدعاء واستعادة معلومات الملفات مثل الختم الزمني وأذونات الوصول واسم صاحب الملف.

ملاحظة: في الإصدار 3.3 من بايثون أضيف دعم الضغط بتقنية lzma.

دوال الوحدة tarfile

تقدّم الوحدة الدوال التالية التي تساعد في التعامل مع ملفات الأرشيف tar:

الدالة tarfile.open()‎

تعيد الدالة كائن TarFile للمسار المعطى.

الدالة tarfile.is_tarfile()‎

تتحقق الدالة ممّا إذا كان بمقدور الوحدة tarfile قراءة ملف الأرشيف المعطى.

استثناءات الوحدة tarfile

تقدّم الوحدة tarfile الاستثناءات التالية:

الاستثناء tarfile.TarError

الصنف الأساسي الذي تُشتقّ منه جميع الاستثناءات في وحدة tarfile.

الاستثناء tarfile.ReadError

يطلق هذا الاستثناء عند فتح أرشيف tar لا يمكن معالجته بواسطة الوحدة tarfile أو عندما يكون الأرشيف مفتوح غير صالح.

الاستثناء tarfile.CompressionError

يطلق هذا الاستثناء عندما تكون طريقة الضغط غير مدعومة أو عندما لا يكون بالإمكان فك تشفير البيانات بصورة صحيحة.

الاستثناء tarfile.StreamError

يُطلق هذا الاستثناء عند حدوث الأخطاء الشائعة لكائنات TarFile الشبيهة بتدفق البيانات.

الاستثناء tarfile.ExtractError

يُطلق هذا الاستثناء للأخطاء غير المميتة non-fatal عند استخدام التابع TarFile.extract()‎، بشرط أن تكون الخاصية TarFile.errorlevel==2.

الاستثناء tarfile.HeaderError

يُطلق هذا الاستثناء بواسطة TarInfo.frombuf()‎ إن كانت الذاكرة التي يحصل عليها غير صالحة.

ثوابت الوحدة tarfile

تقدّم الوحدة tarfile الثوابت التالية على مستوى الوحدة:

tarfile.ENCODING

الترميز الافتراضي للمحارف، ويكون 'utf-8' في نظام ويندوز، والقيمة المعادة من bysys.getfilesystemencoding()‎ في الأنظمة الأخرى.

يعرّف كل ثابت من الثوابت التالية صيغة أرشيف tar التي يكون بمقدور الوحدة tarfile إنشائه. راجع قسم صيغ tar المدعومة للمزيد من التفاصيل.

tarfile.USTAR_FORMAT

صيغة ‎POSIX.1-1988 (ustar)‎.

tarfile.GNU_FORMAT

صيغة GNU tar.

tarfile.PAX_FORMAT

صيغة ‎POSIX.1-2001 (pax)‎.

tarfile.DEFAULT_FORMAT

الصيغة الافتراضية لإنشاء ملفات الأرشيف. القيمة الحالية لهذا الثابت هي GNU_FORMAT.

كائنات TarFile

يقدّم كائن TarFile واجهة لملفات الأرشيف من نوع tar.

كائنات TarInfo

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

واجهة سطر الأوامر

تقدّم وحدة tarfile واجهة بسيطة في سطر الأوامر لغرض التفاعل مع ملفات الأرشيف من نوع tar.

ملاحظة: هذه الواجهة جديدة في الإصدار 3.4 من بايثون.

إن كنت ترغب في إنشاء ملف tar جديد فعليك بتحديد اسمه بعد الخيار ‎-c ثم سرد أسماء الملفات التي يجب أن يضمّها هذا الأرشيف:

$ python -m tarfile -c monty.tar  spam.txt eggs.txt

يمكن تمرير مجلد أيضًا:

$ python -m tarfile -c monty.tar life-of-brian_1979/

إن كنت ترغب في استخراج أرشيف tar إلى المجلد الحالي استخدم الخيار ‎-e:

$ python -m tarfile -e monty.tar

يمكنك أيضًا استخراج الملفات من أرشيف tar في مجلد مختلف عن طريق تمرير اسم ذلك المجلد:

$ python -m tarfile -e monty.tar  other-dir/

للحصول على قائمة بالملفات الموجودة في أرشيف tar، استخدم الخيار ‎-l:

$ python -m tarfile -l monty.tar

خيارات سطر الأوامر

-l <tarfile>
--list <tarfile>

عرض قائمة بالملفات الموجودة في ملف الأرشيف.

-c <tarfile> <source1> ... <sourceN>
--create <tarfile> <source1> ... <sourceN>

إنشاء ملف tar من ملفات مصدرية.

-e <tarfile> [<output_dir>]
--extract <tarfile> [<output_dir>]

استخراج الملفات الموجودة في ملف tar إلى المجلد الحالي في حال عدم تحديد قيمة للوسيط output_dir.

-t <tarfile>
--test <tarfile>

فحص ما إذا كان ملف tar صالحًا للاستخدام أم لا.

-v, --verbose

عرض مخرجات بطريقة مفصّلة.

صيغ tar المدعومة

يمكن إنشاء ثلاث صيغ لملفات tar بواسطة الوحدة tarfile:

• صيغة POSIX.1-1988 ustar (الصيغة USTAR_FORMAT). تدعم هذه الصيغة أسماء ملفات يصل طولها إلى 256 حرفًا في أحسن الأحوال وأسماء وصلات تصل إلى 100 حرف. أقصى حجم للملفات هو 8 كيكابايت. هذه الصيغة قديمة ومقيّدة ولكنّها مدعومة على نطاق واسع.
• صيغة GNU tar (صيغة GNU_FORMAT). تدعم هذه الصيغة أسماء ملفات ووصلات طويلة، ويمكن استخدام ملفات يتجاوز حجمها 8 كيكابايت وكذلك يمكن اسختدام ملفات ذات فراغات sparse files. هذه الصيغة هي الصيغة المتداولة في أنظمة GNU/Linux. تدعم وحدة tarfile وبشكل Gnu tar للأسماء الطويلة، أما دعم الملفات ذات الفراغات فهو للقراءة فقط.
• صيغة POSIX.1-2001 pax (صيغة PAX_FORMAT). هذه الصيغة هي الأكثر مرونة من بين الصيغ المدعومة وهي غير محدودة نظريًا. تدعم هذه الصيغة أسماء الملفات والوصلات الطويلة، إلى جانب دعمها للملفات كبيرة الحجم وتخزّن المسارات بطريقة محمولة. ولكن ليس بمقدور أدوات tar المتوفّرة في الوقت الحاضر أن تتعامل مع ملفات الأرشيف من نوع pax.

صيغة pax هي امتداد لصيغة ustar الحالية، وتستخدم ترويسات إضافية للمعلومات التي لا يمكن تخزينها بطريقة أخرى. هناك نوعان من ترويسات pax: الأول: الترويسات الموسّعة والتي تؤثر على ترويسة الملف اللاحق، والترويسات العامة والتي تكون صالحة للاستخدام في ملف الأرشيف بأكمله وتؤثّر على جميع الملفات اللاحقة. يستخدم الترميز UTF-8 لترميز جميع البيانات في ترويسة pax وذلك لتسهيل نقلها من مكان إلى آخر.

هناك أيضًا صيغ أخرى لملفات tar والتي يمكن قرائتها بواسطة الوحدة دون التمكّن من إنشائها:

• صيغة V7 القديمة، وهي أول صيغة tar وقد ظهرت في الإصدار السابع من Unix، وتخزّن هذه الصيغة الملفات والمجلدات العادية فقط. يجب أن لا يتجاوز اسم الملف في هذه الصيغة 100 حرف، ولا توجد معلومات عن المستخدم أو المجموعة. تعاني بعض ملفات الأرشيف من أخطاء في حساب دالة التحقق للترويسة عند وجود حقول تتضمن حروفًا خارج الترميز ASCII.
• صيغة SunOS الموسّعة. هذه الصيغة هي شكل آخر للصيغة POSIX.1-2001 pax، ولكنّها غير متوافقة معها.

مشاكل Unicode

كان الهدف من إنشاء صيغة tar في الأصل إنشاء نسخة احتياطية لأشرطة التسجيل مع التركيز على فكرة الاحتفاظ بمعلومات النظام. أما اليوم فيشيع استخدام ملفات tar لتوزيع الملفات وتبادل ملفات الأرشيف عبر الشبكات. ولكن تعاني الصيغة الأصلية (والتي تمثل الأساس الذي بنيت علهي الصيغة الأخرى) من مشكلة عدم وجود مفهوم دعم ترميزات متنوعة للحروف. فعلى سبي المثال لا يمكن لأرشيف tar عادي أنشئ باستخدام الترميز UTF-8 أن يُقرأ بصورة صحيحة في نظام يعمل بالترميز Latin-1 إن كان الأرشيف يتضمّن محارف خارج الترميز ASCII، وستتعرض البيانات الوصفية النصية (مثل أسماء الملفات، وأسماء الوصلات، وأسماء المستخدم/المجموعة) للتلف، ولا توجد طريقة آلية للتعرّف على ترميز ملف الأرشيف. صمّمت صيغة pax للتغلّب على هذه المشكلة، إذ إنّها تحفظ البيانات الوصفية التي تكون خارج الترميز ASCII باستخدام الترميز العالمي UTF-8.

تتحكّم المعاملات المفتاحية encoding و errors في صنف TarFile بتفاصيل عملية تحويل المحارف في وحدة tarfile.

يعرّف المعامل encoding ترميز الحروف الذي سيُستخدم لترميز البيانات الوصفية في الأرشيف. يأخذ هذا المعامل قيمة افتراضية هي نتيجة استدعاء الدالة sys.getfilesystemencoding()‎ أو القيمة 'ascii' في حال عدم الحصول على نتيجة من الاستدعاء السابق. يجب ترميز البيانات الوصفية أو فك ترميزها بالاعتماد على ما إذا كان الأرشيف مفتوحًا للقراءة أو للكتابة. ويجدر التنبيه إلى أنّه في حال عدم تهيئة الترميز بطريقة صحيحة، فإنّ عملية التحويل ستفشل.

يعرّف المعامل errors طريقة التعامل مع المحارف التي لا يمكن تحويلها. يأخذ هذا المعامل قيمتين هما 'strict' والتي تطلق الاستثناء UnicodeError عند عدم التمكن من تحويل المحارف، و'ignore' والتي تؤدي إلى الاستمرار في تنفيذ الشيفرة وتجاهل أخطاء التحويل.

تستخدم بايثون النظام الافتراضي 'surrogateescape' والمستخدم من قبل اللغة في استدعاءات نظام الملفات.

في حال استخدام ملفات الأرشيف ذات الصيغة PAX_FORMAT فلا حاجة لاستخدام المعامل encoding لأنّ جميع البيانات الوصفية تخزّن بترميز UTF-8، ويستخدم المعامل encoding في الحالات النادرة التي يفكّ فيها ترميز ترويسة pax الثنائية أو عند تخزين سلاسل نصية تتضمّن محارف بديلة surrogate.

انظر أيضًا

• الوحدة zipfile: تقدّم هذه الوحدة أدواة لإنشاء ملفات ZIP والقراءة منها والكتابة فيها وإلحاق الملفات بها وعرض محتوياتها.

مصادر

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