عرض مصدر Python/GzipFile

<noinclude>{{DISPLAYTITLE:الصنف <code>gzip.GzipFile‎</code> في بايثون}}</noinclude>

الدالة البانية للصنف <code>GzipFile</code>، والذي يقدّم محاكاة لمعظم توابع كائن الملف باستثناء التابع <code>truncate()</code>‎.

==البنية العامة==
<syntaxhighlight lang="python3">
gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)
</syntaxhighlight>
==المعاملات==
===<code>filename</code> و <code>fileobj</code>===
يجب أن يأخذ أحد المعاملين <code>fileobj</code> و <code>filename</code> على الأقل قيمة غير بسيطة non-trivial value.

تستند النسخة الجديدة من الصنف على الكائن <code>fileobj</code>، والذي يمكن أن يكون ملفًّا عاديًا، أو كائن <code>[[Python/BytesIO|io.BytesIO]]</code> أو اي كائن آخر يحاكي الملفات. يأخذ هذا المعامل القيمة <code>None</code>، وفي مثل هذه الحالة يُفتح <code>filename</code> لتوفير كائن ملف.

عندما لا تكون قيمة المعامل <code>fileobj</code> هي <code>None</code>، يستخدم المعامل <code>filename</code> فقط لإدراجه في ترويسة ملف gzip، والتي يمكن أن تتضمن اسم الملف الأصلي غير المضغوط. يأخذ هذا المعامل قيمة افتراضية هي اسم الملف في <code>fileobj</code> -إن كان بالإمكان التعرف على الاسم- وإلّا فإنّ القيمة الافتراضية تكون سلسلة نصية فارغة، وفي هذه الحالة لا يُضمَّن اسم الملف الأصلي في الترويسة.

لاحظ أنّ الملف يبقى مفتوحًا دائمًا في النمط الثنائي. ولفتح ملف مضغوط في النمط النصي يمكن استخدام الدالة <code>open()‎</code> أو (تغليف صنف <code>GzipFile</code> بنسخة من <code>io.TextIOWrapper</code>).
===<code>mode</code>===
يمكن أن يأخذ المعامل <code>mode</code> إحدى القيم التالية ‎<code>'r'</code> ،<code>'rb'</code> ،<code>'a'</code> ،<code>'ab'</code> ،<code>'w'</code> ،<code>'wb'</code> ،<code>'x'</code>  <code>'xb'</code>‎ بالاعتماد على ما إذا كان المطلوب القراءة من الملف أو الكتابة فيه. القيمة الافتراضية لهذا المعامل هي قيمة وضع الكائن <code>fileobj</code> إن كان بالإمكان التعرّف عليها، وإلّا تكون القيمة الافتراضية هي <code>'rb'</code>.

=== <code>compresslevel</code> ===
عدد صحيح يتدرّج بين <code>0</code> و <code>9</code> ويحدّد نسبة الضغط. ينتج عن استخدام العدد <code>1</code> عملية ضغط سريعة مع أقل مقدار من الضغط، أما العدد <code>9</code> فينتج عنه عملية ضغط بكيئة ولكن مع أكبر مقدار ممكن من الضغط. أما العدد <code>0</code> فيعني عدم ضغط الملف. القيمة الافتراضية لهذا المعامل هي <code>9</code>.

=== <code>mtime</code> ===
هو ختم زمني عددي اختياري تجري كتابته في حقل (وقت آخر تعديل) في تدفق البيانات عند إجراء عملية الضغط. يجب تقديم قيمة لهذا المعامل في وضع الضغط فقط، وتستخدم الدالة البانية التاريخ الحالي إن لم يُعط هذا المعامل أيّ قيمة أو أعطي القيمة <code>None</code>. راجع الخاصية <code>mtime</code> لمزيد من التفاصيل.

لا يؤدي استدعاء التابع <code>close()‎</code> في كائنات <code>GzipFile</code> إلى إغلاق الملف <code>fileobj</code>، وذلك لأنّك قد تحتاج إلى إضافة المزيد من البيانات بعد البيانات المضغوط. ويتيح لك هذا الأمر أيضًا أن تمرر نسخة من كائن <code>io.BytesIOobject</code> مفتوحٍ للكتابة على هيئة <code>fileobj</code> واستعادة الذاكرة المؤقتة الناتجة باستخدام التابع <code>getvalue()‎</code> في الكائن <code>io.BytesIO</code>.

يدعم الصنف <code>GzipFile</code> واجهة <code>io.BufferedIOBase</code> بما في ذلك التكرار وعبارة <code>with</code> وباستثناء التابع <code>truncate()‎</code> فإنّه غير مدعوم.
==توابع الكائن <code>GzipFile</code> وخصائصه==
تقدّم كائنات <code>GzipFile</code> التوابع والخصائص التالية:

=== التابع [[Python/GzipFile/peek|<code>peek(n)</code>‎]] ===
يقرأ التابع العدد المحدد من البيانات المضغوطة دون تقديم موقع الملف.

'''ملاحظة:'''

صحيح أن استدعاء التابع <code>peek()‎</code> لا يؤدي إلى تغيير في موقع الملف في كائن <code>GzipFile</code>، ولكنّه قد يؤدي إلى إحداث تغيير في كائن الملف الداخلي (إذا كان كائن <code>GzipFile</code> قد بُني مع استخدام المعامل <code>fileobj</code> مثلًا).

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

=== الخاصية <code>mtime</code> ===
يمكن قراءة قيمة الحقل (وقت آخر تعديل) في آخر ترويسة مقروءة عند إجراء عملية فك الضغط بواسطة هذه الخاصية، وتكون النتيجة عددًا صحيحًا. تكون القيمة الابتدائية لهذه الخاصية قبل قراءة أيّ ترويسة هي القيمة <code>None</code>.

يجب أن تتضمّن جميع البيانات المضغوطة بواسطة gzip حقل الختم الزمني هذا، إذ تستخدم بعض البرامج، مثل gunzip، هذا الختم الزمني في عملها، وتكون صيغته مشابهة للقيمة المعادة من الدالة <code>[[Python/time/time|time.time()‎]]</code> ولقيمة الخاصية <code>st_mtime</code> في الكائن المعاد من الدالة <code>[[Python/os/stat|os.stat()‎]]</code>.

'''ملاحظات''':
*أضيف دعم عبارات <code>with</code> والمعامل <code>mtime</code> في الدالة البانية وخاصية <code>mtime</code> في الإصدار 3.1 من بايثون.
*أضيف دعم الملفات التي تبدأ بالأصفار والملفات غير القابلة للبحث في الإصدار 3.2 من بايثون.
*اعتمد التابع <code>io.BufferedIOBase.read1()</code>‎ في الإصدار 3.3 من بايثون.
*أضيف دعم الوضعين <code>'x'</code> و <code>'xb'</code> في الإصدار 3.4 من بايثون.
*في الإصدار 3.5 من بايثون أصبح بالإمكان كتابة كائنات شبيهة بالبايتات متنوّعة، إضافة إلى أنّ التابع <code>read()‎</code> أصبح يستقبل معاملًا يحمل القيمة <code>None</code>.
*أضيف دعم الكائنات الشبيهة بالملفات في الإصدار 3.6 من بايثون.
==مصادر==
* [https://docs.python.org/3/library/gzip.html صفحة Support for gzip files في توثيق بايثون الرسمي.]
[[تصنيف:Python]]
[[تصنيف:Python Modules]]