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)

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

read(filenames, encoding=None)

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

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

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

import configparser, os

config = configparser.ConfigParser()
config.read_file(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
            encoding='cp1250')

Новое в версии 3.2: Параметр encoding. Ранее все файлы считывались с использованием кодировки по умолчанию для open().

Новое в версии 3.6.1: Параметр filenames принимает объект типа "путь".

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

read_file(f, source=None)

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

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

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

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

Парсинг данных конфигурации из строки.

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

Новое в версии 3.2.

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

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

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

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

Новое в версии 3.2.

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

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

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

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

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

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

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

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

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

Удобный метод, который преобразует option в указанной section в булевое значение. Обратите внимание, что допустимые значения для опции — '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 для опций в заданной section. Необязательные аргументы имеют такое же значение, как и для метода get().

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

set(section, option, value)

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

write(fileobject, space_around_delimiters=True)

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

Примечание

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

remove_option(section, option)

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

remove_section(section)

Удаляет указанную section из конфигурации. Если секция существовала, возвращает True. В противном случае возвращает False.

optionxform(option)

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

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

cfgparser = ConfigParser()
cfgparser.optionxform = str

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

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. Если передано имя default section, возникает исключение ValueError.

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

set(section, option, value)

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

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

Исключения

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)

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