الفرق بين المراجعتين ل"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> | ||
| − | الدالة البانية للصنف | + | الدالة البانية للصنف <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>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>. | |
| − | == توابع الكائن GzipFile وخصائصه == | + | يدعم الصنف <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> مثلًا). | |
| − | صحيح أن استدعاء التابع peek() لا يؤدي إلى تغيير في موقع الملف في كائن | ||
| − | |||
| − | + | '''ملاحظة:''' هذا التابع جديد في الإصدار 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 في توثيق بايثون الرسمي.] | * [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 من بايثون.