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

---

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

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

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

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

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

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

Помимо основной функциональности, [`SafeConfigParser`](https://python-all.ru/3.1/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/3.1/library/configparser.html#configparser.ConfigParser) в виде словаря. Дополнительные умолчания могут быть переданы в метод `get()`, который переопределит все остальные.

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

#### `class configparser.RawConfigParser(defaults=None, dict_type=collections.OrderedDict)`

Базовый объект конфигурации. Если указан параметр *defaults*, он инициализируется в словарь внутренних умолчаний. Если указан *dict\_type*, он будет использоваться для создания объектов-словарей для списка секций, для параметров внутри секции и для значений по умолчанию. Данный класс не поддерживает магическое поведение интерполяции.

Изменено в версии 3.1: Значение по умолчанию *dict\_type* – [`collections.OrderedDict`](https://python-all.ru/3.1/library/collections.html#collections.OrderedDict).

#### `class configparser.ConfigParser(defaults=None, dict_type=collections.OrderedDict)`

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

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

Изменено в версии 3.1: Значение по умолчанию *dict\_type* – [`collections.OrderedDict`](https://python-all.ru/3.1/library/collections.html#collections.OrderedDict).

#### `class configparser.SafeConfigParser(defaults=None, dict_type=collections.OrderedDict)`

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

Изменено в версии 3.1: Значение по умолчанию *dict\_type* – [`collections.OrderedDict`](https://python-all.ru/3.1/library/collections.html#collections.OrderedDict).

#### `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/3.1/library/configparser.html#configparser.MAX_INTERPOLATION_DEPTH)

. Подкласс

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

.

#### `exception configparser.InterpolationMissingOptionError`

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

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

.

#### `exception configparser.InterpolationSyntaxError`

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

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

.

#### `exception configparser.MissingSectionHeaderError`

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

#### `exception configparser.ParsingError`

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

#### `configparser.MAX_INTERPOLATION_DEPTH`

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

`get()`

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

*raw*

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

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

.

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

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

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

#### `RawConfigParser.defaults()`

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

#### `RawConfigParser.sections()`

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

`DEFAULT`

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

#### `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.1/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.1/library/exceptions.html#ValueError)

is raised.

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

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

`DEFAULT`

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

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

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

*section*

.

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

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

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

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

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

.

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

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

#### `RawConfigParser.readfp(fp, filename=None)`

Читает и разбирает данные конфигурации из файла или файлоподобного объекта *fp* (используется только метод `readline()`). Файлоподобный объект должен работать в текстовом режиме, т.е. возвращать строки из `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)`

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.1/library/exceptions.html#ValueError)

.

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

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

`(name, value)`

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

*section*

.

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

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

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

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

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

(или

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

с параметром

*raw*

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

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

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

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

Записывает представление конфигурации в указанный

[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)

, который должен быть открыт в текстовом режиме (принимающем строки). Это представление может быть разобрано последующим вызовом

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

.

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

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

*option*

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

*section*

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

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

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

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

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

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

.

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

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

*section*

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

`True`

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

`False`

.

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

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

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

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

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

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

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

#### `ConfigParser.get(section, option, raw=False, vars=None)`

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

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

#### `ConfigParser.items(section, raw=False, vars=None)`

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

`(name, value)`

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

*разделе*

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

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

.

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

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

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

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

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

.

*значение*

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

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

.

## 13.2.4. Примеры

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

```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', 'w') 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.1/library/configparser.html#configparser.ConfigParser) или [`SafeConfigParser`](https://python-all.ru/3.1/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)
```