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

---

# `configparser` – Парсер конфигурационных файлов

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

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

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

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

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

Базовый объект конфигурации. Если указан параметр

*defaults*

, он инициализируется в словарь внутренних умолчаний. Если указан

*dict\_type*

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

#### `[configparser.ConfigParser]class configparser.ConfigParser([defaults])`

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

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

#### `[configparser.SafeConfigParser]class configparser.SafeConfigParser([defaults])`

Производный класс от

[`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser)

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

#### `[configparser.NoSectionError]exception configparser.NoSectionError`

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

#### `[configparser.DuplicateSectionError]exception configparser.DuplicateSectionError`

Исключение возбуждается, если

`add_section()`

вызывается с именем секции, которая уже существует.

#### `[configparser.NoOptionError]exception configparser.NoOptionError`

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

#### `[configparser.InterpolationError]exception configparser.InterpolationError`

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

#### `[configparser.InterpolationDepthError]exception configparser.InterpolationDepthError`

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

[`MAX_INTERPOLATION_DEPTH`](https://python-all.ru/3.0/library/configparser.html#configparser.MAX_INTERPOLATION_DEPTH)

. Подкласс

[`InterpolationError`](https://python-all.ru/3.0/library/configparser.html#configparser.InterpolationError)

.

#### `[configparser.InterpolationMissingOptionError]exception configparser.InterpolationMissingOptionError`

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

[`InterpolationError`](https://python-all.ru/3.0/library/configparser.html#configparser.InterpolationError)

.

#### `[configparser.InterpolationSyntaxError]exception configparser.InterpolationSyntaxError`

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

[`InterpolationError`](https://python-all.ru/3.0/library/configparser.html#configparser.InterpolationError)

.

#### `[configparser.MissingSectionHeaderError]exception configparser.MissingSectionHeaderError`

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

#### `[configparser.ParsingError]exception configparser.ParsingError`

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

#### `[configparser.MAX_INTERPOLATION_DEPTH]configparser.MAX_INTERPOLATION_DEPTH`

Максимальная глубина рекурсивной интерполяции для

`get()`

, когда параметр

*raw*

имеет значение false. Это актуально только для класса

[`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser)

.

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

## Объекты RawConfigParser

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

#### `[configparser.RawConfigParser.defaults]RawConfigParser.defaults()`

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

#### `[configparser.RawConfigParser.sections]RawConfigParser.sections()`

Возвращает список доступных секций;

`DEFAULT`

не включается в список.

#### `[configparser.RawConfigParser.add_section]RawConfigParser.add_section(section)`

Add a section named

*section*

to the instance. If a section by the given name already exists,

[`DuplicateSectionError`](https://python-all.ru/3.0/library/configparser.html#configparser.DuplicateSectionError)

is raised. If the name

`DEFAULT`

(or any of it’s case-insensitive variants) is passed,

[`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError)

is raised.

#### `[configparser.RawConfigParser.has_section]RawConfigParser.has_section(section)`

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

`DEFAULT`

не учитывается.

#### `[configparser.RawConfigParser.options]RawConfigParser.options(section)`

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

*section*

.

#### `[configparser.RawConfigParser.has_option]RawConfigParser.has_option(section, option)`

Если указанный раздел существует и содержит указанную опцию, возвращает

[`True`](https://python-all.ru/3.0/library/constants.html#True)

; в противном случае возвращает

[`False`](https://python-all.ru/3.0/library/constants.html#False)

.

#### `[configparser.RawConfigParser.read]RawConfigParser.read(filenames)`

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

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

Читает и разбирает конфигурационные данные из файла или файлоподобного объекта

*fp*

(используется только метод

`readline()`

). Если параметр

*filename*

не указан, а

*fp*

имеет атрибут

`name`

, то он используется как

*filename*

; по умолчанию –

`<???>`

.

#### `[configparser.RawConfigParser.get]RawConfigParser.get(section, option)`

Получает значение опции

*option*

для именованного раздела

*section*

.

#### `[configparser.RawConfigParser.getint]RawConfigParser.getint(section, option)`

Удобный метод, который приводит опцию

*option*

в указанном разделе

*section*

к целому числу.

#### `[configparser.RawConfigParser.getfloat]RawConfigParser.getfloat(section, option)`

Удобный метод, который приводит опцию

*option*

в указанном разделе

*section*

к числу с плавающей точкой.

#### `[configparser.RawConfigParser.getboolean]RawConfigParser.getboolean(section, option)`

A convenience method which coerces the

*option*

in the specified

*section*

to a Boolean value. Note that the accepted values for the option are

`"1"`

,

`"yes"`

,

`"true"`

, and

`"on"`

, which cause this method to return

`True`

, and

`"0"`

,

`"no"`

,

`"false"`

, and

`"off"`

, which cause it to return

`False`

. These string values are checked in a case-insensitive manner. Any other value will cause it to raise

[`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError)

.

#### `[configparser.RawConfigParser.items]RawConfigParser.items(section)`

Возвращает список пар

`(name, value)`

для каждой опции в заданном разделе

*section*

.

#### `[configparser.RawConfigParser.set]RawConfigParser.set(section, option, value)`

Если указанный раздел существует, устанавливает заданную опцию в указанное значение; в противном случае возбуждает

[`NoSectionError`](https://python-all.ru/3.0/library/configparser.html#configparser.NoSectionError)

. Хотя можно использовать

[`RawConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.RawConfigParser)

(или

[`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser)

с параметром

*raw*

, установленным в true) для

*внутреннего*

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

#### `[configparser.RawConfigParser.write]RawConfigParser.write(fileobject)`

Записывает представление конфигурации в указанный файловый объект. Это представление может быть разобрано последующим вызовом

[`read()`](https://python-all.ru/3.0/library/configparser.html#configparser.RawConfigParser.read)

.

#### `[configparser.RawConfigParser.remove_option]RawConfigParser.remove_option(section, option)`

Удаляет указанную опцию

*option*

из указанного раздела

*section*

. Если раздел не существует, возбуждает

[`NoSectionError`](https://python-all.ru/3.0/library/configparser.html#configparser.NoSectionError)

. Если опция существовала и была удалена, возвращает

[`True`](https://python-all.ru/3.0/library/constants.html#True)

; в противном случае возвращает

[`False`](https://python-all.ru/3.0/library/constants.html#False)

.

#### `[configparser.RawConfigParser.remove_section]RawConfigParser.remove_section(section)`

Удаляет указанный раздел

*section*

из конфигурации. Если раздел действительно существовал, возвращает

`True`

. В противном случае возвращает

`False`

.

#### `[configparser.RawConfigParser.optionxform]RawConfigParser.optionxform(option)`

Преобразует имя опции

*option*

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

*option*

; подклассы могут переопределить это, или клиентский код может установить атрибут с таким именем на экземплярах, чтобы повлиять на это поведение. Установка этого значения в

[`str()`](https://python-all.ru/3.0/library/functions.html#str)

, например, сделает имена опций чувствительными к регистру.

## Объекты ConfigParser

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

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

Получает значение

*option*

для указанной

*section*

. Все

`'%'`

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

*vars*

, если аргумент

*raw*

не равен true.

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

Возвращает список пар

`(name, value)`

для каждой опции в указанном

*разделе*

. Необязательные аргументы имеют тот же смысл, что и для метода

[`get()`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser.get)

.

## Объекты SafeConfigParser

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

#### `[configparser.SafeConfigParser.set]SafeConfigParser.set(section, option, value)`

Если указанный раздел существует, устанавливает для данной опции заданное значение; в противном случае возбуждает

[`NoSectionError`](https://python-all.ru/3.0/library/configparser.html#configparser.NoSectionError)

.

*значение*

должен быть строкой; если это не так, возбуждается

[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)

.

## Примеры

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

```python
import configparser

config = configparser.RawConfigParser()

# При добавлении разделов или элементов добавляйте их в обратном порядке
# как они должны отображаться в реальном файле.
# Кроме того, обратите внимание, что использование RawConfigParser и raw
# режима соответствующих функций set ConfigParser позволяет присваивать
# нестроковые значения ключам внутри, но вы получите ошибку
# при попытке записи в файл или при получении в необработанном
# режиме. SafeConfigParser не допускает таких присваиваний.
config.add_section('Section1')
config.set('Section1', 'int', '15')
config.set('Section1', 'bool', 'true')
config.set('Section1', '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() делают то же самое для своих типов.
float = config.getfloat('Section1', 'float')
int = config.getint('Section1', 'int')
print(float + int)

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

Для использования подстановки потребуется [`ConfigParser`](https://python-all.ru/3.0/library/configparser.html#configparser.ConfigParser) или [`SafeConfigParser`](https://python-all.ru/3.0/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)
```