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

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


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


==البنية العامة==
<syntaxhighlight lang="python3">
<syntaxhighlight lang="python3">
gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)
gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)
</syntaxhighlight>
</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>filename</code> و <code>fileobj</code> ===
 
يجب أن يأخذ أحد المعاملين fileobj و filename على الأقل قيمة غير بسيطة non-trivial value.
 
تستند النسخة الجديدة من الصنف على الكائن fileobj، والذي يمكن أن يكون ملفًّا عاديًا، أو كائن io.BytesIO أو اي كائن آخر يحاكي الملفات. يأخذ هذا المعامل القيمة None، وفي مثل هذه الحالة يُفتح filename لتوفير كائن ملف.
 
عندما لا تكون قيمة المعامل fileobj هي None، يستخدم المعامل filename فقط لإدراجه في ترويسة ملف gzip، والتي يمكن أن تتضمن اسم الملف الأصلي غير المضغوط. يأخذ هذا المعامل قيمة افتراضية هي اسم الملف في fileobj -إن كان بالإمكان التعرف على الاسم- وإلّا فإنّ القيمة الافتراضية تكون سلسلة نصية فارغة، وفي هذه الحالة لا يُضمَّن اسم الملف الأصلي في الترويسة.
 
لاحظ أنّ الملف يبقى مفتوحًا دائمًا في النمط الثنائي. ولفتح ملف مضغوط في النمط النصي يمكن استخدام الدالة open()‎ أو (تغليف صنف GzipFile بنسخة من io.TextIOWrapper).
 
=== <code>mode</code> ===


يمكن أن يأخذ المعامل mode إحدى القيم التالية ‎'r' ،'rb' ،'a' ،'ab' ،'w' ،'wb' ،'x'  'xb'‎ بالاعتماد على ما إذا كان المطلوب القراءة من الملف أو الكتابة فيه. القيمة الافتراضية لهذا المعامل هي قيمة وضع الكائن fileobj إن كان بالإمكان التعرّف عليها، وإلّا تكون القيمة الافتراضية هي 'rb'.
عندما لا تكون قيمة المعامل <code>fileobj</code> هي <code>None</code>، يستخدم المعامل <code>filename</code> فقط لإدراجه في ترويسة ملف gzip، والتي يمكن أن تتضمن اسم الملف الأصلي غير المضغوط. يأخذ هذا المعامل قيمة افتراضية هي اسم الملف في <code>fileobj</code> -إن كان بالإمكان التعرف على الاسم- وإلّا فإنّ القيمة الافتراضية تكون سلسلة نصية فارغة، وفي هذه الحالة لا يُضمَّن اسم الملف الأصلي في الترويسة.


compresslevel
لاحظ أنّ الملف يبقى مفتوحًا دائمًا في النمط الثنائي. ولفتح ملف مضغوط في النمط النصي يمكن استخدام الدالة <code>open()‎</code> أو (تغليف صنف <code>GzipFile</code> بنسخة من <code>io.TextIOWrapper</code>).
عدد صحيح يتدرّج بين 0 و 9 ويحدّد نسبة الضغط. ينتج عن استخدام العدد 1 عملية ضغط سريعة مع أقل مقدار من الضغط، أما العدد 9 فينتج عنه عملية ضغط بكيئة ولكن مع أكبر مقدار ممكن من الضغط. أما العدد 0 فيعني عدم ضغط الملف. القيمة الافتراضية لهذا المعامل هي 9.
===<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>.


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


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


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


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


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


peek(n)
'''ملاحظة:'''
يقرأ التابع العدد المحدد من البيانات المضغوطة دون تقديم موقع الملف. يُجري التابع عند استدعائه قراءة واحدة على الأكثر على تدفق البيانات المضغوطة، ويمكن لعدد البايتات المعادة أن يكون أقل أو أكثر من المطلوب.


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


mtime
'''ملاحظة:''' هذا التابع جديد في الإصدار 3.2 من بايثون.
يمكن قراءة قيمة الحقل (وقت آخر تعديل) في آخر ترويسة مقروءة عند إجراء عملية فك الضغط بواسطة هذه الخاصية، وتكون النتيجة عددًا صحيحًا. تكون القيمة الابتدائية لهذه الخاصية قبل قراءة أيّ ترويسة هي القيمة None.


يجب أن تتضمّن جميع البيانات المضغوطة بواسطة gzip حقل الختم الزمني هذا، إذ تستخدم بعض البرامج، مثل gunzip، هذا الختم الزمني في عملها، وتكون صيغته مشابهة للقيمة المعادة من الدالة time.time()‎ ولقيمة الخاصية st_mtime في الكائن المعاد من الدالة os.stat()‎.
=== الخاصية <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>.
* أضيف دعم عبارات with والمعامل mtime في الدالة البانية وخاصية mtime في الإصدار 3.1 من بايثون.
* أضيف دعم الملفات التي تبدأ بالأصفار والملفات غير القابلة للبحث في الإصدار 3.2 من بايثون.
* اعتمد التابع io.BufferedIOBase.read1()‎ في الإصدار 3.3 من بايثون.
* أضيف دعم الوضعين 'x' و 'xb' في الإصدار 3.4 من بايثون.
* في الإصدار 3.5 من بايثون أصبح بالإمكان كتابة كائنات شبيهة بالبايتات متنوّعة، إضافة إلى أنّ التابع read()‎ أصبح يستقبل معاملًا يحمل القيمة None.
* أضيف دعم الكائنات الشبيهة بالملفات في الإصدار 3.6 من بايثون.


== مصادر ==
'''ملاحظات''':
*أضيف دعم عبارات <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 في توثيق بايثون الرسمي.]
* [https://docs.python.org/3/library/gzip.html صفحة Support for gzip files في توثيق بايثون الرسمي.]
[[تصنيف:Python]]
[[تصنيف:Python]]
[[تصنيف:Python Modules]]
[[تصنيف:Python Modules]]

مراجعة 12:30، 10 نوفمبر 2018


الدالة البانية للصنف 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 من بايثون.

مصادر

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