configparser — анализатор файлов конфигурации

Исходный код: Lib/configparser.py

Этот модуль предоставляет класс ConfigParser, реализующий простой язык конфигурации со структурой, похожей на структуру INI-файлов Microsoft Windows. С его помощью можно писать программы на Python, которые конечные пользователи могут легко настраивать.

Примечание

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

См. также

Module tomllib: TOML — хорошо специфицированный формат файлов конфигурации приложений. Он специально разработан как улучшенная версия INI.
Module shlex: Поддержка создания мини-языков, похожих на оболочку Unix, которые также можно использовать для файлов конфигурации приложений.
Module json: Модуль json реализует подмножество синтаксиса JavaScript, который иногда используется для конфигурации, но не поддерживает комментарии.

Краткое руководство

Рассмотрим простой файл конфигурации следующего вида:

[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes

[forge.example]
User = hg

[topsecret.server.example]
Port = 50022
ForwardX11 = no

Структура INI-файлов описана в следующем разделе. По сути, файл состоит из секций, каждая из которых содержит ключи со значениями. Классы configparser могут читать и записывать такие файлы. Начнём с программного создания приведённого выше файла конфигурации.

>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'}
>>> config['forge.example'] = {}
>>> config['forge.example']['User'] = 'hg'
>>> config['topsecret.server.example'] = {}
>>> topsecret = config['topsecret.server.example']
>>> topsecret['Port'] = '50022'     # mutates the parser
>>> topsecret['ForwardX11'] = 'no'  # same here
>>> config['DEFAULT']['ForwardX11'] = 'yes'
>>> with open('example.ini', 'w') as configfile:
...   config.write(configfile)
...

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

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

>>> config = configparser.ConfigParser()
>>> config.sections()
[]
>>> config.read('example.ini')
['example.ini']
>>> config.sections()
['forge.example', 'topsecret.server.example']
>>> 'forge.example' in config
True
>>> 'python.org' in config
False
>>> config['forge.example']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.example']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['forge.example']:
...     print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['forge.example']['ForwardX11']
'yes'

Как видно выше, API довольно прост. Единственный нюанс связан с секцией DEFAULT, которая предоставляет значения по умолчанию для всех остальных секций [1]. Также обратите внимание, что ключи в секциях не чувствительны к регистру и хранятся в нижнем регистре [1].

Можно прочитать несколько конфигураций в один объект ConfigParser; при этом конфигурация, добавленная последней, имеет наивысший приоритет. Конфликтующие ключи берутся из более поздней конфигурации, а ранее существовавшие ключи сохраняются. В примере ниже читается файл override.ini, который переопределит все конфликтующие ключи из файла example.ini.

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

Резервные значения

Как и в случае со словарём, можно использовать метод get() секции, чтобы указать резервные значения:

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

Обратите внимание, что значения по умолчанию имеют приоритет над резервными значениями. Например, в нашем примере ключ 'CompressionLevel' был указан только в секции 'DEFAULT'. Если попытаться получить его из секции 'topsecret.server.example', всегда будет возвращено значение по умолчанию, даже если указать резервное значение:

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

Ещё один важный момент: метод get() на уровне анализатора предоставляет особый, более сложный интерфейс, сохранённый для обратной совместимости. При использовании этого метода резервное значение можно передать через аргумент, указываемый только по ключевому слову, fallback:

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

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

По умолчанию допустимым именем секции может быть любая строка, не содержащая символа «\n». Чтобы изменить это поведение, см. ConfigParser.SECTCRE.

Имя первой секции можно опустить, если анализатор настроен на разрешение безымянной секции верхнего уровня с помощью allow_unnamed_section=True. В этом случае ключи/значения можно получать через UNNAMED_SECTION, как в 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_SECTION.

>>> 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 с параметром interpolation, установленным в BasicInterpolation(), разрешит %(home_dir)s в значение home_dir (в данном случае /Users). В результате %(my_dir)s будет разрешено в /Users/lumberjack. Вся интерполяция выполняется по запросу, поэтому ключи, используемые в цепочке ссылок, не обязательно указывать в файле конфигурации в каком-либо определённом порядке.

Если для interpolation задано значение None, анализатор просто вернёт %(my_dir)s/Pictures как значение my_pictures и %(home_dir)s/lumberjack как значение my_dir.

class configparser.ExtendedInterpolation

Альтернативный обработчик интерполяции, реализующий более продвинутый синтаксис, используемый, например, в zc.buildout. Расширенная интерполяция использует ${section:option} для обозначения значения из другой секции. Интерполяция может охватывать несколько уровней. Для удобства, если часть section: опущена, интерполяция выполняется относительно текущей секции (и, возможно, значений по умолчанию из специальной секции).

В случае расширенной интерполяции приведённая выше конфигурация с базовой интерполяцией выглядела бы так:

[Paths]
home_dir: /Users
my_dir: ${home_dir}/lumberjack
my_pictures: ${my_dir}/Pictures

[Escape]
# use a $$ to escape the $ sign ($ is the only character that needs to be escaped):
cost: $$80

Можно также получать значения из других секций:

[Common]
home_dir: /Users
library_dir: /Library
system_dir: /System
macports_dir: /opt/local

[Frameworks]
Python: 3.2
path: ${Common:system_dir}/Library/Frameworks/

[Arthur]
nickname: Two Sheds
last_name: Jackson
my_dir: ${Common:home_dir}/twosheds
my_pictures: ${my_dir}/Pictures
python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}

Доступ через протокол отображения

Добавлено в версии 3.2.

Доступ через протокол отображения — это общее название функциональности, позволяющей использовать пользовательские объекты как словари. В случае configparser реализация интерфейса отображения использует нотацию parser['section']['option'].

В частности, parser['section'] возвращает прокси для данных секции в анализаторе. Это означает, что значения не копируются, а извлекаются из исходного анализатора по запросу. Ещё важнее то, что при изменении значений через прокси секции они фактически изменяются в исходном анализаторе.

Объекты configparser ведут себя максимально похоже на обычные словари. Интерфейс отображения реализован полностью и соответствует ABC MutableMapping. Однако следует учитывать несколько отличий:

По умолчанию доступ ко всем ключам в секциях не зависит от регистра [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 configparser.
parser.items() совместим с протоколом отображения (возвращает список пар section_name, section_proxy, включая DEFAULTSECT). Однако этот метод также можно вызвать с аргументами: parser.items(section, raw, vars). Последний вызов возвращает список пар option, value для указанной section с раскрытой интерполяцией (если не задано raw=True).

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

Настройка поведения анализатора

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

Самый распространённый способ изменить работу конкретного анализатора конфигурации — использовать параметры __init__():

defaults, значение по умолчанию: None

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

Совет: чтобы указать значения по умолчанию для конкретной секции, используйте read_dict() до чтения самого файла.
dict_type, значение по умолчанию: dict

Этот параметр существенно влияет на работу протокола отображения и внешний вид записываемых файлов конфигурации. При использовании стандартного словаря каждая секция хранится в порядке добавления в анализатор. То же относится к параметрам внутри секций.

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

Обратите внимание: существует несколько способов добавить набор пар «ключ-значение» одной операцией. При использовании в таких операциях обычного словаря порядок ключей будет сохранён. Например:
```
>>> parser = configparser.ConfigParser()
>>> parser.read_dict({'section1': {'key1': 'value1',
...                                'key2': 'value2',
...                                'key3': 'value3'},
...                   'section2': {'keyA': 'valueA',
...                                'keyB': 'valueB',
...                                'keyC': 'valueC'},
...                   'section3': {'foo': 'x',
...                                'bar': 'y',
...                                'baz': 'z'}
... })
>>> parser.sections()
['section1', 'section2', 'section3']
>>> [option for option in parser['section3']]
['foo', 'bar', 'baz']
```

allow_no_value, значение по умолчанию: False

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

>>> import configparser

>>> sample_config = """
... [mysqld]
...   user = mysql
...   pid-file = /var/run/mysqld/mysqld.pid
...   skip-external-locking
...   old_passwords = 1
...   skip-bdb
...   # we don't need ACID today
...   skip-innodb
... """
>>> config = configparser.ConfigParser(allow_no_value=True)
>>> config.read_string(sample_config)

>>> # Settings with values are treated as before:
>>> config["mysqld"]["user"]
'mysql'

>>> # Settings without values provide None:
>>> config["mysqld"]["skip-bdb"]

>>> # Settings which aren't specified still raise an error:
>>> config["mysqld"]["does-not-exist"]
Traceback (most recent call last):
  ...
KeyError: 'does-not-exist'

delimiters, значение по умолчанию: ('=', ':')

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

См. также аргумент space_around_delimiters метода ConfigParser.write().
comment_prefixes, значение по умолчанию: ('#', ';')
inline_comment_prefixes, значение по умолчанию: None

Префиксы комментариев — это строки, обозначающие начало допустимого комментария в файле конфигурации. comment_prefixes используются только в остальных пустых строках (с необязательным отступом), тогда как inline_comment_prefixes можно использовать после любого допустимого значения (например, имени секции, параметра, а также в пустых строках). По умолчанию встроенные комментарии отключены, а '#' и ';' используются как префиксы комментариев для целой строки.

Изменено в версии 3.2: В предыдущих версиях поведение configparser соответствовало comment_prefixes=('#',';') и inline_comment_prefixes=(';',).

Обратите внимание, что анализаторы конфигурации не поддерживают экранирование префиксов комментариев, поэтому использование inline_comment_prefixes может помешать пользователям указывать в значениях параметров символы, используемые в качестве префиксов комментариев. Если есть сомнения, не задавайте inline_comment_prefixes. В любом случае единственный способ сохранить символы префикса комментария в начале строки многострочного значения — выполнить интерполяцию префикса, например:
```
>>> from configparser import ConfigParser, ExtendedInterpolation
>>> parser = ConfigParser(interpolation=ExtendedInterpolation())
>>> # the default BasicInterpolation could be used as well
>>> parser.read_string("""
... [DEFAULT]
... hash = #
...
... [hashes]
... shebang =
...   ${hash}!/usr/bin/env python
...   ${hash} -*- coding: utf-8 -*-
...
... extensions =
...   enabled_extension
...   another_extension
...   #disabled_by_comment
...   yet_another_extension
...
... interpolation not necessary = if # is not at line start
... even in multiline values = line #1
...   line #2
...   line #3
... """)
>>> print(parser['hashes']['shebang'])

#!/usr/bin/env python
# -*- coding: utf-8 -*-
>>> print(parser['hashes']['extensions'])

enabled_extension
another_extension
yet_another_extension
>>> print(parser['hashes']['interpolation not necessary'])
if # is not at line start
>>> print(parser['hashes']['even in multiline values'])
line #1
line #2
line #3
```
strict, значение по умолчанию: True

Если задано значение True, анализатор не допускает повторяющихся секций или параметров при чтении из одного источника (с помощью read_file(), read_string() или read_dict()). Для новых приложений рекомендуется использовать строгие анализаторы.

Изменено в версии 3.2: В предыдущих версиях поведение configparser соответствовало strict=False.
empty_lines_in_values, значение по умолчанию: True

В анализаторах конфигурации значения могут занимать несколько строк, если у них больший отступ, чем у содержащего их ключа. По умолчанию анализаторы также допускают пустые строки в составе значений. В то же время сами ключи могут иметь произвольный отступ для улучшения читаемости. В результате при увеличении размера и сложности файлов конфигурации пользователю легко потерять понимание их структуры. Рассмотрим, например:
```
[Section]
key = multiline
  value with a gotcha

 this = is still a part of the multiline value of 'key'
```
Пользователю может быть особенно сложно это заметить, если для редактирования файла используется пропорциональный шрифт. Поэтому, если приложению не нужны значения с пустыми строками, стоит рассмотреть возможность их запрета. Тогда пустые строки всегда будут разделять ключи. В приведённом выше примере это приведёт к созданию двух ключей: key и this.
default_section, значение по умолчанию: configparser.DEFAULTSECT (то есть "DEFAULT")

Соглашение о специальной секции со значениями по умолчанию для других секций или для целей интерполяции — мощная возможность этой библиотеки, позволяющая пользователям создавать сложные декларативные конфигурации. Обычно эта секция называется "DEFAULT", но это имя можно изменить на любое другое допустимое имя секции. Среди типичных вариантов: "general" или "common". Указанное имя используется для распознавания секций значений по умолчанию при чтении из любого источника, а также при записи конфигурации обратно в файл. Текущее значение можно получить с помощью атрибута parser_instance.default_section и изменить во время выполнения (например, для преобразования файлов из одного формата в другой).
interpolation, значение по умолчанию: configparser.BasicInterpolation

Поведение интерполяции можно настроить, передав пользовательский обработчик через аргумент interpolation. Для полного отключения интерполяции можно использовать None, а ExtendedInterpolation() предоставляет более продвинутый вариант, вдохновлённый zc.buildout. Подробнее об этом — в специальном разделе документации. Для RawConfigParser значением по умолчанию является None.
converters, значение по умолчанию: не задано

Анализаторы конфигурации предоставляют методы получения значений параметров с преобразованием типов. По умолчанию реализованы getint(), getfloat() и getboolean(). Если нужны другие методы получения значений, пользователь может определить их в подклассе или передать словарь, в котором каждый ключ — это имя преобразователя, а каждое значение — вызываемый объект, выполняющий соответствующее преобразование. Например, передача {'decimal': decimal.Decimal} добавит getdecimal() как объекту анализатора, так и всем прокси секций. Иными словами, можно будет записывать и parser_instance.getdecimal('section', 'key', fallback=0), и parser_instance['section'].getdecimal('key', 0).

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

Скомпилированное регулярное выражение, используемое для разбора заголовков секций. По умолчанию оно сопоставляет [section] с именем "section". Пробельные символы считаются частью имени секции, поэтому [ larch ] будет прочитано как секция с именем " larch ". Если это нежелательно, переопределите этот атрибут. Например:

>>> 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 и delimiters.

Примеры устаревшего API

В основном из соображений обратной совместимости configparser также предоставляет устаревший API с явными методами get/set. Хотя у описанных ниже методов есть обоснованные варианты применения, для новых проектов предпочтителен доступ через протокол отображения. Устаревший API порой более сложен, низкоуровнев и откровенно неинтуитивен.

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

import configparser

config = configparser.RawConfigParser()

# Please note that using RawConfigParser's set functions, you can assign
# non-string values to keys internally, but will receive an error when
# attempting to write to a file or when you get it in non-raw mode. Setting
# values using the mapping protocol or ConfigParser's set() does not allow
# such assignments to take place.
config.add_section('Section1')
config.set('Section1', 'an_int', '15')
config.set('Section1', 'a_bool', 'true')
config.set('Section1', 'a_float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s is %(baz)s!')

# Writing our configuration file to 'example.cfg'
with open('example.cfg', 'w') as configfile:
    config.write(configfile)

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

import configparser

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

# getfloat() raises an exception if the value is not a float
# getint() and getboolean() also do this for their respective types
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print(a_float + an_int)

# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
# This is because we are using a RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
    print(config.get('Section1', 'foo'))

Чтобы использовать интерполяцию, воспользуйтесь ConfigParser:

import configparser

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

# Set the optional *raw* argument of get() to True if you wish to disable
# interpolation in a single get operation.
print(cfg.get('Section1', 'foo', raw=False))  # -> "Python is fun!"
print(cfg.get('Section1', 'foo', raw=True))   # -> "%(bar)s is %(baz)s!"

# The optional *vars* argument is a dict with members that will take
# precedence in interpolation.
print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
                                       'baz': 'evil'}))

# The optional *fallback* argument can be used to provide a fallback value
print(cfg.get('Section1', 'foo'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'foo', fallback='Monty is not.'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))
      # -> "No such things as monsters."

# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError
# but we can also use:

print(cfg.get('Section1', 'monster', fallback=None))
      # -> None

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

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, он будет использоваться для создания объектов словаря списка разделов, параметров внутри раздела и значений по умолчанию.

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

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

Если задан параметр default_section, он указывает имя специального раздела, содержащего значения по умолчанию для других разделов и целей интерполяции (обычно это "DEFAULT"). Это значение можно получить и изменить во время выполнения с помощью атрибута экземпляра default_section. Это не приведёт к повторной обработке уже разобранного файла конфигурации, но будет использоваться при записи разобранных настроек в новый файл конфигурации.

Поведение интерполяции можно настроить, указав пользовательский обработчик через аргумент interpolation. None можно использовать для полного отключения интерполяции, а ExtendedInterpolation() предоставляет более продвинутый вариант, основанный на zc.buildout. Подробнее об этом см. в специальном разделе документации.

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

Если задан параметр converters, это должен быть словарь, в котором каждый ключ обозначает имя преобразователя типа, а каждое значение — вызываемый объект, выполняющий преобразование строки в нужный тип данных. Для каждого преобразователя в объекте парсера и прокси разделов создаётся соответствующий метод get*().

Если allow_unnamed_section имеет значение True (по умолчанию: False), имя первого раздела можно опустить. См. раздел «Разделы без имени».

Можно прочитать несколько конфигураций в один объект ConfigParser, при этом последняя добавленная конфигурация имеет наивысший приоритет. При конфликте ключи берутся из более поздней конфигурации, а ранее существовавшие ключи сохраняются. В примере ниже считывается файл override.ini, который переопределит конфликтующие ключи из файла example.ini.

[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: Добавлен аргумент converters.

Изменено в версии 3.7: Аргумент defaults считывается с помощью read_dict(), что обеспечивает единообразное поведение парсера: ключи и значения, не являющиеся строками, неявно преобразуются в строки.

Изменено в версии 3.8: Тип dict_type по умолчанию — dict, поскольку теперь он сохраняет порядок вставки.

Изменено в версии 3.13: Вызывается исключение MultilineContinuationError, если allow_no_value имеет значение True, а за ключом без значения следует строка с отступом.

Изменено в версии 3.13: Добавлен аргумент allow_unnamed_section.

defaults(): Возвращает словарь значений по умолчанию для всего экземпляра.

sections(): Возвращает список доступных разделов; раздел по умолчанию в список не включается.

add_section(section): Добавляет в экземпляр раздел с именем section. Если раздел с таким именем уже существует, вызывается исключение DuplicateSectionError. Если передано имя раздела по умолчанию, вызывается исключение ValueError. Имя раздела должно быть строкой; в противном случае вызывается исключение TypeError.

Изменено в версии 3.2: Для имён разделов, не являющихся строками, вызывается исключение TypeError.

has_section(section): Показывает, присутствует ли в конфигурации раздел с указанным именем section. Раздел по умолчанию не учитывается.

options(section): Возвращает список параметров, доступных в указанном разделе section.

has_option(section, option): Если указанный раздел section существует и содержит указанный параметр option, возвращает True; в противном случае возвращает False. Если указанный раздел section равен None или является пустой строкой, предполагается, что это DEFAULT.

read(filenames, encoding=None)

Пытается прочитать и разобрать итерируемый объект с именами файлов и возвращает список успешно разобранных файлов.

Если filenames — это строка, объект bytes или объект, подобный пути, он рассматривается как имя одного файла. Если файл, указанный в filenames, не удаётся открыть, он будет проигнорирован. Это позволяет указать итерируемый объект с возможными расположениями файлов конфигурации (например, текущий каталог, домашний каталог пользователя и системный каталог), после чего будут прочитаны все существующие файлы конфигурации из этого объекта.

Если ни один из указанных файлов не существует, экземпляр 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: Добавлен параметр encoding. Ранее все файлы читались с использованием кодировки по умолчанию для open().

Изменено в версии 3.6.1: Параметр filenames принимает объект, подобный пути.

Изменено в версии 3.7: Параметр filenames принимает объект bytes.

read_file(f, source=None)

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

Необязательный аргумент source задаёт имя читаемого файла. Если он не указан, а у f есть атрибут name, этот атрибут используется как source; по умолчанию используется '<???>'.

Добавлено в версии 3.2: Заменяет readfp().

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

Разбирает данные конфигурации из строки.

Необязательный аргумент source задаёт контекстное имя переданной строки. Если он не указан, используется '<string>'. Обычно это путь в файловой системе или URL.

Добавлено в версии 3.2.

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

Загружает конфигурацию из любого объекта, предоставляющего метод items(), совместимый со словарём. Ключи — это имена разделов, а значения — словари с ключами и значениями, которые должны присутствовать в разделе. Если используемый тип словаря сохраняет порядок, разделы и их ключи будут добавлены в том же порядке. Значения автоматически преобразуются в строки.

Необязательный аргумент source задаёт контекстное имя переданного словаря. Если он не указан, используется <dict>.

Этот метод можно использовать для копирования состояния между парсерами.

Добавлено в версии 3.2.

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

Получает значение параметра option для указанного раздела section. Если задан параметр vars, он должен быть словарём. Параметр option ищется последовательно в vars (если он задан), section и DEFAULTSECT. Если ключ не найден и задан параметр fallback, используется его значение. В качестве значения fallback можно указать None.

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

Изменено в версии 3.2: Аргументы raw, vars и fallback можно задавать только по ключевому слову, чтобы предотвратить случайное использование третьего аргумента в качестве запасного значения fallback (особенно при использовании протокола отображения).

getint(section, option, *, raw=False, vars=None[, fallback]): Удобный метод, который преобразует параметр option в указанном разделе section в целое число. Объяснение параметров raw, vars и fallback см. в описании get().

getfloat(section, option, *, raw=False, vars=None[, fallback]): Удобный метод, который преобразует параметр option в указанном разделе section в число с плавающей точкой. Объяснение параметров raw, vars и fallback см. в описании get().

getboolean(section, option, *, raw=False, vars=None[, fallback]): Удобный метод, который преобразует параметр option в указанном разделе section в логическое значение. Обратите внимание: допустимые значения параметра — '1', 'yes', 'true' и 'on' — заставляют этот метод возвращать True, а '0', 'no', 'false' и 'off' заставляют его возвращать False. Эти строковые значения проверяются без учёта регистра. Для любого другого значения вызывается исключение ValueError. Объяснение параметров raw, vars и fallback см. в описании get().

items(raw=False, vars=None)

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

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

В противном случае возвращает список пар name, value для параметров указанного раздела section. Необязательные аргументы имеют тот же смысл, что и в методе get().

Изменено в версии 3.8: Элементы из vars больше не появляются в результате. Прежнее поведение смешивало реальные параметры парсера с переменными, переданными для интерполяции.

set(section, option, value): Если указанный раздел существует, задаёт указанному параметру заданное значение; в противном случае вызывает исключение NoSectionError. option и value должны быть строками; в противном случае вызывается исключение TypeError.

write(fileobject, space_around_delimiters=True): Записывает представление конфигурации в указанный файловый объект, который должен быть открыт в текстовом режиме (принимать строки). Это представление можно разобрать при последующем вызове read(). Если space_around_delimiters имеет значение true, вокруг разделителей между ключами и значениями добавляются пробелы.

Примечание

Комментарии из исходного файла конфигурации не сохраняются при повторной записи конфигурации. То, что считается комментарием, зависит от заданных значений comment_prefix и inline_comment_prefix.

remove_option(section, option): Удаляет указанный параметр option из указанного раздела section. Если раздел не существует, вызывает исключение NoSectionError. Если удаляемый параметр существовал, возвращает True; в противном случае возвращает False.

remove_section(section): Удаляет указанный раздел section из конфигурации. Если раздел действительно существовал, возвращает True. В противном случае возвращает False.

optionxform(option)

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

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

cfgparser = ConfigParser()
cfgparser.optionxform = str

Обратите внимание: при чтении файлов конфигурации пробелы вокруг имён параметров удаляются до вызова optionxform().

configparser.UNNAMED_SECTION: Специальный объект, представляющий имя раздела, используемое для ссылки на раздел без имени (см. Разделы без имени).

configparser.MAX_INTERPOLATION_DEPTH: Максимальная глубина рекурсивной интерполяции для get(), если параметр raw имеет значение false. Это актуально только при использовании интерполяции по умолчанию.

Объекты 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.5: Добавлен аргумент converters.

Изменено в версии 3.8: Тип dict_type по умолчанию — dict, поскольку теперь он сохраняет порядок вставки.

Изменено в версии 3.13: Добавлен аргумент allow_unnamed_section.

Примечание

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

add_section(section)

Добавляет в экземпляр раздел с именем section. Если раздел с таким именем уже существует, вызывается исключение DuplicateSectionError. Если передано имя раздела по умолчанию, вызывается исключение ValueError.

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

set(section, option, value)

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

Этот метод позволяет пользователям присваивать ключам внутри объекта значения, не являющиеся строками. Такое поведение не поддерживается и приведёт к ошибкам при попытке записи в файл или получения значения в режиме без обработки raw. Используйте API протокола отображения, который не позволяет выполнять такие присваивания.

Исключения

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

exception configparser.NoSectionError: Исключение, вызываемое, если указанный раздел не найден.

exception configparser.DuplicateSectionError: Исключение, вызываемое, если add_section() вызывается с именем уже существующего раздела либо если в строгом парсере раздел встречается более одного раза в одном входном файле, строке или словаре.

Изменено в версии 3.2: В __init__() добавлены необязательные атрибуты и параметры source и lineno.

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: Атрибут filename и аргумент конструктора __init__() удалены. С версии 3.2 они доступны под именем source.

exception configparser.MultilineContinuationError: Исключение, вызываемое, если за ключом без соответствующего значения следует строка с отступом.

Добавлено в версии 3.13.

Сноски

© 2001–2025 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.13/library/configparser.html