الصنف configparser.ConfigParser()‎‎ في بايثون

تعدّ هذه الكائنات المفسّر الرئيسي لملفات الإعدادات.

البنية العامة

configparser.ConfigParser(defaults=None, dict_type=dict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={})

المعاملات

‎defaults

معامل اختياري، تهيّئ قيمته إلى القاموس الذي يحتوي على القيم الافتراضية الداخلية.

dict_type

معامل اختياري، يُستخدم في إنشاء كائنات القاموس لقائمة الأقسام، وللخيارات التي ينطوي عليها القسم، وللقيم الافتراضية.

delimiters

معامل اختياري يُستخدم كمجموعة السلاسل النصية الفرعية التي تقسم المفاتيح عن القيم.

comment_prefixes

معامل اختياري، يُستخدم كمجموعة السلاسل النصية الفرعية التي تسبق التعليقات التي تكتب في أسطر منفردة. ويجدر التنبيه إلى إمكانية إزاحة التعليقات حسب الحاجة.

inline_comment_prefixes

معامل اختياري، ويُستخدم كمجموعة السلاسل النصية التي تسبق التعليقات التي تأتي في الأسطر غير الفارغة.

strict

القيمة الافتراضية لهذا المعامل هي True، ويعني ذلك أنّ المحلل لن يسمح بتكرار عناوين الأقسام أو الخيارات عند قراءة الإعدادات من مصدر واحد (ملف أو سلسلة نصية أو قاموس) وذلك بإطلاق الاستثناء DuplicateSectionError أو الاستثناء DuplicateOptionError.

empty_lines_in_values

إن أخذ هذا المعامل القيمة False (القيمة الافتراضية هي True) سيُعدّ السطر الفارغ علامةً على نهاية الخيار، وإلّا فإنّ الأسطر الفارغة في قيم الخيارات متعددة الأسطر تبقى جزءًا من قيمة الخيار.

allow_no_value

إن أخذ هذا المعامل القيمة True (القيمة الافتراضية: False) فيمكن استخدام الخيارات دون تعيين قيمة لها، وتكون قيمة هذه الخيارات هي None وتُسَلسَل هذه الخيارات من دون الفاصل الذي يأتي في نهايتها.

default_section

معامل اختياري يحدّد اسم القسم الخاص الذي سيحمل القيم الافتراضية للأقسام الباقية ولأغراض استيفاء القيم (عادة ما يحمل الاسم "DEFAULT"). يمكن الحصول على قيمة هذا المعامل أو تغييرها في وقت التشغيل باستخدام الخاصية default_section.

interpolation

يمكن تخصيص طريقة استيفاء القيم عن طريق تقديم متحكّم خاص لهذا المعامل. يمكن استخدام القيمة None لإيقاف عملية الاستيفاء تمامًا. أما القيمة ExtendedInterpolation()‎ فتقدّم طريقة متقدّمة في استيفاء القيم مستوحاة من الحزمة zc.buildout. راجع قسم استيفاء القيم للاطلاع على المزيد من المعلومات.

تمرّ جميع أسماء الخيارات المستخدمة في عملية الاستيفاء عبر التابع optionxform()‎ كما هو الحال مع جميع الإشارات إلى أسماء الخيارات. فعلى سبيل المثال عند استخدام التابع optionxform()‎ بالطريقة الافتراضية (والتي تحوّل أسماء الخيارات إلى أحرف صغيرة) فإنّ القيمتين ‎foo %(bar)s و ‎foo %(BAR)s متساويتان.

converters

معامل اختياري يجب أن تكون قيمته قاموسًا يمثّل كل مفتاح فيه اسم محول لأنواع البيانات، وكل قيمة فيه كائنًا قابلًا للاستدعاء callable ينفّذ عملية تحويل من السلاسل النصية إلى نوع البيانات المطلوب. يحصل كل محوّل على التابع get*()‎ المقابل في كائنات المفسّر وفي روابط الأقسام section proxies.

ملاحظات:

• أصبح نوع القاموس الافتراضي في المعامل dict_type هو القاموس المرتب collections.OrderedDict.
• أضيفت المعاملات allow_no_value و delimiter و comment_prefixes و strict و empty_lines_in_values و default_section و interpolation في الإصدار 3.2 من بايثون.
• أضيف المعامل converters في الإصدار 3.5 من بايثون.
• أصبح المُعامل defaults يُقرأ بواسطة التابع read_dict()‎ في الإصدار 3.7 من بايثون، لتكون طريقة عمله متناسقة في جميع المراحل التي يمرّ بها المفسر، حيث تحوّل المفاتيح والقيم غير النصية إلى سلاسل نصية ضمنيًّا.
• أصبح نوع القاموس الافتراضي في المعامل dict_type هو القاموس العادي dict، وذلك لأنّه أصبح يحتفظ بترتيب إدراج العناصر فيه.

توابع الصنف ConfigParser

التابع defaults()‎

يعيد التابع قاموسًا يتضمّن القيم الافتراضية على مستوى نسخة الصنف instance-wide defaults.

التابع sections()‎

يعيد التابع قائمة بالأقسام المتاحة، ولا يكون القسم default ضمن هذه القائمة.

التابع add_section()‎

يضيف التابع قسمًا يحمل الاسم المعطى إلى نسخة الصنف ConfigParser.

التابع has_section()‎

يتحقّق التابع من وجود القسم المعطى في ملف الإعدادات.

التابع options()‎

يعيد التابع قائمة بالخيارات المتاحة في القسم المحدد.

التابع has_option()‎

يتحقق التابع من وجود الخيار المعطى ضمن القسم المحدد.

التابع read()‎

يحاول التابع قراءة وتفسير مكرِّر iterable من أسماء الملفات ويعيد قائمة بأسماء الملفات التي جرى تفسيرها بنجاح.

التابع read_file()‎

يقرأ التابع ويفسّر الإعدادات من المكرِّر iterable المعطى.

التابع read_string()‎

يفسّر التابع الإعدادات من سلسلة نصية.

التابع read_dict()‎

يحمّل التابع الإعدادات من أي كائن يوفّر تابعًا شبيهًا بالتابع items()‎ في كائنات dict. 

التابع get()‎

يجلب التابع الخيار المحدّد من القسم المعطى.

التابع getint()‎

تابع مساعد وظيفته تحويل الخيار المعطى في القسم المحدّد إلى عدد صحيح.

التابع getfloat()‎

تابع مساعد وظيفته تحويل الخيار المعطى في القسم المحدّد إلى عدد عشري ذي فاصلة عائمة.

التابع getboolean()‎

تابع مساعد وظيفته تحويل الخيار المعطى في القسم المحدّد إلى قيمة منطقية (بوليانية).

التابع items()‎

يعيد التابع الخيارات المنطوية تحت القسم المعطى.

التابع write()‎

يكتب التابع تمثيلًا للإعدادات في كائن الملف المعطى.

التابع remove_option()‎

يحذف التابع القسم المعطى من ملف الإعدادات.

التابع remove_section()‎

يحذف التابع القسم المحدّد من ملف الإعدادات.

التابع optionxform()‎

يحوّل التابع اسم الخيار المعطى وكما هو موجود في ملف الإعدادات أو كما هو ممرّر إلى التابع عن طريق الشيفرة التي يكتبها المستخدم إلى الصيغة التي يجب استخدامها في البنية الداخلية لملفات الإعدادات.

التابع readfp()‎

يقرأ التابع ملفات الإعدادات. هذا التابع مهمل من الإصدار 3.2 من بايثون.

انظر أيضًا

• الصنف RawConfingParser: النسخة القديمة من الصنف ConfigParser.

مصادر

• صفحة Configuration file parser في توثيق بايثون الرسمي.