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

Быстрый старт

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

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

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

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

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

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

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

>>> 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(). Вы можете зарегистрировать собственные преобразователи и настроить предоставленные.

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

Как и в случае со словарем, вы можете использовать метод 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

Поддерживаемая структура файла 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?

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

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

class configparser.BasicInterpolation

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

Например:

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

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

В примере выше, 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]
cost: $$80  # use a $$ to escape the $ sign ($ is the only character that needs to be escaped)

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

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

Доступ к протоколу сопоставления

Доступ к протоколу сопоставления — общее название функциональности, которая позволяет использовать пользовательские объекты так, как будто они являются словарями. В случае с 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, поэтому подклассы, переопределяющие исходный интерфейс, должны иметь работающие сопоставления, как ожидается.

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

Существует почти столько же вариантов формата 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

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

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={})

Основной парсер конфигурации. Если задано 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.

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

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

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

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() типа dict. Ключи — имена разделов, значения — словари с ключами и значениями, которые должны присутствовать в разделе. Если используемый тип словаря сохраняет порядок, разделы и их ключи будут добавлены в порядке. Значения автоматически преобразуются в строки.

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

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

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

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

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

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

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

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

Удобный метод, который приводит параметр в указанном разделе к целому числу. Смотрите get() для объяснения raw, vars и fallback.

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

Удобный метод, который приводит параметр в указанном разделе к числу с плавающей точкой. Смотрите get() для объяснения raw, vars и fallback.

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

Удобный метод, который приводит параметр в указанном разделе к значению булевого типа. Обратите внимание, что допустимые значения для параметра — '1', 'yes', 'true', и 'on', что приводит к возвращению этого метода True, а '0', 'no', 'false', и 'off', что приводит к возвращению False. Эти строковые значения проверяются без учёта регистра. Любое другое значение приведёт к возбуждению ValueError. Смотрите get() для объяснения raw, vars и fallback.

items(raw=False, vars=None)

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

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

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

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

set(section, option, value)

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

write(fileobject, space_around_delimiters=True)

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

remove_option(section, option)

Удаляет указанный параметр из указанного раздела. Если раздела не существует, возбуждается NoSectionError. Если параметр существовал для удаления, возвращает True; в противном случае возвращает False.

remove_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. Это актуально только при использовании стандартной интерполяции.

Объекты 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])

Устаревшая разновидность ConfigParser. По умолчанию интерполяция отключена, и она позволяет использовать имена разделов, имена параметров и значения, не являющиеся строками, через свои небезопасные add_section и set методы, а также устаревшее обработку ключевого аргумента defaults=.

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

Примечание

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

add_section(section)

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

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

set(section, option, value)

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

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

Исключения

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)

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