الصنف gzip.GzipFile في بايثون
الدالة البانية للصنف GzipFile، والذي يقدّم محاكاة لمعظم توابع كائن الملف باستثناء التابع truncate().
البنية العامة
gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)
المعاملات
filename و fileobj
يجب أن يأخذ أحد المعاملين fileobj و filename على الأقل قيمة غير بسيطة non-trivial value.
تستند النسخة الجديدة من الصنف على الكائن fileobj، والذي يمكن أن يكون ملفًّا عاديًا، أو كائن io.BytesIO أو اي كائن آخر يحاكي الملفات. يأخذ هذا المعامل القيمة None، وفي مثل هذه الحالة يُفتح filename لتوفير كائن ملف.
عندما لا تكون قيمة المعامل fileobj هي None، يستخدم المعامل filename فقط لإدراجه في ترويسة ملف gzip، والتي يمكن أن تتضمن اسم الملف الأصلي غير المضغوط. يأخذ هذا المعامل قيمة افتراضية هي اسم الملف في fileobj -إن كان بالإمكان التعرف على الاسم- وإلّا فإنّ القيمة الافتراضية تكون سلسلة نصية فارغة، وفي هذه الحالة لا يُضمَّن اسم الملف الأصلي في الترويسة.
لاحظ أنّ الملف يبقى مفتوحًا دائمًا في النمط الثنائي. ولفتح ملف مضغوط في النمط النصي يمكن استخدام الدالة open() أو (تغليف صنف GzipFile بنسخة من io.TextIOWrapper).
mode
يمكن أن يأخذ المعامل mode إحدى القيم التالية 'r' ،'rb' ،'a' ،'ab' ،'w' ،'wb' ،'x' 'xb' بالاعتماد على ما إذا كان المطلوب القراءة من الملف أو الكتابة فيه. القيمة الافتراضية لهذا المعامل هي قيمة وضع الكائن fileobj إن كان بالإمكان التعرّف عليها، وإلّا تكون القيمة الافتراضية هي 'rb'.
compresslevel عدد صحيح يتدرّج بين 0 و 9 ويحدّد نسبة الضغط. ينتج عن استخدام العدد 1 عملية ضغط سريعة مع أقل مقدار من الضغط، أما العدد 9 فينتج عنه عملية ضغط بكيئة ولكن مع أكبر مقدار ممكن من الضغط. أما العدد 0 فيعني عدم ضغط الملف. القيمة الافتراضية لهذا المعامل هي 9.
mtime هو ختم زمني عددي اختياري تجري كتابته في حقل (وقت آخر تعديل) في تدفق البيانات عند إجراء عملية الضغط. يجب تقديم قيمة لهذا المعامل في وضع الضغط فقط، وتستخدم الدالة البانية التاريخ الحالي إن لم يُعط هذا المعامل أيّ قيمة أو أعطي القيمة None. راجع الخاصية mtime لمزيد من التفاصيل.
لا يؤدي استدعاء التابع close() في كائنات GzipFile إلى إغلاق الملف fileobj، وذلك لأنّك قد تحتاج إلى إضافة المزيد من البيانات بعد البيانات المضغوط. ويتيح لك هذا الأمر أيضًا أن تمرر نسخة من كائن io.BytesIOobject مفتوحٍ للكتابة على هيئة fileobj واستعادة الذاكرة المؤقتة الناتجة باستخدام التابع getvalue() في الكائن io.BytesIO.
يدعم الصنف GzipFile واجهة io.BufferedIOBase بما في ذلك التكرار وعبارة with وباستثناء التابع truncate() فإنّه غير مدعوم.
توابع الكائن GzipFile وخصائصه
تقدّم كائنات GzipFile التوابع والخصائص التالية:
peek(n) يقرأ التابع العدد المحدد من البيانات المضغوطة دون تقديم موقع الملف. يُجري التابع عند استدعائه قراءة واحدة على الأكثر على تدفق البيانات المضغوطة، ويمكن لعدد البايتات المعادة أن يكون أقل أو أكثر من المطلوب.
ملاحظة: صحيح أن استدعاء التابع peek() لا يؤدي إلى تغيير في موقع الملف في كائن GzipFile، ولكنّه قد يؤدي إلى إحداث تغيير في كائن الملف الداخلي (إذا كان كائن GzipFile قد بُني مع استخدام المعامل fileobj مثلًا). هذا التابع جديد في الإصدار 3.2 من بايثون.
mtime يمكن قراءة قيمة الحقل (وقت آخر تعديل) في آخر ترويسة مقروءة عند إجراء عملية فك الضغط بواسطة هذه الخاصية، وتكون النتيجة عددًا صحيحًا. تكون القيمة الابتدائية لهذه الخاصية قبل قراءة أيّ ترويسة هي القيمة None.
يجب أن تتضمّن جميع البيانات المضغوطة بواسطة gzip حقل الختم الزمني هذا، إذ تستخدم بعض البرامج، مثل gunzip، هذا الختم الزمني في عملها، وتكون صيغته مشابهة للقيمة المعادة من الدالة time.time() ولقيمة الخاصية st_mtime في الكائن المعاد من الدالة os.stat().
ملاحظات:
- أضيف دعم عبارات with والمعامل mtime في الدالة البانية وخاصية mtime في الإصدار 3.1 من بايثون.
- أضيف دعم الملفات التي تبدأ بالأصفار والملفات غير القابلة للبحث في الإصدار 3.2 من بايثون.
- اعتمد التابع io.BufferedIOBase.read1() في الإصدار 3.3 من بايثون.
- أضيف دعم الوضعين 'x' و 'xb' في الإصدار 3.4 من بايثون.
- في الإصدار 3.5 من بايثون أصبح بالإمكان كتابة كائنات شبيهة بالبايتات متنوّعة، إضافة إلى أنّ التابع read() أصبح يستقبل معاملًا يحمل القيمة None.
- أضيف دعم الكائنات الشبيهة بالملفات في الإصدار 3.6 من بايثون.