الفرق بين المراجعتين لصفحة: «Python/open»
< Python
ط ←errors |
لا ملخص تعديل |
||
| (مراجعتان متوسطتان بواسطة مستخدمين اثنين آخرين غير معروضتين) | |||
| سطر 1: | سطر 1: | ||
تفتح الدّالة <code>open()</code> ملفّا وتعيد كائن ملفّ (file object) مرتبط به. | تفتح الدّالة <code>open()</code> ملفّا وتعيد كائن ملفّ (file object) مرتبط به. | ||
إن لم يُمكِن فتح الملفّ، فسيُطلَق | إن لم يُمكِن فتح الملفّ، فسيُطلَق الاستثناء <code>[[Python/built-in exceptions#OSError|OSError]]</code>. | ||
== البنية العامة == | == البنية العامة == | ||
| سطر 10: | سطر 9: | ||
== المعاملات == | == المعاملات == | ||
=== <code>file</code> === | === <code>file</code> === | ||
كائن مُشابه للمسارات (path-like object) يُمثّل مسار الملفّ (سواء أكان مُطلقا أو نسبيًّا) المرغوب فتحه. | كائن مُشابه للمسارات (path-like object) يُمثّل مسار الملفّ (سواء أكان مُطلقا أو نسبيًّا) المرغوب فتحه. | ||
| سطر 18: | سطر 18: | ||
مُعامل اختياريّ. | مُعامل اختياريّ. | ||
سلسلة نصيّة تُحدّد الوضع الذي سيُفتح فيه الملفّ. القيمة الافتراضيّة هي <code>'r'</code> والتي تعني أنّ الملفّ سيُفتح في وضع القراءة. | سلسلة نصيّة تُحدّد الوضع الذي سيُفتح فيه الملفّ. القيمة الافتراضيّة هي <code>'r'</code> والتي تعني أنّ الملفّ سيُفتح في وضع القراءة. ومن القيم الشّائعة: | ||
ومن القيم الشّائعة: | |||
* <code>'w'</code> لفتح الملفّ في وضع الكتابة (مع حذف الملفّ إن كان موجودًا مُسبقًا). | * <code>'w'</code> لفتح الملفّ في وضع الكتابة (مع حذف الملفّ إن كان موجودًا مُسبقًا). | ||
* <code>'x'</code> لإنشاء الملفّات حصرًا. | * <code>'x'</code> لإنشاء الملفّات حصرًا. | ||
* <code>'a'</code> لإضافة المحتويات إلى نهاية الملفّ دون حذفه إن كان موجودًا مُسبقًا (والتي تعني في بعض أنظمة | * <code>'a'</code> لإضافة المحتويات إلى نهاية الملفّ دون حذفه إن كان موجودًا مُسبقًا (والتي تعني في بعض أنظمة يونكس أنّ الكتابة ستكون دائمًا على نهاية الملفّ بغضّ النّظر عن موقع المؤشر الحاليّ). | ||
والأوضاع المُتاحة هي كالتّالي: | والأوضاع المُتاحة هي كالتّالي: | ||
{| class="wikitable" | {| class="wikitable" | ||
!المحرف | !المحرف | ||
! | !المعنى | ||
|- | |- | ||
|<code>'r'</code> | |<code>'r'</code> | ||
| فتح الملفّ للقراءة (الوضع الافتراضيّ) | |فتح الملفّ للقراءة (الوضع الافتراضيّ) | ||
|- | |- | ||
|<code>'w'</code> | |<code>'w'</code> | ||
| فتح الملفّ للكتابة، مع حذف محتويات الملفّ إن كان موجودًا | |فتح الملفّ للكتابة، مع حذف محتويات الملفّ إن كان موجودًا | ||
|- | |- | ||
|<code>'x'</code> | |<code>'x'</code> | ||
| فتح الملفّ للإنشاء حصرًا، أي أنّ فتح الملفّ سيفشل إن كان موجودًا مُسبقًا | |فتح الملفّ للإنشاء حصرًا، أي أنّ فتح الملفّ سيفشل إن كان موجودًا مُسبقًا | ||
|- | |- | ||
|<code>'a'</code> | |<code>'a'</code> | ||
| فتح الملفّ للكتابة مع الكتابة إلى نهاية الملفّ إن كان موجودًا مُسبقًا | |فتح الملفّ للكتابة مع الكتابة إلى نهاية الملفّ إن كان موجودًا مُسبقًا | ||
|- | |- | ||
|<code>'b'</code> | |<code>'b'</code> | ||
| الوضع الثّنائي (binary mode) | |الوضع الثّنائي (binary mode) | ||
|- | |- | ||
|<code>'t'</code> | |<code>'t'</code> | ||
| وضع النّصوص (الوضع الافتراضيّ) | |وضع النّصوص (الوضع الافتراضيّ) | ||
|- | |- | ||
|<code>'+'</code> | |<code>'+'</code> | ||
| فتح ملفّ على القرص لتعديله (القراءة والكتابة) | |فتح ملفّ على القرص لتعديله (القراءة والكتابة) | ||
|- | |- | ||
|<code>'U'</code> | |<code>'U'</code> | ||
| وضع الأسطر الجديدة العامّة (universal newlines) وهو وضع مُهمل لا يجب استخدامه. | |وضع الأسطر الجديدة العامّة (universal newlines) وهو وضع مُهمل لا يجب استخدامه. | ||
|- | |- | ||
|} | |} | ||
الوضع الافتراضي هو <code>'r'</code> (لفتح الملفّ لقراءة النّصوص، وهو نفسه الوضع <code>'rt'</code>). للقراءة والكتابة للملفّ بشكل ثُنائيّ، يُمكن استخدام الوضع <code>'w+b'</code> لفتح ملفّ وحذف محتوياته إلى 0 بايت. والوضع <code>'r+b'</code> يفتح الملفّ دون حذف محتوياته. | الوضع الافتراضي هو <code>'r'</code> (لفتح الملفّ لقراءة النّصوص، وهو نفسه الوضع <code>'rt'</code>). للقراءة والكتابة للملفّ بشكل ثُنائيّ، يُمكن استخدام الوضع <code>'w+b'</code> لفتح ملفّ وحذف محتوياته إلى 0 بايت. والوضع <code>'r+b'</code> يفتح الملفّ دون حذف محتوياته. | ||
| سطر 68: | سطر 64: | ||
عندما لا تُمرّر أيّة مُعاملات إلى المُعامل <code>buffering</code> فستعمل سياسة التّخزين الانتقاليّ كما يلي: | عندما لا تُمرّر أيّة مُعاملات إلى المُعامل <code>buffering</code> فستعمل سياسة التّخزين الانتقاليّ كما يلي: | ||
* تُخزّن الملفّات الثّنائيّة في قطع ثابتة الحجم؛ يُحدَّدُ حجم المخزن عبر محاولة الحصول على حجم القطع (block size) الخاصّ بالجهاز، أو تُستعمل القيمة <code>[[Python/io/DEFAULT BUFFER SIZE|io.DEFAULT_BUFFER_SIZE]]</code> إن فشلت المُحاولة. يكون حجم المخزن في العديد من الأنظمة عادةً إمّا 4096 أو 8192 بايت. | |||
* تستعمل الملفّات النّصيّة التّفاعليّة (التي يُعيد فيها استدعاء التّابع <code>[[Python/io/IOBase|isatty()]]</code> القيمة <code>True</code>) تخزين الأسطر. أمّا الملفّات النّصيّة الأخرى فتستعمل سياسة الملفّات الثّنائية الموضّحة أعلاه. | |||
* تستعمل الملفّات النّصيّة التّفاعليّة (التي يُعيد فيها استدعاء التّابع <code>isatty()</code> القيمة <code>True</code>) تخزين الأسطر. أمّا الملفّات النّصيّة الأخرى فتستعمل سياسة الملفّات الثّنائية الموضّحة أعلاه. | |||
=== <code>encoding</code> === | === <code>encoding</code> === | ||
مُعامل اختياريّ. | مُعامل اختياريّ. | ||
اسم التّرميز الذي سيُستعمل لفكّ ترميز وترميز الملفّ. يجب استخدامه فقط في وضع الملفّات النّصيّة. | اسم التّرميز الذي سيُستعمل لفكّ ترميز وترميز الملفّ. يجب استخدامه فقط في وضع الملفّات النّصيّة. في وضع الملفّات النّصيّة، إن لم تُمرّر قيمة للمُعامل <code>encoding</code> فالتّرميز المستخدم سيعتمد على نظام التّشغيل، وسيُستعمل الاستدعاء <code>[[Python/locale/getpreferredencoding|locale.getpreferredencoding(False)]]</code> للحصول على التّرميز المحليّ. (ولقراءة وكتابة البايتات الخام، استعمل الوضع الثّنائي واترك تحديد قيمة للمُعامل <code>encoding</code>.) لكن يُمكن استخدام أي ترميز نصوص تدعمه بايثون. انظر الوحدة <code>[[Python/codecs|codecs]]</code> للحصول على قائمة بالتّرميزات المدعومة. | ||
في وضع الملفّات النّصيّة، إن لم تُمرّر قيمة للمُعامل <code>encoding</code> فالتّرميز المستخدم سيعتمد على نظام التّشغيل، وسيُستعمل الاستدعاء <code>locale.getpreferredencoding(False)</code>للحصول على التّرميز المحليّ. (ولقراءة وكتابة البايتات الخام، استعمل الوضع الثّنائي واترك تحديد قيمة للمُعامل <code>encoding</code>.) | |||
لكن يُمكن استخدام أي ترميز نصوص تدعمه بايثون. انظر الوحدة codecs للحصول على قائمة بالتّرميزات المدعومة. | |||
=== <code>errors</code> === | === <code>errors</code> === | ||
مُعامل اختياريّ. | مُعامل اختياريّ. | ||
سلسلة نصيّة تُحدّد كيفيّة مُعالجة أخطاء ترميز الملفّات وفكّ ترميزها. ولا يُمكن استخدامه في الوضع الثّنائي. | سلسلة نصيّة تُحدّد كيفيّة مُعالجة أخطاء ترميز الملفّات وفكّ ترميزها. ولا يُمكن استخدامه في الوضع الثّنائي. هناك العديد من مُعالجات الأخطاء القياسيّة المتوفّرة (انظر قائمة معالجات الأخطاء)، لكن يُمكن كذلك استعمال أي اسم مُعالج أخطاء مُسجّل بالدّالة <code>[[Python/codecs/register error|codecs.register_error()]]</code>. أسماء مُعالجات الأخطاء القياسيّة تشمل ما يلي: | ||
هناك العديد من مُعالجات الأخطاء القياسيّة المتوفّرة (انظر قائمة معالجات الأخطاء)، لكن يُمكن كذلك استعمال أي اسم مُعالج أخطاء مُسجّل بالدّالة <code> | |||
* <code>'strict'</code> لإطلاق استثناء <code>ValueError</code> إن حدث خطأ في التّرميز. والقيمة الافتراضيّة للمُعامل (أي القيمة <code>None</code>) لها نفس التأثير. | * <code>'strict'</code> لإطلاق استثناء <code>ValueError</code> إن حدث خطأ في التّرميز. والقيمة الافتراضيّة للمُعامل (أي القيمة <code>None</code>) لها نفس التأثير. | ||
* <code>'ignore'</code> لتجاهل الأخطاء. لكن انتبه إلى أنّ تجاهل أخطاء التّرميز قد يتسبّب في فقدان البيانات. | * <code>'ignore'</code> لتجاهل الأخطاء. لكن انتبه إلى أنّ تجاهل أخطاء التّرميز قد يتسبّب في فقدان البيانات. | ||
| سطر 97: | سطر 88: | ||
مُعامل اختياريّ. | مُعامل اختياريّ. | ||
يتحكّم بكيفيّة عمل وضع الأسطر الجديدة العامّ (universal newlines mode) في الوضع النّصيّ. يُمكن للقيم أن تكون <code>None</code>، أو | يتحكّم بكيفيّة عمل وضع الأسطر الجديدة العامّ (universal newlines mode) في الوضع النّصيّ. يُمكن للقيم أن تكون <code>None</code>، أو ''، أو <code>'\n'</code>، أو <code>'\r'</code>، أو <code>'\r\n'</code>. وتعمل كما يلي:'' | ||
* عند قراءة المُدخلات من التّيار (stream)، يكون وضع الأسطر الجديدة العامّ مُفعّلًا إن كانت قيمة المعامل <code>newline</code> تُساوي <code>None</code>. يُمكن للأسطر في المُدخل أن تنتهي بالمقطع <code>'\n'</code>، أو <code>'\r'</code>، أو <code>'\r\n'</code> وستُترجم إلى <code>'\n'</code> قبل إعادتها إلى المُستدعي. وإن كانت قيمة المعامل <code>newline</code> تُساوي <code>''</code> فإنّ وضع الأسطر الجديدة العامّ يكون مُفعّلًا، لكنّ نهايات الأسطر تُعاد إلى المُستدعِي دون ترجمتها. وإن كانت قيمة المعامل <code>newline</code> تُساوي أيًّا من القيم الأخرى المسموح بها، فستنتهي الأسطر بالقيمة المُعطاة فقط، وستُعاد نهايات الأسطر إلى المُستدعِي دون ترجمتها. | |||
* عند قراءة المُدخلات من التّيار (stream)، يكون وضع الأسطر الجديدة العامّ مُفعّلًا إن كانت قيمة المعامل <code>newline</code> تُساوي <code>None</code>. يُمكن للأسطر في المُدخل أن تنتهي بالمقطع <code>'\n'</code>، أو <code>'\r'</code>، أو <code>'\r\n'</code> وستُترجم إلى <code>'\n'</code> قبل إعادتها إلى المُستدعي. وإن كانت قيمة المعامل <code>newline</code> تُساوي <code>''</code> فإنّ وضع الأسطر الجديدة العامّ يكون مُفعّلًا، لكنّ نهايات الأسطر تُعاد إلى المُستدعِي دون ترجمتها. وإن كانت قيمة المعامل <code>newline</code> تُساوي أيًّا من القيم الأخرى المسموح بها، فستنتهي الأسطر بالقيمة المُعطاة فقط، وستُعاد نهايات الأسطر إلى المُستدعِي دون ترجمتها. | * عند الكتابة إلى الملفّ، إن كانت قيمة المعامل <code>newline</code> تُساوي <code>None</code>، فستُترجم أيّة محارف <code>'\n'</code> إلى فاصل الأسطر الافتراضي لنظام التّشغيل، والذي يُمكن الوصول إليه عبر الخاصيّة <code>[[Python/os/linesep|os.linesep]]</code>. وإن كانت قيمة المعامل <code>newline</code> تُساوي <code>''</code> أو <code>'\n'</code> فلن تُترجم نهايات الأسطر. وإن كانت قيمة المعامل <code>newline</code> تُساوي أيًّا من القيم الأخرى المسموح بها، فستُترجم أيّة محارف <code>'\n'</code> إلى القيمة المُعطاة. | ||
* عند الكتابة إلى الملفّ، إن كانت قيمة المعامل <code>newline</code> تُساوي <code>None</code>، فستُترجم أيّة محارف <code>'\n'</code> إلى فاصل الأسطر الافتراضي لنظام التّشغيل، والذي يُمكن الوصول إليه عبر الخاصيّة <code>os.linesep</code>. وإن كانت قيمة المعامل <code>newline</code> تُساوي <code>''</code> أو <code>'\n'</code> فلن تُترجم نهايات الأسطر. وإن كانت قيمة المعامل <code>newline</code> تُساوي أيًّا من القيم الأخرى المسموح بها، فستُترجم أيّة محارف <code>'\n'</code> إلى القيمة المُعطاة. | |||
=== <code>closefd</code> === | === <code>closefd</code> === | ||
مُعامل اختياريّ. | مُعامل اختياريّ. | ||
إن كانت قيمته تُساوي القيمة <code>False</code> وإن أعطِيَ واصف ملفّ (file descriptor) عوضًا عن اسم ملفّ للمُعامل <code>file</code>، فسيبقى واصف الملفّ مفتوحًا عندما يُغلق الملفّ. | إن كانت قيمته تُساوي القيمة <code>False</code> وإن أعطِيَ واصف ملفّ (file descriptor) عوضًا عن اسم ملفّ للمُعامل <code>file</code>، فسيبقى واصف الملفّ مفتوحًا عندما يُغلق الملفّ. إن أُعطيَ اسم ملفّ للمُعامل <code>file</code> فيجب على قيمة المُعامل <code>closefd</code> أن تُساوي <code>True</code> (وهي القيمة الافتراضيّة)، وإلّا سيُطلق استثناء <code>ValueError</code>. | ||
إن أُعطيَ اسم ملفّ للمُعامل <code>file</code> فيجب على قيمة المُعامل <code>closefd</code> أن تُساوي <code>True</code> (وهي القيمة الافتراضيّة)، وإلّا سيُطلق استثناء <code>ValueError</code>. | |||
=== <code>opener</code> === | === <code>opener</code> === | ||
مُعامل اختياريّ. | مُعامل اختياريّ. | ||
يُستعمل هذا المُعامل لاستعمال فاتح ملفّات خاصّ عبر تمريره (على شكل كائنٍ قابل للاستدعاء) إلى المُعامل <code>opener</code>. ويُستخرج واصف الملفّ الضّمني لكائن الملفّ عبر استدعاء الكائن المُمرّر إلى المُعامل <code>opener</code> بالمُعاملات المُعطاة. ويجب على الكائن المُعطى أن يُعيد واصف ملفّ مفتوحًا (تمرير الدّالة <code>os.open</code> كفاتح ملفّات له تأثير مُشابه لتمرير القيمة <code>None</code> الافتراضيّة). | يُستعمل هذا المُعامل لاستعمال فاتح ملفّات خاصّ عبر تمريره (على شكل كائنٍ قابل للاستدعاء) إلى المُعامل <code>opener</code>. ويُستخرج واصف الملفّ الضّمني لكائن الملفّ عبر استدعاء الكائن المُمرّر إلى المُعامل <code>opener</code> بالمُعاملات المُعطاة. ويجب على الكائن المُعطى أن يُعيد واصف ملفّ مفتوحًا (تمرير الدّالة <code>os.open</code> كفاتح ملفّات له تأثير مُشابه لتمرير القيمة <code>None</code> الافتراضيّة). لاحظ أنّ الملفّ المُنشأ حديثًا غير قابل للوراثة (non-inheritable). | ||
لاحظ أنّ الملفّ المُنشأ حديثًا غير قابل للوراثة (non-inheritable). | |||
== القيمة المعادة == | == القيمة المعادة == | ||
كائن ملفّ يعتمد نوعه على الوضع الذي فُتح فيه الملفّ: | كائن ملفّ يعتمد نوعه على الوضع الذي فُتح فيه الملفّ: | ||
* إن استُخدمت الدّالة <code>open()</code> لفتح ملفّ في الوضع النّصيّ (إمّا <code>'w'</code> أو <code>'r'</code> أو <code>'wt'</code> أو <code>'rt'</code>)، فستُعيد صنفًا فرعيًّا من الصّنف <code>[[Python/io/TextIOBase|io.TextIOBase]]</code> (الصّنف <code>[[Python/io/TextIOWrapper|io.TextIOWrapper]]</code> على وجه التّحديد). | |||
* إن استُخدمت الدّالة <code>open()</code> لفتح ملفّ في الوضع النّصيّ (إمّا <code>'w'</code> أو <code>'r'</code> أو <code>'wt'</code> أو <code>'rt'</code>)، فستُعيد صنفًا فرعيًّا من الصّنف <code>io.TextIOBase</code> (الصّنف <code>io.TextIOWrapper</code> على وجه التّحديد). | * إن استُخدمت لفتح ملفّ في الوضع الثّنائي (binary mode) مع التّخزين الانتقاليّ، فالصّنف المُعاد صنفٌ فرعيّ من الصّنف <code>[[Python/io/BufferedIOBase|io.BufferedIOBase]]</code>. والصّنف ذاته يختلف، ففي وضع القراءة الثّنائيّ، سيُعاد <code>[[Python/io/BufferedReader|io.BufferedReader]]</code>؛ وفي وضع الكتابة (والكتابة إلى آخر الملفّ) الثّنائيّ، سيُعاد <code>[[Python/io/BufferedWriter|io.BufferedWriter]]</code>، أمّا في وضع القراءة والكتابة، فيُعاد <code>[[Python/io/BufferedRandom|io.BufferedRandom]]</code> وإن عُطّل التّخزين الانتقاليّ، فسيُعاد التّيار الخام، والذي يكون صنفًا فرعيًّا من <code>[[Python/io/RawIOBase|io.RawIOBase]]</code> أو <code>[[Python/io/FileIO|io.FileIO]]</code>. | ||
* إن استُخدمت لفتح ملفّ في الوضع الثّنائي (binary mode) مع التّخزين الانتقاليّ، فالصّنف المُعاد صنفٌ فرعيّ من الصّنف <code>io.BufferedIOBase</code>. والصّنف ذاته يختلف، ففي وضع القراءة الثّنائيّ، | |||
== أمثلة == | == أمثلة == | ||
المثال التّالي يوضّح كيفيّة عمل هذه الدّالة لفتح ملفّ باسم <code>name.txt</code> وكتابة القيمة <code>Ali</code> إليه: | المثال التّالي يوضّح كيفيّة عمل هذه الدّالة لفتح ملفّ باسم <code>name.txt</code> وكتابة القيمة <code>Ali</code> إليه:<syntaxhighlight lang="python3"> | ||
<syntaxhighlight lang="python3"> | |||
>>> with open('name.txt', 'w') as f: | >>> with open('name.txt', 'w') as f: | ||
... f.write('Ali') | ... f.write('Ali') | ||
... | ... | ||
</syntaxhighlight> | </syntaxhighlight>المثال التّالي يستعمل المُعامل <code>dir_fd</code> الخاصّ بالدّالة <code>[[Python/os/open|os.open]]</code> لفتح ملفّ نسبةً إلى مُجلّد مُعطى:<syntaxhighlight lang="python3"> | ||
المثال التّالي يستعمل المُعامل <code>dir_fd</code> الخاصّ بالدّالة <code>os.open</code> لفتح ملفّ نسبةً إلى مُجلّد مُعطى: | |||
<syntaxhighlight lang="python3"> | |||
>>> import os | >>> import os | ||
>>> dir_fd = os.open('somedir', os.O_RDONLY) | >>> dir_fd = os.open('somedir', os.O_RDONLY) | ||
| سطر 145: | سطر 127: | ||
* [[Python/str|السلاسل النصية في بايثون]]. | * [[Python/str|السلاسل النصية في بايثون]]. | ||
* [[Python/bytes|البايتات في بايثون]]. | * [[Python/bytes|البايتات في بايثون]]. | ||
* [[Python/ | * [[Python/reading_writing_files|قراءة الملفات والكتابة فيها في بايثون]]. | ||
== مصادر == | == مصادر == | ||
* [https://docs.python.org/3/library/functions.html#open قسم الدالة open في صفحة Functions في توثيق Python الرسمي] | * [https://docs.python.org/3/library/functions.html#open قسم الدالة open في صفحة Functions في توثيق Python الرسمي.]<noinclude>{{DISPLAYTITLE:الدالة <code>open()</code> في بايثون}}</noinclude><code></code> | ||
[[تصنيف:Python]] | [[تصنيف:Python]] | ||
[[تصنيف:Python Function]] | [[تصنيف:Python Function]] | ||
[[تصنيف:Python Built-in Functions]] | [[تصنيف:Python Built-in Functions]] | ||
المراجعة الحالية بتاريخ 13:09، 10 يونيو 2018
تفتح الدّالة open() ملفّا وتعيد كائن ملفّ (file object) مرتبط به.
إن لم يُمكِن فتح الملفّ، فسيُطلَق الاستثناء OSError.
البنية العامة
open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
المعاملات
file
كائن مُشابه للمسارات (path-like object) يُمثّل مسار الملفّ (سواء أكان مُطلقا أو نسبيًّا) المرغوب فتحه.
يُمكن كذلك أن يكون واصف ملفّ عدديّ (integer file descriptor) للملفّ لتغطيّته (wrap). إن مُرّر واصف ملفّات، فسيُغلَق عندما يُغلَق كائن I/O المُعاد، إلّا في حالة كانت قيمة المُعامل closefd تساوي False.
mode
مُعامل اختياريّ.
سلسلة نصيّة تُحدّد الوضع الذي سيُفتح فيه الملفّ. القيمة الافتراضيّة هي 'r' والتي تعني أنّ الملفّ سيُفتح في وضع القراءة. ومن القيم الشّائعة:
'w'لفتح الملفّ في وضع الكتابة (مع حذف الملفّ إن كان موجودًا مُسبقًا).'x'لإنشاء الملفّات حصرًا.'a'لإضافة المحتويات إلى نهاية الملفّ دون حذفه إن كان موجودًا مُسبقًا (والتي تعني في بعض أنظمة يونكس أنّ الكتابة ستكون دائمًا على نهاية الملفّ بغضّ النّظر عن موقع المؤشر الحاليّ).
والأوضاع المُتاحة هي كالتّالي:
| المحرف | المعنى |
|---|---|
'r'
|
فتح الملفّ للقراءة (الوضع الافتراضيّ) |
'w'
|
فتح الملفّ للكتابة، مع حذف محتويات الملفّ إن كان موجودًا |
'x'
|
فتح الملفّ للإنشاء حصرًا، أي أنّ فتح الملفّ سيفشل إن كان موجودًا مُسبقًا |
'a'
|
فتح الملفّ للكتابة مع الكتابة إلى نهاية الملفّ إن كان موجودًا مُسبقًا |
'b'
|
الوضع الثّنائي (binary mode) |
't'
|
وضع النّصوص (الوضع الافتراضيّ) |
'+'
|
فتح ملفّ على القرص لتعديله (القراءة والكتابة) |
'U'
|
وضع الأسطر الجديدة العامّة (universal newlines) وهو وضع مُهمل لا يجب استخدامه. |
الوضع الافتراضي هو 'r' (لفتح الملفّ لقراءة النّصوص، وهو نفسه الوضع 'rt'). للقراءة والكتابة للملفّ بشكل ثُنائيّ، يُمكن استخدام الوضع 'w+b' لفتح ملفّ وحذف محتوياته إلى 0 بايت. والوضع 'r+b' يفتح الملفّ دون حذف محتوياته.
وكما ذُكر في تمهيد الوحدة io، لغة بايثون تُفرّق بين كائنات I/O الثّنائية وكائنات I/O النّصيّة. تُعيد الملفّات المفتوحة في الوضع الثّنائي (أي عندما يشمل الوضع المحرف 'b') المحتويات على شكل كائنات بايتات دون فكّ ترميزها (decoding). وأمّا في الوضع النّصيّ (وهو الوضع الافتراضيّ، أو عندما يشمل الوضع المحرف 't')، فتُعاد المحتويات على شكل سلاسل نصيّة، وذلك عبر فكّ ترميز البايتات أولًا باستخدام ترميز يعتمد على نظام التّشغيل أو باستخدام التّرميز المُمرّر للمُعامل encoding.
مُلاحظة: لا تعتمد بايثون على نظام التّشغيل لمعالجة الملفّات النّصيّة، إذ تُعالَج باستخدام لغة بايثون نفسها ما يجعلها مستقلّة عن المنصّة التي تعمل فيها.
buffering
مُعامل اختياريّ.
عدد صحيح يُستعمل لضبط سياسة التّخزين الانتقاليّ (buffering). مرّر القيمةَ 0 لتعطيل التخزين الانتقاليّ (مسموح به في الوضع الثّنائيّ فقط)، أو القيمةَ 1 لاختيار تخزين الأسطر (line buffering) والذي يكون مسموحًا به في الوضع النّصيّ فقط، أو مرّر عددًا صحيحًا أكبر من واحد لتحديد حجم البايتات لمخزن قطع ثابت الحجم (fixed-size chunk buffer).
عندما لا تُمرّر أيّة مُعاملات إلى المُعامل buffering فستعمل سياسة التّخزين الانتقاليّ كما يلي:
- تُخزّن الملفّات الثّنائيّة في قطع ثابتة الحجم؛ يُحدَّدُ حجم المخزن عبر محاولة الحصول على حجم القطع (block size) الخاصّ بالجهاز، أو تُستعمل القيمة
io.DEFAULT_BUFFER_SIZEإن فشلت المُحاولة. يكون حجم المخزن في العديد من الأنظمة عادةً إمّا 4096 أو 8192 بايت.
- تستعمل الملفّات النّصيّة التّفاعليّة (التي يُعيد فيها استدعاء التّابع
isatty()القيمةTrue) تخزين الأسطر. أمّا الملفّات النّصيّة الأخرى فتستعمل سياسة الملفّات الثّنائية الموضّحة أعلاه.
encoding
مُعامل اختياريّ.
اسم التّرميز الذي سيُستعمل لفكّ ترميز وترميز الملفّ. يجب استخدامه فقط في وضع الملفّات النّصيّة. في وضع الملفّات النّصيّة، إن لم تُمرّر قيمة للمُعامل encoding فالتّرميز المستخدم سيعتمد على نظام التّشغيل، وسيُستعمل الاستدعاء locale.getpreferredencoding(False) للحصول على التّرميز المحليّ. (ولقراءة وكتابة البايتات الخام، استعمل الوضع الثّنائي واترك تحديد قيمة للمُعامل encoding.) لكن يُمكن استخدام أي ترميز نصوص تدعمه بايثون. انظر الوحدة codecs للحصول على قائمة بالتّرميزات المدعومة.
errors
مُعامل اختياريّ.
سلسلة نصيّة تُحدّد كيفيّة مُعالجة أخطاء ترميز الملفّات وفكّ ترميزها. ولا يُمكن استخدامه في الوضع الثّنائي. هناك العديد من مُعالجات الأخطاء القياسيّة المتوفّرة (انظر قائمة معالجات الأخطاء)، لكن يُمكن كذلك استعمال أي اسم مُعالج أخطاء مُسجّل بالدّالة codecs.register_error(). أسماء مُعالجات الأخطاء القياسيّة تشمل ما يلي:
'strict'لإطلاق استثناءValueErrorإن حدث خطأ في التّرميز. والقيمة الافتراضيّة للمُعامل (أي القيمةNone) لها نفس التأثير.'ignore'لتجاهل الأخطاء. لكن انتبه إلى أنّ تجاهل أخطاء التّرميز قد يتسبّب في فقدان البيانات.'replace'لإبدال البيانات المشوّهة (التي حدثت عندها مشاكل في التّرميز) بعلامة مثل'?'.'surrogateescape'سيُمثّل أية بايتات غير صالحة لتكون على شكل نقاط شيفرة (code points) في مساحة الاستخدام الخاصّة ليونيكود (Unicode Private Use Area) ضمن المجال U+DC80 إلى U+DCFF. ستُرجع بعد ذلك نقاط الشّيفرة الخاصّة هذه إلى نفس البايتات عندما يُستعمل مُعالج الأخطاءsurrogateescapeلكتابة البيانات. وهذا مُفيد لمُعالجة الملفّات مجهولة التّرميز.'xmlcharrefreplace'مدعوم فقط عند الكتابة إلى ملفّ. ويقوم بإبدال المحارف غير المدعومة من طرف التّرميز إلى مرجع المحرف في مراجع XML (على شاكلة&#nnn;).'backslashreplace'يُبدِل البيانات المُشوّهة بسلاسل التّهريب المسبوقة بالمحرف\في بايثون.'namereplace'مدعوم عند الكتابة فقط. يُبدل المحارف غير المدعومة بسلاسل التّهريب\N{...}.
newline
مُعامل اختياريّ.
يتحكّم بكيفيّة عمل وضع الأسطر الجديدة العامّ (universal newlines mode) في الوضع النّصيّ. يُمكن للقيم أن تكون None، أو ، أو '\n'، أو '\r'، أو '\r\n'. وتعمل كما يلي:
- عند قراءة المُدخلات من التّيار (stream)، يكون وضع الأسطر الجديدة العامّ مُفعّلًا إن كانت قيمة المعامل
newlineتُساويNone. يُمكن للأسطر في المُدخل أن تنتهي بالمقطع'\n'، أو'\r'، أو '\r\n'وستُترجم إلى'\n'قبل إعادتها إلى المُستدعي. وإن كانت قيمة المعاملnewlineتُساوي''فإنّ وضع الأسطر الجديدة العامّ يكون مُفعّلًا، لكنّ نهايات الأسطر تُعاد إلى المُستدعِي دون ترجمتها. وإن كانت قيمة المعاملnewlineتُساوي أيًّا من القيم الأخرى المسموح بها، فستنتهي الأسطر بالقيمة المُعطاة فقط، وستُعاد نهايات الأسطر إلى المُستدعِي دون ترجمتها. - عند الكتابة إلى الملفّ، إن كانت قيمة المعامل
newlineتُساويNone، فستُترجم أيّة محارف'\n'إلى فاصل الأسطر الافتراضي لنظام التّشغيل، والذي يُمكن الوصول إليه عبر الخاصيّةos.linesep. وإن كانت قيمة المعاملnewlineتُساوي''أو'\n'فلن تُترجم نهايات الأسطر. وإن كانت قيمة المعاملnewlineتُساوي أيًّا من القيم الأخرى المسموح بها، فستُترجم أيّة محارف'\n'إلى القيمة المُعطاة.
closefd
مُعامل اختياريّ.
إن كانت قيمته تُساوي القيمة False وإن أعطِيَ واصف ملفّ (file descriptor) عوضًا عن اسم ملفّ للمُعامل file، فسيبقى واصف الملفّ مفتوحًا عندما يُغلق الملفّ. إن أُعطيَ اسم ملفّ للمُعامل file فيجب على قيمة المُعامل closefd أن تُساوي True (وهي القيمة الافتراضيّة)، وإلّا سيُطلق استثناء ValueError.
opener
مُعامل اختياريّ.
يُستعمل هذا المُعامل لاستعمال فاتح ملفّات خاصّ عبر تمريره (على شكل كائنٍ قابل للاستدعاء) إلى المُعامل opener. ويُستخرج واصف الملفّ الضّمني لكائن الملفّ عبر استدعاء الكائن المُمرّر إلى المُعامل opener بالمُعاملات المُعطاة. ويجب على الكائن المُعطى أن يُعيد واصف ملفّ مفتوحًا (تمرير الدّالة os.open كفاتح ملفّات له تأثير مُشابه لتمرير القيمة None الافتراضيّة). لاحظ أنّ الملفّ المُنشأ حديثًا غير قابل للوراثة (non-inheritable).
القيمة المعادة
كائن ملفّ يعتمد نوعه على الوضع الذي فُتح فيه الملفّ:
- إن استُخدمت الدّالة
open()لفتح ملفّ في الوضع النّصيّ (إمّا'w'أو'r'أو'wt'أو'rt')، فستُعيد صنفًا فرعيًّا من الصّنفio.TextIOBase(الصّنفio.TextIOWrapperعلى وجه التّحديد). - إن استُخدمت لفتح ملفّ في الوضع الثّنائي (binary mode) مع التّخزين الانتقاليّ، فالصّنف المُعاد صنفٌ فرعيّ من الصّنف
io.BufferedIOBase. والصّنف ذاته يختلف، ففي وضع القراءة الثّنائيّ، سيُعادio.BufferedReader؛ وفي وضع الكتابة (والكتابة إلى آخر الملفّ) الثّنائيّ، سيُعادio.BufferedWriter، أمّا في وضع القراءة والكتابة، فيُعادio.BufferedRandomوإن عُطّل التّخزين الانتقاليّ، فسيُعاد التّيار الخام، والذي يكون صنفًا فرعيًّا منio.RawIOBaseأوio.FileIO.
أمثلة
المثال التّالي يوضّح كيفيّة عمل هذه الدّالة لفتح ملفّ باسم name.txt وكتابة القيمة Ali إليه:
>>> with open('name.txt', 'w') as f:
... f.write('Ali')
...
المثال التّالي يستعمل المُعامل dir_fd الخاصّ بالدّالة os.open لفتح ملفّ نسبةً إلى مُجلّد مُعطى:
>>> import os
>>> dir_fd = os.open('somedir', os.O_RDONLY)
>>> def opener(path, flags):
... return os.open(path, flags, dir_fd=dir_fd)
...
>>> with open('spamspam.txt', 'w', opener=opener) as f:
... print('somedir/spamspam.txt', file=f) # تطبع مسار الملفّ الذي سيُكتب إليه السّطر
...
>>> os.close(dir_fd) # أغلق واصف الملفّ