الفرق بين المراجعتين لصفحة: «Python/tarfile»

من موسوعة حسوب
التعديل اللاحق ←
مرئينص الويكي
أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الوحدة <code>tarfile‎</code> في بايثون}}</noinclude> تتيح وحدة tarfile القدرة على قراءة ملفات ال...'
 
لا ملخص تعديل
سطر 1: سطر 1:
<noinclude>{{DISPLAYTITLE:الوحدة <code>tarfile‎</code> في بايثون}}</noinclude>
<noinclude>{{DISPLAYTITLE:الوحدة <code>tarfile‎</code> في بايثون}}</noinclude>


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


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


وقبل الدخول في تفاصيل هذه الوحدة يجدر التنبيه إلى النقاط التالية:
وقبل الدخول في تفاصيل هذه الوحدة يجدر التنبيه إلى النقاط التالية:
 
*تقرأ الوحدة وتكتب ملفات <code>gzip</code> و <code>bz2</code> و <code>lzma</code> المضغوطة إن كانت الوحدات المقابلة لكل نوع متوفرة.
* تقرأ الوحدة وتكتب ملفات gzip و bz2 و lzma المضغوطة إن كانت الوحدات المقابلة لكل نوع متوفرة.
*تدعم الوحدة القراءة والكتابة للصيغة <code>POSIX.1-1988</code> ‏(<code>ustar</code>).
* تدعم الوحدة القراءة والكتابة للصيغة POSIX.1-1988 ‏(ustar).
*تدعم الوحدة القراءة والكتابة للصيغة <code>Gnu tar</code> ومن ضمنها ملحقات <code>longname</code> و <code>longlink</code>، ودعم القراءة فقط لمختلف أنواع الملحق <code>sparse</code> بما في ذلك استعادة <code>restoration</code> ملفات <code>spares</code>.
* تدعم الوحدة القراءة والكتابة للصيغة Gnu tar ومن ضمنها ملحقات longname و longlink، ودعم القراءة فقط لمختلف أنواع الملحق sparse بما في ذلك استعادة restoration ملفات spares.
*تتعامل الوحدة مع المجلدات والملفات العادية والوصلات الصلبة hard links، والوصلات الرمزية symbolic links، و fifos، الأجهزة الطرفية المحرفية character devices والأجهزة الطرفية الكتلية block devices، وللوحدة القدرة على استدعاء واستعادة معلومات الملفات مثل الختم الزمني وأذونات الوصول واسم صاحب الملف.
* تتعامل الوحدة مع المجلدات والملفات العادية والوصلات الصلبة hard links، والوصلات الرمزية symbolic links، و fifos، الأجهزة الطرفية المحرفية character devices والأجهزة الطرفية الكتلية block devices، وللوحدة القدرة على استدعاء واستعادة معلومات الملفات مثل الختم الزمني وأذونات الوصول واسم صاحب الملف.
ملاحظة: في الإصدار 3.3 من بايثون أضيف دعم الضغط بتقنية <code>lzma</code>.
 
==دوال الوحدة <code>tarfile</code>==
ملاحظة: في الإصدار 3.3 من بايثون أضيف دعم الضغط بتقنية lzma.
 
== دوال الوحدة tarfile ==
 
تقدّم الوحدة الدوال التالية التي تساعد في التعامل مع ملفات الأرشيف tar:
تقدّم الوحدة الدوال التالية التي تساعد في التعامل مع ملفات الأرشيف tar:
 
===الدالة <code>tarfile.open()‎</code>===
=== الدالة <code>tarfile.open()‎</code> ===
تعيد الدالة كائن <code>[[Python/TarFile|TarFile]]</code> للمسار المعطى.
 
===الدالة <code>tarfile.is_tarfile()‎</code>===
تعيد الدالة كائن TarFile للمسار المعطى.
تتحقق الدالة ممّا إذا كان بمقدور الوحدة <code>tarfile</code> قراءة ملف الأرشيف المعطى.
 
==استثناءات الوحدة <code>tarfile</code>==
=== الدالة <code>tarfile.is_tarfile()‎</code> ===
تقدّم الوحدة <code>tarfile</code> الاستثناءات التالية:
 
===الاستثناء <code>tarfile.TarError</code>===
تتحقق الدالة ممّا إذا كان بمقدور الوحدة tarfile قراءة ملف الأرشيف المعطى.
الصنف الأساسي الذي تُشتقّ منه جميع الاستثناءات في وحدة <code>tarfile</code>.
 
===الاستثناء <code>tarfile.ReadError</code>===
 
يطلق هذا الاستثناء عند فتح أرشيف tar لا يمكن معالجته بواسطة الوحدة <code>tarfile</code> أو عندما يكون الأرشيف مفتوح غير صالح.
== استثناءات الوحدة tarfile ==
===الاستثناء <code>tarfile.CompressionError</code>===
تقدّم الوحدة tarfile الاستثناءات التالية:
 
=== exception tarfile.TarError ===
الصنف الأساسي الذي تُشتقّ منه جميع الاستثناءات في وحدة tarfile.
 
=== exception tarfile.ReadError ===
يطلق هذا الاستثناء عند فتح أرشيف tar لا يمكن معالجته بواسطة الوحدة tarfile أو عندما يكون الأرشيف مفتوح غير صالح.
 
=== exception tarfile.CompressionError ===
يطلق هذا الاستثناء عندما تكون طريقة الضغط غير مدعومة أو عندما لا يكون بالإمكان فك تشفير البيانات بصورة صحيحة.
يطلق هذا الاستثناء عندما تكون طريقة الضغط غير مدعومة أو عندما لا يكون بالإمكان فك تشفير البيانات بصورة صحيحة.
===الاستثناء <code>tarfile.StreamError</code>===
يُطلق هذا الاستثناء عند حدوث الأخطاء الشائعة لكائنات <code>[[Python/TarFile|TarFile]]</code> الشبيهة بتدفق البيانات.
===الاستثناء <code>tarfile.ExtractError</code>===
يُطلق هذا الاستثناء للأخطاء غير المميتة non-fatal عند استخدام التابع <code>[[Python/TarFile/extract|TarFile.extract()‎]]</code>،  بشرط أن تكون الخاصية <code>TarFile.errorlevel==2</code>.
===الاستثناء <code>tarfile.HeaderError</code>===
يُطلق هذا الاستثناء بواسطة <code>[[Python/TarInfo/frombuf|TarInfo.frombuf()]]</code>‎ إن كانت الذاكرة التي يحصل عليها غير صالحة.
==ثوابت الوحدة tarfile==
تقدّم الوحدة <code>tarfile</code> الثوابت التالية على مستوى الوحدة:
===<code>tarfile.ENCODING</code>===
الترميز الافتراضي للمحارف، ويكون <code>'utf-8'</code> في نظام ويندوز، والقيمة المعادة من <code>bysys.getfilesystemencoding()‎</code> في الأنظمة الأخرى.


=== exception tarfile.StreamError ===
يعرّف كل ثابت من الثوابت التالية صيغة أرشيف tar التي يكون بمقدور الوحدة <code>tarfile</code> إنشائه. راجع قسم صيغ tar المدعومة للمزيد من التفاصيل.
يُطلق هذا الاستثناء عند حدوث الأخطاء الشائعة لكائنات TarFile الشبيهة بتدفق البيانات.
===<code>tarfile.USTAR_FORMAT</code>===
 
صيغة ‎<code>POSIX.1-1988 (ustar)</code>‎.
=== exception tarfile.ExtractError ===
===<code>tarfile.GNU_FORMAT</code>===
يُطلق هذا الاستثناء للأخطاء غير المميتة non-fatal عند استخدام التابع TarFile.extract()‎،  بشرط أن تكون الخاصية TarFile.errorlevel==2.
صيغة <code>GNU tar</code>.
 
===<code>tarfile.PAX_FORMAT</code>===
=== exception tarfile.HeaderError ===
صيغة ‎<code>POSIX.1-2001 (pax)</code>‎.
يُطلق هذا الاستثناء بواسطة TarInfo.frombuf()‎ إن كانت الذاكرة التي يحصل عليها غير صالحة.  
===<code>tarfile.DEFAULT_FORMAT</code>===
 
الصيغة الافتراضية لإنشاء ملفات الأرشيف. القيمة الحالية لهذا الثابت هي <code>GNU_FORMAT</code>.
 
==كائنات <code>TarFile</code>==
== ثوابت الوحدة tarfile ==
يقدّم كائن <code>TarFile</code> واجهة لملفات الأرشيف من نوع tar.
تقدّم الوحدة tarfile الثوابت التالية على مستوى الوحدة:
==كائنات <code>TarInfo</code>==
 
يمثّل كائن <code>TarInfo</code> عضوًا واحدًا في كائن <code>TarFile</code>. يحفظ هذا الكائن جميع الخصائص المطلوبة في الملف (مثل نوع الملف، وحجمه، ووقت التعديل، والأذونات، ومالك الملف وغيرها)، إلى جانب أنّه يقدّم بعض التوابع المفيدة لتحديد نوع الملف، ولا يحتوي هذا الكائن على بيانات الملف.
=== tarfile.ENCODING ===
الترميز الافتراضي للمحارف، ويكون 'utf-8' في نظام ويندوز، والقيمة المعادة من bysys.getfilesystemencoding()‎ في الأنظمة الأخرى.


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


=== tarfile.USTAR_FORMAT ===
'''ملاحظة:''' هذه الواجهة جديدة في الإصدار 3.4 من بايثون.
صيغة ‎POSIX.1-1988 (ustar)‎.
=== tarfile.GNU_FORMAT ===
صيغة GNU tar.
=== tarfile.PAX_FORMAT ===
صيغة ‎POSIX.1-2001 (pax)‎.
=== tarfile.DEFAULT_FORMAT ===
الصيغة الافتراضية لإنشاء ملفات الأرشيف. القيمة الحالية لهذا الثابت هي GNU_FORMAT.


== كائنات TarFile ==
إن كنت ترغب في إنشاء ملف tar جديد فعليك بتحديد اسمه بعد الخيار <code>‎-c</code> ثم سرد أسماء الملفات التي يجب أن يضمّها هذا الأرشيف:<syntaxhighlight lang="shell">
 
يقدّم كائن TarFile واجهة لملفات الأرشيف من نوع tar.
 
== كائنات TarInfo ==
 
يمثّل كائن TarInfo عضوًا واحدًا في كائن TarFile. يحفظ هذا الكائن جميع الخصائص المطلوبة في الملف (مثل نوع الملف، وحجمه، ووقت التعديل، والأذونات، ومالك الملف وغيرها)، إلى جانب أنّه يقدّم بعض التوابع المفيدة لتحديد نوع الملف، ولا يحتوي هذا الكائن على بيانات الملف.
 
واجهة سطر الأوامر
ملاحظة: هذه الواجهة جديدة في الإصدار 3.4 من بايثون.
 
تقدّم وحدة tarfile واجهة بسيطة في سطر الأوامر لغرض التفاعل مع ملفات الأرشيف من نوع tar.
 
إن كنت ترغب في إنشاء ملف tar جديد فعليك بتحديد اسمه بعد الخيار ‎-c ثم سرد أسماء الملفات التي يجب أن يضمّها هذا الأرشيف:
 
<syntaxhighlight lang="shell">
$ python -m tarfile -c monty.tar  spam.txt eggs.txt
$ python -m tarfile -c monty.tar  spam.txt eggs.txt
</syntaxhighlight>
</syntaxhighlight>يمكن تمرير مجلد أيضًا:<syntaxhighlight lang="shell">
 
يمكن تمرير مجلد أيضًا:
 
<syntaxhighlight lang="shell">
$ python -m tarfile -c monty.tar life-of-brian_1979/
$ python -m tarfile -c monty.tar life-of-brian_1979/
</syntaxhighlight>
</syntaxhighlight>إن كنت ترغب في استخراج أرشيف tar إلى المجلد الحالي استخدم الخيار ‎<code>-e</code>:<syntaxhighlight lang="shell">
 
إن كنت ترغب في استخراج أرشيف tar إلى المجلد الحالي استخدم الخيار ‎-e:
 
<syntaxhighlight lang="shell">
$ python -m tarfile -e monty.tar
$ python -m tarfile -e monty.tar
</syntaxhighlight>
</syntaxhighlight>يمكنك أيضًا استخراج الملفات من أرشيف tar في مجلد مختلف عن طريق تمرير اسم ذلك المجلد:<syntaxhighlight lang="shell">
 
يمكنك أيضًا استخراج الملفات من أرشيف tar في مجلد مختلف عن طريق تمرير اسم ذلك المجلد:
 
<syntaxhighlight lang="shell">
$ python -m tarfile -e monty.tar  other-dir/
$ python -m tarfile -e monty.tar  other-dir/
</syntaxhighlight>
</syntaxhighlight>للحصول على قائمة بالملفات الموجودة في أرشيف tar، استخدم الخيار ‎<code>-l</code>:<syntaxhighlight lang="shell">
 
للحصول على قائمة بالملفات الموجودة في أرشيف tar، استخدم الخيار ‎-l:
 
<syntaxhighlight lang="shell">
$ python -m tarfile -l monty.tar
$ python -m tarfile -l monty.tar
</syntaxhighlight>
</syntaxhighlight>
 
===خيارات سطر الأوامر===
=== خيارات سطر الأوامر ===
<syntaxhighlight lang="shell">
<syntaxhighlight lang="shell">
-l <tarfile>
-l <tarfile>
--list <tarfile>
--list <tarfile>
</syntaxhighlight>
</syntaxhighlight>عرض قائمة بالملفات الموجودة في ملف الأرشيف.<syntaxhighlight lang="shell">
عرض قائمة بالملفات الموجودة في ملف الأرشيف.
 
<syntaxhighlight lang="shell">
-c <tarfile> <source1> ... <sourceN>
-c <tarfile> <source1> ... <sourceN>
--create <tarfile> <source1> ... <sourceN>
--create <tarfile> <source1> ... <sourceN>
</syntaxhighlight>
</syntaxhighlight>إنشاء ملف tar من ملفات مصدرية.<syntaxhighlight lang="shell">
 
إنشاء ملف tar من ملفات مصدرية.
 
<syntaxhighlight lang="shell">
-e <tarfile> [<output_dir>]
-e <tarfile> [<output_dir>]
--extract <tarfile> [<output_dir>]
--extract <tarfile> [<output_dir>]
</syntaxhighlight>
</syntaxhighlight>استخراج الملفات الموجودة في ملف tar إلى المجلد الحالي في حال عدم تحديد قيمة للوسيط <code>output_dir</code>.<syntaxhighlight lang="shell">
 
استخراج الملفات الموجودة في ملف tar إلى المجلد الحالي في حال عدم تحديد قيمة للوسيط output_dir.
 
<syntaxhighlight lang="shell">
-t <tarfile>
-t <tarfile>
--test <tarfile>
--test <tarfile>
</syntaxhighlight>
</syntaxhighlight>فحص ما إذا كان ملف tar صالحًا للاستخدام أم لا.<syntaxhighlight lang="shell">
 
فحص ما إذا كان ملف tar صالحًا للاستخدام أم لا.
 
<syntaxhighlight lang="shell">
-v, --verbose
-v, --verbose
</syntaxhighlight>
</syntaxhighlight>عرض مخرجات بطريقة مفصّلة.
 
==صيغ tar المدعومة==
عرض مخرجات بطريقة مفصّلة.
يمكن إنشاء ثلاث صيغ لملفات tar بواسطة الوحدة <code>tarfile</code>:
 
*صيغة <code>POSIX.1-1988 ustar</code> (الصيغة <code>USTAR_FORMAT</code>). تدعم هذه الصيغة أسماء ملفات يصل طولها إلى 256 حرفًا في أحسن الأحوال وأسماء وصلات تصل إلى 100 حرف. أقصى حجم للملفات هو 8 كيكابايت. هذه الصيغة قديمة ومقيّدة ولكنّها مدعومة على نطاق واسع.
== صيغ tar المدعومة ==
*صيغة <code>GNU tar</code> (صيغة <code>GNU_FORMAT</code>). تدعم هذه الصيغة أسماء ملفات ووصلات طويلة، ويمكن استخدام ملفات يتجاوز حجمها 8 كيكابايت وكذلك يمكن اسختدام ملفات ذات فراغات sparse files. هذه الصيغة هي الصيغة المتداولة في أنظمة GNU/Linux. تدعم وحدة <code>tarfile</code> وبشكل <code>Gnu tar</code> للأسماء الطويلة، أما دعم الملفات ذات الفراغات فهو للقراءة فقط.
يمكن إنشاء ثلاث صيغ لملفات tar بواسطة الوحدة tarfile:
*صيغة <code>POSIX.1-2001 pax</code> (صيغة <code>PAX_FORMAT</code>). هذه الصيغة هي الأكثر مرونة من بين الصيغ المدعومة وهي غير محدودة نظريًا. تدعم هذه الصيغة أسماء الملفات والوصلات الطويلة، إلى جانب دعمها للملفات كبيرة الحجم وتخزّن المسارات بطريقة محمولة. ولكن ليس بمقدور أدوات tar المتوفّرة في الوقت الحاضر أن تتعامل مع ملفات الأرشيف من نوع pax.
 
صيغة pax هي امتداد لصيغة ustar الحالية، وتستخدم ترويسات إضافية للمعلومات التي لا يمكن تخزينها بطريقة أخرى. هناك نوعان من ترويسات pax: الأول: الترويسات الموسّعة والتي تؤثر على ترويسة الملف اللاحق، والترويسات العامة والتي تكون صالحة للاستخدام في ملف الأرشيف بأكمله وتؤثّر على جميع الملفات اللاحقة. يستخدم الترميز UTF-8 لترميز جميع البيانات في ترويسة pax وذلك لتسهيل نقلها من مكان إلى آخر.
* صيغة 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 والتي يمكن قرائتها بواسطة الوحدة دون التمكّن من إنشائها:
هناك أيضًا صيغ أخرى لملفات tar والتي يمكن قرائتها بواسطة الوحدة دون التمكّن من إنشائها:
 
*صيغة V7 القديمة، وهي أول صيغة tar وقد ظهرت في الإصدار السابع من Unix، وتخزّن هذه الصيغة الملفات والمجلدات العادية فقط. يجب أن لا يتجاوز اسم الملف في هذه الصيغة 100 حرف، ولا توجد معلومات عن المستخدم أو المجموعة. تعاني بعض ملفات الأرشيف من أخطاء في حساب دالة التحقق للترويسة عند وجود حقول تتضمن حروفًا خارج الترميز ASCII.
* صيغة V7 القديمة، وهي أول صيغة tar وقد ظهرت في الإصدار السابع من Unix، وتخزّن هذه الصيغة الملفات والمجلدات العادية فقط. يجب أن لا يتجاوز اسم الملف في هذه الصيغة 100 حرف، ولا توجد معلومات عن المستخدم أو المجموعة. تعاني بعض ملفات الأرشيف من أخطاء في حساب دالة التحقق للترويسة عند وجود حقول تتضمن حروفًا خارج الترميز ASCII.
*صيغة SunOS الموسّعة. هذه الصيغة هي شكل آخر للصيغة <code>POSIX.1-2001 pax</code>، ولكنّها غير متوافقة معها.
* صيغة SunOS الموسّعة. هذه الصيغة هي شكل آخر للصيغة POSIX.1-2001 pax، ولكنّها غير متوافقة معها.
==مشاكل Unicode==
 
== مشاكل Unicode ==
 
كان الهدف من إنشاء صيغة tar في الأصل إنشاء نسخة احتياطية لأشرطة التسجيل مع التركيز على فكرة الاحتفاظ بمعلومات النظام. أما اليوم فيشيع استخدام ملفات tar لتوزيع الملفات وتبادل ملفات الأرشيف عبر الشبكات. ولكن تعاني الصيغة الأصلية (والتي تمثل الأساس الذي بنيت علهي الصيغة الأخرى) من مشكلة عدم وجود مفهوم دعم ترميزات متنوعة للحروف. فعلى سبي المثال لا يمكن لأرشيف tar عادي أنشئ باستخدام الترميز UTF-8 أن يُقرأ بصورة صحيحة في نظام يعمل بالترميز Latin-1 إن كان الأرشيف يتضمّن محارف خارج الترميز ASCII، وستتعرض البيانات الوصفية النصية (مثل أسماء الملفات، وأسماء الوصلات، وأسماء المستخدم/المجموعة) للتلف، ولا توجد طريقة آلية للتعرّف على ترميز ملف الأرشيف. صمّمت صيغة pax للتغلّب على هذه المشكلة، إذ إنّها تحفظ البيانات الوصفية التي تكون خارج الترميز ASCII باستخدام الترميز العالمي UTF-8.
كان الهدف من إنشاء صيغة tar في الأصل إنشاء نسخة احتياطية لأشرطة التسجيل مع التركيز على فكرة الاحتفاظ بمعلومات النظام. أما اليوم فيشيع استخدام ملفات tar لتوزيع الملفات وتبادل ملفات الأرشيف عبر الشبكات. ولكن تعاني الصيغة الأصلية (والتي تمثل الأساس الذي بنيت علهي الصيغة الأخرى) من مشكلة عدم وجود مفهوم دعم ترميزات متنوعة للحروف. فعلى سبي المثال لا يمكن لأرشيف tar عادي أنشئ باستخدام الترميز UTF-8 أن يُقرأ بصورة صحيحة في نظام يعمل بالترميز Latin-1 إن كان الأرشيف يتضمّن محارف خارج الترميز ASCII، وستتعرض البيانات الوصفية النصية (مثل أسماء الملفات، وأسماء الوصلات، وأسماء المستخدم/المجموعة) للتلف، ولا توجد طريقة آلية للتعرّف على ترميز ملف الأرشيف. صمّمت صيغة pax للتغلّب على هذه المشكلة، إذ إنّها تحفظ البيانات الوصفية التي تكون خارج الترميز ASCII باستخدام الترميز العالمي UTF-8.


تتحكّم المعاملات المفتاحية encoding و errors في صنف TarFile بتفاصيل عملية تحويل المحارف في وحدة tarfile.
تتحكّم [[Python/arguments|المعاملات المفتاحية]] <code>encoding</code> و <code>errors</code> في صنف [[Python/TarFile|TarFile]] بتفاصيل عملية تحويل المحارف في وحدة <code>tarfile</code>.
 
يعرّف المعامل encoding ترميز الحروف الذي سيُستخدم لترميز البيانات الوصفية في الأرشيف. يأخذ هذا المعامل قيمة افتراضية هي نتيجة استدعاء الدالة sys.getfilesystemencoding()‎ أو القيمة 'ascii' في حال عدم الحصول على نتيجة من الاستدعاء السابق. يجب ترميز البيانات الوصفية أو فك ترميزها بالاعتماد على ما إذا كان الأرشيف مفتوحًا للقراءة أو للكتابة. ويجدر التنبيه إلى أنّه في حال عدم تهيئة الترميز بطريقة صحيحة، فإنّ عملية التحويل ستفشل.
 
يعرّف المعامل errors طريقة التعامل مع المحارف التي لا يمكن تحويلها. يأخذ هذا المعامل قيمتين هما 'strict' والتي تطلق الاستثناء UnicodeError عند عدم التمكن من تحويل المحارف، و'ignore' والتي تؤدي إلى الاستمرار في تنفيذ الشيفرة وتجاهل أخطاء التحويل.
تستخدم بايثون النظام الافتراضي 'surrogateescape' والمستخدم من قبل اللغة في استدعاءات نظام الملفات.
 
في حال استخدام ملفات الأرشيف ذات الصيغة PAX_FORMAT فلا حاجة لاستخدام المعامل encoding لأنّ جميع البيانات الوصفية تخزّن بترميز UTF-8، ويستخدم المعامل encoding في الحالات النادرة التي يفكّ فيها ترميز ترويسة pax الثنائية أو عند تخزين سلاسل نصية تتضمّن محارف بديلة surrogate.


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


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


== مصادر ==
تستخدم بايثون النظام الافتراضي <code>'surrogateescape'</code> والمستخدم من قبل اللغة في استدعاءات نظام الملفات.
[https://docs.python.org/3/library/tarfile صفحة Read and write tar archive files في توثيق بايثون الرسمي.]


في حال استخدام ملفات الأرشيف ذات الصيغة <code>PAX_FORMAT</code> فلا حاجة لاستخدام المعامل <code>encoding</code> لأنّ جميع البيانات الوصفية تخزّن بترميز UTF-8، ويستخدم المعامل <code>encoding</code> في الحالات النادرة التي يفكّ فيها ترميز ترويسة pax الثنائية أو عند تخزين سلاسل نصية تتضمّن محارف بديلة surrogate.
==انظر أيضًا==
*[[Python/zipfile|الوحدة <code>zipfile</code>]]: تقدّم هذه الوحدة أدواة لإنشاء ملفات ZIP والقراءة منها والكتابة فيها وإلحاق الملفات بها وعرض محتوياتها.
==مصادر==
* <span> </span>[https://docs.python.org/3/library/tarfile صفحة Read and write tar archive files في توثيق بايثون الرسمي.]
[[تصنيف:Python]]
[[تصنيف:Python]]
[[تصنيف:Python Modules]]
[[تصنيف:Python Modules]]
[[تصنيف:Python Methods]]
[[تصنيف:Python Methods]]

مراجعة 18:56، 12 نوفمبر 2018


تتيح وحدة 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 والقراءة منها والكتابة فيها وإلحاق الملفات بها وعرض محتوياتها.

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Python/tarfile&oldid=23284»