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

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

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

[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, где недавно добавленная конфигурация имеет наивысший приоритет. Любые конфликтующие ключи берутся из более поздней конфигурации, а ранее существовавшие ключи сохраняются.

>>> another_config = configparser.ConfigParser()
>>> another_config.read('example.ini')
['example.ini']
>>> another_config['topsecret.server.example']['Port']
'50022'
>>> another_config.read_string("[topsecret.server.example]\nPort=48484")
>>> another_config['topsecret.server.example']['Port']
'48484'
>>> another_config.read_dict({"topsecret.server.example": {"Port": 21212}})
>>> another_config['topsecret.server.example']['Port']
'21212'
>>> another_config['topsecret.server.example']['ForwardX11']
'no'

Это поведение эквивалентно вызову 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.

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

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

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

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

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

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

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

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

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

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

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

Если раздел не указан, возвращает список пар имя_раздела, прокси_раздела, включая DEFAULTSECT.

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

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

set(section, option, value)

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

write(fileobject, space_around_delimiters=True)

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

Примечание

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

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,11)

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