> **Источник:** https://python-all.ru/2.7/library/configparser.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# 13.2. [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#module-ConfigParser) – Парсер конфигурационных файлов

> **Примечание**
>
> Модуль [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#module-ConfigParser) переименован в `configparser` в Python 3. Инструмент [2to3](https://python-all.ru/2.7/glossary.html#term-2to3) автоматически адаптирует импорты при преобразовании исходного кода в Python 3.

Этот модуль определяет класс [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser). Класс [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) реализует базовый язык парсинга файлов конфигурации, который предоставляет структуру, похожую на ту, что встречается в INI-файлах Microsoft Windows. Его можно использовать для написания программ на Python, которые легко настраиваются конечными пользователями.

> **Примечание**
>
> Эта библиотека *не* интерпретирует и не записывает префиксы типов значений, используемые в расширенной версии синтаксиса INI из реестра Windows.

> **См. также**
>
> **Модуль [`shlex`](https://python-all.ru/2.7/library/shlex.html#module-shlex)**
>
> Поддержка создания мини-языков, подобных командным оболочкам Unix, которые можно использовать в качестве альтернативного формата для файлов конфигурации приложений.
>
> **Модуль [`json`](https://python-all.ru/2.7/library/json.html#module-json)**
>
> Модуль json реализует подмножество синтаксиса JavaScript, которое также можно использовать для этой цели.

Файл конфигурации состоит из секций, возглавляемых заголовком `[section]`, за которыми следуют записи `name: value`, с продолжениями в стиле [**RFC 822**](https://python-all.ru/2.7/library/configparser.html) (см. раздел 3.1.1, «LONG HEADER FIELDS»); также принимается `name=value`. Обратите внимание, что начальные пробелы удаляются из значений. Необязательные значения могут содержать строки форматирования, которые ссылаются на другие значения в той же секции или значения в специальной секции `DEFAULT`. Дополнительные значения по умолчанию можно задать при инициализации и получении. Строки, начинающиеся с `'#'` или `';'`, игнорируются и могут использоваться для комментариев.

Файлы конфигурации могут содержать комментарии, помеченные специальными символами (`#` и `;`). Комментарии могут находиться на отдельной пустой строке или вставляться в строки со значениями или именами секций. В последнем случае перед ними должен быть пробельный символ, чтобы распознаваться как комментарий. (Для обратной совместимости только `;` начинает встроенный комментарий, а `#` – нет.)

В дополнение к основной функциональности, [`SafeConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.SafeConfigParser) поддерживает интерполяцию. Это означает, что значения могут содержать строки форматирования, которые ссылаются на другие значения в той же секции или значения в специальной секции `DEFAULT`. Дополнительные значения по умолчанию можно задать при инициализации.

Например:

```python
[My Section]
foodir: %(dir)s/whatever
dir=frob
long: this value continues
   in the next line
```

разрешает `%(dir)s` в значение `dir` (в данном случае `frob`). Все раскрытия ссылок выполняются по требованию.

Значения по умолчанию можно задать, передав их в конструктор [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) в виде словаря. Дополнительные значения по умолчанию можно передать в метод `get()`, который переопределит все остальные.

Секции обычно хранятся во встроенном словаре. Альтернативный тип словаря можно передать конструктору [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser). Например, если передан тип словаря, сортирующий ключи, секции будут отсортированы при записи, как и ключи внутри каждой секции.

#### `class ConfigParser.RawConfigParser([defaults[, dict_type[, allow_no_value]]])`

Базовый объект конфигурации. Когда задан *defaults*, он инициализируется в словарь внутренних значений по умолчанию. Когда задан *dict\_type*, он будет использоваться для создания объектов-словарей для списка секций, для параметров внутри секции и для значений по умолчанию. Когда *allow\_no\_value* имеет значение true (по умолчанию: `False`), параметры без значений принимаются; значение, предоставляемое для них, равно `None`.

Этот класс не поддерживает магическое поведение интерполяции.

Все имена параметров передаются через метод [`optionxform()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.optionxform). Его реализация по умолчанию преобразует имена параметров в нижний регистр.

Новое в версии 2.3.

Изменено в версии 2.6: добавлен *dict\_type*.

Изменено в версии 2.7: Значением по умолчанию для *dict\_type* является [`collections.OrderedDict`](https://python-all.ru/2.7/library/collections.html#collections.OrderedDict). Добавлен *allow\_no\_value*.

#### `class ConfigParser.ConfigParser([defaults[, dict_type[, allow_no_value]]])`

Производный класс от [`RawConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser), реализующий магическую интерполяцию и добавляющий необязательные аргументы к методам [`get()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser.get) и [`items()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser.items). Значения в *defaults* должны быть подходящими для строковой интерполяции `%()s`. Обратите внимание, что *\_\_name\_\_* является внутренним значением по умолчанию; его значением является имя секции, и оно переопределит любое значение, предоставленное в *defaults*.

Все имена параметров, используемые при интерполяции, будут передаваться через метод `optionxform()`, как и любая другая ссылка на имя параметра. При использовании реализации по умолчанию `optionxform()` значения `foo %(bar)s` и `foo %(BAR)s` эквивалентны.

Новое в версии 2.3.

Изменено в версии 2.6: добавлен *dict\_type*.

Изменено в версии 2.7: Значением по умолчанию для *dict\_type* является [`collections.OrderedDict`](https://python-all.ru/2.7/library/collections.html#collections.OrderedDict). Добавлен *allow\_no\_value*.

#### `class ConfigParser.SafeConfigParser([defaults[, dict_type[, allow_no_value]]])`

Производный класс от [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser), реализующий более разумный вариант магической интерполяции. Эта реализация также более предсказуема. Новым приложениям следует предпочитать эту версию, если им не нужна совместимость со старыми версиями Python.

Новое в версии 2.3.

Изменено в версии 2.6: добавлен *dict\_type*.

Изменено в версии 2.7: Значением по умолчанию для *dict\_type* является [`collections.OrderedDict`](https://python-all.ru/2.7/library/collections.html#collections.OrderedDict). Добавлен *allow\_no\_value*.

#### `exception ConfigParser.Error`

Базовый класс для всех остальных исключений configparser.

#### `exception ConfigParser.NoSectionError`

Исключение, возбуждаемое, когда указанный раздел не найден.

#### `exception ConfigParser.DuplicateSectionError`

Исключение возникает, если `add_section()` вызывается с именем секции, которая уже существует.

#### `exception ConfigParser.NoOptionError`

Исключение возбуждается, когда указанный параметр не найден в указанной секции.

#### `exception ConfigParser.InterpolationError`

Базовый класс для исключений, возбуждаемых при возникновении проблем во время выполнения строковой интерполяции.

#### `exception ConfigParser.InterpolationDepthError`

Исключение возникает, когда строковую интерполяцию не удаётся завершить, потому что количество итераций превышает [`MAX_INTERPOLATION_DEPTH`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.MAX_INTERPOLATION_DEPTH). Подкласс [`InterpolationError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.InterpolationError).

#### `exception ConfigParser.InterpolationMissingOptionError`

Исключение возникает, когда параметр, на который ссылается значение, не существует. Подкласс [`InterpolationError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.InterpolationError).

Новое в версии 2.3.

#### `exception ConfigParser.InterpolationSyntaxError`

Исключение возникает, когда исходный текст, в который выполняются подстановки, не соответствует требуемому синтаксису. Подкласс [`InterpolationError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.InterpolationError).

Новое в версии 2.3.

#### `exception ConfigParser.MissingSectionHeaderError`

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

#### `exception ConfigParser.ParsingError`

Исключение, возникающее при ошибках во время разбора файла.

#### `ConfigParser.MAX_INTERPOLATION_DEPTH`

Максимальная глубина рекурсивной интерполяции для `get()`, когда параметр *raw* имеет значение false. Это актуально только для класса [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser).

> **См. также**
>
> **Модуль [`shlex`](https://python-all.ru/2.7/library/shlex.html#module-shlex)**
>
> Поддержка создания мини-языков в стиле оболочки Unix, которые можно использовать как альтернативный формат для конфигурационных файлов приложений.

## 13.2.1. Объекты RawConfigParser

Экземпляры [`RawConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser) имеют следующие методы:

#### `RawConfigParser.defaults()`

Возвращает словарь, содержащий значения по умолчанию для экземпляра.

#### `RawConfigParser.sections()`

Возвращает список доступных секций; `DEFAULT` не включается в список.

#### `RawConfigParser.add_section(section)`

Добавляет секцию с именем *section* в экземпляр. Если секция с указанным именем уже существует, возбуждается [`DuplicateSectionError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.DuplicateSectionError). Если передано имя `DEFAULT` (или любой из его вариантов без учёта регистра), возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).

#### `RawConfigParser.has_section(section)`

Указывает, присутствует ли именованный раздел в конфигурации. Раздел `DEFAULT` не распознан.

#### `RawConfigParser.options(section)`

Возвращает список опций, доступных в указанном разделе *section*.

#### `RawConfigParser.has_option(section, option)`

Если указанный раздел существует и содержит указанный параметр, вернуть [`True`](https://python-all.ru/2.7/library/constants.html#True); в противном случае вернуть [`False`](https://python-all.ru/2.7/library/constants.html#False).

Новое в версии 1.6.

#### `RawConfigParser.read(filenames)`

Пытается прочитать и разобрать список имён файлов, возвращая список имён файлов, которые были успешно разобраны. Если *имена файлов* представляет собой строку или строку Unicode, она считается именем одного файла. Если файл, указанный в *имена файлов*, не удаётся открыть, этот файл игнорируется. Это сделано для того, чтобы можно было указать список возможных мест расположения конфигурационных файлов (например, текущий каталог, домашний каталог пользователя и какой-либо общесистемный каталог), и все существующие конфигурационные файлы из списка будут прочитаны. Если ни один из указанных файлов не существует, экземпляр [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) будет содержать пустой набор данных. Приложение, которому требуется загрузить начальные значения из файла, должно загрузить необходимый файл или файлы с помощью [`readfp()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.readfp) перед вызовом [`read()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.read) для любых необязательных файлов:

```python
import ConfigParser, os

config = ConfigParser.ConfigParser()
config.readfp(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
```

Изменено в версии 2.4: Возвращает список успешно разобранных имён файлов.

#### `RawConfigParser.readfp(fp[, filename])`

Читает и разбирает данные конфигурации из файла или файлоподобного объекта, переданного в *fp* (используется только метод [`readline()`](https://python-all.ru/2.7/library/readline.html#module-readline)). Если *filename* опущен и *fp* имеет атрибут `name`, он используется для *filename*; по умолчанию `<???>`.

#### `RawConfigParser.get(section, option)`

Получает значение опции *option* для именованного раздела *section*.

#### `RawConfigParser.getint(section, option)`

Удобный метод, который приводит опцию *option* в указанном разделе *section* к целому числу.

#### `RawConfigParser.getfloat(section, option)`

Удобный метод, который приводит опцию *option* в указанном разделе *section* к числу с плавающей точкой.

#### `RawConfigParser.getboolean(section, option)`

Удобный метод, который преобразует *параметр* в указанном *разделе* в логическое значение. Обратите внимание, что допустимыми значениями параметра являются `"1"`, `"yes"`, `"true"` и `"on"`, которые заставляют этот метод возвращать `True`, а также `"0"`, `"no"`, `"false"` и `"off"` – которые заставляют его возвращать `False`. Эти строковые значения проверяются без учёта регистра. Любое другое значение приведёт к возбуждению [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).

#### `RawConfigParser.items(section)`

Возвращает список пар `(name, value)` для каждого параметра в указанном *разделе*.

#### `RawConfigParser.set(section, option, value)`

Если указанный раздел существует, устанавливает указанный параметр в заданное значение; в противном случае возбуждает [`NoSectionError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.NoSectionError). Хотя для *внутреннего* хранения нестроковых значений можно использовать [`RawConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser) (или [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) с параметром *raw*, установленным в true), полная функциональность (включая интерполяцию и вывод в файлы) достигается только при использовании строковых значений.

Новое в версии 1.6.

#### `RawConfigParser.write(fileobject)`

Записывает представление конфигурации в указанный файловый объект. Это представление может быть разобрано при будущем вызове [`read()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.read).

Новое в версии 1.6.

#### `RawConfigParser.remove_option(section, option)`

Удаляет указанный *параметр* из указанного *раздела*. Если раздел не существует, возбуждает [`NoSectionError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.NoSectionError). Если параметр существовал и был удалён, возвращает [`True`](https://python-all.ru/2.7/library/constants.html#True); в противном случае возвращает [`False`](https://python-all.ru/2.7/library/constants.html#False).

Новое в версии 1.6.

#### `RawConfigParser.remove_section(section)`

Удаляет указанный *раздел* из конфигурации. Если раздел на самом деле существовал, возвращает `True`. В противном случае возвращает `False`.

#### `RawConfigParser.optionxform(option)`

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

Для использования этого метода не обязательно наследовать ConfigParser; можно также переустановить его в экземпляре, передав функцию, принимающую строковый аргумент. Например, установка его в `str` сделает имена параметров чувствительными к регистру:

```python
cfgparser = ConfigParser()
...
cfgparser.optionxform = str
```

Обратите внимание, что при чтении конфигурационных файлов пробельные символы вокруг имён параметров удаляются перед вызовом [`optionxform()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser.optionxform).

## 13.2.2. Объекты ConfigParser

Класс [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) расширяет некоторые методы интерфейса [`RawConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.RawConfigParser), добавляя несколько необязательных аргументов.

#### `ConfigParser.get(section, option[, raw[, vars]])`

Получает значение *опции* для указанного *раздела*. Если *vars* передан, он должен быть словарём. Поиск *опции* выполняется в *vars* (если передан), *разделе* и *значениях по умолчанию* в указанном порядке.

Все `'%'` подстановки раскрываются в возвращаемых значениях, если только аргумент *raw* не равен true. Значения ключей подстановки ищутся так же, как и опция.

#### `ConfigParser.items(section[, raw[, vars]])`

Возвращает список пар `(name, value)` для каждого параметра в указанном *разделе*. Необязательные аргументы имеют тот же смысл, что и для метода [`get()`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser.get).

Новое в версии 2.3.

## 13.2.3. Объекты SafeConfigParser

Класс [`SafeConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.SafeConfigParser) реализует тот же расширенный интерфейс, что и [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser), со следующим дополнением:

#### `SafeConfigParser.set(section, option, value)`

Если указанная секция существует, устанавливает заданную опцию в указанное значение; в противном случае вызывается [`NoSectionError`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.NoSectionError). *значение* должно быть строкой ([`str`](https://python-all.ru/2.7/library/functions.html#str) или [`unicode`](https://python-all.ru/2.7/library/functions.html#unicode)); если нет, вызывается [`TypeError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.TypeError).

Новое в версии 2.4.

## 13.2.4. Примеры

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

```python
import ConfigParser

config = ConfigParser.RawConfigParser()

# При добавлении разделов или элементов добавляйте их в обратном порядке
# как они должны отображаться в реальном файле.
# Кроме того, обратите внимание, что использование RawConfigParser и raw
# режима соответствующих функций set ConfigParser позволяет присваивать
# нестроковые значения ключам внутри, но вы получите ошибку
# при попытке записи в файл или при получении в необработанном
# режиме. SafeConfigParser не допускает таких присваиваний.
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!')

# Записываем наш конфигурационный файл в 'example.cfg'
with open('example.cfg', 'wb') as configfile:
    config.write(configfile)
```

Пример повторного чтения файла конфигурации:

```python
import ConfigParser

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

# getfloat() вызывает исключение, если значение не является float.
# getint() и getboolean() делают то же самое для своих типов.
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print a_float + an_int

# Обратите внимание, что следующий вывод не интерполирует '%(bar)s' или '%(baz)s'.
# Это потому, что мы используем RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
    print config.get('Section1', 'foo')
```

Для получения интерполяции необходимо использовать [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.ConfigParser) или [`SafeConfigParser`](https://python-all.ru/2.7/library/configparser.html#ConfigParser.SafeConfigParser):

```python
import ConfigParser

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

# Установите третий необязательный аргумент get в 1, если вы хотите использовать raw-режим.
print config.get('Section1', 'foo', 0)  # -> "Python – это весело!"
print config.get('Section1', 'foo', 1)  # -> "%(bar)s – это %(baz)s!"

# Необязательный четвертый аргумент – это словарь с элементами, которые будут принимать
# приоритет при интерполяции.
print config.get('Section1', 'foo', 0, {'bar': 'Documentation',
                                        'baz': 'evil'})
```

Значения по умолчанию доступны во всех трёх типах ConfigParser. Они используются в подстановке, если используемая опция не определена в другом месте.

```python
import ConfigParser

# Новый экземпляр с 'bar' и 'baz', по умолчанию равными 'Life' и 'hard' соответственно.
config = ConfigParser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')

print config.get('Section1', 'foo')  # -> "Python – это весело!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print config.get('Section1', 'foo')  # -> "Жизнь тяжела!"
```

Функция `opt_move` ниже позволяет перемещать опции между секциями:

```python
def opt_move(config, section1, section2, option):
    try:
        config.set(section2, option, config.get(section1, option, 1))
    except ConfigParser.NoSectionError:
        # Создать несуществующий раздел
        config.add_section(section2)
        opt_move(config, section1, section2, option)
    else:
        config.remove_option(section1, option)
```

Известно, что некоторые конфигурационные файлы содержат настройки без значений, но в остальном соответствуют синтаксису, поддерживаемому [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#module-ConfigParser). Параметр *allow\_no\_value* конструктора можно использовать, чтобы указать, что такие значения следует принимать:

```pycon
>>> import ConfigParser
>>> import io

>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-external-locking
... old_passwords = 1
... skip-bdb
... skip-innodb
... """
>>> config = ConfigParser.RawConfigParser(allow_no_value=True)
>>> config.readfp(io.BytesIO(sample_config))

>>> # Настройки со значениями обрабатываются как и раньше:
>>> config.get("mysqld", "user")
'mysql'

>>> # Настройки без значений дают None:
>>> config.get("mysqld", "skip-bdb")

>>> # Настройки, которые не указаны, по-прежнему вызывают ошибку:
>>> config.get("mysqld", "does-not-exist")
Traceback (most recent call last):
  ...
ConfigParser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'
```