# `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

The structure of INI files is described in the following section. Essentially, the file consists of sections, each of which contains keys with values. `configparser` classes can read and write such files. Let’s start by creating the above configuration file programmatically.

    >>> 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. The example below reads in an `override.ini` file, which will override any conflicting keys from the `example.ini` file.

    [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

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

The first section name may be omitted if the parser is configured to allow an unnamed top level section with `allow_unnamed_section=True`. In this case, the keys/values may be retrieved by `UNNAMED_SECTION` as in `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 Sections

The name of the first section (or unique) may be omitted and values retrieved by the `UNNAMED_SECTION` attribute.

    >>> 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` підтримує інтерполяцію. Це означає, що значення можна попередньо обробити перед поверненням із викликів `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}

## Доступ до протоколу відображення

Added in version 3.2.

Mapping protocol access is a generic name for functionality that enables using custom objects as if they were dictionaries. In case of `configparser`, the mapping interface implementation is using the `parser['section']['option']` notation.

`parser['section']` зокрема повертає проксі для даних розділу в аналізаторі. Це означає, що значення не копіюються, а беруться з оригінального аналізатора на вимогу. Ще важливішим є те, що коли значення змінюються на проксі-сервері розділу, вони фактично змінюються в оригінальному парсері.

`configparser` objects behave as close to actual dictionaries as possible. The mapping interface is complete and adheres to the `MutableMapping` ABC. However, there are a few differences that should be taken into account:

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

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

There are nearly as many INI format variants as there are applications using it. `configparser` goes a long way to provide support for the largest sensible set of INI styles available. The default functionality is mainly dictated by historical background and it’s very likely that you will want to customize some of the features.

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`

  Some configuration files are known to include settings without values, but which otherwise conform to the syntax supported by `configparser`. The allow_no_value parameter to the constructor can be used to indicate that such values should be accepted:

      >>> 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: In previous versions of `configparser` behaviour matched `comment_prefixes=('#',';')` and `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: In previous versions of `configparser` behaviour matched `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

Mainly because of backwards compatibility concerns, `configparser` provides also a legacy API with explicit `get`/`set` methods. While there are valid use cases for the methods outlined below, mapping protocol access is preferred for new projects. The legacy API is at times more advanced, low-level and downright counterintuitive.

Приклад запису в конфігураційний файл:

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

  Основний аналізатор конфігурації. Коли задано 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.

  When allow_unnamed_section is `True` (default: `False`), the first section name can be omitted. See the «Unnamed Sections» section.

  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. The example below reads in an `override.ini` file, which will override any conflicting keys from the `example.ini` file.

      [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: Додано аргумент конвертери.

  Змінено в версії 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`, оскільки тепер зберігається порядок вставки.

  Змінено в версії 3.13: Raise a `MultilineContinuationError` when allow_no_value is `True`, and a key without a value is continued with an indented line.

  Змінено в версії 3.13: The allow_unnamed_section argument was added.

  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 `'<???>'`.

    Added in version 3.2: Replaces `readfp()`.

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

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

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

    Added in version 3.2.

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

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

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

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

    Added in version 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, роздільники між ключами та значеннями оточуються пробілами.

    Змінено в версії 3.14: Raises InvalidWriteError if this would write a representation which cannot be accurately parsed by a future `read()` call from this parser.

  Примітка

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

configparser.UNNAMED_SECTION

  A special object representing a section name used to reference the unnamed section (see Unnamed Sections).

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=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: Додано аргумент конвертери.

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

  Змінено в версії 3.13: The allow_unnamed_section argument was added.

  Примітка

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

  add_section(section)

    Add a section named section or `UNNAMED_SECTION` to the instance.

    If the given section already exists, `DuplicateSectionError` is raised. If the default section name is passed, `ValueError` is raised. If `UNNAMED_SECTION` is passed and support is disabled, `UnnamedSectionDisabledError` is raised.

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

  Змінено в версії 3.14: Added support for `UNNAMED_SECTION`.

  set(section, option, value)

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

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

## Винятки

exception configparser.Error

  Base class for all other `configparser` exceptions.

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.12: The `filename` attribute and `__init__()` constructor argument were removed. They have been available using the name `source` since 3.2.

exception configparser.MultilineContinuationError

  Exception raised when a key without a corresponding value is continued with an indented line.

  Added in version 3.13.

exception configparser.UnnamedSectionDisabledError

  Exception raised when attempting to use the `UNNAMED_SECTION` without enabling it.

  > Added in version 3.14.

exception configparser.InvalidWriteError

  Exception raised when an attempted `ConfigParser.write()` would not be parsed accurately with a future `ConfigParser.read()` call.

  Ex: Writing a key beginning with the `ConfigParser.SECTCRE` pattern would parse as a section header when read. Attempting to write this will raise this exception.

  Added in version 3.14.

Виноски

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

Синтаксичні аналізатори конфігурації дозволяють здійснювати серйозні налаштування. Якщо ви зацікавлені в зміні поведінки, окресленої посиланням на виноску, зверніться до розділу «Налаштування поведінки аналізатора» (Customizing Parser Behaviour).