configparser — Configuration file parser

Вихідний код: Lib/configparser.py

Цей модуль надає клас ConfigParser, який реалізує базову мову конфігурації, яка забезпечує структуру, подібну до тієї, що міститься у файлах Microsoft Windows INI. Ви можете використовувати це для написання програм на Python, які можуть бути легко налаштовані кінцевими користувачами.

Примітка

Ця бібліотека не інтерпретує та не записує префікси типу значень, які використовуються в розширеній версії синтаксису INI реєстру Windows.

Дивись також

Module tomllib

TOML is a well-specified format for application configuration files. It is specifically designed to be an improved version of INI.

Модуль shlex

Support for creating Unix shell-like mini-languages which can also be used for application configuration files.

Модуль json

The json module implements a subset of JavaScript syntax which is sometimes used for configuration, but does not support comments.

Швидкий початок

Давайте візьмемо простий файл конфігурації, який виглядає так:

[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].

It is possible to read several configurations into a single ConfigParser, where the most recently added configuration has the highest priority. Any conflicting keys are taken from the more recent configuration while the previously existing keys are retained.

>>> another_config = configparser.ConfigParser()
>>> another_config.read('example.ini')
['example.ini']
>>> another_config['topsecret.server.example']['Port']
'50022'
>>> another_config.read_string("[topsecret.server.example]\nPort=48484")
>>> another_config['topsecret.server.example']['Port']
'48484'
>>> another_config.read_dict({"topsecret.server.example": {"Port": 21212}})
>>> another_config['topsecret.server.example']['Port']
'21212'
>>> another_config['topsecret.server.example']['ForwardX11']
'no'

Така поведінка еквівалентна виклику ConfigParser.read() з кількома файлами, переданими в параметр filenames.

Підтримувані типи даних

Синтаксичні аналізатори конфігурації не вгадують типи даних значень у файлах конфігурації, завжди зберігаючи їх усередині як рядки. Це означає, що якщо вам потрібні інші типи даних, ви повинні конвертувати самостійно:

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

Оскільки це завдання дуже поширене, аналізатори конфігурації надають ряд зручних методів отримання для обробки цілих чисел, чисел з плаваючою точкою та логічних значень. Останнє є найцікавішим, тому що проста передача значення в 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]

Запасні значення

As with a dictionary, you can use a section’s get() method to provide fallback values:

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

Please note that default values have precedence over fallback values. For instance, in our example the 'CompressionLevel' key was specified only in the 'DEFAULT' section. If we try to get it from the section 'topsecret.server.example', we will always get the default, even if we specify a fallback:

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

One more thing to be aware of is that the parser-level get() method provides a custom, more complex interface, maintained for backwards compatibility. When using this method, a fallback value can be provided via the fallback keyword-only argument:

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

Той самий резервний аргумент можна використовувати з методами 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], у цьому випадку роздільник ключ/значення також може бути пропущений. Значення також можуть охоплювати кілька рядків, якщо вони мають відступ глибший, ніж перший рядок значення. Залежно від режиму аналізатора, порожні рядки можуть розглядатися як частини багаторядкових значень або ігноруватися.

By default, a valid section name can be any string that does not contain „\n“. To change this, see ConfigParser.SECTCRE.

Файли конфігурації можуть містити коментарі, перед якими стоять певні символи (# і ; за замовчуванням [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?

Інтерполяція значень

Окрім основних функцій, ConfigParser підтримує інтерполяцію. Це означає, що значення можна попередньо обробити перед поверненням із викликів 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 з інтерполяцією, встановленою на BasicInterpolation(), перетворює %(home_dir)s на значення home_dir (/Users у цьому випадку ). %(my_dir)s фактично перетворювався б на /Users/lumberjack. Усі інтерполяції виконуються на вимогу, тому ключі, які використовуються в ланцюжку посилань, не потрібно вказувати в певному порядку у файлі конфігурації.

Якщо interpolation встановлено на None, аналізатор просто повертатиме %(my_dir)s як значення my_pictures і %(home_dir)s/lumberjack як значення my_dir.

class configparser.ExtendedInterpolation

Альтернативний обробник для інтерполяції, який реалізує розширеніший синтаксис, який використовується, наприклад, у 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 об’єкти поводяться якомога ближче до справжніх словників. Інтерфейс зіставлення завершений і відповідає MutableMapping ABC. Однак є кілька відмінностей, які слід взяти до уваги:

  • За замовчуванням усі ключі в розділах доступні без урахування регістру [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 конфігуратора.

  • parser.items() сумісний із протоколом відображення (повертає список пар section_name, section_proxy, включаючи DEFAULTSECT). Однак цей метод також можна викликати за допомогою аргументів: parser.items(section, raw, vars). Останній виклик повертає список пар option, value для вказаного розділу з усіма розширеними інтерполяціями (якщо не надано raw=True).

Протокол відображення реалізовано поверх існуючого застарілого API, так що підкласи, які замінюють вихідний інтерфейс, все ще повинні мати відображення, що працюють належним чином.

Налаштування поведінки аналізатора

Існує майже стільки ж варіантів формату INI, скільки програм, які його використовують. configparser робить довгий шлях, щоб забезпечити підтримку найбільшого розумного набору доступних стилів INI. Функціональність за замовчуванням здебільшого продиктована історичним минулим, і дуже ймовірно, що ви захочете налаштувати деякі функції.

The most common way to change the way a specific config parser works is to use the __init__() options:

  • за замовчуванням, значення за замовчуванням: None

    Цей параметр приймає словник пар ключ-значення, який спочатку буде розміщено в розділі DEFAULT. Це створює елегантний спосіб підтримки стислих конфігураційних файлів, які не вказують значення, які збігаються з документованими за замовчуванням.

    Hint: if you want to specify default values for a specific section, use read_dict() before you read the actual file.

  • dict_type, значення за умовчанням: dict

    Цей параметр значно впливає на роботу протоколу відображення та вигляд записаних конфігураційних файлів. У стандартному словнику кожен розділ зберігається в порядку їх додавання до синтаксичного аналізатора. Те саме стосується параметрів у розділах.

    Альтернативний тип словника можна використовувати, наприклад, для сортування розділів і параметрів під час зворотного запису.

    Зверніть увагу: є способи додати набір пар ключ-значення за одну операцію. Якщо ви використовуєте звичайний словник у цих операціях, порядок ключів буде впорядкованим. Наприклад:

    >>> 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'

  • роздільники, значення за умовчанням: ('=', ':')

    Роздільники — це підрядки, які відокремлюють ключі від значень у розділі. Перше входження розділювального підрядка в рядок вважається роздільником. Це означає, що значення (але не ключі) можуть містити розділювачі.

    Дивіться також аргумент 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

  • строгий, значення за умовчанням: True

    When set to True, the parser will not allow for any section or option duplicates while reading from a single source (using read_file(), read_string() or read_dict()). It is recommended to use strict parsers in new applications.

    Змінено в версії 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")

    Угода про дозвіл спеціального розділу значень за замовчуванням для інших розділів або для цілей інтерполяції є потужною концепцією цієї бібліотеки, що дозволяє користувачам створювати складні декларативні конфігурації. Цей розділ зазвичай називається "ЗА УМОВЧУВАННЯМ", але його можна налаштувати так, щоб вказувати на будь-яку іншу дійсну назву розділу. Деякі типові значення включають: "загальний" або "загальний". Надана назва використовується для розпізнавання розділів за замовчуванням під час читання з будь-якого джерела та під час запису конфігурації назад у файл. Його поточне значення можна отримати за допомогою атрибута parser_instance.default_section і можна змінити під час виконання (тобто для перетворення файлів з одного формату в інший).

  • інтерполяція, значення за умовчанням: configparser.BasicInterpolation

    Поведінку інтерполяції можна налаштувати, надавши спеціальний обробник через аргумент interpolation. None можна використовувати, щоб повністю вимкнути інтерполяцію, ExtendedInterpolation() надає більш просунутий варіант, натхненний zc.buildout. Більше про цю тему див. у розділі спеціальної документації. RawConfigParser має значення за замовчуванням None.

  • конвертери, значення за замовчуванням: не встановлено

    Config parsers provide option value getters that perform type conversion. By default getint(), getfloat(), and getboolean() are implemented. Should other getters be desirable, users may define them in a subclass or pass a dictionary where each key is a name of the converter and each value is a callable implementing said conversion. For instance, passing {'decimal': decimal.Decimal} would add getdecimal() on both the parser object and all section proxies. In other words, it will be possible to write both parser_instance.getdecimal('section', 'key', fallback=0) and parser_instance['section'].getdecimal('key', 0).

    Якщо конвертеру потрібно отримати доступ до стану аналізатора, його можна реалізувати як метод у підкласі аналізатора конфігурації. Якщо назва цього методу починається з get, він буде доступний на всіх проксі-серверах розділів у формі, сумісній з dict (див. приклад 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 перетворює назви опцій у канонічну форму. Це має бути ідемпотентна функція: якщо ім’я вже є в канонічній формі, його слід повернути без змін.

ConfigParser.SECTCRE

Зкомпільований регулярний вираз, який використовується для аналізу заголовків розділів. За умовчанням [розділ] відповідає назві "розділ". Пробіли вважаються частиною назви розділу, тому [ arch ] читатиметься як розділ назви " arch ". Перевизначте цей атрибут, якщо він не підходить. Наприклад:

>>> 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 і роздільники.

Приклади застарілих 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'))

Щоб отримати інтерполяцію, використовуйте 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

Значення за замовчуванням доступні в обох типах ConfigParsers. Вони використовуються в інтерполяції, якщо використовувана опція не визначена в іншому місці.

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={})

Основний аналізатор конфігурації. Коли задано defaults, воно ініціалізується у словнику внутрішніх типових значень. Якщо вказано dict_type, він використовуватиметься для створення об’єктів словника для списку розділів, параметрів у розділі та значень за замовчуванням.

Якщо вказано роздільники, вони використовуються як набір підрядків, які відділяють ключі від значень. Якщо вказано comment_prefixes, він використовуватиметься як набір підрядків, які додають коментарі до порожніх рядків. Коментарі можна робити з відступом. Якщо задано inline_comment_prefixes, воно використовуватиметься як набір підрядків, які додають коментарі до непорожніх рядків.

Якщо strict має значення True (за замовчуванням), синтаксичний аналізатор не допускатиме жодних дублікатів розділів або параметрів під час читання з одного джерела (файлу, рядка або словника), викликаючи DuplicateSectionError або DuplicateOptionError. Коли empty_lines_in_values має значення False (за замовчуванням: True), кожен порожній рядок позначає кінець параметра. В іншому випадку внутрішні порожні рядки багаторядкового параметра зберігаються як частина значення. Якщо allow_no_value має значення True (за замовчуванням: False), параметри без значень приймаються; значенням, яке зберігається для них, є None, і вони серіалізуються без кінцевого розділювача.

When default_section is given, it specifies the name for the special section holding default values for other sections and interpolation purposes (normally named "DEFAULT"). This value can be retrieved and changed at runtime using the default_section instance attribute. This won’t re-evaluate an already parsed config file, but will be used when writing parsed settings to a new config file.

Поведінку інтерполяції можна налаштувати, надавши спеціальний обробник через аргумент interpolation. None можна використовувати, щоб повністю вимкнути інтерполяцію, ExtendedInterpolation() надає більш просунутий варіант, натхненний zc.buildout. Більше про цю тему див. у розділі спеціальної документації.

Усі назви опцій, що використовуються в інтерполяції, будуть передані через метод optionxform() так само, як і будь-яке інше посилання на назву опції. Наприклад, використовуючи стандартну реалізацію optionxform() (яка перетворює назви опцій у нижній регістр), значення foo %(bar)s і foo %(BAR)s є еквівалентними.

When converters is given, it should be a dictionary where each key represents the name of a type converter and each value is a callable implementing the conversion from string to the desired datatype. Every converter gets its own corresponding get*() method on the parser object and section proxies.

Змінено в версії 3.1: Типом dict_type є collections.OrderedDict.

Змінено в версії 3.2: Додано allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section та interpolation.

Змінено в версії 3.5: Додано аргумент конвертери.

Змінено в версії 3.7: The defaults argument is read with read_dict(), providing consistent behavior across the parser: non-string keys and values are implicitly converted to strings.

Змінено в версії 3.8: Типом dict_type є dict, оскільки тепер зберігається порядок вставки.

defaults()

Повертає словник, що містить значення за замовчуванням для всього екземпляра.

sections()

Повернути список доступних розділів; розділ за замовчуванням не включено до списку.

add_section(section)

Додайте до екземпляра розділ із назвою section. Якщо розділ із вказаною назвою вже існує, виникає DuplicateSectionError. Якщо передано назву розділу за замовчуванням, виникає помилка ValueError. Назва розділу має бути рядком; якщо ні, виникає TypeError.

Змінено в версії 3.2: Нерядкові назви розділів викликають TypeError.

has_section(section)

Вказує, чи присутній названий розділ у конфігурації. Розділ за замовчуванням не підтверджується.

options(section)

Повернути список опцій, доступних у вказаному розділі.

has_option(section, option)

Якщо заданий розділ існує та містить вказаний опціон, поверніть True; інакше повертає False. Якщо вказаний розділ має значення None або порожній рядок, передбачається DEFAULT.

read(filenames, encoding=None)

Спроба прочитати та розібрати ітерацію імен файлів, повертаючи список імен файлів, які були успішно розібрані.

Якщо filenames є рядком, об’єктом bytes або path-like object, воно розглядається як одне ім’я файлу. Якщо файл із назвою filenaname неможливо відкрити, цей файл буде проігноровано. Це призначено для того, щоб ви могли вказати ітерацію потенційних розташувань файлів конфігурації (наприклад, поточний каталог, домашній каталог користувача та деякий загальносистемний каталог), і всі існуючі файли конфігурації в ітерації будуть прочитані.

Якщо жоден із названих файлів не існує, екземпляр 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: Added the encoding parameter. Previously, all files were read using the default encoding for open().

Змінено в версії 3.6.1: Параметр filenames приймає path-like object.

Змінено в версії 3.7: Параметр filenames приймає об’єкт bytes.

read_file(f, source=None)

Читати та аналізувати конфігураційні дані з f, які мають бути повторюваними рядками Unicode (наприклад, файли, відкриті в текстовому режимі).

Optional argument source specifies the name of the file being read. If not given and f has a name attribute, that is used for source; the default is '<???>'.

Нове в версії 3.2: Replaces readfp().

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

Аналіз даних конфігурації з рядка.

Необов’язковий аргумент джерело вказує контекстно-залежну назву переданого рядка. Якщо не вказано, використовується ' <string>'. Зазвичай це має бути шлях до файлової системи або URL-адреса.

Нове в версії 3.2.

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

Завантажте конфігурацію з будь-якого об’єкта, який надає dict-подібний метод items(). Ключі - це назви розділів, значення - це словники з ключами та значеннями, які повинні бути присутніми в розділі. Якщо використовуваний тип словника зберігає порядок, розділи та їхні ключі будуть додані в порядку. Значення автоматично перетворюються на рядки.

Необов’язковий аргумент джерело вказує контекстно-залежну назву переданого словника. Якщо не вказано, використовується <dict>.

Цей метод можна використовувати для копіювання стану між парсерами.

Нове в версії 3.2.

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

Отримайте значення option для названого розділу. Якщо вказано vars, це має бути словник. Опція шукається в vars (якщо передбачено), section і в DEFAULTSECT у такому порядку. Якщо ключ не знайдено і надано резервний, він використовується як резервне значення. None можна надати як резервне значення.

Усі інтерполяції '%' розгортаються у значеннях, що повертаються, якщо аргумент raw не має значення true. Значення для ключів інтерполяції шукаються так само, як і параметр.

Змінено в версії 3.2: Аргументи raw, vars і fallback є лише ключовими словами, щоб захистити користувачів від спроб використовувати третій аргумент як резервний резерв (особливо під час використання протоколу відображення).

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

Зручний метод, який приводить опцію у вказаному розділі до цілого числа. Перегляньте get() для пояснення raw, vars і fallback.

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

A convenience method which coerces the option in the specified section to a floating point number. See get() for explanation of raw, vars and fallback.

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

Зручний метод, який приводить параметр у вказаному розділі до логічного значення. Зауважте, що допустимими значеннями параметра є '1', 'yes', 'true' і 'on', через що цей метод повертає True і '0', 'no', 'false' і 'off', які повертають False. Ці рядкові значення перевіряються без урахування регістру. Будь-яке інше значення призведе до виникнення ValueError. Перегляньте get() для пояснення raw, vars і fallback.

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

Якщо section не вказано, повертає список пар section_name, section_proxy, включаючи DEFAULTSECT.

В іншому випадку поверніть список пар ім’я, значення для опцій у вказаному розділі. Необов’язкові аргументи мають те саме значення, що й для методу get().

Змінено в версії 3.8: Елементи, присутні в vars, більше не відображаються в результатах. Попередня поведінка змішувала фактичні параметри аналізатора зі змінними, наданими для інтерполяції.

set(section, option, value)

Якщо даний розділ існує, установіть для даного параметра вказане значення; інакше підняти NoSectionError. option і value мають бути рядками; якщо ні, виникає TypeError.

write(fileobject, space_around_delimiters=True)

Запишіть представлення конфігурації у вказаний file object, який потрібно відкрити в текстовому режимі (приймаючи рядки). Це представлення може бути проаналізовано майбутнім викликом read(). Якщо space_around_delimiters має значення true, роздільники між ключами та значеннями оточуються пробілами.

Примітка

Коментарі у вихідному файлі конфігурації не зберігаються під час повторного запису конфігурації. Те, що вважається коментарем, залежить від заданих значень для comment_prefix і inline_comment_prefix.

remove_option(section, option)

Видалити вказаний параметр із зазначеного розділу. Якщо розділ не існує, підніміть NoSectionError. Якщо існувала опція для видалення, поверніть True; інакше повертає False.

remove_section(section)

Видалити вказаний розділ із конфігурації. Якщо розділ дійсно існував, поверніть True. Інакше поверніть False.

optionxform(option)

Перетворює назву параметра option, знайдену у вхідному файлі або передану кодом клієнта, у форму, яка має використовуватися у внутрішніх структурах. Реалізація за замовчуванням повертає версію option у нижньому регістрі; підкласи можуть замінити це, або код клієнта може встановити атрибут цього імені в екземплярах, щоб вплинути на цю поведінку.

Вам не потрібно створювати підкласи синтаксичного аналізатора, щоб використовувати цей метод, ви також можете встановити його на екземпляр, на функцію, яка приймає рядковий аргумент і повертає рядок. Наприклад, якщо встановити значення str, назви опцій будуть чутливими до регістру:

cfgparser = ConfigParser()
cfgparser.optionxform = str

Зауважте, що під час читання конфігураційних файлів пробіли навколо назв параметрів видаляються перед викликом optionxform().

readfp(fp, filename=None)

Застаріло починаючи з версії 3.2: Use read_file() instead.

Змінено в версії 3.2: readfp() now iterates on fp instead of calling fp.readline().

For existing code calling readfp() with arguments which don’t support iteration, the following generator may be used as a wrapper around the file-like object:

def readline_generator(fp):
    line = fp.readline()
    while line:
        yield line
        line = fp.readline()

Instead of parser.readfp(fp) use parser.read_file(readline_generator(fp)).

configparser.MAX_INTERPOLATION_DEPTH

The maximum depth for recursive interpolation for get() when the raw parameter is false. This is relevant only when the default interpolation is used.

Об’єкти 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])

Застарілий варіант ConfigParser. Він має інтерполяцію вимкнено за замовчуванням і дозволяє використовувати нерядкові назви розділів, назви параметрів і значення за допомогою небезпечних методів add_section і set, а також застарілої обробки аргументів ключового слова defaults=. .

Змінено в версії 3.8: Типом dict_type є dict, оскільки тепер зберігається порядок вставки.

Примітка

Розгляньте можливість використання ConfigParser натомість, який перевіряє типи значень, які зберігатимуться всередині. Якщо вам не потрібна інтерполяція, ви можете використати ConfigParser(interpolation=None).

add_section(section)

Додайте до екземпляра розділ із назвою section. Якщо розділ із вказаною назвою вже існує, виникає DuplicateSectionError. Якщо передано назву розділу за замовчуванням, виникає помилка ValueError.

Тип розділу не позначено, що дозволяє користувачам створювати розділи без рядкових імен. Така поведінка не підтримується та може викликати внутрішні помилки.

set(section, option, value)

Якщо даний розділ існує, установіть для даного параметра вказане значення; інакше підняти NoSectionError. Хоча можна використовувати RawConfigParser (або ConfigParser з raw параметрами, встановленими на true) для внутрішнього зберігання нерядкових значень, повна функціональність (включно з інтерполяцією та виведенням у файли) можна досягти лише за допомогою рядкових значень.

Цей метод дозволяє користувачам внутрішньо призначати нерядкові значення ключам. Така поведінка не підтримується та спричинить помилки під час спроби запису у файл або отримання його в режимі без обробки. Використовуйте API протоколу зіставлення, який не дозволяє виконувати такі призначення.

Винятки

exception configparser.Error

Базовий клас для всіх інших винятків configparser.

exception configparser.NoSectionError

Виняток виникає, коли вказаний розділ не знайдено.

exception configparser.DuplicateSectionError

Exception raised if add_section() is called with the name of a section that is already present or in strict parsers when a section if found more than once in a single input file, string or dictionary.

Змінено в версії 3.2: Added the optional source and lineno attributes and parameters to __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.2: The filename attribute and __init__() argument were renamed to source for consistency.

Виноски