configparser --- پارسر پرونده پیکربندی

کد منبع: Lib/configparser.py

---

این ماژول، کلاس ConfigParser را ارائه می‌دهد که یک زبان پیکربندی پایه را پیاده‌سازی می‌کند و ساختاری مشابه آنچه در پرونده‌های INI ویندوز مایکروسافت یافت می‌شود، دارد. شما می‌توانید از آن برای نوشتن برنامه‌های پایتون استفاده کنید که کاربران نهایی بتوانند به‌راحتی آن‌ها را سفارشی‌سازی کنند.

توجه

این کتابخانه پیشوندهای نوع مقدار استفاده‌شده در نسخه گسترش‌یافته سینتکس INI در Windows Registry را تفسیر یا نوشتن نمی‌کند.

همچنین ملاحظه نمائید

ماژول tomllib

TOML قالبی با مشخصات دقیق برای پرونده‌های پیکربندی برنامه‌ها است. این قالب به‌طور خاص به‌عنوان نسخه‌ای بهبودیافته از INI طراحی شده است.

ماژول shlex

پشتیبانی از ایجاد زبان‌های کوچک شبیه به پوسته‌ی یونیکس که می‌توان از آن‌ها برای پرونده‌های پیکربندی برنامه نیز استفاده کرد.

ماژول json

ماژول json زیرمجموعه‌ای از سینتکس JavaScript را پیاده‌سازی می‌کند که گاهی برای پیکربندی به کار می‌رود، اما از کامنت پشتیبانی نمی‌کند.

شروع سریع

بیایید یک پرونده‌ی پیکربندی بسیار ساده را در نظر بگیریم که به این شکل است:

[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes

[forge.example]
User = hg

[topsecret.server.example]
Port = 50022
ForwardX11 = no

ساختار پرونده‌های INI در بخش زیر توضیح داده شده است. در اصل، پرونده از بخش‌هایی تشکیل شده است که هر یک شامل کلیدهایی دارای مقدار است. کلاس‌های configparser می‌توانند چنین پرونده‌هایی را بخوانند و بنویسند. برای شروع، پرونده پیکربندی فوق را به‌صورت برنامه‌ای ایجاد می‌کنیم.

>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'}
>>> config['forge.example'] = {}
>>> config['forge.example']['User'] = 'hg'
>>> config['topsecret.server.example'] = {}
>>> topsecret = config['topsecret.server.example']
>>> topsecret['Port'] = '50022'     # mutates the parser
>>> topsecret['ForwardX11'] = 'no'  # same here
>>> config['DEFAULT']['ForwardX11'] = 'yes'
>>> with open('example.ini', 'w') as configfile:
...   config.write(configfile)
...

همان‌طور که می‌بینید، می‌توانیم با یک پارسر پیکربندی بسیار شبیه به یک دیکشنری رفتار کنیم. تفاوت‌هایی وجود دارد، که در ادامه توضیح داده شده‌اند، اما رفتار آن بسیار به آنچه از یک دیکشنری انتظار دارید نزدیک است.

اکنون که یک پرونده پیکربندی ایجاد و ذخیره کرده‌ایم، آن را دوباره می‌خوانیم و داده‌هایی را که در خود نگه می‌دارد بررسی می‌کنیم.

>>> config = configparser.ConfigParser()
>>> config.sections()
[]
>>> config.read('example.ini')
['example.ini']
>>> config.sections()
['forge.example', 'topsecret.server.example']
>>> 'forge.example' in config
True
>>> 'python.org' in config
False
>>> config['forge.example']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.example']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['forge.example']:
...     print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['forge.example']['ForwardX11']
'yes'

همان‌طور که در بالا می‌بینیم، API کاملاً سرراست است. تنها نکته‌ی جادویی مربوط به بخش DEFAULT است که مقادیر پیش‌فرض را برای تمام بخش‌های دیگر فراهم می‌کند [1]. همچنین توجه داشته باشید که کلیدهای موجود در بخش‌ها به بزرگی و کوچکی حروف حساس نیستند و به‌صورت حروف کوچک ذخیره می‌شوند [1].

می‌توان چند پیکربندی را در یک ConfigParser خواند، که در آن آخرین پیکربندی اضافه‌شده بیشترین اولویت را دارد. کلیدهای متعارض از پیکربندی جدیدتر گرفته می‌شوند، در حالی که کلیدهای از پیش موجود حفظ می‌شوند. مثال زیر پرونده override.ini را می‌خواند که کلیدهای متعارض موجود در پرونده example.ini را بازنویسی می‌کند.

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

این رفتار معادل فراخوانی ConfigParser.read() با چند پرونده است که به پارامتر filenames داده شده‌اند.

انواع داده پشتیبانی‌شده

پارسرهای پیکربندی انواع داده‌ی مقادیر موجود در پرونده‌های پیکربندی را حدس نمی‌زنند و همیشه آن‌ها را به‌صورت داخلی به‌عنوان رشته ذخیره می‌کنند. این بدان معناست که اگر به انواع داده دیگری نیاز دارید، باید خودتان آن‌ها را تبدیل کنید:

>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0

از آن‌جا که این کار بسیار رایج است، پارسرهای پیکربندی (config parsers) مجموعه‌ای از متدهای getter کاربردی را برای مدیریت اعداد صحیح، اعداد اعشاری و بولی‌ها ارائه می‌کنند. آخرین مورد جالب‌ترین است، زیرا صرفاً فرستادن مقدار به bool() فایده‌ای ندارد، چرا که bool('False') همچنان True است. به همین دلیل پارسرهای پیکربندی getboolean() را نیز ارائه می‌کنند. این متد به بزرگی و کوچکی حروف حساس نیست و مقادیر بولی را از 'yes'/'no'، 'on'/'off'، 'true'/'false' و '1'/'0' [1] تشخیص می‌دهد. برای مثال:

>>> topsecret.getboolean('ForwardX11')
False
>>> config['forge.example'].getboolean('ForwardX11')
True
>>> config.getboolean('forge.example', 'Compression')
True

علاوه بر getboolean()، پارسرهای پیکربندی همچنین متدهای معادل getint() و getfloat() را نیز ارائه می‌دهند. شما می‌توانید مبدل‌های خودتان را ثبت کنید و مبدل‌های ارائه‌شده را سفارشی‌سازی کنید. [1]

مقادیر جایگزین

مانند دیکشنری، می‌توانید از متد get() یک بخش برای ارائه مقادیر جایگزین استفاده کنید:

>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'

لطفاً توجه داشته باشید که مقادیر پیش‌فرض بر مقادیر جایگزین (fallback) اولویت دارند. برای مثال، در مثال ما کلید 'CompressionLevel' فقط در بخش 'DEFAULT' تعیین شده است. اگر سعی کنیم آن را از بخش 'topsecret.server.example' دریافت کنیم، همیشه مقدار پیش‌فرض را دریافت خواهیم کرد، حتی اگر یک مقدار جایگزین (fallback) تعیین کنیم:

>>> topsecret.get('CompressionLevel', '3')
'9'

نکته دیگری که باید از آن آگاه باشید این است که متد get() در سطح پارسر، رابطی سفارشی و پیچیده‌تر را فراهم می‌کند که برای سازگاری با نسخه‌های پیشین حفظ شده است. هنگام استفاده از این متد، می‌توانید یک مقدار جایگزین (fallback) را از طریق آرگومان فقط کلیدواژه‌ای fallback ارائه دهید:

>>> config.get('forge.example', 'monster',
...            fallback='No such things as monsters')
'No such things as monsters'

می‌توان از همان آرگومان fallback در متدهای getint()، getfloat() و getboolean() استفاده کرد، برای مثال:

>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False

ساختار پرونده INI پشتیبانی‌شده

یک پرونده پیکربندی از بخش‌ها تشکیل شده است؛ هر بخش با یک سرآیند [section] آغاز می‌شود و پس از آن، ورودی‌های کلید/مقدار قرار دارند که با یک رشته مشخص (به‌صورت پیش‌فرض = یا : [1]) از هم جدا شده‌اند. به‌صورت پیش‌فرض، نام بخش‌ها به بزرگی و کوچکی حروف حساس هستند، اما کلیدها حساس نیستند [1]. فضای سفید ابتدایی و انتهایی از کلیدها و مقدارها حذف می‌شود. در صورتی که پارسر به‌گونه‌ای پیکربندی شده باشد که حذف مقدارها مجاز باشد [1]، می‌توان آن‌ها را حذف کرد؛ در این صورت، جداکننده کلید/مقدار نیز می‌تواند حذف شود. مقدارها همچنین می‌توانند چند خط را در بر بگیرند، مشروط بر اینکه نسبت به خط اول مقدار تورفتگی بیشتری داشته باشند. بسته به حالت پارسر، سطرهای خالی ممکن است به‌عنوان بخشی از مقدارهای چندخطی در نظر گرفته شوند یا نادیده گرفته شوند.

به‌طور پیش‌فرض، یک نام بخش معتبر می‌تواند هر رشته‌ای باشد که حاوی '\n' نیست. برای تغییر این، ConfigParser.SECTCRE را ببینید.

اگر پارسر به‌گونه‌ای پیکربندی شده باشد که با allow_unnamed_section=True اجازه‌ی وجود یک بخش سطح‌بالای بی‌نام داده شود، می‌توان نام اولین بخش را حذف کرد. در این حالت، می‌توان کلیدها/مقدارها را با استفاده از UNNAMED_SECTION، مانند config[UNNAMED_SECTION]، بازیابی کرد.

پرونده‌های پیکربندی ممکن است شامل کامنت‌هایی باشند که با نویسه‌های مشخصی آغاز می‌شوند (به‌طور پیش‌فرض # و ; [1]). کامنت‌ها ممکن است به‌تنهایی در سطری که در غیر این صورت خالی است قرار بگیرند، احتمالاً با تورفتگی. [1]

برای مثال:

[Simple Values]
key=value
spaces in keys=allowed
spaces in values=allowed as well
spaces around the delimiter = obviously
you can also use : to delimit keys from values

[All Values Are Strings]
values like this: 1000000
or this: 3.14159265359
are they treated as numbers? : no
integers, floats and booleans are held as: strings
can use the API to get converted values directly: true

[Multiline Values]
chorus: I'm a lumberjack, and I'm okay
    I sleep all night and I work all day

[No Values]
key_without_value
empty string value here =

[You can use comments]
# like this
; or this

# By default only in an empty line.
# Inline comments can be harmful because they prevent users
# from using the delimiting characters as parts of values.
# That being said, this can be customized.

    [Sections Can Be Indented]
        can_values_be_as_well = True
        does_that_mean_anything_special = False
        purpose = formatting for readability
        multiline_values = are
            handled just fine as
            long as they are indented
            deeper than the first line
            of a value
        # Did I mention we can indent comments, too?

بخش‌های بی‌نام

نام اولین بخش (یا یکتا) می‌تواند حذف شود و مقادیر از طریق ویژگی UNNAMED_SECTION بازیابی شوند.

>>> config = """
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)
>>> unnamed.read_string(config)
>>> unnamed.get(configparser.UNNAMED_SECTION, 'option')
'value'

درون‌یابی مقادیر

علاوه بر قابلیت‌های اصلی، ConfigParser از درون‌یابی (interpolation) پشتیبانی می‌کند. این بدان معناست که می‌توان مقادیر را پیش از بازگرداندن آن‌ها از فراخوانی‌های get() پیش‌پردازش کرد.

class configparser.BasicInterpolation

پیاده‌سازی پیش‌فرضی که توسط ConfigParser استفاده می‌شود. این امکان را فراهم می‌کند که مقادیر شامل رشته‌های قالب‌بندی باشند که به مقادیر دیگر در همان بخش، یا مقادیر بخش پیش‌فرض خاص [1] ارجاع می‌دهند. می‌توان مقادیر پیش‌فرض اضافی را در هنگام مقداردهی اولیه ارائه کرد.

برای مثال:

[Paths]
home_dir: /Users
my_dir: %(home_dir)s/lumberjack
my_pictures: %(my_dir)s/Pictures

[Escape]
# use a %% to escape the % sign (% is the only character that needs to be escaped):
gain: 80%%

در مثال بالا، ConfigParser که درون‌یابی (interpolation) آن روی BasicInterpolation() تنظیم شده است، %(home_dir)s را به مقدار home_dir حل می‌کند (در این مورد /Users). در عمل، %(my_dir)s به /Users/lumberjack حل می‌شود. همه درون‌یابی‌ها در زمان نیاز انجام می‌شوند، بنابراین کلیدهای استفاده‌شده در زنجیره‌ای از ارجاع‌ها لازم نیست با ترتیب خاصی در پرونده پیکربندی مشخص شوند.

وقتی interpolation روی None تنظیم شده باشد، پارسر به‌سادگی %(my_dir)s/Pictures را به‌عنوان مقدار my_pictures و %(home_dir)s/lumberjack را به‌عنوان مقدار my_dir برمی‌گرداند.

class configparser.ExtendedInterpolation

یک هندلر جایگزین برای درون‌یابی (interpolation) که سینتکس پیشرفته‌تری را پیاده‌سازی می‌کند و برای نمونه در zc.buildout استفاده می‌شود. درون‌یابی گسترده از ${section:option} برای مشخص کردن مقداری از یک بخش دیگر استفاده می‌کند. درون‌یابی می‌تواند چندین سطح را در بر بگیرد. برای سهولت، اگر قسمت section: حذف شود، درون‌یابی به‌طور پیش‌فرض از بخش جاری (و احتمالاً از مقادیر پیش‌فرض بخش ویژه) استفاده می‌کند.

برای مثال، پیکربندی مشخص‌شده در بالا با درون‌یابی پایه، با درون‌یابی گسترده به این شکل خواهد بود:

[Paths]
home_dir: /Users
my_dir: ${home_dir}/lumberjack
my_pictures: ${my_dir}/Pictures

[Escape]
# use a $$ to escape the $ sign ($ is the only character that needs to be escaped):
cost: $$80

مقادیر بخش‌های دیگر را نیز می‌توان واکشی کرد:

[Common]
home_dir: /Users
library_dir: /Library
system_dir: /System
macports_dir: /opt/local

[Frameworks]
Python: 3.2
path: ${Common:system_dir}/Library/Frameworks/

[Arthur]
nickname: Two Sheds
last_name: Jackson
my_dir: ${Common:home_dir}/twosheds
my_pictures: ${my_dir}/Pictures
python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}

دسترسی به پروتکل نگاشت

اضافه شده در نسخه‌ی 3.2.

دسترسی به پروتکل نگاشت نامی کلی برای قابلیتی است که امکان استفاده از اشیاء سفارشی را گویی آن‌ها دیکشنری هستند، فراهم می‌کند. در مورد configparser، پیاده‌سازی رابط نگاشت از نمادگذاری parser['section']['option'] استفاده می‌کند.

parser['section'] به‌طور خاص یک پراکسی برای داده‌های بخش در پارسر برمی‌گرداند. این بدان معناست که مقادیر کپی نمی‌شوند، بلکه در صورت درخواست از پارسر اصلی گرفته می‌شوند. آنچه حتی مهم‌تر است این است که وقتی مقادیر روی یک پراکسی بخش تغییر می‌کنند، در واقع در پارسر اصلی تغییر می‌یابند.

اشیای configparser تا حد ممکن مانند دیکشنری‌های واقعی رفتار می‌کنند. رابط نگاشت کامل است و از ABC MutableMapping پیروی می‌کند. با این حال، چند تفاوت وجود دارد که باید در نظر گرفته شوند:

• به‌طور پیش‌فرض، همه کلیدهای درون بخش‌ها به‌صورت غیرحساس به حروف کوچک و بزرگ قابل دسترسی هستند [1]. برای مثال، for option in parser["section"] فقط نام کلیدهای گزینه‌ای را که با optionxform تبدیل‌شده‌اند برمی‌گرداند. این یعنی کلیدها به‌طور پیش‌فرض با حروف کوچک هستند. در عین حال، برای بخشی که کلید 'a' را دارد، هر دو عبارت True را برمی‌گردانند:

  "a" in parser["section"]
  "A" in parser["section"]
  

• همه‌ی بخش‌ها شامل مقادیر DEFAULTSECT نیز می‌شوند، به این معنا که .clear() روی یک بخش ممکن است بخش را به‌صورت قابل‌مشاهده‌ای خالی نگذارد. دلیلش این است که نمی‌توان مقادیر پیش‌فرض را از بخش حذف کرد (زیرا از نظر فنی در آنجا وجود ندارند). اگر این مقادیر در بخش بازنویسی شده باشند، حذف از بخش باعث می‌شود مقدار پیش‌فرض دوباره نمایان شود. تلاش برای حذف یک مقدار پیش‌فرض منجر به KeyError می‌شود.

• DEFAULTSECT را نمی‌توان از پارسر حذف کرد:

  • تلاش برای حذف آن موجب پرتاب ValueError می‌شود،

  • parser.clear() آن را دست‌نخورده باقی می‌گذارد،

  • parser.popitem() هرگز آن را برنمی‌گرداند.

• parser.get(section, option, **kwargs) - آرگومان دوم یک مقدار جایگزین نیست. با این حال توجه داشته باشید که متدهای get() در سطح بخش، هم با پروتکل نگاشت و هم با API کلاسیک configparser سازگار هستند.

• parser.items() با پروتکل نگاشت سازگار است (فهرستی از جفت‌های section_name و section_proxy را برمی‌گرداند که DEFAULTSECT را نیز شامل می‌شود). با این حال، می‌توان این متد را با آرگومان‌ها نیز فراخوانی کرد: parser.items(section, raw, vars). فراخوانی دوم، فهرستی از جفت‌های option و value را برای یک section مشخص برمی‌گرداند، به‌طوری که همه درون‌یابی‌ها (interpolations) بسط یافته‌اند (مگر آنکه raw=True ارائه شده باشد).

پروتکل نگاشت بر روی API قدیمی موجود پیاده‌سازی شده است، به‌طوری که زیرکلاس‌هایی که رابط اصلی را بازنویسی می‌کنند نیز همچنان باید نگاشت‌هایی داشته باشند که طبق انتظار کار می‌کنند.

سفارشی‌سازی رفتار پارسر

تقریباً به تعداد برنامه‌هایی که از قالب INI استفاده می‌کنند، گونه‌های مختلفی از این قالب وجود دارد. configparser تا حد زیادی پشتیبانی از بزرگ‌ترین مجموعه‌ی معقول از سبک‌های موجود INI را فراهم می‌کند. عملکرد پیش‌فرض عمدتاً تحت تأثیر پیشینه‌ی تاریخی است و بسیار محتمل است که بخواهید برخی از قابلیت‌ها را سفارشی‌سازی کنید.

رایج‌ترین روش برای تغییر شیوه‌ی کار یک پارسر پیکربندی (config parser) مشخص، استفاده از گزینه‌های __init__() است:

• defaults، مقدار پیش‌فرض: None

  این گزینه یک دیکشنری از جفت‌های کلید-مقدار را می‌پذیرد که در ابتدا در بخش DEFAULT قرار می‌گیرند. این امر راهی ظریف برای پشتیبانی از پرونده‌های پیکربندی مختصر فراهم می‌کند که مقادیر همسان با پیش‌فرض مستندشده را مشخص نمی‌کنند.

  نکته: اگر می‌خواهید مقادیر پیش‌فرض برای یک بخش مشخص تعیین کنید، قبل از خواندن پرونده واقعی از read_dict() استفاده کنید.

• dict_type، مقدار پیش‌فرض: dict

  این گزینه تأثیر عمده‌ای بر رفتار پروتکل نگاشت و ظاهر پرونده‌های پیکربندی نوشته‌شده دارد. با دیکشنری استاندارد، هر بخش به ترتیبی که به پارسر افزوده شده است، ذخیره می‌شود. همین موضوع برای گزینه‌های درون بخش‌ها نیز صدق می‌کند.

  برای مثال، می‌توان از یک نوع دیکشنری جایگزین برای مرتب‌سازی بخش‌ها و گزینه‌ها در زمان بازنویسی (write-back) استفاده کرد.

  توجه داشته باشید: راه‌هایی برای افزودن مجموعه‌ای از جفت‌های کلید-مقدار در یک عملیات وجود دارد. هنگامی که از یک دیکشنری معمولی در آن عملیات‌ها استفاده می‌کنید، ترتیب کلیدها حفظ خواهد شد. برای مثال:

  >>> parser = configparser.ConfigParser()
  >>> parser.read_dict({'section1': {'key1': 'value1',
  ...                                'key2': 'value2',
  ...                                'key3': 'value3'},
  ...                   'section2': {'keyA': 'valueA',
  ...                                'keyB': 'valueB',
  ...                                'keyC': 'valueC'},
  ...                   'section3': {'foo': 'x',
  ...                                'bar': 'y',
  ...                                'baz': 'z'}
  ... })
  >>> parser.sections()
  ['section1', 'section2', 'section3']
  >>> [option for option in parser['section3']]
  ['foo', 'bar', 'baz']
  

• allow_no_value، مقدار پیش‌فرض: False

  شناخته شده است که برخی از پرونده‌های پیکربندی شامل تنظیمات بدون مقدار هستند، اما در غیر این صورت با سینتکس پشتیبانی‌شده توسط configparser مطابقت دارند. می‌توان از پارامتر allow_no_value در سازنده برای نشان دادن اینکه چنین مقادیری باید پذیرفته شوند استفاده کرد:

  >>> import configparser
  
  >>> sample_config = """
  ... [mysqld]
  ...   user = mysql
  ...   pid-file = /var/run/mysqld/mysqld.pid
  ...   skip-external-locking
  ...   old_passwords = 1
  ...   skip-bdb
  ...   # we don't need ACID today
  ...   skip-innodb
  ... """
  >>> config = configparser.ConfigParser(allow_no_value=True)
  >>> config.read_string(sample_config)
  
  >>> # Settings with values are treated as before:
  >>> config["mysqld"]["user"]
  'mysql'
  
  >>> # Settings without values provide None:
  >>> config["mysqld"]["skip-bdb"]
  
  >>> # Settings which aren't specified still raise an error:
  >>> config["mysqld"]["does-not-exist"]
  Traceback (most recent call last):
    ...
  KeyError: 'does-not-exist'
  

• delimiters، مقدار پیش‌فرض: ('=', ':')

  جداکننده‌ها زیررشته‌هایی هستند که کلیدها را از مقادیر درون یک بخش جدا می‌کنند. نخستین رخداد یک زیررشته جداکننده در یک خط به‌عنوان جداکننده در نظر گرفته می‌شود. این بدان معناست که مقادیر (نه کلیدها) می‌توانند شامل جداکننده‌ها باشند.

  همچنین آرگومان space_around_delimiters برای ConfigParser.write() را ببینید.

• comment_prefixes، مقدار پیش‌فرض: ('#', ';')

• inline_comment_prefixes، مقدار پیش‌فرض: None

  پیشوندهای کامنت رشته‌هایی هستند که آغاز یک کامنت معتبر در پرونده پیکربندی را نشان می‌دهند. comment_prefixes فقط در سطرهایی که در غیر این صورت خالی هستند (با تورفتگی اختیاری) استفاده می‌شوند، در حالی که inline_comment_prefixes می‌توانند پس از هر مقدار معتبر (برای مثال نام بخش‌ها، گزینه‌ها و همچنین سطرها خالی) استفاده شوند. به‌طور پیش‌فرض، کامنت‌های درون‌خطی غیرفعال هستند و از '#' و ';' به‌عنوان پیشوند برای کامنت‌های کل خط استفاده می‌شود.

  تغییر یافته در نسخه‌ی 3.2: در نسخه‌های پیشین configparser، رفتار مطابق comment_prefixes=('#',';') و inline_comment_prefixes=(';',) بود.

  لطفاً توجه داشته باشید که پارسرهای پیکربندی از خنثی‌سازی پیشوندهای کامنت پشتیبانی نمی‌کنند، بنابراین استفاده از inline_comment_prefixes ممکن است کاربران را از تعیین مقادیر گزینه حاوی نویسه‌هایی که به‌عنوان پیشوندهای کامنت استفاده می‌شوند، باز دارد. در صورت تردید، از تنظیم inline_comment_prefixes خودداری کنید. در هر شرایطی، تنها راه ذخیره‌سازی نویسه‌های پیشوند کامنت در ابتدای یک خط در مقادیر چندخطی، درون‌یابی پیشوند است، برای مثال:

  >>> from configparser import ConfigParser, ExtendedInterpolation
  >>> parser = ConfigParser(interpolation=ExtendedInterpolation())
  >>> # the default BasicInterpolation could be used as well
  >>> parser.read_string("""
  ... [DEFAULT]
  ... hash = #
  ...
  ... [hashes]
  ... shebang =
  ...   ${hash}!/usr/bin/env python
  ...   ${hash} -*- coding: utf-8 -*-
  ...
  ... extensions =
  ...   enabled_extension
  ...   another_extension
  ...   #disabled_by_comment
  ...   yet_another_extension
  ...
  ... interpolation not necessary = if # is not at line start
  ... even in multiline values = line #1
  ...   line #2
  ...   line #3
  ... """)
  >>> print(parser['hashes']['shebang'])
  
  #!/usr/bin/env python
  # -*- coding: utf-8 -*-
  >>> print(parser['hashes']['extensions'])
  
  enabled_extension
  another_extension
  yet_another_extension
  >>> print(parser['hashes']['interpolation not necessary'])
  if # is not at line start
  >>> print(parser['hashes']['even in multiline values'])
  line #1
  line #2
  line #3
  

• strict، مقدار پیش‌فرض: True

  هنگامی که روی True تنظیم شود، پارسر هنگام خواندن از یک منبع واحد (با استفاده از read_file()، read_string() یا read_dict()) اجازه نمی‌دهد هیچ بخش یا گزینه‌ای تکرار شود. توصیه می‌شود در برنامه‌های کاربردی جدید از پارسرهای سخت‌گیر استفاده شود.

  تغییر یافته در نسخه‌ی 3.2: در نسخه‌های پیشین configparser، رفتار با strict=False مطابقت داشت.

• empty_lines_in_values، مقدار پیش‌فرض: True

  در پارسرهای پیکربندی، مقدارها می‌توانند چندین خط را در بر بگیرند، به‌شرطی که تورفتگی آن‌ها بیشتر از کلیدی باشد که آن‌ها را نگه می‌دارد. به‌طور پیش‌فرض، پارسرها همچنین اجازه می‌دهند سطرهای خالی بخشی از مقدارها باشند. در عین حال، خود کلیدها نیز می‌توانند به‌دلخواه تورفتگی داشته باشند تا خوانایی بهبود یابد. در نتیجه، هنگامی که پرونده‌های پیکربندی بزرگ و پیچیده می‌شوند، ممکن است کاربر به‌راحتی رد ساختار پرونده را گم کند. برای نمونه:

  [Section]
  key = multiline
    value with a gotcha
  
   this = is still a part of the multiline value of 'key'
  

  دیدن این موضوع می‌تواند برای کاربر به‌ویژه مشکل‌ساز باشد، اگر برای ویرایش پرونده از قلم متناسب استفاده کند. به همین دلیل، هنگامی که برنامه شما به مقادیر دارای سطرهای خالی نیازی ندارد، باید در نظر بگیرید که آن‌ها را غیرمجاز کنید. این کار باعث می‌شود سطرهای خالی هر بار کلیدها را جدا کنند. در مثال بالا، این کار دو کلید، key و this، تولید می‌کند.

• default_section، مقدار پیش‌فرض: configparser.DEFAULTSECT (یعنی "DEFAULT")

  قراردادِ وجود یک بخش ویژه از مقادیر پیش‌فرض برای سایر بخش‌ها یا اهداف درون‌یابی (interpolation)، مفهوم قدرتمندی در این کتابخانه است که به کاربران امکان می‌دهد پیکربندی‌های اعلامی پیچیده‌ای ایجاد کنند. این بخش معمولاً "DEFAULT" نامیده می‌شود، اما می‌توان آن را سفارشی‌سازی کرد تا به هر نام بخش معتبر دیگری اشاره کند. برخی مقادیر معمول عبارت‌اند از: "general" یا "common". نام ارائه‌شده برای شناسایی بخش‌های پیش‌فرض هنگام خواندن از هر منبعی استفاده می‌شود و همچنین هنگام نوشتن پیکربندی به یک پرونده نیز به کار می‌رود. مقدار فعلی آن را می‌توان با استفاده از ویژگی parser_instance.default_section دریافت کرد و می‌توان آن را در ران‌تایم تغییر داد (یعنی برای تبدیل پرونده‌ها از یک قالب به قالب دیگر).

• interpolation، مقدار پیش‌فرض: configparser.BasicInterpolation

  می‌توان رفتار درون‌یابی (interpolation) را با ارائه یک هندلر سفارشی از طریق آرگومان interpolation سفارشی‌سازی کرد. می‌توان از None برای غیرفعال کردن کامل درون‌یابی استفاده کرد؛ ExtendedInterpolation() گونه‌ای پیشرفته‌تر را فراهم می‌کند که از zc.buildout الهام‌گرفته است. اطلاعات بیشتر درباره این موضوع در بخش اختصاصی مستندات آمده است. RawConfigParser دارای مقدار پیش‌فرض None است.

• converters، مقدار پیش‌فرض: تنظیم‌نشده

  پارسرهای پیکربندی، دریابنده‌های مقدار گزینه را فراهم می‌کنند که تبدیل نوع را انجام می‌دهند. به‌طور پیش‌فرض getint()، getfloat() و getboolean() پیاده‌سازی شده‌اند. در صورت نیاز به دریابندههای دیگر، کاربران می‌توانند آن‌ها را در یک زیرکلاس تعریف کنند یا یک دیکشنری ارسال کنند که هر کلید آن نام مبدل و هر مقدار آن یک شیء فراخوانی‌پذیر است که تبدیل مذکور را پیاده‌سازی می‌کند. برای مثال، ارسال {'decimal': decimal.Decimal} باعث می‌شود getdecimal() هم به شیء پارسر و هم به تمام پراکسی‌های بخش اضافه شود. به بیان دیگر، امکان نوشتن هر دو parser_instance.getdecimal('section', 'key', fallback=0) و parser_instance['section'].getdecimal('key', 0) وجود خواهد داشت.

  اگر مبدل نیاز به دسترسی به وضعیت پارسر داشته باشد، می‌توان آن را به‌صورت متدی در یک زیرکلاس پارسر پیکربندی پیاده‌سازی کرد. اگر نام این متد با get آغاز شود، در همه پراکسی‌های بخش، در قالب سازگار با دیکشنری در دسترس خواهد بود (مثال getdecimal() بالا را ببینید).

با تغییر مقادیر پیش‌فرض این ویژگی‌های پارسر می‌توان به سفارشی‌سازی پیشرفته‌تری دست یافت. مقادیر پیش‌فرض روی کلاس‌ها تعریف شده‌اند، بنابراین می‌توان آن‌ها را در زیرکلاس‌ها یا از طریق انتساب ویژگی تغییر داد.

ConfigParser.BOOLEAN_STATES

به‌طور پیش‌فرض هنگام استفاده از getboolean()، پارسرهای پیکربندی مقادیر زیر را True در نظر می‌گیرند: '1'، 'yes'، 'true'، 'on' و مقادیر زیر را False در نظر می‌گیرند: '0'، 'no'، 'false'، 'off'. می‌توانید این پیش‌فرض را با مشخص کردن یک دیکشنری سفارشی از رشته‌ها و نتایج بولی آن‌ها تغییر دهید. برای مثال:

>>> custom = configparser.ConfigParser()
>>> custom['section1'] = {'funky': 'nope'}
>>> custom['section1'].getboolean('funky')
Traceback (most recent call last):
...
ValueError: Not a boolean: nope
>>> custom.BOOLEAN_STATES = {'sure': True, 'nope': False}
>>> custom['section1'].getboolean('funky')
False

سایر جفت‌های بولی رایج شامل accept/reject یا enabled/disabled هستند.

ConfigParser.optionxform(option)

این متد نام گزینه‌ها را در هر عملیات خواندن، دریافت یا تنظیم تبدیل می‌کند. حالت پیش‌فرض نام را به حروف کوچک تبدیل می‌کند. این همچنین به این معناست که هنگامی که یک پرونده پیکربندی نوشته می‌شود، همه کلیدها با حروف کوچک خواهند بود. اگر این مناسب نیست، این متد را بازنویسی کنید. برای مثال:

>>> config = """
... [Section1]
... Key = Value
...
... [Section2]
... AnotherKey = Value
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> list(typical['Section1'].keys())
['key']
>>> list(typical['Section2'].keys())
['anotherkey']
>>> custom = configparser.RawConfigParser()
>>> custom.optionxform = lambda option: option
>>> custom.read_string(config)
>>> list(custom['Section1'].keys())
['Key']
>>> list(custom['Section2'].keys())
['AnotherKey']

توجه

تابع optionxform نام گزینه‌ها را به یک صورت کانونیکال تبدیل می‌کند. این باید یک تابع هم‌توان (idempotent) باشد: اگر نام از قبل در صورت کانونیکال باشد، باید بدون تغییر بازگردانده شود.

ConfigParser.SECTCRE

یک عبارت باقاعده کامپایل‌شده که برای تجزیه سرآیند‌های بخش استفاده می‌شود. مقدار پیش‌فرض [section] را با نام "section" تطبیق می‌دهد. فضای سفید به‌عنوان بخشی از نام بخش در نظر گرفته می‌شود، بنابراین [  larch  ] به‌عنوان بخشی با نام "  larch  " خوانده می‌شود. اگر این مناسب نیست، این ویژگی را بازنویسی کنید. برای مثال:

>>> import re
>>> config = """
... [Section 1]
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> typical.sections()
['Section 1', '  Section 2  ']
>>> custom = configparser.ConfigParser()
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
>>> custom.read_string(config)
>>> custom.sections()
['Section 1', 'Section 2']

توجه

اگرچه اشیای ConfigParser همچنین از یک ویژگی OPTCRE برای تشخیص سطرهای گزینه استفاده می‌کنند، توصیه نمی‌شود آن را بازنویسی کنید، زیرا این کار با گزینه‌های سازنده یعنی allow_no_value و delimiters تداخل ایجاد می‌کند.

نمونه‌های API قدیمی

عمدتاً به دلیل ملاحظات سازگاری با نسخه‌های قبلی، configparser همچنین یک API قدیمی با متدهای صریح get/set ارائه می‌دهد. اگرچه برای متدهایی که در زیر توضیح داده شده‌اند موارد استفاده معتبری وجود دارد، دسترسی از طریق پروتکل نگاشت برای پروژه‌های جدید ترجیح داده می‌شود. API قدیمی گاهی اوقات پیشرفته‌تر، سطح پایین‌تر و کاملاً غیرشهودی است.

مثالی از نوشتن در یک پرونده پیکربندی:

import configparser

config = configparser.RawConfigParser()

# Please note that using RawConfigParser's set functions, you can assign
# non-string values to keys internally, but will receive an error when
# attempting to write to a file or when you get it in non-raw mode. Setting
# values using the mapping protocol or ConfigParser's set() does not allow
# such assignments to take place.
config.add_section('Section1')
config.set('Section1', 'an_int', '15')
config.set('Section1', 'a_bool', 'true')
config.set('Section1', 'a_float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s is %(baz)s!')

# Writing our configuration file to 'example.cfg'
with open('example.cfg', 'w') as configfile:
    config.write(configfile)

مثالی از خواندن دوباره‌ی پرونده پیکربندی:

import configparser

config = configparser.RawConfigParser()
config.read('example.cfg')

# getfloat() raises an exception if the value is not a float
# getint() and getboolean() also do this for their respective types
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print(a_float + an_int)

# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
# This is because we are using a RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
    print(config.get('Section1', 'foo'))

برای درون‌یابی (interpolation)، از ConfigParser استفاده کنید:

import configparser

cfg = configparser.ConfigParser()
cfg.read('example.cfg')

# Set the optional *raw* argument of get() to True if you wish to disable
# interpolation in a single get operation.
print(cfg.get('Section1', 'foo', raw=False))  # -> "Python is fun!"
print(cfg.get('Section1', 'foo', raw=True))   # -> "%(bar)s is %(baz)s!"

# The optional *vars* argument is a dict with members that will take
# precedence in interpolation.
print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
                                       'baz': 'evil'}))

# The optional *fallback* argument can be used to provide a fallback value
print(cfg.get('Section1', 'foo'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'foo', fallback='Monty is not.'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))
      # -> "No such things as monsters."

# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError
# but we can also use:

print(cfg.get('Section1', 'monster', fallback=None))
      # -> None

مقادیر پیش‌فرض در هر دو نوع ConfigParser در دسترس هستند. اگر گزینه‌ی استفاده‌شده در جای دیگری تعریف‌نشده باشد، این مقادیر در درون‌یابی (interpolation) استفاده می‌شوند.

import configparser

# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')

print(config.get('Section1', 'foo'))     # -> "Python is fun!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print(config.get('Section1', 'foo'))     # -> "Life is hard!"

اشیای ConfigParser

class 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={}, allow_unnamed_section=False)

پارسر اصلی پیکربندی. هنگامی که 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) را می‌توان با ارائه یک هندلر سفارشی از طریق آرگومان interpolation سفارشی‌سازی کرد. می‌توان از None برای غیرفعال کردن کامل درون‌یابی استفاده کرد، و ExtendedInterpolation() یک گونه پیشرفته‌تر ارائه می‌دهد که از zc.buildout الهام گرفته است. اطلاعات بیشتر درباره این موضوع در بخش اختصاصی مستندات.

تمام نام‌های گزینه‌ای که در درون‌یابی (interpolation) استفاده می‌شوند، دقیقاً مانند هر ارجاع دیگری به نام گزینه، از متد optionxform() عبور می‌کنند. برای مثال، با استفاده از پیاده‌سازی پیش‌فرض optionxform() (که نام گزینه‌ها را به حروف کوچک تبدیل می‌کند)، مقادیر foo %(bar)s و foo %(BAR)s معادل هستند.

هنگامی که converters داده شود، باید یک دیکشنری باشد که در آن هر کلید نشان‌دهنده‌ی نام یک مبدل نوع است و هر مقدار یک شیء فراخوانی‌پذیر است که تبدیل از رشته به نوع داده مورد نظر را پیاده‌سازی می‌کند. هر مبدل متد get*() متناظر با خود را روی شیء پارسر و پراکسی‌های بخش دریافت می‌کند.

هنگامی که allow_unnamed_section True باشد (پیش‌فرض: False)، می‌توان نام بخش نخست را حذف کرد. بخش «بخش‌های بی‌نام» <#unnamed-sections>`_ را ببینید.

می‌توان چند پیکربندی را در یک ConfigParser خواند، که در آن آخرین پیکربندی اضافه‌شده بیشترین اولویت را دارد. کلیدهای متعارض از پیکربندی جدیدتر گرفته می‌شوند، در حالی که کلیدهای از پیش موجود حفظ می‌شوند. مثال زیر پرونده override.ini را می‌خواند که کلیدهای متعارض موجود در پرونده example.ini را بازنویسی می‌کند.

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

تغییر یافته در نسخه‌ی 3.1: dict_type پیش‌فرض collections.OrderedDict است.

تغییر یافته در نسخه‌ی 3.2: allow_no_value، delimiters، comment_prefixes، strict، empty_lines_in_values، default_section و interpolation افزوده شدند.

تغییر یافته در نسخه‌ی 3.5: آرگومان converters افزوده شد.

تغییر یافته در نسخه‌ی 3.7: آرگومان defaults با read_dict() خوانده می‌شود و رفتار سازگاری را در سراسر پارسر فراهم می‌کند: کلیدها و مقدارهای غیررشته‌ای به‌صورت ضمنی به رشته تبدیل می‌شوند.

تغییر یافته در نسخه‌ی 3.8: مقدار پیش‌فرض dict_type، dict است، زیرا اکنون ترتیب درج را حفظ می‌کند.

تغییر یافته در نسخه‌ی 3.13: هنگامی که allow_no_value برابر True باشد و یک کلید بدون مقدار با یک خط دارای تورفتگی ادامه یابد، یک MultilineContinuationError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.13: آرگومان allow_unnamed_section افزوده شد.

defaults()

یک دیکشنری شامل پیش‌فرض‌های سراسری نمونه برمی‌گرداند.

sections()

فهرستی از بخش‌های موجود را برمی‌گرداند؛ بخش پیش‌فرض در این فهرست گنجانده نشده است.

add_section(section)

یک بخش با نام section به نمونه اضافه می‌کند. اگر بخشی با نام داده‌شده از قبل وجود داشته باشد، استثنای DuplicateSectionError پرتاب می‌شود. اگر نام بخش پیش‌فرض داده شود، استثنای ValueError پرتاب می‌شود. نام بخش باید یک رشته باشد؛ در غیر این صورت، استثنای TypeError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.2: نام‌بخش‌های غیررشته‌ای باعث پرتاب TypeError می‌شوند.

has_section(section)

نشان می‌دهد که آیا section نام‌برده در پیکربندی وجود دارد یا خیر. بخش پیش‌فرض شناسایی نمی‌شود.

options(section)

فهرستی از گزینه‌های موجود در section مشخص‌شده را برمی‌گرداند.

has_option(section, option)

اگر section داده‌شده وجود داشته باشد و شامل option داده‌شده باشد، True را برمی‌گرداند؛ در غیر این صورت False را برمی‌گرداند. اگر section مشخص‌شده None یا یک رشته خالی باشد، DEFAULT در نظر گرفته می‌شود.

read(filenames, encoding=None)

تلاش می‌کند یک پیمایش‌پذیر از نام پرونده‌ها را بخواند و تجزیه کند، و فهرستی از نام پرونده‌هایی را که با موفقیت تجزیه شده‌اند برمی‌گرداند.

اگر filenames یک رشته، یک شیء bytes یا یک شیء شبه‌مسیر (path-like object) باشد، به‌عنوان یک نام پرونده واحد در نظر گرفته می‌شود. اگر نتوان پرونده‌ای را که در filenames ذکر شده است باز کرد، از آن پرونده چشم‌پوشی خواهد شد. این به گونه‌ای طراحی شده است که شما بتوانید یک پیمایش‌پذیر از محل‌های احتمالی برای پرونده‌های پیکربندی مشخص کنید (برای مثال، پوشه جاری، پوشه خانه کاربر، و یک پوشه سراسری سیستم)، و همه پرونده‌های پیکربندی موجود در آن پیمایش‌پذیر خوانده خواهند شد.

اگر هیچ‌کدام از پرونده‌های نام‌برده‌شده وجود نداشته باشند، نمونه‌ی ConfigParser حاوی یک مجموعه‌داده خالی خواهد بود. برنامه‌ای که نیازمند بارگذاری مقادیر اولیه از یک پرونده است، باید پرونده یا پرونده‌های موردنیاز را با استفاده از read_file() بارگذاری کند، پیش از فراخوانی read() برای هر پرونده اختیاری:

import configparser, os

config = configparser.ConfigParser()
config.read_file(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
            encoding='cp1250')

تغییر یافته در نسخه‌ی 3.2: پارامتر encoding افزوده شد. پیش از این، تمام پرونده‌ها با کدگذاری پیش‌فرض open() خوانده می‌شدند.

تغییر یافته در نسخه‌ی 3.6.1: پارامتر filenames یک شیء شبه‌مسیر (path-like object) را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.7: پارامتر filenames یک شیء bytes را می‌پذیرد.

read_file(f, source=None)

داده‌های پیکربندی را از f بخوانید و تجزیه کنید؛ f باید پیمایش‌پذیری باشد که رشته‌های یونیکد تولید می‌کند (برای مثال پرونده‌هایی که در حالت متنی باز شده‌اند).

آرگومان اختیاری source نام پرونده‌ای که خوانده می‌شود را مشخص می‌کند. اگر داده نشود و f ویژگی name داشته باشد، از آن برای source استفاده می‌شود؛ مقدار پیش‌فرض '<???>' است.

اضافه شده در نسخه‌ی 3.2: جایگزین readfp() می‌شود.

read_string(string, source='<string>')

تجزیه داده‌های پیکربندی از یک رشته.

آرگومان اختیاری source نامی وابسته به زمینه برای رشته‌ی داده‌شده مشخص می‌کند. اگر داده نشود، از '<string>' استفاده می‌شود. این معمولاً باید یک مسیر سامانه فایل‌بندی یا یک URL باشد.

اضافه شده در نسخه‌ی 3.2.

read_dict(dictionary, source='<dict>')

پیکربندی از هر شیءای که متد items() دیکشنری‌مانند را فراهم می‌کند، بارگذاری می‌شود. کلیدها نام بخش‌ها هستند؛ مقدارها دیکشنری‌هایی هستند که کلیدها و مقدارهای آن‌ها باید در آن بخش وجود داشته باشند. اگر نوع دیکشنری استفاده‌شده ترتیب را حفظ کند، بخش‌ها و کلیدهای آن‌ها به‌ترتیب اضافه خواهند شد. مقدارها به‌طور خودکار به رشته تبدیل می‌شوند.

آرگومان اختیاری source نامی مختص به زمینه برای دیکشنری ارسال‌شده مشخص می‌کند. اگر داده نشود، از <dict> استفاده می‌شود.

می‌توان از این متد برای کپی وضعیت بین پارسرها استفاده کرد.

اضافه شده در نسخه‌ی 3.2.

get(section, option, *, raw=False, vars=None[, fallback])

مقدار یک option را برای section مشخص‌شده دریافت کنید. اگر vars ارائه شده باشد، باید یک دیکشنری باشد. option به‌ترتیب در vars (در صورت ارائه)، section و در DEFAULTSECT جستجو می‌شود. اگر کلید پیدا نشود و fallback ارائه شده باشد، به‌عنوان مقدار جایگزین استفاده می‌شود. می‌توان None را به‌عنوان مقدار fallback ارائه کرد.

تمام درون‌یابی‌های '%' در مقادیر بازگشتی بسط داده می‌شوند، مگر اینکه آرگومان raw صحیح باشد. مقادیر کلیدهای درون‌یابی به همان شیوه‌ای که گزینه جست‌وجو می‌شود، جست‌وجو می‌شوند.

تغییر یافته در نسخه‌ی 3.2: آرگومان‌های raw، vars و fallback فقط کلیدواژه‌ای هستند تا از تلاش کاربران برای استفاده از سومین آرگومان به‌عنوان مقدار جایگزین (fallback) برای fallback جلوگیری شود (به‌ویژه هنگام استفاده از پروتکل نگاشت).

getint(section, option, *, raw=False, vars=None[, fallback])

متدی آسان‌کننده که option را در section مشخص‌شده به عدد صحیح تبدیل می‌کند. برای توضیح raw، vars و fallback به get() مراجعه کنید.

getfloat(section, option, *, raw=False, vars=None[, fallback])

متد آسان‌کننده‌ای که option را در section مشخص‌شده به یک عدد ممیز شناور تبدیل می‌کند. برای توضیحات مربوط به raw، vars و fallback به get() مراجعه کنید.

getboolean(section, option, *, raw=False, vars=None[, fallback])

یک متد سهولت‌بخش که option را در section مشخص‌شده به یک مقدار بولی تبدیل می‌کند. توجه داشته باشید که مقادیر پذیرفته‌شده برای گزینه عبارت‌اند از '1'، 'yes'، 'true' و 'on' که باعث می‌شوند این متد True را برگرداند، و '0'، 'no'، 'false' و 'off' که باعث می‌شوند این متد False را برگرداند. این مقادیر رشته‌ای به‌صورت غیرحساس به بزرگی و کوچکی حروف بررسی می‌شوند. هر مقدار دیگری باعث می‌شود این متد ValueError را پرتاب کند. برای توضیح raw، vars و fallback به get() مراجعه کنید.

items(raw=False, vars=None)

items(section, raw=False, vars=None)

هنگامی که section داده نشده باشد، فهرستی از جفت‌های section_name و section_proxy شامل DEFAULTSECT را برمی‌گرداند.

در غیر این صورت، فهرستی از جفت‌های name، value برای گزینه‌های موجود در section داده‌شده برمی‌گرداند. آرگومان‌های اختیاری همان معنایی را دارند که برای متد get() دارند.

تغییر یافته در نسخه‌ی 3.8: آیتم‌های موجود در vars دیگر در نتیجه ظاهر نمی‌شوند. رفتار پیشین، گزینه‌های واقعی پارسر را با متغیرهای ارائه‌شده برای درون‌یابی (interpolation) مخلوط می‌کرد.

set(section, option, value)

اگر بخش داده‌شده وجود داشته باشد، گزینه‌ی داده‌شده را به مقدار مشخص‌شده تنظیم می‌کند؛ در غیر این صورت NoSectionError پرتاب می‌شود. option و value باید رشته باشند؛ در غیر این صورت TypeError پرتاب می‌شود.

write(fileobject, space_around_delimiters=True)

بازنمایی‌ای از پیکربندی را در file object مشخص بنویسید، که باید در حالت متنی باز شده باشد (و رشته‌ها را بپذیرد). این بازنمایی را می‌توان با یک فراخوانی بعدی read() تجزیه کرد. اگر space_around_delimiters برابر true باشد، جداکننده‌های بین کلیدها و مقدارها با فاصله احاطه می‌شوند.

تغییر یافته در نسخه‌ی 3.14: در صورتی که این عمل منجر به نوشتن بازنمایی‌ای شود که یک فراخوانی آینده read() از این پارسر نتواند آن را به‌دقت تجزیه کند، InvalidWriteError را پرتاب می‌کند.

توجه

کامنت‌های موجود در پرونده پیکربندی اصلی، هنگام نوشتن مجدد پیکربندی حفظ نمی‌شوند. اینکه چه چیزی کامنت در نظر گرفته می‌شود، به مقادیر داده‌شده برای comment_prefix و inline_comment_prefix بستگی دارد.

remove_option(section, option)

option مشخص‌شده را از section مشخص‌شده حذف می‌کند. اگر بخش وجود نداشته باشد، NoSectionError را پرتاب می‌کند. اگر گزینه برای حذف وجود داشته باشد، True را برمی‌گرداند؛ در غیر این صورت False را برمی‌گرداند.

remove_section(section)

section مشخص‌شده را از پیکربندی حذف می‌کند. اگر بخش در واقع وجود داشته باشد، True برمی‌گرداند. در غیر این صورت False برمی‌گرداند.

optionxform(option)

نام گزینه option را، همان‌گونه که در یک پرونده ورودی یافت می‌شود یا توسط کد کلاینت ارسال می‌شود، به شکلی تبدیل می‌کند که باید در ساختارهای داخلی استفاده شود. پیاده‌سازی پیش‌فرض، نسخه‌ای با حروف کوچک از option را برمی‌گرداند؛ زیرکلاس‌ها می‌توانند این را بازنویسی کنند یا کد کلاینت می‌تواند ویژگی‌ای به این نام را روی نمونه‌ها تنظیم کند تا بر این رفتار اثر بگذارد.

برای استفاده از این متد نیازی نیست پارسر را زیرکلاس کنید؛ می‌توانید آن را بر روی یک نمونه نیز به تابعی تنظیم کنید که یک آرگومان رشته‌ای دریافت می‌کند و یک رشته برمی‌گرداند. برای مثال، تنظیم آن به str باعث می‌شود نام گزینه‌ها به بزرگی و کوچکی حروف حساس شوند:

cfgparser = ConfigParser()
cfgparser.optionxform = str

توجه داشته باشید که هنگام خواندن پرونده‌های پیکربندی، فاصله‌های سفید اطراف نام گزینه‌ها پیش از فراخوانی optionxform() حذف می‌شود.

configparser.UNNAMED_SECTION

یک شیء خاص که نشان‌دهنده‌ی نام بخش است و برای ارجاع به بخش بی‌نام استفاده می‌شود (به بخش‌های بی‌نام مراجعه کنید).

configparser.MAX_INTERPOLATION_DEPTH

حداکثر عمق درون‌یابی بازگشتی برای get() زمانی که پارامتر raw نادرست باشد. این مورد تنها زمانی مرتبط است که از interpolation پیش‌فرض استفاده شود.

اشیای RawConfigParser

class configparser.RawConfigParser(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={}, allow_unnamed_section=False)

گونه‌ای قدیمی از ConfigParser. درون‌یابی در آن به‌طور پیش‌فرض غیرفعال است و از طریق متدهای ناامن add_section و set و نیز مدیریت قدیمی آرگومان کلیدواژه‌ای defaults=، امکان استفاده از نام‌های بخش، نام‌های گزینه و مقادیر غیررشته‌ای را فراهم می‌کند.

تغییر یافته در نسخه‌ی 3.2: allow_no_value، delimiters، comment_prefixes، strict، empty_lines_in_values، default_section و interpolation افزوده شدند.

تغییر یافته در نسخه‌ی 3.5: آرگومان converters افزوده شد.

تغییر یافته در نسخه‌ی 3.8: مقدار پیش‌فرض dict_type، dict است، زیرا اکنون ترتیب درج را حفظ می‌کند.

تغییر یافته در نسخه‌ی 3.13: آرگومان allow_unnamed_section افزوده شد.

توجه

در عوض، استفاده از ConfigParser را در نظر بگیرید که نوع مقادیری را که باید به‌صورت داخلی ذخیره شوند بررسی می‌کند. اگر درون‌یابی نمی‌خواهید، می‌توانید از ConfigParser(interpolation=None) استفاده کنید.

add_section(section)

یک بخش با نام section یا UNNAMED_SECTION به نمونه اضافه می‌کند.

اگر بخش داده‌شده از قبل وجود داشته باشد، DuplicateSectionError پرتاب می‌شود. اگر نام بخش پیش‌فرض داده شود، ValueError پرتاب می‌شود. اگر UNNAMED_SECTION داده شود و پشتیبانی غیرفعال باشد، UnnamedSectionDisabledError پرتاب می‌شود.

نوع section بررسی نمی‌شود و این به کاربران امکان می‌دهد بخش‌هایی با نام‌های غیررشته‌ای ایجاد کنند. این رفتار پشتیبانی نمی‌شود و ممکن است باعث خطاهای داخلی شود.

تغییر یافته در نسخه‌ی 3.14: پشتیبانی از UNNAMED_SECTION افزوده شد.

set(section, option, value)

اگر بخش داده‌شده وجود داشته باشد، گزینه‌ی داده‌شده به مقدار مشخص‌شده تنظیم می‌شود؛ در غیر این صورت NoSectionError پرتاب می‌شود. اگرچه می‌توان از RawConfigParser (یا ConfigParser با پارامترهای raw که به true تنظیم شده‌اند) برای ذخیره‌سازی داخلی مقادیر غیررشته‌ای استفاده کرد، اما قابلیت کامل (شامل درون‌یابی و خروجی به پرونده‌ها) تنها با استفاده از مقادیر رشته‌ای امکان‌پذیر است.

این متد به کاربران اجازه می‌دهد که مقادیر غیررشته‌ای را به‌صورت داخلی به کلیدها منتسب کنند. این رفتار پشتیبانی نمی‌شود و هنگام تلاش برای نوشتن در یک پرونده یا دریافت آن در حالت غیرخام، باعث بروز خطاها خواهد شد. از API پروتکل نگاشت استفاده کنید که چنین انتساب‌هایی را مجاز نمی‌داند.

استثناها

exception configparser.Error

کلاس پایه برای تمام استثناهای دیگر configparser.

exception configparser.NoSectionError

استثنایی که هنگام پیدا نشدن بخش مشخص‌شده پرتاب می‌شود.

exception configparser.DuplicateSectionError

استثنایی پرتاب می‌شود اگر add_section() با نام بخشی که از قبل موجود است فراخوانی شود، یا در پارسرهای سخت‌گیر وقتی بخشی بیش از یک بار در یک پرونده ورودی، رشته یا دیکشنری واحد یافت شود.

تغییر یافته در نسخه‌ی 3.2: ویژگی‌ها و پارامترهای اختیاری source و lineno به __init__() اضافه شدند.

exception configparser.DuplicateOptionError

استثنایی که توسط پارسرهای سخت‌گیر در صورتی پرتاب می‌شود که یک گزینه هنگام خواندن از یک پرونده، رشته یا دیکشنری واحد دو بار ظاهر شود. این امر غلط‌های املایی و خطاهای مربوط به حساسیت به حروف کوچک و بزرگ را شناسایی می‌کند، برای مثال ممکن است یک دیکشنری دو کلید داشته باشد که نشان‌دهنده‌ی یک کلید پیکربندی بدون حساسیت به حروف کوچک و بزرگ باشند.

exception configparser.NoOptionError

استثنایی که هنگامی پرتاب می‌شود که گزینه‌ی مشخص‌شده در بخش مشخص‌شده یافت نشود.

exception configparser.InterpolationError

کلاس پایه برای استثناهایی که هنگام بروز مشکلات در انجام درون‌یابی رشته پرتاب می‌شوند.

exception configparser.InterpolationDepthError

استثنایی که هنگامی پرتاب می‌شود که درون‌یابی رشته نمی‌تواند تکمیل شود، زیرا تعداد تکرارها از MAX_INTERPOLATION_DEPTH فراتر می‌رود. زیرکلاسی از InterpolationError.

exception configparser.InterpolationMissingOptionError

استثنایی که هنگامی پرتاب می‌شود که گزینه‌ای که از یک مقدار به آن ارجاع داده شده است وجود نداشته باشد. زیرکلاسی از InterpolationError.

exception configparser.InterpolationSyntaxError

استثنایی که در صورتی پرتاب می‌شود که متن منبعی که جایگذاری‌ها در آن انجام می‌شوند، با سینتکس مورد نیاز مطابقت نداشته باشد. زیرکلاسی از InterpolationError است.

exception configparser.MissingSectionHeaderError

استثنایی که هنگام تلاش برای تجزیه‌ی پرونده‌ای که هیچ سرآیند بخشی ندارد پرتاب می‌شود.

exception configparser.ParsingError

استثنایی که هنگام بروز خطا در تلاش برای تجزیه‌ی یک پرونده پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.12: ویژگی filename و آرگومان سازنده‌ی __init__() حذف شده‌اند. این موارد از 3.2 با استفاده از نام source در دسترس بوده‌اند.

exception configparser.MultilineContinuationError

استثنایی که هنگامی پرتاب می‌شود که یک کلید بدون مقدار متناظر، با یک خط تورفته ادامه یابد.

اضافه شده در نسخه‌ی 3.13.

exception configparser.UnnamedSectionDisabledError

استثنایی که هنگام تلاش برای استفاده از UNNAMED_SECTION بدون فعال‌سازی آن پرتاب می‌شود.

اضافه شده در نسخه‌ی 3.14.

exception configparser.InvalidWriteError

استثنایی که هنگامی پرتاب می‌شود که تلاش برای فراخوانی ConfigParser.write() نتواند با یک فراخوانی ConfigParser.read() در آینده به‌طور دقیق تجزیه شود.

مثال: نوشتن کلیدی که با الگوی ConfigParser.SECTCRE آغاز می‌شود، هنگام خواندن به‌عنوان سرآیند بخش تجزیه می‌شود. تلاش برای نوشتن این مورد باعث پرتاب این استثنا می‌شود.

اضافه شده در نسخه‌ی 3.14.

پانویس‌ها

[1] (1,2,3,4,5,6,7,8,9,10,11)

پارسرهای پیکربندی امکان سفارشی‌سازی گسترده‌ای را فراهم می‌کنند. اگر به تغییر رفتار شرح‌داده‌شده در ارجاع پانویس علاقه‌مند هستید، به بخش Customizing Parser Behaviour مراجعه کنید.