configparser — Парсер файлов конфигурации

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

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

Примечание

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

См. также

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

14.2.1. Быстрый старт

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

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

[bitbucket.org]
User = hg

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

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

>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'}
>>> config['bitbucket.org'] = {}
>>> config['bitbucket.org']['User'] = 'hg'
>>> config['topsecret.server.com'] = {}
>>> topsecret = config['topsecret.server.com']
>>> 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)
...

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

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

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

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

14.2.2. Поддерживаемые типы данных

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

>>> 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['bitbucket.org'].getboolean('ForwardX11')
True
>>> config.getboolean('bitbucket.org', 'Compression')
True

Помимо getboolean(), парсеры конфигурации также предоставляют эквивалентные методы getint() и getfloat(). Вы можете зарегистрировать собственные преобразователи и настроить предоставленные. 1

14.2.3. Значения по умолчанию

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

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

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

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

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

>>> config.get('bitbucket.org', '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

14.2.4. Поддерживаемая структура файлов INI

Файл конфигурации состоит из разделов, каждый из которых начинается заголовком [section], за которым следуют записи ключ/значение, разделенные определённой строкой (= или : по умолчанию 1). По умолчанию имена разделов чувствительны к регистру, но ключи нет 1. Пробелы в начале и конце ключей и значений удаляются. Значения могут быть опущены, в этом случае разделитель ключ/значение также может быть опущен. Значения также могут занимать несколько строк, если они отступом глубже, чем первая строка значения. В зависимости от режима работы парсера, пустые строки могут рассматриваться как части многострочных значений или игнорироваться.

Файлы конфигурации могут содержать комментарии, которые начинаются со специальных символов (# и ; по умолчанию 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?

14.2.5. Интерполяция значений

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

class configparser.BasicInterpolation

Реализация по умолчанию, используемая ConfigParser. Она позволяет значениям содержать строки формата, которые ссылаются на другие значения в том же разделе или значения в специальном разделе по умолчанию 1. Дополнительные значения по умолчанию можно предоставить при инициализации.

Например:

[Paths]
home_dir: /Users
my_dir: %(home_dir)s/lumberjack
my_pictures: %(my_dir)s/Pictures

В примере выше, ConfigParser с интерполяцией, установленной на 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

Также можно получать значения из других разделов:

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

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

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

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

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

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

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

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

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

Подсказка: если вы хотите указать значения по умолчанию для определенного раздела, используйте read_dict() перед чтением фактического файла.
dict_type, значение по умолчанию: collections.OrderedDict

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

Для сортировки разделов и опций при записи обратно можно использовать альтернативный тип словаря. Также для повышения производительности можно использовать обычный словарь.

Обратите внимание: есть способы добавить набор пар ключ-значение в одной операции. При использовании обычного словаря в этих операциях порядок ключей может быть случайным. Например:
```
>>> 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()
['section3', 'section2', 'section1']
>>> [option for option in parser['section3']]
['baz', 'foo', 'bar']
```
В этих операциях также необходимо использовать словарь с сохранением порядка:
```
>>> from collections import OrderedDict
>>> parser = configparser.ConfigParser()
>>> parser.read_dict(
...   OrderedDict((
...     ('s1',
...      OrderedDict((
...        ('1', '2'),
...        ('3', '4'),
...        ('5', '6'),
...      ))
...     ),
...     ('s2',
...      OrderedDict((
...        ('a', 'b'),
...        ('c', 'd'),
...        ('e', 'f'),
...      ))
...     ),
...   ))
... )
>>> parser.sections()
['s1', 's2']
>>> [option for option in parser['s1']]
['1', '3', '5']
>>> [option for option in parser['s2'].values()]
['b', 'd', 'f']
```

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

ConfigParser.SECTCRE

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

>>> config = """
... [Section 1]
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> typical = ConfigParser()
>>> typical.read_string(config)
>>> typical.sections()
['Section 1', '  Section 2  ']
>>> custom = ConfigParser()
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
>>> custom.read_string(config)
>>> custom.sections()
['Section 1', 'Section 2']

Примечание

Хотя объекты ConfigParser также используют атрибут OPTCRE для распознавания строк опций, не рекомендуется его переопределять, потому что это повлияет на параметры конструктора allow_no_value и delimiters.

14.2.8. Примеры устаревшего 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!"

14.2.9. Объекты ConfigParser

class configparser.ConfigParser(defaults=None, dict_type=collections.OrderedDict, 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={})

Основной парсер конфигурации. Если задан параметр 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*() в объекте парсера и прокси-объектах раздела.

Изменено в версии 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.

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

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

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

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

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

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

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

read(filenames, encoding=None)

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

Если filenames — строка или объект, подобный пути, она обрабатывается как единственное имя файла. Если файл, указанный в 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 принимает объект, подобный пути.

read_file(f, source=None)

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

Необязательный аргумент 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])

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

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

Изменено в версии 3.2: Аргументы raw, vars и fallback являются только ключевыми для защиты пользователей от попыток использования третьего аргумента в качестве 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 в булево значение. Допустимые значения для параметра option — '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().

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

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

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().

readfp(fp, filename=None)

Устарело начиная с версии 3.2: Используйте read_file() вместо этого.

Изменено в версии 3.2: readfp() теперь итерирует по fp вместо вызова fp.readline().

Для существующего кода, вызывающего readfp() с аргументами, которые не поддерживают итерацию, можно использовать следующий генератор в качестве обёртки вокруг объекта-подобного-файлу:

def readline_generator(fp):
    line = fp.readline()
    while line:
        yield line
        line = fp.readline()

Вместо parser.readfp(fp) используйте parser.read_file(readline_generator(fp)).

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

14.2.10. Объекты RawConfigParser

class configparser.RawConfigParser(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT[, interpolation])

Устаревшая версия ConfigParser с отключённой интерполяцией по умолчанию и небезопасными методами add_section и set.

Примечание

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

add_section(section)

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

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

set(section, option, value)

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

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

14.2.11. Исключения

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

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

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

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

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

exception configparser.NoOptionError: Исключение, генерируемое, когда указанная опция не найдена в указанном разделе.

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

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

exception configparser.InterpolationMissingOptionError: Исключение, которое возникает, когда опция, на которую ссылается значение, не существует. Подкласс InterpolationError.

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

exception configparser.MissingSectionHeaderError: Исключение, возникающее при попытке парсинга файла, у которого нет заголовков разделов.

exception configparser.ParsingError: Исключение, которое возникает при возникновении ошибок при попытке парсинга файла.

Изменено в версии 3.2: Атрибут filename и аргумент __init__() были переименованы в source для обеспечения согласованности.

Примечания

1(1,2,3,4,5,6,7,8,9,10): Парсеры конфигураций допускают значительную настройку. Если вы заинтересованы в изменении поведения, описанного в ссылке в примечании, обратитесь к разделу Настройка поведения парсера.

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